TypeError: Cannot read properties of undefined (reading ‘chats’)`.

快速结论：该报错发生在 RAGFlow 通过 Docker Compose 启动时，Infinity 冷启动重放元数据超过 120 秒导致主 API 服务初始化失败。优先排查方向是 docker/entrypoint.sh 中主 Web 服务循环未加 || true 保护，被 set -e 静默终止且不会自动重启。

适用环境：RAGFlow v0.27.0-25-g994148278、Infinity 0.7.3（单节点 standalone）、Docker Compose CPU profile、Linux 主机（16 vCPU）。Infinity 数据卷已存在大量历史元数据（约几 GB），冷启动重放需约 150 秒。

最快修复方案：Issue 讨论中确认的修复方案是在 entrypoint.sh 中给主 Web 服务器和 admin server 的 while true 循环加上 || true，防止 set -e 在子 shell 遇到非零退出码时终止整个循环；同时建议测试 PR #17196（为 Infinity 连接初始化加入指数退避重试）来替代固定的 120 秒超时。但该 PR 尚未合并，属于可优先尝试的解决方向。

注意事项：上述补丁来自 Issue 评论中的分析和建议，属于已确认根因后的推荐修复方式，但尚未在 Issue 中明确标注已合并或已验证。即使延长 Infinity 超时时间，若首次启动仍失败，循环仍会静默退出，因此两个修复需要同时进行。

问题场景

用户使用 Docker Compose 部署 RAGFlow（CPU 版本），在 Infinity 数据卷已有大量持久化元数据的情况下执行 docker compose up -d。由于 Infinity 冷启动需要重放约 150 秒的元数据，超过 RAGFlow 预设的 120 秒健康检查超时，导致主 API 服务（api/ragflow_server.py）初始化失败。与此同时，admin server、task executor、data sync 均能自动恢复，但主 Web 服务无法自动重启，表现为前端（nginx）正常返回 200，但后端 9380 端口无监听、连接被拒绝。

报错原文

2026-08-20 11:36:29,019 WARNING  57 (2008, 'Infinity is initing'). Waiting Infinity infinity:23817 to be healthy.
ERROR:root:Infinity infinity:23817 is unhealthy in 120s.
Start RAGFlow server...
Traceback (most recent call last):
  File "/ragflow/api/ragflow_server.py", line 36, in <module>
    from api.apps import app
  File "/ragflow/api/apps/__init__.py", line 40, in <module>
    settings.init_settings()
  File "/ragflow/common/settings.py", line 404, in init_settings
    docStoreConn = rag.utils.infinity_conn.InfinityConnection()
  File "/ragflow/common/doc_store/infinity_conn_pool.py", line 74, in __init__
    raise Exception(msg)
Exception: Infinity infinity:23817 is unhealthy in 120s.

原因分析

该问题由两个独立缺陷叠加导致，已获 Issue 确认：

原因一（已确认）：docker/entrypoint.sh 第 3 行设置了 set -e，而主 Web 服务器在 while true; do ... done & 后台子 shell 中运行。当 api/ragflow_server.py 以非零退出码结束时，set -e 会直接终止整个子 shell，导致死循环无法回到下次重试。相比之下，task executor 和 data sync 使用了 & + wait 模式，前台 wait 回收子进程后循环仍能继续。

原因二（已确认）：common/doc_store/infinity_conn_pool.py 中硬编码了 24 次 × 5 秒 = 120 秒的健康检查等待，超时后直接抛异常，且没有环境变量覆盖。对于大型元数据冷启动场景（重放超过 120 秒），连接必然失败。

环境排查

RAGFlow 版本：v0.27.0-25-g994148278（commit 994148278）
Docker 镜像：infiniflow/ragflow-cpu（Docker Compose 部署）
Infinity 版本：0.7.3（release 2026-08-06，commit d755c5a），单节点 standalone
部署方式：docker compose up -d（CPU profile）
主机环境：16 vCPU，内存充足；仅涉及 infinity 和 ragflow 两个容器
Infinity 数据卷：存在大量历史 META 条目，冷启动重放约 2.5 分钟

解决步骤

确认是否存在已合并或开放的 PR 修复了 entrypoint.sh 中的 || true 问题；Issue 评论确认当时没有合并或开放的 PR。
手动修改 docker/entrypoint.sh 中主 Web 服务器循环（约第 294–299 行），在启动命令后添加 || true，确保 Python 服务退出后子 shell 不因 set -e 被终止，循环继续执行 sleep 后重试。同理处理 admin server 循环（约第 271–276 行）。
针对 Infinity 120 秒硬编码超时，测试 PR #17196（fix(doc_store): retry transient connection errors in pool init），该 PR 将固定 for _ in range(24) 改为指数退避（MAX_RETRIES = 8，基准 5 秒，上限 60 秒，最长约 165 秒），并增加单次尝试日志。该 PR 尚未合并，需自行 cherry-pick 或补齐后验证。
重新构建镜像或使用修改后的 entrypoint.sh 启动容器，验证主 API 服务在 Infinity 冷启动超过 120 秒时仍能自动恢复。

验证方法

修复后，在 Infinity 冷启动超过 120 秒的情况下启动容器，观察日志中出现多次 Attempt to start RAGFlow python server... 标记，且最终能在 Infinity 就绪后成功启动；同时验证 curl http://127.0.0.1:9380 不再返回 000 连接拒绝，且容器内存在主 Web 服务器的循环包装进程及对应的 Python 进程，前端 80 端口与后端 9380 端口均正常响应。