8 · 开发与工具（Development and Tools）

轻量图谱增强检索 · 本章是 LightRAG DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目LightRAG 章节8 状态全文译文模块安装与启动、测试、发布与运维、智能体运行时、存储与持久化

项目要点页2.5 参考项目项目章节目录LightRAG DeepWiki 原始章节Development and Tools 上一章7.6 下一章8.1

源码线索

AGENTS.md
CLAUDE.md
config.ini.example
lightrag/llm/binding_options.py
pyproject.toml
requirements-offline-llm.txt
requirements-offline-storage.txt
requirements-offline.txt
scripts/test.sh
uv.lock

模块标签

安装与启动
测试、发布与运维
智能体运行时
存储与持久化
接口与服务契约

中文译文

部署与基础设施（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/HKUDS/LightRAG/8-deployment-and-infrastructure

翻译时间：2026-05-27T08:45:14.665Z

翻译模型：deepseek-chat

原文字符数：6997

项目：LightRAG (lightrag)

---

部署与基础设施

部署概述

根据基础设施需求，LightRAG 可采用以下三种主要模式进行部署：

基于宿主机部署：直接在物理机或虚拟机上使用 Python 环境运行 lightrag-server。
容器化部署（Docker Compose）：使用提供的 Dockerfile 和 docker-compose.yml 编排 API 服务器及各种存储后端（PostgreSQL、Neo4j、Milvus 等）。
云原生部署（Kubernetes）：利用 Helm Chart 实现检索增强生成（RAG）技术栈的自动化部署、扩缩容和管理。

系统架构映射

下图将概念性的部署服务映射到管理这些服务的具体代码实体和配置。

部署实体映射

graph TD
    subgraph "编排层"
        [Makefile] -- "调用" --> [setup.sh]
        [setup.sh] -- "生成" --> [docker-compose.final.yml]
        [setup.sh] -- "更新" --> [.env]
    end

    subgraph "容器空间"
        [Dockerfile] -- "构建" --> [lightrag_image]
        [lightrag_image] -- "运行" --> [lightrag_server.py]
        [lightrag_server.py] -- "使用" --> [GlobalArgsProxy]
    end

    subgraph "基础设施服务"
        [lightrag_server.py] -- "连接" --> [PostgreSQL]
        [lightrag_server.py] -- "连接" --> [Neo4j]
        [lightrag_server.py] -- "连接" --> [vLLM_Services]
    end

    style [setup.sh] stroke-dasharray: 5 5
    style [lightrag_server.py] stroke-dasharray: 5 5

来源： scripts/setup/setup.sh:1-30、docker-compose.yml:1-28、lightrag/api/lightrag_server.py:1-111

---

交互式设置向导

推荐使用交互式设置向导来配置任何部署方案。该工具可管理环境变量、存储后端兼容性以及 Docker 服务生成的复杂性。

入口：通过 make 目标访问，例如 make env-base、make env-storage 和 make env-server Makefile:77-90。
逻辑：该向导由 scripts/setup/setup.sh 和一组辅助脚本库驱动 scripts/setup/setup.sh:1-15。
主要特性：
规范化：当从宿主机运行时迁移到容器运行时，会自动将 localhost 转换为 host.docker.internal scripts/setup/setup.sh:243-255。
校验：检查所有支持数据库的 URI 格式 scripts/setup/lib/validation.sh:3-34。
安全审计：包含 security-check 目标，用于识别弱 JWT 密钥或暴露的 API 密钥 docs/InteractiveSetup.md:199-202。

有关使用该向导的详细信息，请参阅 Docker Compose 部署。

---

部署选项

Docker Compose

Docker 部署使用多阶段构建的 Dockerfile，其中包含 frontend-builder（使用 Bun）和 builder（使用 UV）阶段，以优化镜像大小和构建速度 Dockerfile:1-69。它还支持用于最小化环境的 "Lite" 版本 Dockerfile.lite:1-112。

docker-compose.yml：基本部署的标准入口点 docker-compose.yml:1-28。
docker-compose.final.yml：由设置向导生成的自定义技术栈，仅包含您选择的服务（例如，用于嵌入向量的本地 vLLM）docs/DockerDeployment.md:83-89。

有关详细信息，请参阅 Docker Compose 部署。

Kubernetes 和 Helm

对于需要高可用性的生产环境，LightRAG 提供了 Helm Chart。它支持：

生产模式：与 KubeBlocks 集成，用于托管数据库操作符。
持久化：为检索增强生成（RAG）存储和输入目录提供可配置的持久卷声明（PVC）。

有关详细信息，请参阅 Kubernetes / Helm 部署。

多站点与离线部署

LightRAG 支持复杂的网络场景：

离线/隔离环境：使用 requirements-offline.txt 和预下载的 tiktoken 缓存 Dockerfile:62-66。
本地推理：与 vLLM 集成，用于本地嵌入向量和重排序服务，避免依赖外部 API docs/DockerDeployment.md:116-123。

有关详细信息，请参阅 多站点与离线部署。

---

基础设施配置映射

下表将基础设施需求映射到管理这些需求的代码变量和文件。

需求	代码变量 / 实体	实现文件
运行时目标	`LIGHTRAG_RUNTIME_TARGET`	`scripts/setup/setup.sh:134-143`
API 端口	`PORT`（默认值：9621）	`docker-compose.yml:10`
数据持久化	`WORKING_DIR`	`Dockerfile:103`
SSL/TLS	`SSL`、`SSL_CERTFILE`、`SSL_KEYFILE`	`scripts/setup/lib/file_ops.sh:85-107`
数据库服务	`STORAGE_SERVICES` 数组	`scripts/setup/setup.sh:56-65`
本地推理	`VLLM_SERVICES` 数组	`scripts/setup/setup.sh:51-54`

基础设施依赖流程

graph LR
    subgraph "外部/托管"
        [OpenAI/Ollama]
        [Neo4j_Cloud]
    end

    subgraph "Docker_技术栈 (docker-compose.final.yml)"
        [lightrag_service] -- "依赖" --> [postgres_service]
        [lightrag_service] -- "依赖" --> [vllm-embed_service]
        [lightrag_service] -- "挂载" --> [rag_storage_volume]
    end

    [lightrag_service] -- "环境文件" --> [.env]
    [.env] -- "由...管理" --> [setup.sh]

来源： docker-compose-full.yml:5-49、docs/InteractiveSetup.md:122-152、scripts/setup/lib/file_ops.sh:155-197

来源：

scripts/setup/setup.sh:1-255
Makefile:1-100
Dockerfile:1-112
docker-compose.yml:1-28
docs/InteractiveSetup.md:1-203
docs/DockerDeployment.md:1-230