RAGFlow私有化部署常见问题与排障

发表于 2026/07/31

作者 handsomestwei

9 分钟阅读

RAGFlow私有化部署常见问题与排障

RAGFlow 私有化部署常见问题与排障

本文整理 RAGFlow 私有化 Docker 部署中的常见故障与处置步骤：文档解析卡死、Redis/MySQL 任务清理、task_executor 未启动、外接 BGE 向量服务、跨版本升级配置等。操作前请停服并备份；可接受清空业务数据时，优先 docker compose down -v 后按目标版本整套替换 docker/ 配置（见 [Upgrading RAGFlow](https://ragflow.io/docs/upgrade_ragflow)）。

一、跨版本升级要点
二、外接 Embedding 向量模型
三、典型现象与根因对照
四、Redis 队列清理
五、MySQL 卡死任务清理
六、删知识库与清库
七、验证 task_executor
八、解析恢复后的防再犯建议
九、浏览器语音与 HTTP 访问
十、相关 Issue / PR 索引
十一、参考链接

一、跨版本升级要点

官方要求升级时同时更新镜像与 docker/ 目录配置（docker-compose.yml、docker-compose-base.yml、.env、entrypoint.sh、service_conf.yaml.template），不能只改 RAGFLOW_IMAGE。参见 [Upgrading RAGFlow](https://ragflow.io/docs/upgrade_ragflow)、Issue #11950。

跨越版本	须关注
0.20.0	旧 Agent 不兼容，须重建工作流
0.22.0	仅 slim 镜像，无内置 embedding；须外接向量服务
0.25.0	数据库升级脚本、默认 MinIO 镜像、ES 9.x 等
0.26.0	Redis 队列改为 `te.0.common_queue`；模型 Provider 表迁移；`entrypoint.sh` 启动 executor 参数变更

从 v0.19 只换主镜像到 0.26 的典型后果：宿主机挂载的旧 entrypoint.sh 覆盖镜像内新脚本，task_executor.py 启动参数不兼容 → 进度卡在 0.01%、界面几乎无日志。须用目标 tag（如 v0.26.4）的整套 docker/ 文件，见 Issue #15372。

v0.26.4 ragflow-cpu 服务要点：

  
command:
  - --enable-adminserver
  - --init-model-provider-tables   # 首次从旧版升级或清库后可保留一次
volumes:
  - ./entrypoint.sh:/ragflow/entrypoint.sh   # 必须为与镜像同版本文件

勿使用 --disable-taskexecutor；勿再启用已废弃的独立 entrypoint_task_executor.sh 容器。

二、外接 Embedding 向量模型

自 v0.22.0 起 Docker 仅发 slim 镜像，不含 BGE/BCE 等内置权重。知识库与 Memory 均须配置外置 embedding。

2.1 直连 OpenAI-Compatible 服务（如自建 BGE-M3）

步骤	操作
1	Model Providers → OpenAI-API-Compatible
2	Base URL：向量服务根地址（多数版本 RAGFlow 会自行拼接 `/v1/embeddings`；若 404 再试是否在 base 中带 `/v1`）
3	API Key：按推理服务要求填写
4	添加 Embedding 模型，名称与上游 `model` 字段一致
5	知识库选用 `模型名@OpenAI-API-Compatible`

推理服务须提供 POST /v1/embeddings。从 RAGFlow 容器内 curl 验证可达后再解析文档。

2.2 经 One-API 网关（带鉴权）

环节	配置
RAGFlow → One-API	Base URL = One-API 地址；API Key = One-API 发放的 `sk-...`
One-API → BGE	Channel 指向上游 BGE 服务；Channel 内配置上游 Key 与模型映射

RAGFlow 不必须经 One-API；直连 BGE 更简单，网关适合统一鉴权与多模型路由。

2.3 embedding 阶段 OOM

日志出现 NPU/GPU out of memory、Error code: 424 时：减小 .env 中 EMBEDDING_BATCH_SIZE（如 4）、限制并发解析篇数、大文档拆分上传，并在向量服务侧限制 batch/并发。

三、典型现象与根因对照

现象	常见根因
解析在 embedding 阶段失败，日志 OOM / 424	外接向量服务资源不足；chunk 多、并发高
进度 0.01%～1% 不动，「0 tasks are ahead in the queue」	task_executor 未消费队列（未启动、参数错误、僵死）
界面几乎无解析日志	须在容器日志排查，不能只看 Web 详情
Redis / MySQL 已清理仍卡住	executor 未正确启动，或 Redis consumer group 未按版本重建
删文档 / 删知识库无效	UI 取消未必清 Redis；旧版删库未必清队列，见 PR #12799

四、Redis 队列清理

文档：FAQs - xxx tasks are ahead in the queue

操作前：docker compose -f docker/docker-compose.yml stop（清数据用 down -v）。

v0.26.0 及以后

  
docker exec -it ragflow-redis /bin/bash
redis-cli -a <REDIS_PASSWORD>
select 1
XGROUP DESTROY te.0.common_queue te.0.common_task_broker
XGROUP CREATE te.0.common_queue te.0.common_task_broker $ MKSTREAM
exit

v0.26 之前

select 1
XGROUP DESTROY rag_flow_svr_queue rag_flow_svr_task_broker
XGROUP CREATE rag_flow_svr_queue rag_flow_svr_task_broker $ MKSTREAM

不确定版本：select 1 后 KEYS *queue*。CREATE 失败时 FAQ 允许 FLUSHDB（慎用）。清理后 重启 RAGFlow 主容器。

五、MySQL 卡死任务清理

官方 FAQ 仅写 Redis + 重启；下列 SQL 整理自 Issue #8739，须与第四节 Redis 清理配合。

docker compose -f docker/docker-compose.yml stop

  
SELECT id, name, progress, run FROM document WHERE progress < 1 OR run NOT IN ('0','1');
SELECT id, doc_id, progress FROM task WHERE progress < 1;

DELETE FROM task WHERE progress < 1;
UPDATE document SET progress = 0, run = '2' WHERE progress < 1;

  
docker exec -it <mysql容器名> mysql -uroot -p<MYSQL_PASSWORD> rag_flow

单条 GraphRAG 任务：见 Issue #11583。

六、删知识库与清库

方式	效果
删除整个知识库	删文档与 MinIO 等；不保证清 Redis 队列
v0.26+（PR #12799）	删库前会尝试 cancel 任务
文档 Running	界面可能无法删库，须先停任务或走第四、五节
数据可丢弃	`docker compose down -v` + 目标版本整套 `docker/` 重装

七、验证 task_executor

Admin（v0.22+）：http://<地址>/admin（默认 admin@ragflow.io / admin）→ Service status → task_executor。须在 compose 中启用 --enable-adminserver，见 Admin UI。

命令行：

  
docker logs <ragflow-cpu容器名> 2>&1 | grep -iE "task.executor|Starting.*executor|unrecognized"
docker exec <ragflow-cpu容器名> ps aux | grep task_executor

期望进程含：python3 rag/svr/task_executor.py -i <host>_<id> -t common。出现 unrecognized arguments 即 entrypoint.sh 版本与镜像不匹配。

八、解析恢复后的防再犯建议

限制并发解析；.env 设置 EMBEDDING_BATCH_SIZE=4、DOC_BULK_SIZE=2
暂时关闭 RAPTOR、知识图谱、为 chunk 自动生成问题等
更换 embedding 模型后须 重新解析 知识库
升级时 镜像 + docker 配置 同步更新

九、浏览器语音与 HTTP 访问

自 v0.23.0 起 Agent 支持语音。通过 http://<IP>:<端口> 访问时，浏览器可能拒绝麦克风（非 Secure Context）。

现象	原因
语音不可用	`getUserMedia` 要求 `https://` 或 `http://localhost`

临时（Chrome/Edge）：chrome://flags/#unsafely-treat-insecure-origin-as-secure，填入如 http://192.168.1.100:9380，重启浏览器。

生产：使用 HTTPS 反向代理（Nginx / Caddy + 证书）。

十、相关 Issue / PR 索引

主题	链接
MySQL + Redis 逐步清理	Issue #8739
Task Executor 僵死	Issue #8466
解析卡在 1% 以内	Issue #9466
删知识库后队列仍堵	Issue #5355
删库前 cancel 任务	PR #12799
entrypoint / executor 参数	Issue #15372
升级须换 docker 配置	Issue #11950
GraphRAG 单任务删除	Issue #11583
清空处理队列	Issue #5537
v0.22+ 外接 embedding	Issue #11226
官方 FAQ	FAQs \| RAGFlow
官方升级	Upgrading \| RAGFlow

十一、参考链接

FAQs（含 Redis 队列清理）
[Upgrading RAGFlow](https://ragflow.io/docs/upgrade_ragflow)
Admin UI
Admin Service
Supported models

界面与队列名随版本变化，请以当前部署版本与官方文档为准。

AI, RAG

AI RAG RAGFlow 运维排障

本文由作者按照 CC BY 4.0 进行授权