4.1 · 服务端架构与生命周期（Server Architecture and Lifecycle）

Graph 存储后端

图存储后端

相关源文件

本章引用的主要源码文件：

• lightrag/kg/faiss_impl.py
• lightrag/kg/json_doc_status_impl.py
• lightrag/kg/json_kv_impl.py
• lightrag/kg/memgraph_impl.py
• lightrag/kg/milvus_impl.py
• lightrag/kg/mongo_impl.py
• lightrag/kg/nano_vector_db_impl.py
• lightrag/kg/neo4j_impl.py
• lightrag/kg/networkx_impl.py
• lightrag/kg/postgres_impl.py
• lightrag/kg/qdrant_impl.py
• lightrag/kg/redis_impl.py
• tests/README_WORKSPACE_ISOLATION_TESTS.md
• tests/test_graph_storage.py
• tests/test_neo4j_fulltext_index.py
• tests/test_postgres_index_name.py
• tests/test_postgres_retry_integration.py
• tests/test_workspace_isolation.py
• tests/test_workspace_sanitization.py
• tests/test_write_json_optimization.py

LightRAG 为知识图谱（KG）存储提供了可插拔的架构，支持从本地基于文件的图到企业级分布式图数据库的多种后端。每个后端都实现了 BaseGraphStorage 接口，提供了实体和关系管理、子图检索以及工作空间隔离的方法。

后端实现

LightRAG 支持五种主要的图存储后端，每种后端针对不同的规模和性能需求进行了优化。

1. NetworkX（默认）

默认后端使用 NetworkX 库进行内存中的图操作，并将数据持久化到 .graphml 文件中。它非常适合本地开发和小型到中型数据集。

• 基于文件的持久化：数据以 graph_{namespace}.graphml 格式保存在工作空间目录中 lightrag/kg/networkx_impl.py:51-53。
• 并发处理：使用 get_namespace_lock 和 get_update_flag 来协调多个进程之间的访问，如果其他进程修改了图，则会从磁盘重新加载 lightrag/kg/networkx_impl.py:77-96。
• 性能优化：包含 upsert_nodes_batch 和 upsert_edges_batch 等批量方法，以最小化入库期间的异步开销 lightrag/kg/networkx_impl.py:157-181。

2. Neo4j

一个适用于企业级用例的健壮实现，支持 Cypher 查询和高级图算法。

• BFS 检索：使用 Neo4j 的 apoc.path.subgraphAll（如果可用）或标准 Cypher 进行广度优先搜索子图检索 lightrag/kg/neo4j_impl.py:383-400。
• 中日韩（CJK）全文索引：实现了针对实体 ID 的专用全文索引。它会检测 CJK 字符以应用合适的分析器，确保对中文、日文和韩文文本的高效检索 lightrag/kg/neo4j_impl.py:121-133。
• 弹性恢复：通过 READ_RETRY 装饰器实现了指数退避重试机制，用于读取操作 lightrag/kg/neo4j_impl.py:56-61。

3. 带 Apache AGE 的 PostgreSQL

使用 Apache AGE 扩展在关系型 PostgreSQL 数据库中实现图功能。

• 通过 SQL 执行 Cypher：通过将 Cypher 包装在 PostgreSQL 的 ag_catalog.cypher 函数中来执行图查询 lightrag/kg/postgres_impl.py:1162-1175。
• 安全标识符：包含一个 _safe_index_name 工具函数，通过对长表名进行哈希处理，防止 PostgreSQL 的 63 字节标识符截断问题 lightrag/kg/postgres_impl.py:74-104。
• 美元符号引用：使用动态的 _dollar_quote 辅助函数，安全地包装包含特殊字符的 Cypher 字符串 lightrag/kg/postgres_impl.py:112-140。

4. MongoDB

使用 MongoDB 的文档模型和 $graphLookup 聚合来模拟图关系。

• 图模拟：将节点和边存储在一个集合中。关系被建模为边文档，遍历通过 $graphLookup 操作符执行 lightrag/kg/mongo_impl.py:41-42。
• BFS 策略：通过 MONGO_GRAPH_BFS_MODE 环境变量支持"双向"、"上游"或"下游"的 BFS 模式 lightrag/kg/mongo_impl.py:41。

5. Memgraph

一个与 Neo4j bolt 协议兼容的内存图数据库。

• 高性能：针对低延迟图遍历进行了优化。
• 索引：在初始化期间，自动在工作空间标签内的 entity_id 上创建索引 lightrag/kg/memgraph_impl.py:99-104。

数据流与抽象

BaseGraphStorage 类定义了所有后端必须遵循的契约。下图展示了 LightRAG 核心如何与这些后端交互。

系统架构：核心到存储

来源： lightrag/base.py:30-32, lightrag/kg/networkx_impl.py:26, lightrag/kg/neo4j_impl.py:66, lightrag/kg/postgres_impl.py:143, lightrag/kg/mongo_impl.py:86, lightrag/kg/memgraph_impl.py:35

工作空间隔离

LightRAG 使用"工作空间"概念实现了严格的数据隔离。这使得单个数据库实例可以托管多个独立的知识图谱。

关键函数与检索策略

子图检索（get_knowledge_graph）

此函数对于可视化器和本地检索模式至关重要。它获取节点和边的局部邻域。

• Neo4j 实现：使用 MATCH (n) WHERE n:label RETURN n 构建图结构 lightrag/kg/neo4j_impl.py:348-360。
• NetworkX 实现：直接返回内部的 nx.Graph 对象 lightrag/kg/networkx_impl.py:255-257。

广度优先搜索（embed_nodes）

在检索期间用于查找相关上下文。

• Neo4j：利用 apoc.path.subgraphAll 进行高效的多跳遍历 lightrag/kg/neo4j_impl.py:383-388。
• NetworkX：使用基于 collections.deque 的手动 BFS 实现 lightrag/kg/networkx_impl.py:220-253。

实现映射：代码到存储

来源： lightrag/kg/networkx_impl.py:81-97, lightrag/kg/neo4j_impl.py:348-381, lightrag/types.py:16-18

配置摘要

来源：

• lightrag/kg/networkx_impl.py
• lightrag/kg/neo4j_impl.py
• lightrag/kg/postgres_impl.py
• lightrag/kg/mongo_impl.py
• lightrag/kg/memgraph_impl.py
• lightrag/base.py