***环境***：K8s 命名空间 ragflow，镜像 infiniflow/ragflow:v0.27.0

***入口***：http://10.0.90.121:26052（NodePort → 容器内 Nginx 1.31.3）

***时间***：2026-08-24 ～ 2026-08-25

***结果***：API 502 与文档解析卡住均已恢复

—

## 1. 问题现象

连续出现两件表面不同、根因相同的故障。

### 1.1 接口 502

删除主 Pod 后新 Pod 很快变为 1/1 Running，但：

curl http://10.0.90.121:26052/api/v1/system/version

HTTP/1.1 502 Bad Gateway

Server: nginx/1.31.3

MySQL / Redis / MinIO / Infinity 均为 Running，容易误判为「服务已正常」。

1.2 知识库解析卡住

创建知识库、解析文档时，进度长期停在：

0 tasks are ahead in the queue…

手动把 API 拉起来后，建库/上传可用，解析仍不动。

2. 定位过程

2.1 502 出在 Nginx 上游，不是 NodePort

容器内直连 API 失败：

curl http://127.0.0.1:9380/v1/system/version

# Failed to connect to 127.0.0.1 port 9380

NodePort 和 Nginx（80）通；反代目标 9380 无人监听。

2.2 进程残缺

ps aux 实际只有：

进程 作用 当时状态
entrypoint.sh --enable-adminserver 启动脚本 在
nginx 反代 80 在
sync_data_source.py 数据源同步 在（约 800MB）
ragflow_server.py（9380） HTTP API 无
Admin（9381） 管理端 无
task_executor.py 解析队列消费者 无

1/1 Ready 只表示容器主进程还在，不表示 API / 解析 worker 已就绪。

kubectl logs 显示：库表初始化成功、Infinity healthy、Nginx 与 data sync 已启动，并打印 Starting 1 task executor(s)，但进程表中没有 executor；日志停在 RAGFlow data sync is ready，没有 0.0.0.0:9380。

2.3 依赖与配置不是 502 主因

手动执行：

cd /ragflow && python3 api/ragflow_server.py

可正常读 service_conf.yaml、连 MySQL（ragflow-mysql.ragflow.svc:3306）、Infinity，并监听 9380。
说明 库和配置足以支撑 API，问题在 entrypoint 未把 API / executor 常驻拉起。

2.4 解析卡住是缺消费者

手动只起了 ragflow_server.py 后：

  • API 可建库、提交解析任务
  • task_executor.py 仍不存在
  • UI 文案「前面 0 个任务」只表示队列前方为空，不是已在解析

补起 executor 后，进程先处于加载（高 CPU、约 650MB），/ragflow/logs 里一度没有 task_executor*.log（日志尚未落盘或只打在 exec 终端）。待 worker 真正 ready，并 取消后重新点解析，文档开始处理。

3. 原因结论

直接原因

官方镜像是 同容器多进程：Nginx + API(9380) + task_executor +（可选）admin。

本次 entrypoint.sh --enable-adminserver 只稳定拉起了 Nginx + sync_data_source.py，没有把 ragflow_server / task_executor 维持为常驻进程。

故障 机制
502 Nginx 活着，9380 未监听
解析卡住 API 把任务入队，没有 consumer 取任务

根因分层

已证实：

  1. 故障时无 API、无 executor。
  2. MySQL 初始化、Infinity 探活、手动起 ragflow_server.py 成功。
  3. 补起 task_executor.py 并重新解析后恢复。

未在源码级钉死：

entrypoint 在「启 Nginx、启 data sync、打印 Starting task executor」之后，未能成功常驻后续 Python 服务。可能包括：子进程启动失败被吞、未 exec 到 API、资源压力导致秒退等。持久方案仍应修启动命令/脚本，而不是长期 kubectl exec。

不是主因：

  • NodePort / 节点网络
  • Load term.freq FAIL!（警告，手动启动同样出现）
  • SECRET_KEY 自动生成警告
  • user_default_llm.base_url: 'http://:80'（host 为空，会影响后续 embedding，不是本次 502 / 「队列为 0」的直接原因，建议后续改掉）

4. 处理过程

  1. 容器内手动启动 API：python3 api/ragflow_server.py → 9380 可访问，502 消失。
  2. 文档解析仍卡住 → 确认 ps 中无 task_executor。
  3. 手动启动：python3 rag/svr/task_executor.py（进程在、初期无 log 文件属正常）。
  4. 待 worker 起来后，重新触发解析 → 恢复。

注意：kubectl exec 前台进程随会话/Pod 结束而退出，不是持久方案。

5. 建议（持久化）

  1. 保证 Pod 启动时 entrypoint 真正拉起并守护：
    • api/ragflow_server.py（9380）
    • rag/svr/task_executor.py（解析）
    • 若启用 --enable-adminserver，还有 9381
  2. 对 9380（如 /v1/system/version）加 readinessProbe，避免 Nginx-only 即 Ready。
  3. 解析卡住时先 ps 看有没有 task_executor，再查 /ragflow/logs。
  4. 旧解析任务在 worker 晚于任务提交时启动时，通常需要 取消后重新解析。
  5. 修正默认 embedding 的 base_url: 'http://:80'，避免后续切到向量化阶段再失败。
  6. 关注内存：data_sync ≈ 800MB，API ≈ 1.2GB，executor ≈ 650MB，注意 Limit / OOM。

6. 一句话

entrypoint 只起了 Nginx 和数据同步，没常驻 API 和解析 worker。
Nginx 无上游 → 502；API 无消费者 → 解析永远停在 0 tasks are ahead in the queue...。手动拉起两个 Python 进程后恢复，生产上需要把启动脚本和就绪探针修好。