Docker Compose 部署
Docker Compose 部署
相关源文件
本章引用的主要源码文件：
DockerfileDockerfile.liteMakefiledocker-compose-full.ymldocker-compose.podman.ymldocker-compose.ymldocs/AdvancedFeatures.mddocs/DockerDeployment.mddocs/InteractiveSetup.mdenv.docker-compose-fullscripts/setup/lib/file_ops.shscripts/setup/lib/presets.shscripts/setup/lib/prompts.shscripts/setup/lib/storage_requirements.shscripts/setup/lib/validation.shscripts/setup/setup.shscripts/setup/templates/memgraph.ymlscripts/setup/templates/milvus-gpu.ymlscripts/setup/templates/milvus.ymlscripts/setup/templates/mongodb.ymlscripts/setup/templates/neo4j.ymlscripts/setup/templates/opensearch.ymlscripts/setup/templates/postgres.ymlscripts/setup/templates/qdrant.ymlscripts/setup/templates/redis.ymlscripts/setup/templates/vllm-embed-gpu.ymlscripts/setup/templates/vllm-embed.ymlscripts/setup/templates/vllm-rerank-gpu.ymlscripts/setup/templates/vllm-rerank.ymltests/test_interactive_setup/test_collect.pytests/test_interactive_setup/test_generate.pytests/test_interactive_setup/test_misc.py
LightRAG 代码库提供了一套基于 Docker 的复杂部署基础设施，能够处理从单容器执行到多服务堆栈的各种场景。该系统利用多阶段 Dockerfile、交互式设置向导和基于模板的生成系统，最终生成一个可用于生产环境的 docker-compose.final.yml 文件。
Docker 镜像与构建流程
LightRAG 维护了两个主要的 Dockerfile 变体，以在功能完整性和镜像大小之间取得平衡。
Dockerfile（完整版）
标准 Dockerfile 采用多阶段构建流程，以优化性能和安全性 Dockerfile:1-111。
- 前端阶段：使用
oven/bun构建基于 React 的 WebUI 资源Dockerfile:6-17。 - Python 构建阶段：使用
ghcr.io/astral-sh/uv实现快速、并行的依赖解析。该阶段会安装系统依赖（如用于编译 wheel 的 Rust），并预先同步 Python 环境Dockerfile:20-60。 - 缓存预填充：执行
lightrag-download-cache命令，将tiktoken数据预填充到/app/data/tiktoken目录，从而实现离线功能Dockerfile:64-66。 - 最终阶段：使用
python:3.12-slim镜像，仅复制必要的虚拟环境和应用程序代码Dockerfile:69-81。
Dockerfile.lite
这是一个精简版本，适用于不需要外部解析器（如 MinerU 或 Docling）的环境，生成的镜像体积显著更小。
来源： Dockerfile:1-111，docs/DockerDeployment.md:68-76
交互式设置向导
部署过程通过位于 scripts/setup/setup.sh 的 Bash 交互式向导进行管理。该向导会在主机端执行和容器端执行之间规范化配置。
向导架构与流程
该向导通过 make 目标调用，这些目标确保兼容 Bash 4+ 环境 Makefile:2-3。
| 目标 | 描述 | 关键代码函数 |
|---|---|---|
make env-base | 配置大语言模型（LLM）、嵌入向量和重排序器。 | collect_base_config |
make env-storage | 配置数据库后端（Postgres、Neo4j 等）。 | collect_storage_config |
make env-server | 配置端口、认证和 SSL。 | collect_server_config |
make env-validate | 校验 .env 语法和存储兼容性。 | validate_required_variables |
向导管理的服务
当用户选择通过 Docker 运行某个服务（如 Neo4j 或 vLLM）时，向导会从 scripts/setup/templates/*.yml 中提取模板，并将服务定义注入到最终的 compose 文件中 scripts/setup/setup.sh:13-15。
来源： Makefile:77-100，scripts/setup/setup.sh:1-90，docs/InteractiveSetup.md:1-49
配置规范化（主机 vs Compose）
LightRAG 部署的一个关键特性是运行时目标规范化。系统会区分 LIGHTRAG_RUNTIME_TARGET=host 和 compose 两种模式 env.docker-compose-full:6。
主机名转换
当 LightRAG 在容器内运行（compose 目标），但需要访问主机上运行的服务时，向导会自动将 localhost 或 127.0.0.1 转换为 host.docker.internal scripts/setup/setup.sh:243-255。
SSL 暂存
如果启用了 SSL，向导会"暂存"证书。它会将本地证书文件复制到 ./data/certs/ 目录，以便通过绑定挂载的方式将其挂载到容器的 /app/data/certs/ 路径下 scripts/setup/lib/file_ops.sh:85-107。
图表：配置流向代码实体
下图展示了用户输入如何转换为代码级别的环境变量和 Docker 配置。
"向导输入到代码的映射"
来源： scripts/setup/setup.sh:243-255，scripts/setup/lib/file_ops.sh:85-107，env.docker-compose-full:1-30
Docker Compose 文件生成
系统使用 docker-compose.final.yml 作为主要的运行时定义文件。该文件不会手动编辑，而是由向导生成或合并。
服务模板
向导维护了一组用于托管服务的 YAML 模板。例如，postgres 模板包含健康检查，该检查使用 cat /proc/net/tcp 来确保在 lightrag 服务启动之前端口已处于活动状态 scripts/setup/templates/postgres.yml:7-13。
依赖关系图
生成的堆栈使用带有 service_healthy 条件的 depends_on 来确保正确的启动顺序，特别是对于需要 etcd 和 minio 的复杂向量数据库（如 Milvus）docker-compose-full.yml:38-49。
图表：多服务数据流
此图展示了 LightRAG 容器与托管后端服务之间的关系。
"容器化服务架构"
来源： docker-compose-full.yml:4-49，scripts/setup/templates/vllm-embed.yml:1-20，docs/DockerDeployment.md:108-114
安全审计
在部署之前，系统会提供安全审计机制。命令 make env-security-check 会调用 scripts/setup/setup.sh --security-check。
审计检查
审计器会校验多个关键安全参数：
- 认证：检查是否设置了
AUTH_ACCOUNTSscripts/setup/lib/validation.sh:152-163。 - JWT 完整性：验证
TOKEN_SECRET是否未使用默认值scripts/setup/lib/validation.sh:156。 - 白名单安全性：检查
WHITELIST_PATHS是否包含过于宽松的模式docs/DockerDeployment.md:102-106。 - 插值风险：确保敏感密钥不包含
${...}语法，该语法可能通过环境变量注入被利用scripts/setup/lib/validation.sh:146-150。
来源： scripts/setup/lib/validation.sh:146-188，docs/DockerDeployment.md:99-106，Makefile:95-96