RAGFlow Docker 部署配置详解

RAGFlow 的 Docker 部署涉及 4 个核心配置文件：docker-compose.yml、docker-compose-base.yml、.env 和 service_conf.yaml.template。理解它们的分工和协作关系，是顺利部署以及对接企业现有环境的关键。

一、两个 Compose 文件的分工

RAGFlow 将 Docker Compose 配置拆分为两个文件，通过 include 指令组合：

1. docker-compose-base.yml — 基础依赖服务

定义 RAGFlow 运行所需的第三方中间件：MySQL、Redis、MinIO、Elasticsearch、Infinity、OpenSearch、OceanBase、SeekDB 等。这些服务通过 Docker Compose Profile 机制控制是否启动：

• 无 profile 限制（始终启动）：MySQL、MinIO、Redis —— 这三个是 RAGFlow 运行的必要依赖。
• 按 profile 按需启动：各文档检索引擎（es01 → elasticsearch、infinity → infinity、opensearch01 → opensearch、oceanbase → oceanbase、seekdb → seekdb），以及 sandbox-executor-manager（profile: sandbox）、TEI 文本嵌入服务（profile: tei-cpu / tei-gpu）。

2. docker-compose.yml — RAGFlow 主服务

这是部署的入口文件，包含：

• include: ./docker-compose-base.yml —— 将基础依赖全部引入。
• ragflow-cpu（profile: cpu）和 ragflow-gpu（profile: gpu）—— RAGFlow 主服务，二选一启动。
• deepdoc（profile: deepdoc）—— 独立的文档视觉解析服务。

实际启动哪些服务，由 .env 中的 COMPOSE_PROFILES 变量决定。

---

二、Profile 机制：如何控制启动哪些服务

COMPOSE_PROFILES 的构成

.env 中通过变量组合自动生成 COMPOSE_PROFILES：

DEVICE=cpu                        # 或 gpu
DOC_ENGINE=elasticsearch          # 可选: infinity, opensearch, oceanbase, seekdb
COMPOSE_PROFILES=${DOC_ENGINE},${DEVICE}

假设 DOC_ENGINE=elasticsearch、DEVICE=cpu，则 COMPOSE_PROFILES=elasticsearch,cpu，Docker Compose 只会启动匹配这些 profile 的服务：es01（elasticsearch profile）和 ragflow-cpu（cpu profile），外加无 profile 的 MySQL、MinIO、Redis。

按需启用的扩展 Profile

除文档引擎和设备类型外，以下 profile 需要在 .env 中手动追加到 COMPOSE_PROFILES：

Profile	作用	对应服务
deepdoc	独立的文档视觉解析服务（OCR/TSR/DLR），与主服务解耦	deepdoc
tei-cpu / tei-gpu	Text Embeddings Inference 文本嵌入服务，加速海量文档向量化	tei
sandbox	Agent 代码沙箱执行环境（基于 gVisor），支持运行 Python/JS 代码	sandbox-executor-manager

使用示例：

# 同时启用 Infinity 引擎 + GPU 推理 + Sandbox
COMPOSE_PROFILES=infinity,gpu,sandbox

---

三、.env 文件：环境变量与功能开关

.env 不仅是密码配置，更是系统特性的控制中枢。关键变量：

变量	默认值	说明
DOC_ENGINE	elasticsearch	文档检索引擎选择
DEVICE	cpu	DeepDoc 推理设备（cpu / gpu）
RAGFLOW_IMAGE	infiniflow/ragflow:latest	主服务镜像版本
STACK_VERSION	8.11.3	Elasticsearch 版本
MYSQL_PASSWORD	infini_rag_flow	MySQL 密码
REDIS_PASSWORD	infini_rag_flow	Redis 密码
MINIO_USER / MINIO_PASSWORD	rag_flow / infini_rag_flow	MinIO 凭证
SVR_HTTP_PORT	9380	API 服务端口
SVR_WEB_HTTP_PORT	80	Web UI 端口
API_PROXY_SCHEME	—	API 路由模式（python / go / hybrid）
SANDBOX_ENABLED	—	设为 1 启用 Agent 代码沙箱

关于 API_PROXY_SCHEME：RAGFlow 主镜像内同时包含 Python（Quart）和 Go（Gin）两套 API 服务。API_PROXY_SCHEME 控制 Nginx 将请求路由到哪个后端：python 全部走 Python，go 全部走 Go，hybrid 按端点分流。Go 服务承担高性能场景（搜索、分词、文档摄取），Python 负责 Agent 编排等复杂业务逻辑。这不是需要额外部署的独立服务，而是主镜像内置的组件。

---

四、对接企业现有中间件

如果你的公司已有 MySQL、Redis、ES 等高可用集群，不需要 Docker 重新部署这些服务。

标准操作步骤

1. 禁用不需要的容器服务：

• 对于有 profile 的服务（如 es01），只需不在 COMPOSE_PROFILES 中包含对应 profile 即可。
• 对于无 profile 的基础服务（MySQL、MinIO、Redis），需要在 docker-compose-base.yml 中将其注释掉，或通过 docker compose 的 --scale 等机制处理。

2. 修改 service_conf.yaml.template：

该模板文件使用 ${VAR:-default} 语法进行环境变量替换。在容器启动时，entrypoint.sh 会读取 .env 中的变量，替换模板生成最终的 service_conf.yaml。

连接外部服务的关键配置项：

mysql:
  name: '${MYSQL_DBNAME:-rag_flow}'
  user: '${MYSQL_USER:-root}'
  password: '${MYSQL_PASSWORD:-infini_rag_flow}'
  host: '${MYSQL_HOST:-mysql}'        # 改为公司 MySQL 地址
  port: 3306

redis:
  db: 1
  password: '${REDIS_PASSWORD:-infini_rag_flow}'
  host: '${REDIS_HOST:-redis}:6379'    # 改为公司 Redis 地址

es:
  hosts: 'http://${ES_HOST:-es01}:9200' # 改为公司 ES 地址
  username: '${ES_USER:-elastic}'
  password: '${ELASTIC_PASSWORD:-infini_rag_flow}'

3. 重启服务：

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

---

五、Agent 代码沙箱（Sandbox）

RAGFlow 的 Agent 支持通过"Code"组件执行 Python 和 JavaScript 代码。出于安全考虑，代码运行在独立的沙箱容器中（基于 gVisor 的 runsc 运行时）。

启用步骤

1. 安装 gVisor（runsc）并配置 Docker runtime。
2. 在 .env 中设置：

   SANDBOX_ENABLED=1
   COMPOSE_PROFILES=${DOC_ENGINE},${DEVICE},sandbox
   

3. 拉取沙箱基础镜像：

   docker pull infiniflow/sandbox-base-python:latest
   docker pull infiniflow/sandbox-base-nodejs:latest
   

4. 在 RAGFlow 管理后台的 Admin → Sandbox Settings 中选择 self_managed 并测试连接。

注意：Sandbox 要求 Docker ≥ 25.0、Docker Compose ≥ 2.26.1，且目前仅在 Linux 下完整支持 gVisor。

---

总结

文件	职责
docker-compose.yml	部署入口，定义 RAGFlow 主服务 + deepdoc，通过 include 引入基础依赖
docker-compose-base.yml	基础依赖服务池，通过 profile 控制按需启动
.env	环境变量与功能开关（引擎选择、算力调度、扩展 profile 组合）
service_conf.yaml.template	后端服务配置模板，支持 ${VAR:-default} 语法对接外部服务

理解这 4 个文件的协作关系，无论是单机快速体验还是对接企业基础设施，都能按需调整。

关于非 Docker 部署：本文以官方 Docker Compose 部署方式为基准展开，但文中涉及的服务依赖关系（MySQL、Redis、MinIO、文档检索引擎）、环境变量（.env 中的各项配置）以及 service_conf.yaml 配置项本身与部署方式无关。即便企业采用裸机、Kubernetes 或其他容器编排方案部署，这些依赖关系和配置参数是通用的，只需按其对应规则完成配置即可。

---

（END）