KG-RAG容器化Debug总结

第一阶段：网络与基础环境问题

1. 镜像下载超时 (TLS handshake timeout)

• 现象：docker-compose up 时一直卡在 Downloading，最后报错超时。
• 原因：Docker Hub 服务器在国外，国内网络直连困难。
• 解决： -- 配置国内镜像加速源。在 Docker Desktop 的 Settings -> Docker Engine 中添加阿里云、网易等 registry-mirrors。 -- 最终通过 Docker Desktop 设置手动代理 (Proxies)，指向本地 V** 端口解决。在 Settings -> Proxies 中删除遗留的代理地址，改为 System proxy 或 Manual without proxy。

2. 代理连接被拒绝 (target machine actively refused it)

• 现象：配置了代理后，报错连不上 127.0.0.1:7890。
• 原因：Docker 盲目使用了默认端口 7890，但你使用的 V** 软件实际监听端口并非 7890。
• 解决：通过 Windows 代理设置查出真实端口，并在 Docker Desktop 中修改为正确端口。

3. 环境变量未读取 (variable is not set)

• 现象：警告 The "NEO4J_USER" variable is not set。
• 原因：docker-compose 默认读取行为不稳定，或者 Powershell 环境未加载。
• 解决：在运行命令时显式指定：docker-compose --env-file .env up ...，并在 yaml 文件中显式添加 env_file: - .env。

4. 构建上下文过大（传输慢）

• 现象：构建日志显示 transferring context: 5.85GB (75.6s)。
• 原因：Docker 在构建前会将当前目录下所有内容打包。项目里有一个 test 文件夹（5.53GB），.dockerignore 里没有忽略它，导致 Docker 试图搬运这个巨大的文件堆。
• 解决方法： -- 识别垃圾文件，发现是 test 目录。 -- 修改忽略规则：在 .dockerignore 文件中添加 test。 -- 概念理解：明白了通过 Volume 挂载（映射）大文件，而不是打包进镜像。

5. CUDA 版本不匹配（No matching distribution）

• 现象：报错 No matching distribution found for torch==2.5.1+cu121。
• 原因：版本地址“对不上号”。requirements.txt 里写着要 torch==2.5.1+cu121 (CUDA 12.1)。Dockerfile 里的下载路径却指向了 whl/cu118 (CUDA 11.8)。程序去 11.8 的仓库里自然找不到 12.1 的包。
• 解决方法：统一版本。确认本机支持 CUDA 12.1（因为本地跑通过），将 Dockerfile 里的源地址改为 whl/cu121。

第二阶段：Python 依赖与版本冲突

6. 包版本不兼容 (Could not find a version...)

• 现象：先报错 No matching distribution found for networkx==3.6.1，再报错 No matching distribution found for numpy==2.4.0。
• 原因：环境代沟。本地用的是 Python 3.12（最新版），生成的 requirements.txt 里的包版本太新；而 Docker 基础镜像最初写的是 3.10（老版），不支持这些新包。
• 解决：升级 Docker 环境。将 Dockerfile 第一行改为 FROM python:3.12-slim，让容器环境与开发环境对齐。

7. 异步循环冲突 (ValueError: Can't patch loop... uvloop)

• 现象：Python 3.12 容器启动后，app.py 报错崩溃。
• 原因：强强冲突。Docker 版 Python 3.12 默认启用了高性能的 C 语言循环 uvloop，但我们的代码依赖 nest_asyncio 来给标准循环打补丁，两者不兼容。
• 解决：卸载 uvloop。在 Dockerfile 中增加 RUN pip uninstall -y uvloop || true，强迫容器使用 Python 标准库的 asyncio 循环。

第三阶段：服务配置与连接问题

8. 变量名不匹配 (NEO4J_USER vs USERNAME)

• 现象：Python 程序连不上数据库，认证失败。
• 原因：命名习惯冲突。Python 代码里写的是 NEO4J_USER，但 .env 文件里配的是 NEO4J_USERNAME。
• 解决：Docker 内部映射。在 docker-compose.yml 中使用 - NEO4J_USER=${NEO4J_USERNAME}，充当翻译官，既不改代码也不改配置文件。

9. Neo4j 容器无限重启 (Unrecognized setting)

• 现象：数据库容器状态一直是 Restarting，报错配置项无法识别。
• 原因：变量污染。我们将整个 .env 文件传给了 Neo4j 容器，其中包含 NEO4J_USERNAME。Neo4j 误以为这是数据库配置参数，发现不认识后报错退出。
• 解决：精准传参。在 docker-compose.yml 的 neo4j-db 服务中删除 env_file，只保留需要的 NEO4J_AUTH 环境变量。

10. 数据库不存在 (Database does not exist)

• 现象：导入数据脚本报错，找不到 gb500732013 数据库。
• 原因：版本差异。Docker 里的 Neo4j 社区版不支持创建自定义名称的数据库，只能用默认名 neo4j。
• 解决：入乡随俗。修改 .env 和 import_graph.py，将目标数据库名统一改为 neo4j。

11. 容器内数据为空

• 现象：容器启动后，Web 界面能打开，但图谱检索为空。
• 原因：隔离性。Docker 里的数据库是全新的，宿主机的数据不会自动飞进去。
• 解决：容器内执行。使用 docker exec -it archrag-core python import_graph.py 在容器内部重新运行了一次数据导入。