LightRAG 交互式配置向导实战：make env-* 命令族如何生成 .env 与 Docker Compose 栈

LightRAG 提供了基于 make 的交互式配置向导（Interactive Setup Wizard），可以替代手工编辑 .env 文件，分三个步骤完成 LLM/Embedding/Reranker、存储后端、服务端安全与 SSL 的配置，并自动生成可运行的 docker-compose.final.yml。读完本篇，你将掌握完整的 make env-* 命令族用法、各场景下向导的具体提问与默认值、MongoDB Atlas Local 等易错约束的底层原因，以及配置校验（validate）与安全审计（security-check）的操作方式。

一、命令族总览：make 目标与底层脚本

向导通过仓库根目录 Makefile 中的 env-* 目标暴露，底层统一调用 scripts/setup/setup.sh。不需要直接调用 shell 脚本：

Make 目标	别名（可去掉 env- 前缀）	底层调用	用途
make env-base	make base / make configure	setup.sh --base	配置 LLM、embedding、reranker（首次运行从这里开始，创建初始 .env）
make env-storage	make storage	setup.sh --storage	配置存储后端与数据库（需要已有 .env）
make env-server	make server	setup.sh --server	配置服务端口、WebUI 标签、认证、API Key、SSL（需要已有 .env）
make env-validate	make validate	setup.sh --validate	校验现有 .env 的内部一致性
make env-security-check	make security / make security-check	setup.sh --security-check	审计 .env 的安全风险
make env-backup	make backup	setup.sh --backup	单独备份 .env（及已生成的 compose 文件），不改动配置
make env-base-rewrite	make base-rewrite	setup.sh --base --rewrite-compose	在 base 流程中强制从内置模板重新生成向导托管的 compose 服务
make env-storage-rewrite	make storage-rewrite	setup.sh --storage --rewrite-compose	在 storage 流程中强制重新生成

补充几点来自 Makefile 的实现细节：

• Bash 4+ 自动探测：SETUP_BASH 变量会依次探测 Homebrew/ports 安装的新版 bash，找不到才回退到系统 bash。setup.sh 开头会显式检查 BASH_VERSINFO，版本低于 4 直接报错退出。
• 透传额外参数：任意目标都支持 SETUP_OPTS 透传，例如 make env-storage SETUP_OPTS=--debug 开启调试日志，SETUP_OPTS=--rewrite-compose 强制重写 compose 服务（等价于 *-rewrite 目标）。
• make help 会打印完整的交互式配置目标清单与典型工作流（make dev → make env-base → make env-storage → make env-server）。

二、向导的三段式设计

向导把完整配置拆成三部分，每部分可以独立重跑：

• env-base：设置 LLM、embedding 模型与可选的 reranker；
• env-storage：添加或更换存储后端，支持 PostgreSQL、Neo4j、Redis、Milvus、Qdrant、MongoDB、Memgraph 等；
• env-server：设置服务器 host/port、WebUI 标题描述、摘要语言、认证与 API Key、SSL/TLS。

重跑时向导会加载现有 .env，把当前值显示为默认值，你只需要修改有差异的项。源码层面这一行为由 setup.sh 的 load_existing_env_if_present 实现：它逐行解析 .env 填充 ENV_VALUES 关联数组，并快照为 ORIGINAL_ENV_VALUES，后续收集器（collector）一律以“已有值优先”的方式提问——这一点有回归测试 tests/setup/test_env.py 验证：env-base 流程不得触碰 server、security、observability 等与推理无关的值。

开始前须知：

• 所有命令从仓库根目录执行；
• make env-* 目标自动选择兼容的 Bash 4+ 解释器；
• 使用文档化的 make env-* 目标，不要直接调用 setup 脚本；
• make env-base 是正常起点（它创建初始 .env）；
• make env-storage 和 make env-server 要求已存在 .env，否则报错 Run 'make env-base' first；
• 只要你选择了任意“向导托管”的 Docker 服务，向导同时会把 LightRAG 自身切换到 Docker 启动路径（LIGHTRAG_RUNTIME_TARGET=compose）。

三、如何选择安装路径

原文档给出的快速决策表（docs/InteractiveSetup.md）：

• 想用远程模型供应商尽快跑起来：make env-base
• 想让 embedding 或 reranking 在本地 Docker 中运行：make env-base
• 模型已配好，现在要数据库：make env-storage
• 模型已配好，现在要认证、API Key 或 SSL：make env-server
• 想检查当前配置是否合法：make env-validate
• 想在暴露到网络前做一次安全审计：make env-security-check
• 想单独备份而不改配置：make env-backup
• 需要从内置模板完整重建向导托管的 compose 服务：make env-base-rewrite 或 make env-storage-rewrite

四、场景 1：首次本地部署（远程模型 + 本机服务）

适用于已有远程模型端点或 API Key、希望以最少配置跑起 LightRAG 的场景。

命令

make env-base

向导会依次询问（对应 setup.sh 的 collect_llm_config）：

• LLM 供应商、模型、端点、API Key。供应商选项为 openai、azure_openai、ollama、openai-ollama、lollms、gemini、bedrock；各供应商有内置默认模型，例如 openai 默认 gpt-5-mini，bedrock 默认 anthropic.claude-3-5-sonnet-20241022-v2:0
• 是否启用 reranking；启用后询问是否用本地 Docker 运行 rerank 服务；继续则询问 rerank 供应商（cohere / jina / aliyun）、模型、端点、API Key
• 是否把 embedding 模型放到本地 Docker 运行（vLLM）；若不本地运行，则询问 embedding 供应商、模型、维度、端点、API Key

写入内容

• .env
• 仅当启用了向导托管的 Docker 服务时才生成 docker-compose.final.yml

下一步

# 未启用向导托管 Docker 服务：
lightrag-server

# 启用了向导托管 Docker 服务：
docker compose -f docker-compose.final.yml up -d

从源码看，env-base 结束时还会把四个存储类初始化为本地文件默认值（JsonKVStorage / NanoVectorDBStorage / NetworkXStorage / JsonDocStatusStorage，见 setup.sh 的 initialize_default_storage_backends），这样尚未跑过 env-storage 的新用户也能直接启动。

五、场景 2：本地 Docker 托管 Embedding 或 Rerank（vLLM）

适合希望 embedding 和/或 reranking 走本地推理的场景。

命令

make env-base

推荐回答

• 对 Run embedding model locally via Docker (vLLM)? 回答 yes 以获得本地 embedding；
• 对 Enable reranking? 回答 yes，再对 Run rerank service locally via Docker? 回答 yes 以获得本地 reranking。

启用本地服务后向导会询问

• 本地 vLLM 使用的 embedding 模型名；
• 本地 vLLM 使用的 rerank 模型名；
• 主 LLM 仍为远程时的远程 LLM 参数。

源码层面，选择本地 vLLM 时向导会应用内置预设（setup.sh）：

服务	预设值	说明
vllm-embed	EMBEDDING_MODEL=BAAI/bge-m3、EMBEDDING_DIM=1024、VLLM_EMBED_PORT=8001	宿主机视角 EMBEDDING_BINDING_HOST=http://localhost:8001/v1，容器内 compose 覆写为 http://vllm-embed:8001/v1
vllm-rerank	RERANK_MODEL=BAAI/bge-reranker-v2-m3、VLLM_RERANK_PORT=8000	RERANK_BINDING=cohere 兼容端点，宿主机视角 http://localhost:8000/rerank

此外向导在启动时会探测 GPU：调用 nvidia-smi 成功则新本地 vLLM 服务默认 CUDA（GPU 镜像 + float16），否则默认 CPU 镜像 + float32（env_base_flow 开头日志）；VLLM_EMBED_DEVICE / VLLM_RERANK_DEVICE 也可在提问中手动选择，选 cuda 但宿主机无 NVIDIA 驱动时会给出警告。vLLM 服务首次启用时还会自动生成随机 API Key（openssl rand -hex 16）同时写入 VLLM_EMBED_API_KEY 与 EMBEDDING_BINDING_API_KEY。

写入内容

• .env
• 包含所选本地服务的 docker-compose.final.yml（服务模板来自 scripts/setup/templates/vllm-embed.yml、scripts/setup/templates/vllm-rerank.yml，以及对应的 *-gpu.yml GPU 变体）

下一步

docker compose -f docker-compose.final.yml up -d

这会同时启动生成的 Docker 版 LightRAG 栈与所选本地推理服务。

六、场景 3：基础配置后追加数据库存储

适用于已有 .env（由 make env-base 生成）、希望从默认本地文件存储切换到数据库存储的场景。

命令

make env-storage

前提：.env 必须已存在。

向导会依次询问（select_storage_backends，setup.sh）：

• KV 存储后端：JsonKVStorage / PGKVStorage / MongoKVStorage / OpenSearchKVStorage / RedisKVStorage
• 向量存储后端：NanoVectorDBStorage / PGVectorStorage / MongoVectorDBStorage / OpenSearchVectorDBStorage / MilvusVectorDBStorage / FaissVectorDBStorage / QdrantVectorDBStorage
• 图存储后端：NetworkXStorage / PGTableGraphStorage / MongoGraphStorage / OpenSearchGraphStorage / MemgraphStorage / Neo4JStorage / PGGraphStorage
• 文档状态存储后端：JsonDocStatusStorage / PGDocStatusStorage / MongoDocStatusStorage / OpenSearchDocStatusStorage / RedisDocStatusStorage
• 对每个被引用的数据库，是否通过本地 Docker 运行，以及连接参数（host、URI、port、user、password、数据库名、设备类型）

完整选项与每个存储类依赖的环境变量定义在 scripts/setup/lib/storage_requirements.sh，例如 MilvusVectorDBStorage 要求 MILVUS_URI 与 MILVUS_DB_NAME，PGVectorStorage 要求 POSTGRES_USER/POSTGRES_PASSWORD/POSTGRES_DATABASE。选择后 check_storage_compatibility 会打印兼容性警告，例如“NetworkX 图存储仅适合小数据集”“JSON 存储仅推荐本地开发”“Mongo 向量存储需要 Atlas Search / Vector Search 支持”，并在不合规时询问是否继续。

重要规则（MongoDB）

• MongoVectorDBStorage 要求 Atlas Search / Vector Search 支持；
• 若选择向导托管的 Docker MongoDB 服务，向导实际部署的是 MongoDB Atlas Local 而非社区版，因此 MongoVectorDBStorage 可以跑在本地 Docker 上；宿主机侧 MONGO_URI 使用 ?directConnection=true，容器内 compose 覆写为 mongodb://mongodb:27017/?directConnection=true（见 setup.sh 的 collect_mongodb_config）；
• 若不使用向导托管的 Docker MongoDB，请提供外部具备 Atlas 能力的端点（mongodb+srv:// 集群 URI 或 Atlas Local 的 mongodb://...?...directConnection=true URI）；
• 对外部 mongodb://...?...directConnection=true URI，向导只能校验 URI 格式，无法静态判断目标部署是否真的提供 Atlas Search / Vector Search。

该校验由 scripts/setup/lib/validation.sh 的 validate_mongo_vector_storage_config 实现，且 env-base、env-storage、env-server 三个流程写盘前都会执行。

每个数据库的交互默认值（摘自 setup.sh 的各 collect_*_config）：

数据库	本地 Docker 默认	询问参数
PostgreSQL	POSTGRES_HOST=postgres（容器内），端口固定 5432	host / user（默认 rag）/ password（默认 rag）/ database（默认 lightrag）
Neo4j	NEO4J_URI=neo4j://neo4j:7687	URI / username / password / database
MongoDB	MONGO_URI=mongodb://localhost:27017/?directConnection=true	URI / database（默认 LightRAG）
Redis	REDIS_URI=redis://redis:6379	URI；同时从 redis.conf.template 生成配置资产
Milvus	MILVUS_URI=http://milvus:19530	URI / 设备（cpu/cuda）/ 数据库名；Docker 模式会补默认 MINIO_ACCESS_KEY_ID/MINIO_SECRET_ACCESS_KEY
Qdrant	QDRANT_URL=http://qdrant:6333	URL / 设备（cpu/cuda）
Memgraph	MEMGRAPH_URI=bolt://memgraph:7687	URI
OpenSearch	OPENSEARCH_HOSTS=opensearch:9200	hosts / user / password（强制强度校验：≥8 位且含大小写、数字、特殊字符）/ SSL / 分片副本

写入内容

• .env
• 若选择了向导托管的存储服务，则生成/更新 docker-compose.final.yml（服务模板位于 scripts/setup/templates/，如 postgres.yml、neo4j.yml、milvus.yml、qdrant.yml 等）

下一步

• 选择了 Docker 托管存储服务：

docker compose -f docker-compose.final.yml up -d

• 指向外部数据库：启动 LightRAG 前确保这些服务可达。

七、场景 4：认证与 SSL 加固

适用于已有 .env、需要为共享或对外使用做准备的场景。

命令

make env-server
make env-security-check

前提：.env 必须已存在。

env-server 会询问（setup.sh 的 collect_server_config / collect_security_config / collect_ssl_config）：

• 服务器 host（默认 0.0.0.0）与 port（默认 9621，范围 1–65535 强校验）
• WebUI 标题与描述（默认 My Graph KB / Simple and Fast Graph Based RAG System）
• 摘要语言（默认 English）
• 是否配置认证与 API Key；是则询问：
  • 认证账号 AUTH_ACCOUNTS（user:pass 逗号分隔，支持 {bcrypt} 哈希）
  • JWT 密钥 TOKEN_SECRET——留空时向导用 openssl rand -hex 32 自动生成并写入 .env
  • Token 有效期 TOKEN_EXPIRE_HOURS（默认 48）
  • LIGHTRAG_API_KEY
  • 白名单路径 WHITELIST_PATHS（生产场景默认收窄为 /health）
• 是否启用 SSL/TLS，以及证书文件路径与私钥文件路径（两者都会做“文件存在”校验）

写入内容

• .env
• 若当前配置已使用向导托管的 Docker 服务，docker-compose.final.yml 可能同步更新。容器化运行时，向导会把证书暂存到 data/certs/ 并在 compose 中覆写为 /app/data/certs/ 下的容器路径（file_ops.sh 的 stage_ssl_assets / setup.sh 的 prepare_compose_ssl_overrides），强制 WORKING_DIR/INPUT_DIR/PROMPT_DIR 指向容器内数据目录。

下一步

• 运行 make env-security-check；
• 栈在 Docker 上：用 compose 文件重建 LightRAG 服务（向导结束时会提示 docker compose -f docker-compose.final.yml up -d --force-recreate lightrag）；
• 栈在宿主机上：重启 lightrag-server。

更广泛的部署指导见 DockerDeployment.md。

八、校验、审计与备份

这三条命令不走完整配置流程，但属于日常运维的一部分。

校验当前配置

make env-validate

validate_env_file（setup.sh）会报告：缺失的必填值、格式错误的认证配置、非法 URI（按 neo4j://、mongodb(+srv)://、rediss?://、http(s)://、bolt:// 分库种校验）、非法端口、SSL 开启但证书/私钥文件缺失、以及 Mongo 向量存储与部署模式不匹配等问题。相关分支均有回归测试，例如 tests/setup/test_validate.py 中“SSL 开启但文件缺失必须失败”的用例。

暴露前安全审计

make env-security-check

security_check_env_file（setup.sh）逐项检查：

• 未配置任何 API 保护（无 AUTH_ACCOUNTS 且无 LIGHTRAG_API_KEY），且 HOST 非回环地址时风险更高；
• AUTH_ACCOUNTS 格式错误、密码以 admin/pass 等可预测前缀开头；
• 启用账号认证但缺少 TOKEN_SECRET，或仍使用内置默认值；
• WHITELIST_PATHS 以 /api 前缀形式豁免了 API 路由；
• 敏感值中残留未解析的 ${...} 插值占位符；
• OPENSEARCH_PASSWORD 仍为内置默认值。

每条发现都会附带修复建议，退出码非 0。

单独备份

make env-backup

不调用任何配置流程，仅把 .env 备份为 .env.backup.YYYYMMDD_HHMMSS，若已生成 compose 文件则同时备份为 docker-compose.backup<时间戳>.yml（file_ops.sh）。

九、生成物语义

.env

向导把 .env 写到仓库根目录，它代表最近一次向导运行产出的当前运行时配置：

• 重跑向导会更新 .env；
• 已有值在后续运行中作为默认值复用；
• 应把 .env 视为“最近配置的这套工作流”的生效配置（LIGHTRAG_RUNTIME_TARGET=host 或 compose 二选一）；
• env-base / env-storage / env-server 在写盘前都会自动为已有 .env 创建带时间戳的备份。

.env 以 env.example 为基底生成——该文件头部注释明确说明：所有可配置环境变量都会以激活或注释状态出现在这个样例文件中，make env-* 用它生成最终的 .env。

docker-compose.final.yml

仅在以下情况创建或更新：你选择了向导托管的 Docker 服务，或既有向导生成的 compose 配置需要与新的 server 设置保持一致。任何 setup 流程在替换或删除既有生成文件前，都会先创建带时间戳的备份。

• 基线 docker-compose.yml 是项目通用的 compose 文件；生成的 docker-compose.final.yml 是向导托管输出，用 docker compose -f docker-compose.final.yml up -d 启动；
• MongoDB 存储走向导托管 Docker 路径时，使用 MongoDB Atlas Local 而非社区版，以在本地提供 Atlas Search / Vector Search 工作流；
• 宿主机上的 loopback 地址（localhost/127.0.0.1/0.0.0.0）在生成容器环境时会被自动改写为 host.docker.internal（normalize_loopback_uri_for_compose），避免容器内连接宿主机时“指环回自己”。

十、故障排查与高级注意事项

• 若 make env-storage 或 make env-server 提示 .env 缺失：先跑 make env-base；
• 重跑 env-base / env-storage / env-server 之前不必手动 make env-backup——这些流程自己会备份既有 .env，并在改动前备份生成的 compose 文件；
• 需要从当前内置模板完整重建向导托管的 compose 服务时，用 make env-base-rewrite 或 make env-storage-rewrite（即 --rewrite-compose，跳过“保留既有镜像/服务”的合并逻辑）；
• 在“宿主机模式”和“Docker 模式”之间切换时，重跑相应配置步骤即可，不要手工合并两套旧设置——向导通过 LIGHTRAG_RUNTIME_TARGET 标记当前目标运行时，切换后它会重写 .env；
• 若生成的栈包含本地 Milvus，运行 docker compose -f docker-compose.final.yml up -d 前确保 MINIO_ACCESS_KEY_ID 与 MINIO_SECRET_ACCESS_KEY 可用；
• 更深入的 Docker 部署细节见 DockerDeployment.md。

十一、典型命令序列

远程模型 + 本机服务

make env-base
lightrag-server

远程 LLM + 本地 Docker embedding/rerank

make env-base
docker compose -f docker-compose.final.yml up -d

基础配置后追加存储

make env-base
make env-storage
docker compose -f docker-compose.final.yml up -d

暴露前加安全与 SSL

make env-base
make env-storage
make env-server
make env-security-check
docker compose -f docker-compose.final.yml up -d

十二、小结

LightRAG 的交互式配置向导把“手写 .env”这件事收敛为三条正交流程（base / storage / server）加三条运维命令（validate / security-check / backup），每个流程只改动自己职责域内的变量、其余值原样保留，并在写盘前完成敏感字面量校验、Mongo 向量存储合规校验、认证配置校验和自动备份。整套实现集中在 scripts/setup/setup.sh 与 scripts/setup/lib/ 中，行为有 tests/setup/ 下十余个回归测试文件守护，因此按本文步骤操作时，可以预期向导的输出（.env + docker-compose.final.yml）与文档描述完全一致。