docs: Enterprise Edition & Multi-tenancy attribution (#5 )

* Remove outdated documentation files: Quick Start Guide, Apache AGE Analysis, and Scratchpad.

* Add multi-tenant testing strategy and ADR index documentation

- Introduced ADR 008 detailing the multi-tenant testing strategy for the ./starter environment, covering compatibility and multi-tenant modes, testing scenarios, and implementation details.
- Created a comprehensive ADR index (README.md) summarizing all architecture decision records related to the multi-tenant implementation, including purpose, key sections, and reading paths for different roles.

* feat(docs): Add comprehensive multi-tenancy guide and README for LightRAG Enterprise

- Introduced `0008-multi-tenancy.md` detailing multi-tenancy architecture, key concepts, roles, permissions, configuration, and API endpoints.
- Created `README.md` as the main documentation index, outlining features, quick start, system overview, and deployment options.
- Documented the LightRAG architecture, storage backends, LLM integrations, and query modes.
- Established a task log (`2025-01-21-lightrag-documentation-log.md`) summarizing documentation creation actions, decisions, and insights.

2025-12-04 18:09:15 +08:00

5.2 KiB

Raw Blame History

Multi-Tenant Audit - Test Execution Log

Date: November 29, 2025
Status: In Progress

Environment Setup

Docker Containers (Audit)

Container	Image	Port	Status
lightrag-audit-postgres	pgvector/pgvector:pg16	5433	✅ Healthy
lightrag-audit-redis	redis:7-alpine	6380	✅ Healthy

Test Configuration

PostgreSQL: localhost:5433 (User: lightrag, DB: lightrag_audit)
Redis: localhost:6380
API will run locally on port 9622 (to avoid conflict)
WebUI will run locally on port 5173

Execution Timeline

Session 1: Initial Setup and Codebase Review

Time: 2025-11-29 [Start]

Observation 1: Multi-Tenant Architecture Components Identified

Web UI Layer:
- tenant.ts store: Zustand store for tenant/KB selection with localStorage persistence
- client.ts: Axios interceptor adds X-Tenant-ID and X-KB-ID headers
- Console logging enabled for debugging header propagation
REST API Layer:
- dependencies.py: get_tenant_context() extracts tenant from headers
- tenant_routes.py: CRUD for tenants and KBs
- document_routes.py: Tenant-scoped document operations
- query_routes.py: Tenant-scoped query operations
Storage Layer:
- PostgreSQL tables have tenant_id and kb_id columns with composite PKs
- SQL queries use TenantSQLBuilder for automatic filtering
- Redis uses namespace prefixes

Initial Findings from Code Review

Finding 1: Potential Issue in Document Routes

Location: lightrag/api/routers/document_routes.py
Need to verify tenant context is consistently applied to all endpoints

Finding 2: Query Route Tenant Handling

Location: lightrag/api/routers/query_routes.py
The get_tenant_rag() dependency falls back to global RAG if no context
This could be a security issue if headers are missing

Finding 3: WebUI State Management

Recent fix in DocumentManager.tsx to clear state on tenant/KB change
Need to verify this works correctly in practice

Test Execution

Phase 1: Setup Python Environment

source ~/.venv/bin/activate
pip install ".[dev]" -q

Status: ✅ Completed

Phase 2: Unit Test Execution

Test Suite: test_multitenant_e2e.py

Status: ✅ PASSED (32/32 tests) in 0.47s

Test Class	Tests	Status
TestCompositeKeyPattern	4	✅
TestDataIsolation	3	✅
TestRedisNamespaceIsolation	5	✅
TestContextPropagation	2	✅
TestTenantManagement	2	✅
TestKnowledgeBaseManagement	2	✅
TestDocumentOperations	3	✅
TestEntityRelationIsolation	2	✅
TestEdgeCases	5	✅
TestConcurrentAccess	2	✅
TestDataConsistency	2	✅

Test Suite: test_tenant_security.py

Status: ✅ PASSED (11/11 tests) in 0.26s

Test Class	Tests	Status
TestPermissionEnforcement	5	✅
TestTenantContextValidation	4	✅
TestRoleHierarchy	2	✅

Test Suite: test_multi_tenant_backends.py

Status: ✅ PASSED (37/37 tests) in 0.45s

Test Class	Tests	Status
TestPostgresMultiTenant	7	✅
TestMongoMultiTenant	5	✅
TestRedisMultiTenant	6	✅
TestVectorMultiTenant	6	✅
TestGraphMultiTenant	6	✅
TestTenantIsolationSecurity	3	✅
TestBackwardCompatibility	3	✅

Test Suite: test_tenant_storage_phase3.py

Status: ✅ PASSED (22/22 tests) in 0.34s

Test Class	Tests	Status
TestTenantRAGManagerBasics	4	✅
TestTenantContextUnit	5	✅
TestTenantModel	4	✅
TestTenantConfigModel	3	✅
TestMultiTenantStructure	4	✅
TestTenantContextIsolation	2	✅

Test Summary

Test Suite	Tests	Passed	Status
test_multitenant_e2e.py	32	32	✅
test_tenant_security.py	11	11	✅
test_multi_tenant_backends.py	37	37	✅
test_tenant_storage_phase3.py	22	22	✅
Total	102	102	✅

Phase 3: API Endpoint Testing

Status: In Progress

Phase 4: WebUI Testing

Status: Pending

Issues Found

Issue 1: Test Import Errors

Files: test_document_routes_tenant_scoped.py, test_tenant_api_routes.py Problem: These files have import issues when run outside API context Root Cause: lightrag.api.routers.document_routes imports trigger CLI argument parsing Impact: 2 test files cannot be run Recommendation: Fix import structure or mock CLI initialization

Issue 2: Deprecation Warnings

Files: Multiple test files Warning: datetime.datetime.utcnow() is deprecated Recommendation: Update to datetime.datetime.now(datetime.UTC)

Lessons Learned

All 102 unit tests pass - The multi-tenant implementation at the model and storage layer is solid
Import issues exist in API route tests due to CLI argument parsing at import time
Test coverage is comprehensive for backend multi-tenant isolation
Role-based access control is properly tested with clear permission boundaries

5.2 KiB Raw Blame History