企业官网建设流程全解析

简介：这份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 a+r /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 detected，Docker 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_count=262144 # 永久生效 echo "vm.max_map_count=262144" | 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_IMAGE=infiniflow/ragflow:v0.15.0 SVR_HTTP_PORT=9380 MYSQL_PASSWORD=infini_rag_flow MINIO_PASSWORD=infini_rag_flow ES_PORT=1200 TIMEZONE=Asia/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_PASSWORD=xxx，它会覆盖.env里的值。这个特性在调试时有用，但也容易造成「我明明改了 .env 怎么不生效」的翻车现场。排查时先docker compose config看一下最终解析出来的配置，比猜要快得多。

3.2 systemd 从文件加载环境变量：服务器常驻场景

如果你希望 RAGFlow 随系统启动，用 systemd 管理 compose 是个常见做法。systemd 加载环境变量有两种方式：Environment=直接写，或者EnvironmentFile=从文件读。后者更适合管理多个变量：

# /etc/systemd/system/ragflow.service [Unit] Description=RAGFlow Docker Compose Requires=docker.service After=docker.service network-online.target Wants=network-online.target [Service] Type=oneshot RemainAfterExit=yes WorkingDirectory=/opt/ragflow/docker EnvironmentFile=/opt/ragflow/docker/.env ExecStart=/usr/bin/docker compose up -d ExecStop=/usr/bin/docker compose down TimeoutStartSec=300 [Install] WantedBy=multi-user.target

这里EnvironmentFile指向的就是.env，systemd 会把它读进来作为进程环境变量，再传给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-server

docker 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/json"

API key 在页面右上角用户设置里生成。如果这个请求返回 401，检查 key 是否正确；返回 502，说明 ragflow-server 没起来或者端口不对；返回 500，去看docker compose logs ragflow-server里的堆栈。API 通了，才说明整套服务链路是完整的。

4.3 批量处理文件的配置要点

RAGFlow 的批量解析能力依赖任务队列和 worker 数量。在service_conf.yaml里可以调整相关参数：

# 任务相关配置 worker: num: 4 timeout: 600

worker.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_count=262144；Windows 上在 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_PASSWORD=prod_strong_pwd export MINIO_PASSWORD=prod_minio_pwd export SVR_HTTP_PORT=9380 export ES_PORT=1200 export TIMEZONE=Asia/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', encoding='utf-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(f"YAML 解析失败: {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 解析技巧、智能体编排都是顺水推舟的事。希望帮到你。

本文还有配套的精品资源，点击获取