★ FEATURED ARTICLE 简介这是一份面向有一定Docker基础的技术人员的RAGFlow部署配置指南以PDF形式提供共1个文件大小121KB重点讲解基于Docker Compose的完整配置流程。文档覆盖三个关键文件的使用方法.env环境变量设置含MySQL、MinIO、Redis、端口及内存限制、service_conf.yaml.template系统级配置API服务器、数据库、对象存储、OAuth等、docker-compose.yml多容器编排并给出修改HTTP端口、重启容器生效等操作指导。针对不同环境还补充了时区、Hugging Face镜像站点、macOS优化及非官方Compose文件的使用建议同时介绍默认LLM与OAuth的配置思路。已有4465人学习适合需要快速部署RAGFlow的研发人员以及希望按业务场景灵活调整服务参数、规避生产环境配置风险的运维人员。通过阅读可掌握从基础环境变量到前端端口映射、从容器资源限制到镜像替换的实用排错与调优方法。1. 为什么 RAGFlow 部署卡在配置层三个文件决定整个系统的命运RAGFlow 这类检索增强生成系统部署本身并不算难真正容易把人卡住的是它那套「三层配置」的设计.env管 Docker 层变量service_conf.yaml.template管后端服务参数docker-compose.yml管容器编排。很多开发者第一次部署时都习惯性地只改端口、只改密码结果容器起来了首页却打不开或者 Elasticsearch 连不上、文件传上去但检索不到内容——这些问题十有八九出在这三个文件没有对齐。这篇笔记就按实际部署顺序把每一个配置项的用途、修改方式、生效条件和容易踩的坑说清楚适合对 Docker 有一定基础、正在部署或准备调整 RAGFlow 生产环境的开发者。2. 部署前要动的那几个文件.env 环境变量与数据面端口映射2.1 端口全映射表改端口前先想清楚谁依赖谁.env文件是 RAGFlow 所有外部访问端口的唯一入口里面每条*_PORT都对应一个对外暴露的端口。我在第一次部署时犯过一个典型错误只改了SVR_HTTP_PORT结果前端页面能开但 MinIO 控制台还是走默认端口开发和测试环境里多个服务端口撞在一起排查了半天才发现是端口映射没对齐。下面这张表是.env里最常用到的端口参数建议部署前先打印出来贴在终端旁边参数名默认值说明修改时注意SVR_HTTP_PORT9380RAGFlow HTTP API 服务对外端口网页端和 API 调用都走这个ES_PORT1200Elasticsearch 对外端口和 MySQL、Redis 端口不要冲突MYSQL_PORT5455MySQL 对外端口注意容器内实际监听 3306MINIO_PORT9000MinIO API 端口上传文件的对象存储入口MINIO_CONSOLE_PORT9001MinIO 控制台 Web 端口改端口后控制台 URL 要跟着变REDIS_PORT6379Redis 对外端口一般不用动KIBANA_PORT6601Kibana 可视化端口不常用但排查 ES 时很有用修改方式很简单直接编辑.env文件即可。比如把 RAGFlow 的对外服务端口改成 8080# 进入 docker 目录后编辑 .env cd docker cp .env .env.bak # 改之前先备份这是后悔药 sed -i s/^SVR_HTTP_PORT.*/SVR_HTTP_PORT8080/ .env逻辑说明sed -i是原地替换^SVR_HTTP_PORT匹配以该参数名开头的行.*匹配整行内容。备份.env.bak这一步是我自己加的因为.env文件里包含密码改坏了直接用备份恢复比重新初始化快得多。参数说明里最容易被忽略的是MYSQL_PORT——它只改宿主机映射端口容器内 MySQL 还是监听 3306service_conf.yaml.template里配的port必须保持 3306不要跟着改成 5455否则后端服务连不上数据库。2.2 镜像版本与加速源slim 和完整版的差距不在体积.env里RAGFLOW_IMAGE这一行直接决定你用的是哪种镜像。默认值是infiniflow/ragflow:v0.18.0-slim这个镜像不内嵌模型体积小、启动快但你要自己配置嵌入模型。另一个完整版infiniflow/ragflow:v0.18.0内置了BAAI/bge-large-zh-v1.5和maidalun1020/bce-embedding-base_v1两个嵌入模型适合不想折腾模型下载的场景。我在测试环境用 slim生产环境用完整版因为生产环境网络隔离模型下载通道不通。如果镜像拉不下来可以把RAGFLOW_IMAGE替换成国内可访问的镜像仓库地址。对nightly版本有两种替代# 华为云仓库 RAGFLOW_IMAGEswr.cn-north-4.myhuaweicloud.com/infiniflow/ragflow:nightly # 阿里云仓库 RAGFLOW_IMAGEregistry.cn-hangzhou.aliyuncs.com/infiniflow/ragflow:nightlyslim版本的替换方式完全一样只是 tag 换成nightly-slim。这里有一个需要留意的点官方文档明确说nightly版本不做稳定性保证功能更新频繁接口有变化的可能。我一般只在体验新功能时用nightly正式部署锁定v0.18.0或v0.18.0-slim这样的具体版本号。2.3 内存限制、时区与 macOS 优化非功能性配置同样影响稳定性MEM_LIMIT这个参数不太起眼但坑得最多。它的单位是字节默认值是 8073741824即 7.5GB限制的是单个容器可用的最大内存。如果你的机器只有 8GB 内存启动后 Elasticsearch、MySQL、Redis、MinIO、RAGFlow 五个容器同时跑起来内存会直接打满表现就是容器反复重启或者页面响应极慢。我一般按机器物理内存的 60% 左右来设比如 16GB 内存的机器# 16GB 物理内存给容器总量留 10GB sed -i s/^MEM_LIMIT.*/MEM_LIMIT10737418240/ .envTIMEZONE默认就是Asia/Shanghai国内部署不需要动。macOS 用户需要把# MACOS这一行取消注释因为 macOS 的 Docker Desktop 文件系统兼容性和 Linux 不同不开启这个优化项挂载目录的读写性能和文件事件监听会出现问题。HF_ENDPOINT这个参数默认是注释状态它指向 Hugging Face 镜像站点如果模型下载超时取消注释这一行通常能解决。2.4 避坑改了 .env 却没重建容器所有改动照旧现象修改了.env里的端口和密码执行docker compose up -d结果显示容器已在运行没有变化。原因Docker Compose 在容器已经存在的情况下不会自动重新读取.env中的环境变量除非你显式删除旧容器或者加--force-recreate参数。解决更新.env后必须强制重建容器docker compose -f docker/docker-compose.yml up -d --force-recreate如果再彻底一点直接把相关容器删掉再启动docker compose -f docker/docker-compose.yml down docker compose -f docker/docker-compose.yml up -d注意down会同时删除容器和默认网络但不会删除数据卷所以 MySQL 和 Elasticsearch 的数据还在不用担心丢失。3. service_conf.yaml.template系统级配置的变量替换规则3.1 MySQL 连接池参数max_connections 与 stale_timeout 的联动service_conf.yaml.template是 RAGFlow 后端服务的核心配置模板。容器启动时系统会基于这个模板生成真正的service_conf.yaml模板里所有环境变量都会被替换成实际值。我在第一次部署时不理解这个机制直接改生成的service_conf.yaml结果容器一重启就被覆盖了——所有在启动时发生的修改都白做了。MySQL 部分的配置很直观但有两个参数需要联动理解mysql: name: rag_flow user: root password: ${MYSQL_PASSWORD} port: 3306 max_connections: 100 stale_timeout: 30逻辑说明name、user、password对应数据库名、用户名和密码port是容器内 MySQL 的端口固定 3306。max_connections是最大并发连接数默认 100stale_timeout是连接池中超时连接的回收阈值默认 30 秒。这两个参数的联动逻辑是当并发请求超过max_connections时新的连接请求会排队等待如果等待时间超过stale_timeout这个连接请求就会被判定为过期连接并释放。我把max_connections调到 200 后任务执行高峰期的报错明显减少。3.2 MinIO 的 host 配置写 minio:9000 而不是 localhostMinIO 配置是整个模板里最容易出错的地方尤其是host这一项minio: user: ${MINIO_USER} password: ${MINIO_PASSWORD} host: minio:9000这里的host写的是 Docker 网络内的服务名minio:9000不是localhost:9000也不是宿主机 IP。因为 RAGFlow 后端服务跑在容器内它访问 MinIO 走的是 Docker 内部网络。如果你写成localhost服务在容器内解析的是容器自己的回环地址永远连不上 MinIO表现就是文件上传一直失败日志里报connection refused。类似的坑在 Elasticsearch 配置上也有凡是模板中出现服务名如mysql、minio、elasticsearch的地方一律保持服务名不变这些名称由docker-compose-base.yml定义不需要也不应该改成 IP 或 localhost。3.3 OAuth 与默认 LLM注释开得越早后期返工越少模板里oauth和user_default_llm默认都是注释状态。oauth用于第三方账号登录需要从 GitHub 开发者设置页面申请client_id和secret_key。user_default_llm则为新用户指定默认的大模型user_default_llm: factory: DeepSeek api_key: ${LLM_API_KEY}factory可选值有OpenAI、DeepSeek、Moonshot、Tongyi-Qianwen、VolcEngine、ZHIPU-AI这几个。如果团队里有多个模型供应商的账号建议在部署阶段就把这个配置解开注释并指定一个通用 key否则每个新用户都要手动配一次模型后台会收到一堆「模型未配置」的疑问工单。顺便说一句api_key里存的是明文密钥记得对.env和service_conf.yaml设置严格的文件权限。3.4 避坑YAML 缩进错误导致容器反复重启现象修改模板后启动容器后端服务一直处于Restarting状态日志里报 YAML 解析错误。原因service_conf.yaml.template是 YAML 文件对缩进极其敏感。很多人用 Tab 键缩进或者复制粘贴时混入了全角空格都会导致解析失败。另一个隐蔽问题是模板中的${VAR}占位符如果.env里没有定义对应变量替换后留下空字符串YAML 结构可能被破坏。解决改完模板先本地校验# 先替换环境变量生成完整配置 set -a source .env set a envsubst service_conf.yaml.template service_conf.yaml # 校验 YAML 语法 python3 -c import yaml; yaml.safe_load(open(service_conf.yaml))如果第二条命令报错把报错行号对应的缩进修好再启动。我后来养成的习惯是模板文件一律用空格缩进不用 Tab改完先跑一遍这个校验再执行 compose。4. docker-compose.yml 的编排与端口切换三个文件的分工与优先级4.1 三个 Compose 文件的分工谁定义了什么谁继承了什么RAGFlow 的 docker 目录下存在多个 compose 文件用途完全不同。docker-compose-base.yml定义基础依赖服务——Elasticsearch、MySQL、MinIO、Redis 这四个底层组件docker-compose.yml定义 RAGFlow 主服务并依赖基础文件。官方文档特别提醒docker-compose-CN-oc9.yml、docker-compose-gpu-CN-oc9.yml、docker-compose-gpu.yml这三个文件没有主动维护使用需自行承担风险。我在一个 GPU 环境里试过docker-compose-gpu.yml第一次启动没问题但升级版本后配置格式对不上最后还是切回了标准配置文件。4.2 HTTP 服务端口切换先改映射还是先改服务配置默认情况下 RAGFlow 的网页端监听 80 端口如果你要在同一台机器上跑多个 Web 服务80 端口冲突几乎是必然的。官方给的做法是修改docker-compose.yml中的端口映射把80:80改成YOUR_SERVING_PORT:80。以切换到 8080 为例services: ragflow-server: ports: - 8080:80逻辑说明冒号左边是宿主机端口外部访问用右边是容器内端口不要改动。改完之后访问http://服务器IP:8080就是 RAGFlow 的页面。同时.env里的SVR_HTTP_PORT也要保持一致因为这个参数控制的是 API 服务对外端口页面和 API 用的端口不同会导致前端调用失败。我遇到过一次症状很迷惑的情况页面能打开但点击「解析文档」按钮没反应F12 看请求全是 404就是因为页面端口和 API 端口不一致。4.3 避坑docker compose命令路径写错导致启动的是旧配置现象修改了docker-compose.yml后执行docker compose up -d启动发现端口没变化甚至服务起不来。原因命令中指定的 compose 文件路径不对。最典型的错误是在 docker 目录下执行docker compose up -d不带-f参数Compose 默认只读取当前目录下的docker-compose.yml不会自动读取docker/docker-compose.yml。解决启动时显式指定文件cd docker docker compose -f docker/docker-compose.yml up -d很多人以为在 docker 目录里执行就不用写路径实际写全路径最稳妥。另外配置文件更新后需要重启所有容器才能生效正确做法是down之后重新up而不是只执行restart命令——restart不会重新读取配置。5. 配置不生效排查指南三个现象与对应解法5.1 现象一改了端口服务起不来现象修改.env或 compose 文件中的端口后执行up -d某些容器报port is already allocated服务起不来。原因宿主机上有其他进程占用该端口或者你指定的端口落在系统保留端口区间内。这个报错的另一个常见来源是修改了MYSQL_PORT但忘记检查宿主机是否已有 MySQL 在跑。解决先用lsof -i :端口号查占用情况确认空闲后再启动。如果端口被占换一个端口修改.env和 compose 文件。更系统化的做法是维护一张端口分配表把 A 机器上所有服务端口汇总记录下来避免下次部署时冲突。5.2 现象二镜像拉不下来容器一直ImagePullBackOff现象执行docker compose up -d后docker ps看到容器状态是ImagePullBackOff或ErrImagePull。原因默认镜像源不可达或者你指定的镜像 tag 不存在。nightly版本清理比较积极一段时间没更新旧的 nightly tag 可能已经被删掉了。解决确认镜像源可达性改用替代镜像仓库。检查.env中RAGFLOW_IMAGE拼写是否精确匹配仓库中的 tag。验证方法docker pull infiniow/ragflow:v0.18.0-slim如果 pull 失败替换成对应厂商的镜像地址再 pull。注意 pull 成功后再执行 compose 启动不要边 pull 边启动否则 Compose 可能拉取失败后直接进入重试状态表现上像是卡住了。5.3 现象三容器都起来了但页面打不开现象docker compose ps显示所有容器都是Up状态但浏览器访问http://IP:80或自定义端口一直超时。原因最常见的是宿主机防火墙/安全组没有放行对应端口。其次是容器内部服务还没就绪——Elasticsearch 启动时间较长RAGFlow 后端会持续重试连接 ES页面在 ES 就绪前一直返回 502。解决先排除容器内服务状态docker logs docker-ragflow-server-1 --tail 50日志里如果出现waiting for elasticsearch说明 ES 还没就绪等 30 秒再刷新页面。如果日志里出现connection refused检查宿主机防火墙放行端口sudo ufw allow 80/tcp sudo ufw allow 9380/tcp云服务器则需要在安全组里添加入方向规则。这一步消耗的时间往往比配置本身还多我一般会在部署前先确认安全组规则避免页面打不开时来回排查。6. 用 docker inspect 验证配置是否真的注入把玄学变成可视化检查6.1 验证端口映射是否生效改完配置后最直接的问题就是「我改的是不是生效了」。与其猜不如直接查看容器的实际端口映射docker inspect docker-ragflow-server-1 | grep -A 10 Ports如果输出显示8080/tcp: [{HostIp: 0.0.0.0, HostPort: 8080}]说明端口映射已生效。如果显示的还是 80说明你改的文件不是 Compose 实际读取的那个文件回到第 4.3 节检查-f参数。6.2 验证环境变量是否注入到容器内端口映射生效不代表环境变量注入成功。.env文件中的变量如果拼写有误Compose 不会报错只是不会注入容器内表现为密码不匹配或配置丢失。验证方法docker exec docker-ragflow-server-1 env | grep -E MYSQL|MINIO|REDIS正常输出会包含MYSQL_PASSWORDxxx等变量。如果输出为空说明.env中没有定义对应的变量名检查拼写是否与 compose 文件中的${VAR}完全一致。6.3 验证 service_conf.yaml 是否由模板正确生成容器启动后查看容器内生成的配置内容重点确认环境变量替换是否成功docker exec docker-ragflow-server-1 cat /ragflow/conf/service_conf.yaml | grep -v password如果看到${MYSQL_PASSWORD}这样的原始占位符说明模板替换没有完成通常是envsubst步骤失败或者.env中的变量名与模板中的不一致。这里再强调一次不要再手动改容器内的service_conf.yaml容器重建后一切手动修改都会丢失正确改法是修改宿主机上的service_conf.yaml.template。整个配置过程走下来我最深的体会是 RAGFlow 这套配置体系其实不复杂但它要求的是一致性思维.env、service_conf.yaml.template、docker-compose.yml三者互相引用任何一处不同步都会在启动若干分钟后才暴露问题而这个时间差恰恰是排查成本最高的地方。从那以后我每次部署都强制走一遍这个流程先列端口分配表、再改.env和模板、跑 YAML 校验、最后用docker inspect验证。希望这套流程能帮你少踩几个我已经踩过的坑。本文还有配套的精品资源点击获取
阅读完成 · 觉得有帮助？
