LightRAG 怎么在 Apple Silicon Mac 上用 Apple container 运行 Postgres、Neo4j、Milvus 与 API 服务

LightRAG 怎么在 Apple Silicon Mac 上用 Apple container 运行 Postgres、Neo4j、Milvus 与 API 服务

【免费下载链接】LightRAG[EMNLP2025] LightRAG: Simple and Fast Retrieval-Augmented Generation项目地址: https://gitcode.com/GitHub_Trending/li/LightRAG

在 Apple Silicon Mac 上想跑一套和 Docker Compose 类似的 LightRAG 生产级存储栈——PostgreSQL、Neo4j、Milvus（含 etcd 与 MinIO 两个 sidecar）再加上 LightRAG API 服务，但不想装 Docker Desktop——Apple 官方原生的containerCLI 是可行路径。仓库提供了scripts/setup/apple-container.sh，它在这台机器上一次性拉起全部容器，并以 CPU 模式运行（LLM 与 embedding 走普通出站 HTTPS 调用，例如 OpenAI API，栈里没有 GPU、没有 vLLM）。

这套方案要求macOS 26 (Tahoe) 或更新版本的 Apple Silicon 机器：容器间网络与container network命令在 macOS 26 之前不存在，脚本在旧系统上会直接拒绝运行。本文按仓库文档 docs/AppleContainerSetup.md 的操作顺序展开。

准备条件

从仓库根目录开始，下面所有命令都在该目录下执行：

git clone https://github.com/HKUDS/LightRAG.git cd LightRAG

逐项确认以下前提：

1. 安装并启动containerCLI。从 Applecontainer的签名发行版安装，然后启动一次系统（提示时接受默认 kernel 安装）：

   container system start

2. Bash 4 或更新。macOS 自带 Bash 3.2，不满足脚本要求（脚本开头会检查BASH_VERSINFO并直接报错退出）。用 Homebrew 装一个现代 bash 并显式用它执行脚本：

   brew install bash bash scripts/setup/apple-container.sh up

3. 准备好.env文件，写入 LLM/embedding 供应商与 API key。没有现成的就从模板复制：

   cp env.example .env # 设置 LLM_BINDING / LLM_MODEL / LLM_BINDING_API_KEY 和 EMBEDDING_* 各键

   env.example 中默认的示例值是LLM_BINDING=openai、LLM_MODEL=gpt-5.4-mini、LLM_BINDING_API_KEY=your_api_key，以及EMBEDDING_BINDING=openai、EMBEDDING_MODEL=text-embedding-3-large、EMBEDDING_DIM=3072。这里只需改 LLM 和 embedding 两组配置（例如在LLM_BINDING_API_KEY和EMBEDDING_BINDING_API_KEY两处都填同一个 OpenAI key），存储后端相关变量保持原样——脚本会覆盖它们指向容器里的 Postgres / Neo4j / Milvus。不要从env.docker-compose-full起步，那个文件是为 GPU Docker 栈预配置的。也可以跑make env-base交互式生成.env。

全程不需要sudo。

启动整套存储栈

最短主路径就是一条命令：

# 启动整套栈（数据库 + LightRAG server） bash scripts/setup/apple-container.sh up

仓库还给了等价且会自动解析 bash 4+ 解释器的make目标（见 Makefile）：make apple-up、make apple-down、make apple-status、make apple-logs SVC=lightrag、make apple-restart SVC=<service>、make apple-pull。脚本参数通过SETUP_OPTS传递，例如make apple-up SETUP_OPTS=--no-lightrag或make apple-down SETUP_OPTS=--purge。

up会依次完成：按依赖顺序创建网络与各容器、等待健康检查（脚本用PORT_HEX的/proc/net/tcp探测代替 Compose 的 healthcheck）、通过container inspect发现每个服务在共享网络lightrag上分配到的 IP 并据此连线（Applecontainer1.0.0 不支持容器间服务名 DNS），最后为容器化 LightRAG server 生成.apple-container.env。

up的输出里会打印出各服务地址，其中包含 Neo4j Browser（:7474）和 MinIO console（:9001）的容器 IP 地址——host 可以直接访问容器子网。之后要找回某个 IP，重跑一次幂等的up或container inspect <service>即可。

如果只想起数据库、LightRAG server 由自己在 host 上运行，用可选分支：

bash scripts/setup/apple-container.sh up --no-lightrag

确认服务真的起来了

栈起来后的检查方式：

# 查看运行状态 bash scripts/setup/apple-container.sh status # 跟踪某个服务的日志 bash scripts/setup/apple-container.sh logs lightrag --follow

浏览器访问两个本地入口：

• LightRAG WebUI：http://127.0.0.1:9621/webui
• LightRAG 健康检查：http://127.0.0.1:9621/health

整套栈里只有 LightRAG server 发布 host 端口127.0.0.1:9621；Postgres（:5432）、Neo4j（:7687）、Milvus（:19530）及 etcd/MinIO 都不发布到 host，所以不会和 host 上已占用的5432冲突。容器名统一带lightrag-前缀（如lightrag-postgres），脚本不会碰到或复用其他项目的同名容器。

栈的结构如下（文档示意）：

host (macOS 26, Apple Silicon) └─ 127.0.0.1:9621 ──▶ [lightrag] ──┐ (--network lightrag) ├─▶ postgres :5432 (volume lightrag_pg) ├─▶ neo4j :7687 (volume lightrag_neo4j) └─▶ milvus :19530 (volume lightrag_milvus) ├─▶ milvus-etcd :2379 (volume lightrag_etcd) └─▶ milvus-minio :9000 (volume lightrag_minio) [lightrag] ──── outbound HTTPS ────▶ api.openai.com

栈内各服务用的镜像与配置来源

各服务镜像（均验证发布了linux/arm64manifest）：

两处相对docker-compose-full.yml/ 模板的刻意偏差，理解了就不会怀疑是漏配：

• Postgres用pgvector/pgvector:pg18而不是模板里的gzdaniel/postgres-for-rag:pg18-age-pgvector。两者都发布 arm64 manifest，这不是架构约束——模板镜像附加的 Apache AGE 图扩展在这里用不上：图存储是 Neo4j、向量存储是 Milvus，Postgres 只承担PGKVStorage+PGDocStatusStorage。
• Milvus用 CPU 标签milvusdb/milvus:v2.6.11，不用…-gpu标签，后者是 amd64 + CUDA，跑不了 Apple Silicon。

.env本身只读不改：脚本复制它生成 git-ignored 的.apple-container.env（权限600），只覆盖存储选择与连接端点：

LIGHTRAG_KV_STORAGE=PGKVStorage LIGHTRAG_DOC_STATUS_STORAGE=PGDocStatusStorage LIGHTRAG_GRAPH_STORAGE=Neo4JStorage LIGHTRAG_VECTOR_STORAGE=MilvusVectorDBStorage POSTGRES_HOST=<postgres 容器 IP> NEO4J_URI=neo4j://<neo4j 容器 IP>:7687 MILVUS_URI=http://<milvus 容器 IP>:19530 MILVUS_DB_NAME=lightrag

其中三个<...>是脚本在up时按实际发现的容器 IP 填入的，不需要你手工编辑。LLM/embedding 配置（LLM_BINDING、EMBEDDING_BINDING、API key、模型名、EMBEDDING_DIM等）原样继承，务必在入库文档或查询之前确认.env里是真实 key。

数据库凭据的优先级是shell 变量 →.env中的值 → 开发默认值，常改项如下（均可选）：

信任边界注意：这是本地单人开发栈。数据库容器虽不发布 host 端口，但在 vmnet IP 上以默认开发凭据可达——不要部署在共享/多用户机器上；若他人能路由到容器子网，覆盖POSTGRES_PASSWORD/NEO4J_PASSWORD/MINIO_SECRET_ACCESS_KEY。

数据持久化与常见故障

所有数据都在命名卷里：lightrag_pg、lightrag_neo4j、lightrag_milvus、lightrag_etcd、lightrag_minio、lightrag_lightrag。容器名与卷名都从LIGHTRAG_AC_PREFIX派生命名空间，所以用不同前缀再起的第二套栈有自己的容器和自己的存储。down只删容器、保留卷，之后的up会恢复数据；只有down --purge会删除卷（连同.apple-container.env）。

排查时按现象对号：

• bind(...): Address already in use——host 上已有进程占用9621（例如 host 上的lightrag-server），停掉后重试。数据库端口不发布，host 上5432的 Postgres 不受影响。
• 单独restart某个数据库后其 IP 变了——栈在up时按 IP 连线，IP 变化会导致依赖方失连，down后再up重新连线。
• Milvus 或 Neo4j 被杀 / 很慢——两者吃内存，调高LIGHTRAG_AC_MEM_HEAVY（例如8G）。
• /health是绿的，但入库或查询失败——栈本身没问题，是 LLM/embedding 调用失败：确认LLM_BINDING_API_KEY和EMBEDDING_BINDING_API_KEY两处都填了真实 key，供应商有配额/余额（OpenAI 欠费时返回429 insufficient_quota）。logs lightrag能看到具体 HTTP 错误。
• Rerank is enabled but no rerank model is configured——这套 CPU 栈不带本地 reranker，检索仍然可用；想消掉这个提示，要么配置托管 reranker（RERANK_BINDING+RERANK_MODEL+ key），要么在查询参数里传enable_rerank=false。
• 想看某个服务内部：bash scripts/setup/apple-container.sh logs <service>或container exec <service> sh。

停止与清理

# 停止并删除容器（保留数据） bash scripts/setup/apple-container.sh down # 停止、删除容器并删掉全部存储数据 bash scripts/setup/apple-container.sh down --purge

down --purge会删除上面全部命名卷，数据不可恢复，执行前确认这确实是想要的终态。网络可选删除：

container network delete lightrag

至此，Postgres、Neo4j、Milvus 与 LightRAG API 服务已在 Applecontainer上完整跑通：http://127.0.0.1:9621/webui可以进入 WebUI 做入库和查询，/health用于日常探活，数据落在命名卷里、跨down/up保留。若你的目标其实是 Docker/Podman 部署路径，参见 docs/DockerDeployment.md。

【免费下载链接】LightRAG[EMNLP2025] LightRAG: Simple and Fast Retrieval-Augmented Generation项目地址: https://gitcode.com/GitHub_Trending/li/LightRAG