RAGFlow 文档解析卡死?从队列积压到 DNS 解析,一次完整的故障排查实录

前言

在使用 RAGFlow 构建 RAG 应用时，文档解析是整个流程的第一步。然而，不少用户会遇到一个令人头疼的问题：上传文档后，解析进度条卡在某个百分比（如 0.77%）纹丝不动，界面提示 “18 tasks are ahead in the queue”，但实际队列却空空如也。

本文将详细记录我近期处理的一起 RAGFlow 解析卡死问题的完整过程，涵盖从初步排查到根因定位、再到最终修复的全流程。如果你也遇到了类似问题，这篇文章或许能帮你节省大量时间。

一、问题现象

某天，我在虚拟机中通过 Docker Compose 部署的 RAGFlow 环境突然出现文档解析异常，具体表现为：

1. 界面提示：上传文档后，界面显示 18 tasks are ahead in the queue

2. 解析进度卡死：多个文档的解析进度分别卡在 0.77%、0.93%、0.08% 等数值

3. 队列名存实亡：进入 Redis 查看队列长度，XLEN rag_flow_svr_queue 返回 (integer) 0

4. 重启无效：多次重启 RAGFlow 服务后，问题依然存在

环境信息如下：

二、初步排查：资源与配置

2.1 检查系统资源

首先使用 docker stats 查看各容器的资源使用情况：

bash

CONTAINER ID    NAME                   CPU %    MEM USAGE / LIMIT    MEM %fcdef89cffd8    docker-ragflow-cpu-1   0.29%    4.358GiB / 15.62GiB  27.91%d004f9a7a2b7    docker-mysql-1         0.98%    384.6MiB / 15.62GiB  2.41%gb07b6eaad96    docker-redis-1         0.30%    3.816MiB / 15.62GiB  0.02%6f3e09ed9fd4    docker-es01-1          0.49%    4.206GiB / 7.519GiB  55.94%2744b96bd072    docker-minio-1         0.08%    178.2MiB / 15.62GiB  1.11%

所有容器的 CPU 和内存使用率均在健康范围内，排除资源瓶颈。

2.2 检查 Redis 队列状态

进入 Redis 容器检查队列和消费者组：

bash

dockerexec-it docker-redis-1 redis-cli -a infini_rag_flow127.0.0.1:6379> XLEN rag_flow_svr_queue(integer)0127.0.0.1:6379> XINFO GROUPS rag_flow_svr_queue(empty array)

队列长度为 0，消费者组不存在——这说明任务根本没有进入 Redis 队列，或者队列状态已经紊乱。

2.3 手动重建队列

尝试手动重建队列和消费者组：

bash

127.0.0.1:6379> DEL rag_flow_svr_queue127.0.0.1:6379> XGROUP DESTROY rag_flow_svr_queue rag_flow_svr_task_broker127.0.0.1:6379> XGROUP CREATE rag_flow_svr_queue rag_flow_svr_task_broker $ MKSTREAMOK

重启 RAGFlow 后重新提交文档，问题依旧。这说明问题不在队列本身，而在更上层。

三、深入排查：日志分析

3.1 查看 RAGFlow 实时日志

bash

docker logs -f docker-ragflow-cpu-1 2>&1|grep-i"error\|fail"

然而主日志中并未发现明显的错误信息。问题可能在任务执行器的专属日志中。

3.2 查看任务执行器日志

进入 RAGFlow 容器，查看 task_executor 的日志：

bash

dockerexec-it docker-ragflow-cpu-1 bashtail-f /ragflow/logs/task_executor_*.log |grep-i"redis\|error"

关键发现：日志中反复出现以下错误：

text

2026-04-15 18:23:24,560 WARNING 26 RedisDB.get_...-cancel got exception: Error -3 connecting to redis:6379. Temporary failure in name resolution.2026-04-15 19:06:23,576 INFO 37 Realtime synonym is disabled, since no redis connection.2026-04-15 19:00:34,678 WARNING 26 Failed to acquire Redis lock: Error -3 connecting to redis:6379. Temporary failure in name resolution.

根因浮出水面：RAGFlow 容器内部无法解析 redis 这个主机名，导致所有 Redis 操作失败！

3.3 验证 DNS 解析问题

在 RAGFlow 容器内测试网络连通性：

bash

dockerexec-it docker-ragflow-cpu-1 ping redisping: bad address 'redis'

结果证实了我们的判断——RAGFlow 容器无法将 redis 解析为 IP 地址。

四、根因分析

为什么会无法解析 redis 主机名？

回顾我们的环境配置：

• Redis 容器名：docker-redis-1

• RAGFlow 配置中的 Redis 主机名：默认值为 redis

在 Docker Compose 创建的默认网络中，容器间可以通过服务名进行通信。但我们的 Redis 服务名是 redis（在 docker-compose.yml 中定义），而容器名被手动指定为 docker-redis-1。

RAGFlow 默认配置使用 redis 作为主机名，理论上是正确的（服务名为 redis）。但由于某种原因（可能是网络配置或 Compose 版本差异），DNS 解析未能正常工作。

五、解决方案

方案一：为 Redis 容器添加网络别名（推荐）

这是最稳妥的方案，无需修改应用配置文件，只需在 docker-compose.yml 中为 Redis 服务添加一个网络别名。

操作步骤：

1. 编辑 docker-compose.yml：

bash

vim docker/docker-compose.yml

1. 找到 Redis 服务配置，添加 aliases（注意 YAML 缩进）：

yaml

services:redis:image: valkey/valkey:8container_name: docker-redis-1networks:default:aliases:- redis          # 添加此行，使 redis 主机名可解析command: redis-server --requirepass infini_rag_flowports:-"16379:6379"# ... 其他配置

1. 验证 YAML 语法：

bash

docker-compose config

1. 重启服务：

bash

docker-compose downdocker-compose up -d

1. 验证修复效果：

bash

# 测试 DNS 解析dockerexec-it docker-ragflow-cpu-1 ping-c2 redis# 观察日志是否还有报错docker logs -f docker-ragflow-cpu-1 2>&1|grep-i"name resolution"

执行后，RAGFlow 顺利连接 Redis，任务队列恢复正常，文档解析完成。

方案二：修改 RAGFlow 配置文件（备选）

如果方案一因某些原因无法实施，可以直接修改 RAGFlow 的 Redis 连接配置。

1. 编辑 conf/service_conf.yaml：

yaml

redis:host: docker-redis-1# 改为实际容器名port:6379password: infini_rag_flowdb:1

1. 强制重建容器使配置生效：

bash

docker-compose up -d --force-recreate ragflow

方案三：手动重建 Redis 队列（适用于队列状态异常）

如果仅仅是队列状态紊乱，可以执行以下命令重置：

bash

dockerexec-it docker-redis-1 redis-cli -a infini_rag_flow# 清空并重建DEL rag_flow_svr_queueXGROUP DESTROY rag_flow_svr_queue rag_flow_svr_task_brokerXGROUP CREATE rag_flow_svr_queue rag_flow_svr_task_broker $ MKSTREAM

六、常见踩坑点总结

在排查过程中，我还遇到了一些小问题，在此一并记录供参考：

七、排查命令速查表

为了方便日后快速定位，这里整理了一份常用命令清单：

八、总结与建议

8.1 问题总结

本次 RAGFlow 解析卡死的根本原因是：RAGFlow 容器内无法解析 Redis 主机名，导致任务执行器与 Redis 失联。虽然队列层面一切正常，但任务调度链路已经断裂，造成了“前端提示排队，后端队列为空”的诡异现象。

8.2 预防建议

1. 规范容器命名：尽量使用 Compose 服务名作为主机名，避免手动指定不一致的 container_name

2. 启用健康检查：在 docker-compose.yml 中为关键服务添加 healthcheck，便于及时发现异常

3. 定期查看日志：养成定期检查 task_executor 日志的习惯，很多问题在日志中早有端倪

4. 保持版本更新：RAGFlow 迭代较快，许多 Bug 在新版本中已被修复，建议定期升级

8.3 写在最后

排查技术问题就像破案，现象是线索，日志是证据。这次排查过程中，最关键的一步就是进入容器查看任务执行器的详细日志——正是这条日志中的 Temporary failure in name resolution 直接指向了根因。

希望这篇记录能帮助到遇到类似问题的朋友。如果你有其他排查经验或问题，欢迎在评论区交流讨论！