简介这份PDF文档面向具备Docker基础、希望部署或深入理解RAGFlow配置的技术人员系统讲解基于Docker的RAGFlow环境搭建与参数调优方法。内容围绕.env环境变量、service_conf.yaml.template系统级配置与docker-compose.yml多容器编排展开覆盖API服务器、MySQL、MinIO、Elasticsearch、Redis等组件的端口、密码与内存限制设置并给出更新HTTP服务端口、重启容器生效的操作要点同时提示非官方维护的Compose文件风险以及时区、Hugging Face镜像、macOS优化、OAuth与默认LLM选择等进阶配置。资源包为1个PDF文件大小约121KB结构紧凑便于查阅。目前已有4463人学习下载适合需要快速搭建RAGFlow环境、按实际场景调整配置并规避生产停机风险的研发与运维人员参考。1. RAGFlow 部署为什么环境变量和 service_conf.yaml 才是真正的分水岭很多人第一次在本地跑 RAGFlow卡住的地方往往不是模型也不是镜像拉取而是容器起来了、端口也映射了打开页面却报 502或者上传文档后解析任务一直排队。翻日志才发现问题出在service_conf.yaml和系统级环境变量没对齐。RAGFlow 的 Docker 部署本质上是一套多容器编排MySQL、Redis、MinIO、Elasticsearch 负责存储与检索ragflow-server 负责 API 和任务调度而docker-compose只负责把它们拉起来。真正决定这套系统能不能跑通、跑稳的是环境变量怎么传、service_conf.yaml怎么配、容器之间怎么互相看见。这篇内容面向的是准备做 RAGFlow 本地化部署的工程师不管你是 win11 上用 Docker Desktop还是 Ubuntu 服务器上装 docker只要你想把 RAGFlow 从「能启动」推到「能批量解析文件、能调 API」环境变量和配置文件这两关就绕不过去。2. 部署前的系统级准备Docker、compose 与内核参数2.1 先确认 Docker 和 docker-compose 的版本底线RAGFlow 官方给出的部署方式依赖docker compose注意是带空格的 v2 插件形式不是老的docker-compose二进制。在 Ubuntu 上装 Docker 的常见做法是走官方仓库而不是apt install docker.io后者版本往往偏旧compose 插件也不一定带。下面这套命令我在 Ubuntu 22.04 和 24.04 上都跑过# 卸载可能存在的旧版本 sudo apt remove docker docker-engine docker.io containerd runc # 安装依赖 sudo apt update sudo apt install -y ca-certificates curl gnupg # 添加 Docker 官方 GPG key sudo install -m 0755 -d /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \ sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg sudo chmod ar /etc/apt/keyrings/docker.gpg # 添加仓库 echo deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.gpg] \ https://download.docker.com/linux/ubuntu $(. /etc/os-release echo $VERSION_CODENAME) stable | \ sudo tee /etc/apt/sources.list.d/docker.list /dev/null # 安装 Docker 与 compose 插件 sudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin # 验证 docker --version docker compose version这里的关键点是docker-compose-plugin它提供的是docker compose子命令。如果你只装了老的docker-compose独立二进制RAGFlow 的启动脚本可能仍然能跑但后续排查时命令对不上容易把自己绕进去。版本上Docker 24 以上、compose v2.20 以上是比较稳的区间太老的版本对depends_on的健康检查支持不完整会导致 ragflow-server 在 MySQL 还没就绪时就启动然后反复重启。Windows 这边win11 上装 Docker Desktop 是主流选择。安装前要在 BIOS 里确认虚拟化打开否则会直接报virtualization support not detectedDocker Desktop 起不来。装完之后建议在 Settings 里把 WSL2 backend 打开资源分配至少给 8GB 内存因为 Elasticsearch 单独就要吃掉 2GB 左右。很多人用 win11 跑 RAGFlow 失败不是配置写错而是 Docker Desktop 默认内存给太少ES 容器被 OOM kill表现就是 ragflow-server 一直连不上 ES。2.2 内核参数与文件句柄ES 容器的隐形门槛Elasticsearch 在容器里跑对vm.max_map_count有硬性要求默认 65530 不够需要调到 262144。这不是 RAGFlow 特有的任何在 Docker 里跑 ES 的场景都要改# 临时生效 sudo sysctl -w vm.max_map_count262144 # 永久生效 echo vm.max_map_count262144 | sudo tee -a /etc/sysctl.conf sudo sysctl -p另外文件句柄数也建议一起调尤其是你要做 ragflow 批量处理文件的时候解析任务会同时打开大量文件描述符# 查看当前限制 ulimit -n # 永久调整编辑 /etc/security/limits.conf追加 * soft nofile 65536 * hard nofile 65536改完 limits.conf 需要重新登录 shell 才生效。这一步经常被跳过直到某天批量上传几百个 PDF解析到一半任务全挂日志里出现too many open files才回头来补。血泪经验是部署阶段就把这两个参数写进初始化脚本别等出问题再查。3. 环境变量怎么传.env、systemd 与 compose 的优先级3.1 RAGFlow 的 .env 文件与 docker-compose 变量注入RAGFlow 的 docker 目录下有一个.env文件docker-compose.yml里大量使用了${VAR}形式的变量引用。这个.env是 compose 默认读取的优先级低于 shell 环境变量但高于 compose 文件里的默认值。常见做法是复制一份模板再改# 进入 ragflow 的 docker 目录 cd ragflow/docker # 查看 .env 内容 cat .env典型的.env里会有这些条目# .env 示例按实际需求修改 RAGFLOW_IMAGEinfiniflow/ragflow:v0.15.0 SVR_HTTP_PORT9380 MYSQL_PASSWORDinfini_rag_flow MINIO_PASSWORDinfini_rag_flow ES_PORT1200 TIMEZONEAsia/Shanghai这里有几个参数值得单独说。SVR_HTTP_PORT是 ragflow-server 对外暴露的端口默认 9380如果你前面还有 Nginx 反代这个端口只需要本机可达。ES_PORT是 ES 的宿主映射端口默认 1200改成别的端口时service_conf.yaml里的 ES 地址也要同步改否则 ragflow-server 会连到旧端口。TIMEZONE影响日志时间和任务调度国内环境设成Asia/Shanghai不然解析任务的时间戳会对不上。环境变量的传递链路是这样的shell 环境变量 .env文件 docker-compose.yml里的默认值。也就是说如果你在 shell 里export MYSQL_PASSWORDxxx它会覆盖.env里的值。这个特性在调试时有用但也容易造成「我明明改了 .env 怎么不生效」的翻车现场。排查时先docker compose config看一下最终解析出来的配置比猜要快得多。3.2 systemd 从文件加载环境变量服务器常驻场景如果你希望 RAGFlow 随系统启动用 systemd 管理 compose 是个常见做法。systemd 加载环境变量有两种方式Environment直接写或者EnvironmentFile从文件读。后者更适合管理多个变量# /etc/systemd/system/ragflow.service [Unit] DescriptionRAGFlow Docker Compose Requiresdocker.service Afterdocker.service network-online.target Wantsnetwork-online.target [Service] Typeoneshot RemainAfterExityes WorkingDirectory/opt/ragflow/docker EnvironmentFile/opt/ragflow/docker/.env ExecStart/usr/bin/docker compose up -d ExecStop/usr/bin/docker compose down TimeoutStartSec300 [Install] WantedBymulti-user.target这里EnvironmentFile指向的就是.envsystemd 会把它读进来作为进程环境变量再传给docker compose。注意WorkingDirectory必须设对否则 compose 找不到docker-compose.yml。TimeoutStartSec给到 300 秒是因为首次启动要拉镜像、初始化 MySQL时间会比较长。改完 service 文件后sudo systemctl daemon-reload sudo systemctl enable ragflow sudo systemctl start ragflow sudo systemctl status ragflow用 systemd 管理的好处是开机自启、日志统一走 journalctl。但要注意docker compose down会停掉所有容器如果你只想重启 ragflow-server别用 systemctl restart直接docker compose restart ragflow-server更精准。3.3 service_conf.yaml容器内服务的连接真相service_conf.yaml是 RAGFlow 服务端读取的配置文件它决定了 ragflow-server 怎么连 MySQL、Redis、MinIO、ES。这个文件在 docker 目录下会被挂载进容器。很多人改了.env里的密码却忘了同步改service_conf.yaml结果就是容器起来了但服务连不上数据库。# service_conf.yaml 关键片段 mysql: name: rag_flow user: root password: infini_rag_flow host: mysql port: 3306 max_connections: 100 stale_timeout: 30 redis: db: 1 password: infini_rag_flow host: redis port: 6379 minio: user: rag_flow password: infini_rag_flow host: minio port: 9000 bucket: ragflow es: hosts: http://es01:9200 username: elastic password: infini_rag_flow这里的host用的是 compose 服务名不是 localhost也不是 127.0.0.1。因为 ragflow-server 在容器里跑它要通过 Docker 内部网络访问其他容器服务名就是 DNS 名。这是新手最容易踩的坑把 host 改成localhost然后发现连不上因为容器里的 localhost 是容器自己不是宿主机。es.hosts里的es01也是服务名端口 9200 是容器内端口不是宿主映射的 1200。参数上mysql.max_connections默认 100如果你要跑大量并发解析任务可以适当调高但也要看 MySQL 容器的资源限制。redis.db选 1 是为了和别的服务隔离避免 key 冲突。minio.bucket是存储桶名首次启动时 ragflow-server 会自动创建如果权限不对会报错检查 MinIO 的MINIO_ROOT_USER和MINIO_ROOT_PASSWORD是否和service_conf.yaml一致。4. 启动、验证与批量解析的实操路径4.1 启动顺序与健康检查RAGFlow 的 compose 文件里定义了depends_on和健康检查但不同版本行为有差异。稳妥的做法是手动确认每个基础服务就绪后再启动 ragflow-server# 先拉起基础服务 docker compose up -d mysql redis minio es01 # 查看健康状态等待 healthy docker compose ps # 确认 MySQL 可连接 docker compose exec mysql mysql -uroot -pinfini_rag_flow -e show databases; # 确认 ES 可访问 curl -u elastic:infini_rag_flow http://localhost:1200 # 最后启动 ragflow-server docker compose up -d ragflow-serverdocker compose ps里 STATUS 列显示healthy才算就绪running不代表服务可用。MySQL 首次初始化会执行init.sql大概需要 30 到 60 秒这期间 ragflow-server 如果启动会报连接失败。ES 的健康检查是curl集群状态返回 JSON 里有status: green或yellow都算可用red就要看日志了。4.2 用 API 验证部署是否真正可用页面能打开不代表 API 能用。RAGFlow 提供 REST API部署完成后可以用一个简单的请求验证# 获取 API key 后列出数据集 curl -X GET http://localhost:9380/api/v1/datasets \ -H Authorization: Bearer YOUR_API_KEY \ -H Content-Type: application/jsonAPI key 在页面右上角用户设置里生成。如果这个请求返回 401检查 key 是否正确返回 502说明 ragflow-server 没起来或者端口不对返回 500去看docker compose logs ragflow-server里的堆栈。API 通了才说明整套服务链路是完整的。4.3 批量处理文件的配置要点RAGFlow 的批量解析能力依赖任务队列和 worker 数量。在service_conf.yaml里可以调整相关参数# 任务相关配置 worker: num: 4 timeout: 600worker.num控制并发解析任务数默认值偏保守。如果你机器内存充足32GB 以上可以调到 4 到 8。但要注意每个解析任务会占用内存尤其是 PDF 里的表格和图片提取内存不够时任务会失败。timeout是单任务超时时间大文件解析慢的话要调大否则任务会被中断。批量上传时建议先小批量测试确认解析质量后再放量避免一次性灌入大量文件导致队列积压。5. 避坑与排查那些让部署翻车的细节5.1 容器起来了但页面 502现象docker compose ps显示所有容器 running但访问http://localhost:9380返回 502。 原因ragflow-server 进程崩溃或还在初始化也可能是端口映射写错。 解决先看docker compose logs -f ragflow-server如果是数据库连接失败检查service_conf.yaml里的 host 和密码如果是端口问题确认.env里SVR_HTTP_PORT和 compose 文件里的端口映射一致。5.2 ES 容器反复重启现象es01 容器状态一直是 restarting日志里有max virtual memory areas vm.max_map_count相关报错。 原因宿主机vm.max_map_count没调或者 Docker Desktop 分配内存不足。 解决Linux 上执行sudo sysctl -w vm.max_map_count262144Windows 上在 Docker Desktop 设置里把内存调到 8GB 以上然后重启 Docker Desktop。5.3 改了 .env 但配置没生效现象修改.env里的密码后重启服务仍然用旧密码连接。 原因shell 环境变量覆盖了.env或者容器没有重新创建。 解决先unset相关环境变量再docker compose down docker compose up -d。注意restart不会重新读取.env必须down再up。5.4 批量解析任务卡在排队现象上传文件后任务一直显示排队worker 不消费。 原因worker 数量为 0或者 Redis 连接失败导致队列不可用。 解决检查service_conf.yaml里worker.num是否大于 0确认 Redis 容器健康docker compose exec redis redis-cli -a infini_rag_flow ping返回 PONG。5.5 Windows 上路径挂载失败现象win11 上启动时提示 volume 挂载错误或者容器内看不到挂载的文件。 原因Docker Desktop 的文件共享没开或者路径里有中文/空格。 解决在 Docker Desktop 设置里把项目所在盘符加入 File Sharing项目路径尽量用纯英文避免空格。6. 进阶用环境变量覆盖做多环境隔离与配置校验部署跑通之后下一步要考虑的是多环境管理。开发、测试、生产用同一套 compose 文件靠环境变量区分是常见做法。RAGFlow 的.env支持被 shell 变量覆盖这正好可以用来做隔离。比如生产环境用独立的密码和端口# 生产环境启动脚本 export MYSQL_PASSWORDprod_strong_pwd export MINIO_PASSWORDprod_minio_pwd export SVR_HTTP_PORT9380 export ES_PORT1200 export TIMEZONEAsia/Shanghai cd /opt/ragflow/docker docker compose -f docker-compose.yml up -d这样.env里可以保留开发环境的默认值生产环境通过 export 覆盖不需要维护两份文件。但要注意docker compose config会显示最终解析结果启动前跑一遍确认关键变量都是期望的值docker compose config | grep -E MYSQL_PASSWORD|SVR_HTTP_PORT|ES_PORT另一个技巧是给service_conf.yaml做启动前校验。这个文件是 YAML缩进错了容器起不来但报错不明显。可以用 Python 快速校验import yaml import sys def validate(path): try: with open(path, r, encodingutf-8) as f: cfg yaml.safe_load(f) required [mysql, redis, minio, es] for key in required: if key not in cfg: print(f缺少配置段: {key}) return False # 检查 host 是否为服务名而非 localhost for section in required: host cfg[section].get(host, ) if host in (localhost, 127.0.0.1): print(f{section}.host 不能是 {host}应为 compose 服务名) return False print(service_conf.yaml 校验通过) return True except yaml.YAMLError as e: print(fYAML 解析失败: {e}) return False if __name__ __main__: sys.exit(0 if validate(service_conf.yaml) else 1)这个脚本检查两件事必需的配置段是否存在以及 host 有没有误写成 localhost。把它加到启动脚本里能在容器起来之前就拦住大部分配置错误。参数上required列表按你实际用到的服务增减如果没用 MinIO 可以去掉但 RAGFlow 默认依赖它存文件一般不建议删。最后说一个我自己的习惯每次改完配置先docker compose config看解析结果再跑一遍上面的 YAML 校验最后才up -d。这套流程看起来多两步但比容器起来之后翻日志找问题要快得多。RAGFlow 的部署难点不在 Docker 本身而在环境变量和配置文件之间的对齐关系把这条链路理清楚后面做 ragflow 解析技巧、智能体编排都是顺水推舟的事。希望帮到你。本文还有配套的精品资源点击获取