简介这份PDF文档面向具备Docker基础、希望部署或深入理解RAGFlow配置的技术人员系统梳理了基于Docker的RAGFlow部署与配置方法。内容围绕环境变量与系统级服务配置展开涵盖.env中Elasticsearch、MySQL、MinIO、Redis等组件的端口、密码与内存限制设定service_conf.yaml.template中API服务器、数据库连接、对象存储及OAuth、默认LLM等参数说明并给出更新HTTP服务端口、重启容器使配置生效的操作指引。同时针对不同环境补充了时区设置、Hugging Face镜像站点、macOS优化及非官方维护Compose文件的选用提醒。资源包为1个PDF文件大小约121KB结构紧凑便于查阅。目前已有4463人学习下载适合需要快速搭建RAGFlow环境、按实际需求调整各项配置的研发与运维人员参考可帮助读者理解关键参数含义、规避配置误区并规划生产环境停机窗口。1. 从一次端口冲突说起RAGFlow 的 Docker 部署到底在配什么很多人第一次部署 RAGFlow卡住的地方不是模型跑不起来而是docker compose up -d之后浏览器打不开页面。我遇到最多的一种情况是宿主机上已经跑着 Nginx 或者别的服务占用了 80 端口而 RAGFlow 的docker-compose.yml默认就把 HTTP 服务映射到80:80容器看起来是起来了访问却一直转圈。这类问题的根源基本都能追溯到三个文件.env、service_conf.yaml.template、docker-compose.yml。它们分别管环境变量、系统级服务配置和容器编排理解了这三层RAGFlow 的 Docker 部署才算真正落地。这份配置指南面向的是已经对 Docker 有基本操作能力、准备把 RAGFlow 跑在自己机器或服务器上的技术人员。它不教你 Docker 怎么装而是把 RAGFlow 这套多容器应用Elasticsearch、MySQL、MinIO、Redis 加上 RAGFlow 本体的配置项拆开讲清楚每个环境变量控制什么、改哪个文件、改完怎么生效、哪些 Compose 文件官方没维护要自己担风险。下面按「先看懂文件分工再动手改配置最后排坑」的顺序展开。2. 三个配置文件的分工.env、service_conf 模板与 compose 编排2.1 .env 负责容器级环境变量.env是 Docker Compose 默认读取的环境变量文件RAGFlow 用它来给各个依赖服务设定端口、密码、版本号这些「容器启动前就要确定」的值。它和service_conf.yaml.template的区别在于.env里的变量是给 Docker 编排层用的决定容器怎么起、端口怎么映射而模板文件里的变量是给 RAGFlow 应用进程用的决定应用连哪个数据库、用哪个 LLM。常见做法是先把.env复制一份再改避免直接动原始文件。下面这段是 Elasticsearch、MySQL、MinIO、Redis 四类依赖的核心变量我按用途分组列出来# Elasticsearch STACK_VERSION8.11.3 # ES 版本默认 8.11.3 ES_PORT1200 # ES 暴露到宿主机的端口默认 1200 ELASTIC_PASSWORDinfini_rag_flow # ES 密码 # Kibana KIBANA_PORT6601 # Kibana 暴露端口默认 6601 KIBANA_USERrag_flow KIBANA_PASSWORDinfini_rag_flow # 资源限制 MEM_LIMIT8073741824 # 单容器最大内存字节约 7.5GB # MySQL MYSQL_PASSWORDinfini_rag_flow MYSQL_PORT5455 # MySQL 暴露端口默认 5455 # MinIO MINIO_CONSOLE_PORT9001 # MinIO 控制台端口 MINIO_PORT9000 # MinIO API 端口 MINIO_USERrag_flow MINIO_PASSWORDinfini_rag_flow # Redis REDIS_PORT6379 REDIS_PASSWORDinfini_rag_flow # RAGFlow 本体 SVR_HTTP_PORT9380 # RAGFlow HTTP API 端口默认 9380 RAGFLOW_IMAGEinfiniflow/ragflow:v0.18.0-slim # 镜像版本 TIMEZONEAsia/Shanghai逻辑说明这些变量在docker compose up时被 compose 文件引用最终注入到各容器。参数上要特别注意MEM_LIMIT它默认约 7.5GB如果你的机器内存小于 16GBES 加 MySQL 加 MinIO 一起跑很容易触发 OOM建议按实际内存调低或者干脆只保留 slim 镜像不跑内置嵌入模型。ES_PORT、MYSQL_PORT这些端口是暴露给宿主机的如果宿主机上已经有服务占用改这里比改 compose 文件更省事。2.2 service_conf.yaml.template 负责应用级系统配置这个模板文件在容器启动时会被渲染成service_conf.yaml渲染过程会替换掉里面所有环境变量占位符从而实现「同一份镜像不同环境不同配置」。它由 RAGFlow 的 API 服务器和任务执行器共同读取管的是应用连什么、用什么。ragflow: host: 0.0.0.0 # 容器内 API 监听地址 port: 9380 # 容器内 API 端口 mysql: name: rag_flow user: root password: ${MYSQL_PASSWORD} port: 3306 # 容器内 MySQL 端口注意不是宿主机的 5455 max_connections: 100 stale_timeout: 30 minio: user: ${MINIO_USER} password: ${MINIO_PASSWORD} host: minio:9000 # 容器内通过服务名访问逻辑说明这里最容易搞混的是端口。mysql.port写的是容器内部的 3306不是.env里暴露到宿主机的 5455minio.host用的是 Docker 网络里的服务名minio不是localhost。如果你把这里改成localhost:9000容器内根本连不上 MinIO因为 localhost 指向的是 RAGFlow 容器自己。max_connections默认 100并发解析大量文档时可以适当调高但要和 MySQL 实际承载能力匹配。2.3 docker-compose.yml 与 base 文件的关系docker-compose.yml定义 RAGFlow 本体和依赖的编排docker-compose-base.yml单独定义依赖项Elasticsearch/Infinity、MySQL、MinIO、Redis的环境。这种拆分的好处是依赖层和本体层可以独立更新。要改默认 HTTP 端口直接改docker-compose.yml里的端口映射services: ragflow: ports: - 8080:80 # 把默认的 80:80 改成 8080:80改完之后必须重启所有容器才生效命令是docker compose -f docker/docker-compose.yml up -d注意官方明确没有主动维护docker-compose-CN-oc9.yml、docker-compose-gpu-CN-oc9.yml、docker-compose-gpu.yml这几个文件用它们出问题要自己担。生产环境建议只用官方维护的主 compose 文件需要 GPU 或特定区域镜像时优先通过.env里的RAGFLOW_IMAGE换镜像地址而不是换整个 compose 文件。3. 按场景改配置端口、内存、时区与镜像源3.1 端口冲突的排查与改法RAGFlow 涉及的端口不少80HTTP 服务、9380API、1200ES、5455MySQL、9000/9001MinIO、6379Redis、6601Kibana。部署前先查一遍宿主机占用ss -tlnp | grep -E :(80|9380|1200|5455|9000|9001|6379|6601)\b如果 80 被占改docker-compose.yml的80:80为你的端口:80如果 1200、5455 这些被占改.env里对应的ES_PORT、MYSQL_PORT。改完统一重启docker compose -f docker/docker-compose.yml down docker compose -f docker/docker-compose.yml up -d逻辑说明down再up比直接up -d更稳妥因为端口映射变更后旧容器不会自动重建。参数上你的端口建议选 1024 以上未被占用的端口避免和系统服务抢。3.2 内存限制与时区设置MEM_LIMIT默认 8073741824 字节约 7.5GB。这个值针对的是单个容器ES 本身就很吃内存。如果机器只有 8GB建议把它降到 4GB 左右同时考虑用 slim 镜像减少嵌入模型的内存占用。时区通过TIMEZONE控制默认Asia/Shanghai如果你的日志时间对不上先检查这里。# 查看当前容器内存使用 docker stats --no-stream # 修改 .env 后重启 MEM_LIMIT4294967296 TIMEZONEAsia/Shanghai逻辑说明docker stats能实时看到每个容器的内存占用如果 ES 长期接近上限说明MEM_LIMIT给低了或者数据量太大。时区不对会导致任务执行器记录的时间戳偏移排查定时任务时容易被误导。3.3 镜像拉取与 HuggingFace 访问RAGFLOW_IMAGE默认是infiniflow/ragflow:v0.18.0-slimslim 版不含嵌入模型完整版v0.18.0内置了BAAI/bge-large-zh-v1.5和maidalun1020/bce-embedding-base_v1。如果拉取镜像慢可以换成国内镜像地址# nightly-slim 版本 RAGFLOW_IMAGEswr.cn-north-4.myhuaweicloud.com/infiniflow/ragflow:nightly-slim # 或 RAGFLOW_IMAGEregistry.cn-hangzhou.aliyuncs.com/infiniflow/ragflow:nightly-slimHuggingFace 访问受限时取消.env里HF_ENDPOINT的注释并填入镜像站点。macOS 用户如果遇到文件系统性能问题可以取消MACOS那行的注释启用优化。逻辑说明换镜像地址只改.env一行不用动 compose 文件这是最安全的做法HF_ENDPOINT影响的是模型下载和容器编排无关。3.4 OAuth 与默认 LLM 的启用service_conf.yaml.template里的oauth和user_default_llm默认都是关闭的需要手动取消注释。OAuth 目前支持 GitHub要去 GitHub 开发者设置页拿client_id和secret_key。默认 LLM 支持 OpenAI、DeepSeek、Moonshot、Tongyi-Qianwen、VolcEngine、ZHIPU-AI填对应的api_key即可。user_default_llm: factory: DeepSeek api_key: sk-xxxxxxxx逻辑说明factory的值必须是上面列出的供应商之一拼写错误会导致新用户登录后没有默认模型可用。api_key需要提前在对应平台申请这里只是配置入口不负责申请。4. 部署避坑五条血泪经验4.1 现象容器全起来了但页面打不开原因docker-compose.yml默认80:80宿主机 80 被占或者防火墙没放行。解决先ss -tlnp | grep :80确认占用改映射端口为你的端口:80再检查防火墙规则。4.2 现象ES 容器反复重启原因MEM_LIMIT给太低或者宿主机vm.max_map_count不满足 ES 要求。解决调高MEM_LIMIT并在宿主机执行sysctl -w vm.max_map_count262144写入/etc/sysctl.conf持久化。4.3 现象RAGFlow 连不上 MySQL原因把service_conf.yaml.template里的mysql.port改成了宿主机的 5455。解决容器内互连必须用容器端口 3306宿主机端口只在外部访问时用。4.4 现象改了配置不生效原因只改了文件没重启容器或者只重启了 RAGFlow 没重启依赖。解决配置变更后统一docker compose -f docker/docker-compose.yml up -d让所有相关容器重建。4.5 现象用了非官方 compose 文件后各种异常原因docker-compose-CN-oc9.yml、docker-compose-gpu.yml等官方不维护版本可能和当前镜像不匹配。解决回到官方主 compose 文件需要换镜像就改.env里的RAGFLOW_IMAGE不要换整个编排文件。5. 验证部署是否真正可用从容器状态到 API 连通性部署完别急着用先按顺序验证一遍。第一步看容器状态docker compose -f docker/docker-compose.yml ps五个服务ragflow、es、mysql、minio、redis都应该是running或healthy。第二步验证 API 端口curl -I http://localhost:9380返回 HTTP 响应头说明 API 服务在监听。第三步验证 MinIO 控制台能打开浏览器访问http://宿主机IP:9001用.env里的MINIO_USER和MINIO_PASSWORD登录能看到存储桶说明对象存储正常。第四步进 RAGFlow 页面传一个小文件做解析能走完流程才算真正可用。我自己的习惯是每次改完配置先docker compose config检查一遍渲染后的 compose 文件有没有语法问题再up -d。这个命令能把.env变量替换后的最终配置打出来端口映射、环境变量一目了然比直接启动再排查省事得多。从那以后我每次动.env或模板文件都强制走一遍config加ps加curl这三步翻车的次数明显少了。希望帮到你。本文还有配套的精品资源点击获取