文章

RAGFlow国内源最小部署说明

发表于
Preview Image
作者 handsomestwei
15 分钟阅读
RAGFlow国内源最小部署说明

RAGFlow 国内源最小部署说明

面向国内网络的 RAGFlow Docker Compose 本地/内网最小部署：默认拓扑为 DOC_ENGINE=elasticsearch + DEVICE=cpu，镜像与文档对齐 v0.26.4。文中给出华为云 SWR / ddn-k8s 镜像替换、必改配置、端口冲突、启动验证、可选组件与常见故障速查。

参考与延伸阅读：

目录

一、宿主机前提条件

项目要求说明
CPU≥ 4 核知识图谱建议更高
内存≥ 16 GB知识图谱建议 32GB+
磁盘≥ 50 GB另算镜像与数据卷
Docker≥ 24.0.0 
Docker Compose≥ v2.26.1 
架构x86_64 / amd64官方镜像不提供 ARM64
vm.max_map_count≥ 262144使用 Elasticsearch 时必须（WSL2/Linux）
gVisor可选仅启用 Sandbox 时需要

Linux / WSL2：

1
2
3

sudo sysctl -w vm.max_map_count=262144
# 永久生效：在 /etc/sysctl.conf 增加
# vm.max_map_count=262144

二、最小部署组件与国内镜像

默认 COMPOSE_PROFILES=elasticsearch,cpu，只需 5 个镜像：

#组件作用Profile官方镜像（改前）国内华为镜像（改后）
1RAGFlow 主服务Web UI + API + 任务执行cpuinfiniflow/ragflow:v0.26.4swr.cn-north-4.myhuaweicloud.com/infiniflow/ragflow:v0.26.4
2MySQL 8.0元数据、用户、知识库配置始终启动mysql:8.0.39swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/mysql:8.0.39
3MinIO上传文件 / 对象存储始终启动pgsty/minio:RELEASE.2026-03-25T00-00-00Zswr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/pgsty/minio:RELEASE.2026-03-25T00-00-00Z
4Redis (Valkey)缓存、队列、Embedding 缓存始终启动valkey/valkey:8swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/valkey/valkey:8
5Elasticsearch向量检索 / 文档索引 / 知识图谱存储elasticsearchelasticsearch:8.11.3swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.elastic.co/elasticsearch/elasticsearch:8.11.3

2.1 一键拉取

1
2
3
4
5

docker pull swr.cn-north-4.myhuaweicloud.com/infiniflow/ragflow:v0.26.4
docker pull swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/mysql:8.0.39
docker pull swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/pgsty/minio:RELEASE.2026-03-25T00-00-00Z
docker pull swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/valkey/valkey:8
docker pull swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.elastic.co/elasticsearch/elasticsearch:8.11.3

或在 docker/ 目录：

1
2

cd docker
docker compose -f docker-compose.yml pull

2.2 最小部署不需要拉

镜像 / 服务原因
TEI未启用 tei-cpu / tei-gpu
DeepDoc 独立服务未启用 deepdoc；默认主容器内联 ONNX
Sandbox未启用 sandbox
NATS未启用 ragflow-go
Kibana未启用 kibana
Infinity / OpenSearch / OceanBase / SeekDB未切换 DOC_ENGINE

三、要改哪些文件

文件是否必须改改什么
docker/.env必须国内主镜像、端口冲突项；可选 TEI/Sandbox 镜像
docker/docker-compose-base.yml必须（国内拉基础镜像）MySQL / MinIO / Redis / ES 等 image:
docker/docker-compose.yml强烈建议（对齐 v0.26.4）去掉 --init-model-provider-tables；注释 entrypoint.sh 挂载
docker/entrypoint.sh权限chmod +x entrypoint.sh（内容尽量用镜像内置）

3.1 docker/.env

变量改前（官方）改后（国内最小部署）
RAGFLOW_IMAGEinfiniflow/ragflow:v0.26.4swr.cn-north-4.myhuaweicloud.com/infiniflow/ragflow:v0.26.4
TEI_IMAGE_CPUinfiniflow/text-embeddings-inference:cpu-1.8swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/infiniflow/text-embeddings-inference:cpu-1.8
TEI_IMAGE_GPUinfiniflow/text-embeddings-inference:1.8swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/infiniflow/text-embeddings-inference:1.8
SANDBOX_EXECUTOR_MANAGER_IMAGEinfiniflow/sandbox-executor-manager:latestswr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/infiniflow/sandbox-executor-manager:latest
SANDBOX_BASE_PYTHON_IMAGEinfiniflow/sandbox-base-python:latestswr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/infiniflow/sandbox-base-python:latest
SANDBOX_BASE_NODEJS_IMAGEinfiniflow/sandbox-base-nodejs:latestswr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/infiniflow/sandbox-base-nodejs:latest
HF_ENDPOINT注释掉需要时取消注释：https://hf-mirror.com
EXPOSE_MYSQL_PORT3306（示例环境常冲突）冲突时改为 5455 等
SVR_WEB_HTTP_PORT80（示例环境常冲突）冲突时改为 8080 / 8090 等

阿里云备选主镜像（.env 注释中常见）：

1

registry.cn-hangzhou.aliyuncs.com/infiniflow/ragflow:v0.26.4

3.2 docker/docker-compose-base.yml

服务改前改后
es01elasticsearch:${STACK_VERSION}swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.elastic.co/elasticsearch/elasticsearch:${STACK_VERSION}
mysqlmysql:8.0.39swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/mysql:8.0.39
miniopgsty/minio:RELEASE.2026-03-25T00-00-00Zswr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/pgsty/minio:RELEASE.2026-03-25T00-00-00Z
redisvalkey/valkey:8swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/valkey/valkey:8
opensearch01opensearchproject/opensearch:2.19.1swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/opensearchproject/opensearch:2.19.1
infinityinfiniflow/infinity:v0.7.0swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/infiniflow/infinity:v0.7.0
oceanbaseoceanbase/oceanbase-ce:4.4.1.0-100000032025101610swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/oceanbase/oceanbase-ce:4.4.1.0-100000032025101610
seekdboceanbase/seekdb:latestswr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/oceanbase/seekdb:latest
natsnats:2.14.2swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/nats:2.14.2
kibanakibana:${STACK_VERSION}swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.elastic.co/kibana/kibana:${STACK_VERSION}

3.3 docker/docker-compose.yml（版本对齐关键）

当本地代码新于镜像 v0.26.4，挂载宿主机 entrypoint.sh + --init-model-provider-tables 会导致：

1

./entrypoint.sh: line 258: tools/scripts/run_migrations.sh: No such file or directory

容器反复重启，8090 / 80 出现 Connection reset by peer。

项改前改后（推荐）
command--enable-adminserver + --init-model-provider-tables仅保留 --enable-adminserver，或整段注释用镜像默认启动
volumes 中 entrypoint.sh./entrypoint.sh:/ragflow/entrypoint.sh注释掉，使用镜像内置脚本
1
2
3
4
5
6
7
8

    command:
      - --enable-adminserver
      # - --init-model-provider-tables   # v0.26.4 镜像内无此脚本，勿开

    volumes:
      - ./ragflow-logs:/ragflow/logs
      - ./service_conf.yaml.template:/ragflow/conf/service_conf.yaml.template
      # - ./entrypoint.sh:/ragflow/entrypoint.sh

更稳妥：代码与镜像完全对齐：

1
2
3
4

cd /opt/ragflow-v0.26.4   # 你的部署目录
cp docker/.env docker/.env.my-backup
git checkout v0.26.4
# 再把 .env 中的国内镜像、端口改回

四、挂载路径与数据位置

4.1 Bind mount（相对 docker/ 目录）

服务宿主机路径容器内路径用途
ragflow-cpu./ragflow-logs/ragflow/logs日志
ragflow-cpu./service_conf.yaml.template/ragflow/conf/service_conf.yaml.template后端配置模板
ragflow-cpu./entrypoint.sh（建议注释）/ragflow/entrypoint.sh启动脚本
mysql./init.sql/data/application/init.sql初始化 SQL
infinity（可选）./infinity_conf.toml/infinity_conf.tomlInfinity 配置

4.2 Docker 命名卷（默认不在项目目录）

数据卷名（在 docker/ 下启动时）容器内路径说明
MySQL 元数据docker_mysql_data/var/lib/mysql用户 / 知识库配置
上传文件docker_minio_data/data对象存储
Redisdocker_redis_data/data缓存 / 队列
ES 向量 / 图谱docker_esdata01/usr/share/elasticsearch/data索引与知识图谱 chunk
1
2

docker volume ls
docker volume inspect docker_minio_data

Windows + Docker Desktop：数据在 WSL2 虚拟磁盘内，常见访问路径类似：

1

\\wsl$\docker-desktop-data\version-pack-data\community\docker\volumes\<卷名>\_data

Mountpoint（如 /var/lib/docker/volumes/.../_data）是 Docker 虚拟机内部路径，不是 Windows 盘符路径。

五、端口一览与冲突处理

5.1 默认端口

变量（.env）默认宿主机端口容器端口服务
SVR_WEB_HTTP_PORT8080Web 界面
SVR_WEB_HTTPS_PORT443443HTTPS
SVR_HTTP_PORT93809380HTTP API
ADMIN_SVR_HTTP_PORT93819381Admin API
SVR_MCP_PORT93829382MCP
GO_ADMIN_PORT93839383Go Admin
GO_HTTP_PORT93849384Go API
EXPOSE_MYSQL_PORT33063306MySQL 对外映射
MYSQL_PORT3306—容器内连接端口，一般不改
REDIS_PORT63796379Redis
MINIO_PORT90009000MinIO API
MINIO_CONSOLE_PORT90019001MinIO 控制台
ES_PORT12009200Elasticsearch

5.2 常见冲突：改哪个参数

报错现象改文件改参数示例不要改
bind host port 0.0.0.0:3306 ... address already in use.envEXPOSE_MYSQL_PORT5455不要改 MYSQL_PORT
bind host port 0.0.0.0:80 ... address already in use.envSVR_WEB_HTTP_PORT8080 / 8090—
443 被占用.envSVR_WEB_HTTPS_PORT任意空闲—
6379 被占用.envREDIS_PORT6380—
9000/9001 被占用.envMINIO_PORT / MINIO_CONSOLE_PORT——
变量含义
MYSQL_PORTRAGFlow 容器通过 Docker 网络连 mysql:3306，用容器内 MySQL 时保持 3306
EXPOSE_MYSQL_PORT映射到宿主机的端口，冲突只改它
1

ss -tlnp | grep -E '3306|80|443|6379|9000|1200'

改完后：

1
2

docker compose -f docker-compose.yml down
docker compose -f docker-compose.yml up -d

5.3 访问地址示例

假设 SVR_WEB_HTTP_PORT=8090，服务器 IP 192.168.1.201：

用途URL
Web 界面http://192.168.1.201:8090/
HTTP APIhttp://192.168.1.201:9380/
MinIO 控制台http://192.168.1.201:9001/

MinIO 能开、Web 打不开：多半是 ragflow-cpu 未就绪或反复重启，不是防火墙问题。先看：
docker logs docker-ragflow-cpu-1 --tail 80

六、启动与验证

1
2
3
4
5
6
7
8
9

cd docker
# 建议：代码与镜像同版本
# git checkout v0.26.4

chmod +x entrypoint.sh
docker compose -f docker-compose.yml up -d

docker compose ps
docker logs -f docker-ragflow-cpu-1

成功标志（日志）：

1

Running on all addresses (0.0.0.0)

本机探活：

1

curl -I http://127.0.0.1:8090/   # 端口按你的 SVR_WEB_HTTP_PORT

期望：HTTP/1.1 200 或 302。若 Connection reset by peer，容器多半在重启，查 entrypoint / migrations 问题（见 §三.3、§九）。

七、可选服务

服务Profile / 启用方式国内镜像功能对 RAGFlow 的作用最小部署是否需要
InfinityDOC_ENGINE=infinity.../ddn-k8s/docker.io/infiniflow/infinity:v0.7.0向量库替代 ES 做检索与图谱存储否（默认用 ES）
OpenSearchDOC_ENGINE=opensearch.../ddn-k8s/docker.io/opensearchproject/opensearch:2.19.1检索引擎替代 ES否
OceanBaseDOC_ENGINE=oceanbase.../ddn-k8s/docker.io/oceanbase/oceanbase-ce:4.4.1.0-...文档 / 向量引擎替代 ES；宿主机 nofile 要求高否
SeekDBDOC_ENGINE=seekdb.../ddn-k8s/docker.io/oceanbase/seekdb:latest轻量文档引擎替代 ES否
TEI CPU.env 增加 COMPOSE_PROFILES=...,tei-cpu.../ddn-k8s/docker.io/infiniflow/text-embeddings-inference:cpu-1.8本地 Embedding不依赖云端 Embedding API否（可用云端 Embedding）
TEI GPU...,tei-gpu.../ddn-k8s/docker.io/infiniflow/text-embeddings-inference:1.8GPU Embedding同上，更快否
DeepDoc...,deepdocDEEPDOC_IMAGE（默认需自建或官方）OCR / 版面 / 表格独立视觉解析；默认主容器内联亦可否
Sandbox...,sandbox + SANDBOX_ENABLED=1见 .env 中三条 sandbox 华为镜像Agent 代码执行工具沙箱；需 gVisor + Docker sock否
NATSragflow-go / Go 混合部署.../ddn-k8s/docker.io/nats:2.14.2消息队列Go 服务通信否（API_PROXY_SCHEME=python）
Kibana...,kibana.../ddn-k8s/docker.elastic.co/kibana/kibana:8.11.3ES 可视化运维排查否
ragflow-gpuDEVICE=gpu同 RAGFLOW_IMAGEGPU 加速 DeepDoc解析加速否（CPU 可跑）

启用本地 Embedding 示例：

# docker/.env
COMPOSE_PROFILES=${DOC_ENGINE},${DEVICE},tei-cpu
# 可选小模型降内存：
# TEI_MODEL=BAAI/bge-small-en-v1.5

单独重试拉 TEI：

1

docker pull swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/infiniflow/text-embeddings-inference:cpu-1.8

八、国内镜像规律与验证记录

8.1 前缀规律

类型正确前缀示例
RAGFlow 主镜像swr.cn-north-4.myhuaweicloud.com/infiniflow/.../infiniflow/ragflow:v0.26.4
Docker Hub / Elastic 等swr.cn-north-4.myhuaweicloud.com/ddn-k8s/....../ddn-k8s/docker.io/mysql:8.0.39
Elastic 官方路径.../ddn-k8s/docker.elastic.co/....../elasticsearch/elasticsearch:8.11.3

8.2 易错点

错误写法结果正确写法
swr.cn-north-4.myhuaweicloud.com/infiniflow/infinity:v0.7.0401 Unauthorized.../ddn-k8s/docker.io/infiniflow/infinity:v0.7.0
.../infiniflow/text-embeddings-inference:...（无 ddn-k8s）401.../ddn-k8s/docker.io/infiniflow/text-embeddings-inference:...

8.3 拉取验证（实操记录）

镜像结果备注
Valkey / MySQL / ES / Kibana / MinIO(pgsty) / NATS / OpenSearch / OceanBase成功ddn-k8s 路径可用
Infinity（ddn-k8s/.../infinity:v0.7.0）成功compose 配置可用
TEI cpu-1.8中途 unexpected EOF网络中断，不是地址错误；可重试；最小部署不依赖
.../infiniflow/infinity（无 ddn-k8s）401勿用

HuggingFace 慢时，在 .env 取消注释：

HF_ENDPOINT=https://hf-mirror.com

九、常见故障速查

现象原因处理
MySQL address already in use宿主机 3306 占用只改 EXPOSE_MYSQL_PORT
MySQL 长期 Waiting / 不 healthy首次初始化慢 / 旧数据卷密码不一致 / 内存不足看 docker logs docker-mysql-1；全新可 docker volume rm docker_mysql_data
exec: "./entrypoint.sh": permission denied无执行权限chmod +x entrypoint.sh
run_migrations.sh: No such file + 容器反复重启新代码 entrypoint 挂进旧镜像注释 entrypoint 挂载；去掉 --init-model-provider-tables；或 git checkout v0.26.4
Web 端口冲突（80）Nginx 等占用改 SVR_WEB_HTTP_PORT
MinIO 通、Web 不通 / Connection resetragflow-cpu 未就绪或在重启docker logs docker-ragflow-cpu-1
页面 network abnormal后端未完全起来就访问等到日志出现 Running on all addresses
能开页不能问答未配 LLM / EmbeddingUI「模型」或 service_conf.yaml.template 配置

MySQL 健康检查依赖 MYSQL_PASSWORD；Waiting 最长约 20 分钟（120 次 × 10s）。

十、知识图谱：最小安装是否够

项目是否足够
上述 5 个 Docker 组件足够（图谱存在 ES，不需 Neo4j）
额外 Docker 服务不需要
Chat LLM API必须另配
Embedding 模型必须另配（云端 API 或启用 TEI）
文档已解析入库必须（先有 chunk 再建图）
16GB 内存小图谱可试；大图谱建议 32GB+

流程：配置 Chat + Embedding → 建库上传并解析 → Configuration 设实体类型 → Files → Generate → Knowledge graph → 对话开启 Use knowledge graph。

十一、离线导出与加载

导出示例目录：E:\docker-images\ragflow-0.26.4

1
2
3
4
5

docker save -o mysql-8.0.39.tar swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/mysql:8.0.39
docker save -o minio-RELEASE.2026-03-25.tar swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/pgsty/minio:RELEASE.2026-03-25T00-00-00Z
docker save -o valkey-8.tar swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/valkey/valkey:8
docker save -o elasticsearch-8.11.3.tar swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.elastic.co/elasticsearch/elasticsearch:8.11.3
docker save -o ragflow-v0.26.4.tar swr.cn-north-4.myhuaweicloud.com/infiniflow/ragflow:v0.26.4

离线机加载：

1

for f in *.tar; do docker load -i "$f"; done

删除本地镜像：

1
2

docker rmi swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/mysql:8.0.39
# ...其余同理

十二、推荐启动清单

步骤操作
1git checkout v0.26.4（与镜像对齐）
2备份并修改 .env：国内 RAGFLOW_IMAGE、冲突端口
3修改 docker-compose-base.yml：基础镜像改华为 ddn-k8s
4修改 docker-compose.yml：去掉 migrations 参数；注释 entrypoint 挂载
5chmod +x entrypoint.sh
6docker compose -f docker-compose.yml up -d
7日志确认 Running；浏览器访问 http://IP:SVR_WEB_HTTP_PORT
8UI 配置 LLM + Embedding

十三、相关文件索引

文件用途
docker/.env端口、密码、镜像、Profile
docker/docker-compose.ymlRAGFlow 主服务、挂载、command
docker/docker-compose-base.ymlMySQL / MinIO / Redis / ES 等依赖
docker/service_conf.yaml.template后端服务配置模板
docker/entrypoint.sh容器启动脚本（建议用镜像内置）
docker/init.sqlMySQL 初始化
docker/README.md官方 Docker 说明

十四、小结

要点结论
最小拓扑ES + CPU，5 个镜像即可
国内源主镜像走华为 infiniflow/；依赖镜像走 ddn-k8s/...
必改文件.env、docker-compose-base.yml；建议对齐 docker-compose.yml
版本对齐代码 tag v0.26.4 与镜像一致，避免 entrypoint / migrations 踩坑
端口冲突Web 改 SVR_WEB_HTTP_PORT；MySQL 只改 EXPOSE_MYSQL_PORT
图谱不需额外图数据库；须另配 LLM + Embedding

镜像标签以 v0.26.4 为准；实践基于华为云 SWR / ddn-k8s 国内源。

AI, RAG
AI RAG RAGFlow Docker 部署 国内镜像
本文由作者按照 CC BY 4.0 进行授权