环境：K8s 命名空间 ragflow，镜像 infiniflow/ragflow:v0.27.0
入口：http://10.0.90.121:26052（NodePort → 容器内 Nginx）
时间：2026-08-24

1. 现象

删除主 Pod 后新 Pod 很快变为 1/1 Running，但外部接口不可用：

1
2
3
4
5
6
7
kubectl delete pod ragflow-56d494b667-znbkr -n ragflow
kubectl get pods -n ragflow -w
# ragflow-56d494b667-8nl8l   1/1     Running

curl -v 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，容易误判为「服务已正常」。

2. 定位过程

2.1 初步排查：调整 Nginx 缓冲区

操作： 调大 Nginx 的 large_client_header_buffers 参数，排除因请求头过大导致后端拒绝的问题。

结果： 调整后错误从 400 Bad Request 变为 502 Bad Gateway，说明 Nginx 已能转发请求，但后端服务未能正常响应。

2.2 502 出在 Nginx 上游，不是 NodePort 网络

容器内直连 API 端口失败：

kubectl exec -n ragflow ragflow-56d494b667-8nl8l – \

curl -sS -m 5 http://127.0.0.1:9380/v1/system/version

# curl: (7) Failed to connect to 127.0.0.1 port 9380

说明：

  • NodePort 26052 和容器内 Nginx（80）是通的
  • Nginx 反代的上游（默认 127.0.0.1:9380，即 RAGFlow API）没有进程在听
  • 对外 502 只是这个结果的表象

2.3进程列表：API / Admin / Task Executor 均未启动

ps aux 实际只有：

进程 状态
bash ./entrypoint.sh --enable-adminserver 在
nginx: master/worker 在
python3 rag/svr/sync_data_source.py 在（约 800MB RSS）
api/ragflow_server.py（9380） 无
Admin（9381） 无
task_executor 无

1/1 Ready 只表示容器主进程（entrypoint / Nginx 侧）还在，不表示 HTTP API 已就绪。该 Deployment 未按 9380 做 readiness 探测时会出现这种假健康。

2.4标准输出日志容易误导

kubectl logs 可见：

  • 版本 v0.27.0，库表初始化成功
  • Nginx、data sync 已启动
  • Infinity ragflow-infinity.ragflow.svc:23817 healthy
  • 打印了 Starting 1 task executor(s)，但进程列表中没有 executor
  • 停在 RAGFlow data sync is ready，没有 API 的 0.0.0.0:9380 监听日志

stdout 主要是 data_sync（PID 39）的日志，API 是否起来不能只看这一段。

2.5 手动拉起 API 正常

kubectl exec -n ragflow ragflow-56d494b667-8nl8l – \

sh -c ‘cd /ragflow && python3 api/ragflow_server.py’

结果：

  • 读到 /ragflow/conf/service_conf.yaml
  • MySQL：ragflow-mysql.ragflow.svc:3306 / 库 rag_flow
  • Infinity、MinIO、Redis 均指向集群内 Service
  • 打印 RAGFlow version: v0.27.0、http_port: 9380、MAX_CONTENT_LENGTH 等，启动链路通过

说明：依赖和配置足以支撑 API，问题不在「连不上 MySQL/Infinity」，而在 entrypoint 没有把 ragflow_server 拉起来（或拉起后立刻退出且未留在进程表中）。

3. 原因结论

直接原因

容器内 RAGFlow HTTP API（9380）未监听。
Nginx 已启动并对外提供 80，转发失败 → 502 Bad Gateway。

根因（已证实部分 + 推断部分）

已证实：

  1. 故障时只有 Nginx + sync_data_source.py，没有 ragflow_server。
  2. MySQL 初始化、Infinity 探活、手动执行 python3 api/ragflow_server.py 均成功，排除「配置写死 / 依赖全挂」作为 502 主因。
  3. entrypoint.sh --enable-adminserver 作为 PID 1 仍在，但未把 API / Admin / Task Executor 维持为常驻进程。

未在源码级钉死（entrypoint 脚本未完整核对）：

集群启动脚本在「启 Nginx、启 data sync、打印 Starting task executor」之后，未能成功常驻 ragflow_server（以及 admin、task_executor）。可能情况包括：

  • 后续进程启动失败后被吞掉，stdout 只剩 data_sync
  • 子进程退出，entrypoint 未 exec 到 API、也未重启
  • 资源压力（data_sync 已占用约 800MB）导致 API/executor 起不来或被杀（当时未用 dmesg / OOM 最终确认）

不是主因的项：

  • NodePort / 节点 IP 10.0.90.121:26052 网络
  • Load term.freq FAIL!（警告，手动启动同样出现）
  • SECRET_KEY 自动生成警告
  • user_default_llm.base_url: 'http://:80'（host 为空，会影响后续模型调用，不会单独导致 9380 不监听）

4. 处理与验证

临时：在容器内手动启动 API 后，9380 应开始监听，此时再访问：

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

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

注意：kubectl exec 里前台跑的 ragflow_server.py 会随 exec 会话结束而退出，不是持久方案。持久修复需要保证 Pod 启动时 entrypoint 真正拉起并守护：

  • api/ragflow_server.py（9380）
  • admin（若启用，9381）
  • task_executor

建议补充：

  1. 对 9380（或 /v1/system/version）做 readinessProbe，避免 Nginx-only 即 Ready。
  2. 查看 /ragflow/logs/ragflow_server.log、task_executor*.log 确认 entrypoint 侧失败原因。
  3. 核对 Deployment 的 command/args、内存 limit，以及官方 Helm/entrypoint 在 --enable-adminserver 下的启动顺序。

5. 一句话

Nginx 活着、API 没起来 → 502；依赖是好的，手动起 ragflow_server.py 正常；问题在容器 entrypoint 未把 9380 服务常驻拉起。