2.1 · Docker Compose 部署（Docker Compose Deployment）

Docker Compose 部署

Docker Compose 部署

相关源文件

本章引用的主要源码文件：

• AGENTS.md
• CLAUDE.md
• Dockerfile.scratch.oc9
• README.md
• README_ar.md
• README_fr.md
• README_id.md
• README_ja.md
• README_ko.md
• README_pt_br.md
• README_tr.md
• README_tzh.md
• README_zh.md
• agent/tools/code_exec.py
• docker/.env
• docker/README.md
• docker/docker-compose-CN-oc9.yml
• docker/docker-compose-macos.yml
• docker/docker-compose.yml
• docker/entrypoint.sh
• docs/guides/manage_files.md
• docs/quickstart.mdx
• mcp/client/client.py
• mcp/client/streamable_http_client.py
• mcp/server/server.py

本文档记录了 RAGFlow 的 Docker Compose 部署架构，包括服务配置、容器编排、网络和存储管理。关于配置选项和环境变量的相关细节，请参阅配置管理。关于选择文档存储引擎的指导，请参考文档引擎选择。

概述

RAGFlow 利用 Docker Compose 将多个容器化服务编排成一个统一的应用栈。此部署主要通过两个 Compose 文件控制：

• docker-compose.yml – 主编排文件，用于设置 RAGFlow 应用容器。
• docker-compose-base.yml – 定义依赖服务，包括数据库和存储引擎。

Docker Compose 的 profiles（配置文件）功能用于根据所选的文档引擎（例如 Elasticsearch、Infinity）和硬件设备类型（CPU 或 GPU）来选择性激活服务。

来源：docker/docker-compose.yml:1-135，docker/docker-compose-base.yml:1-245，README.md:141-145，docs/quickstart.mdx:186-203

服务架构

以下是 RAGFlow Docker Compose 部署中主要组件的高层示意图，其布局从面向用户的层，经过核心应用服务，再到持久化存储。该图明确地将自然语言空间概念与相应的代码实体和文件名关联起来。

图例说明：

• ragflow_server.py：提供 RAGFlow API 的主要 Python 后端服务。
• task_executor.py：处理异步任务（如索引和嵌入向量生成）的后台工作进程。
• mcp/server/server.py：管理对话上下文的 MCP（模型上下文协议）服务。
• admin_server.py：暴露管理 API 的管理服务。
• sandbox-executor-manager：管理沙箱化代码执行组件。
• cmd/server_main.go：可选启用的 Go 语言服务组件。

来源：docker/docker-compose-base.yml:1-245，docker/.env:10-28，docker/docker-compose.yml:5-109，README.md:141-145

核心服务组件

文档存储服务（基于 Profile）

RAGFlow 的文档存储层使用互斥的 Docker Compose profiles 实现。以下文档引擎服务中，有且仅有一个会被激活，由 .env 文件中的 DOC_ENGINE 环境变量控制：

环境变量 DOC_ENGINE 也会通过 COMPOSE_PROFILES 激活配对的 profile（详见 docker/.env:20-28）。

来源：docker/docker-compose-base.yml:2-146，docker/.env:10-28

持久化数据服务

MySQL 服务（mysql）

MySQL 容器作为 RAGFlow 的权威元数据存储，管理用户、数据集、文档和运行时元数据。

• 镜像：mysql:8.0.39
• 数据库名称：根据环境变量配置为 rag_flow
• 健康检查：使用 mysqladmin ping 在依赖服务启动前确认其可用性。
• 数据持久化卷：mysql_data

来源：docker/docker-compose-base.yml:176-202，docker/.env:109-123

MinIO 服务（minio）

MinIO 是一个高性能、兼容 S3 的对象存储服务，用于存储上传的文件和文档图片。

• 镜像：pgsty/minio:RELEASE.2026-03-25T00-00-00Z
• 端口：控制台端口为 ${MINIO_CONSOLE_PORT}（默认 9001），API 端口为 ${MINIO_PORT}（默认 9000）
• 凭证：通过 MINIO_USER 和 MINIO_PASSWORD 环境变量管理
• 数据持久化卷：minio_data

来源：docker/docker-compose-base.yml:204-223，docker/.env:125-138

Redis 服务（redis）

Redis 通过 Redis Streams 支持后台任务编排，并为 RAGFlow 提供缓存功能。

• 镜像：valkey/valkey:8（Valkey 8 Redis 发行版）
• 配置：采用 allkeys-lru 策略，缓存最大内存限制为 128MB
• 端口：通过 ${REDIS_PORT}（默认 6379）暴露
• 密码：由 REDIS_PASSWORD 控制

来源：docker/docker-compose-base.yml:225-245，docker/.env:140-146

应用服务

主 RAGFlow 应用运行在 ragflow-cpu 或 ragflow-gpu 容器中，通过 DEVICE 环境变量选择用于 CPU 或 GPU 工作负载。

• 镜像：由 RAGFLOW_IMAGE 指定（默认为 infiniflow/ragflow:v0.25.4）
• Profiles：cpu 或 gpu 决定启动哪个服务
• GPU 支持：ragflow-gpu 服务部署时启用了 Nvidia 设备预留和 GPU 能力

可以通过传递命令参数来启用其他服务功能，例如：

• --enable-mcpserver 启用 MCP 服务组件
• --enable-adminserver 启动管理服务

暴露的端口包括 HTTP、管理 API、MCP 服务和 Go 后端端口（如果启用了 Go 服务）。

来源：docker/docker-compose.yml:5-109，docker/.env:22-28

配置系统

RAGFlow 使用模板驱动的配置设置，将 Docker 环境变量桥接到服务运行时配置中。

入口点脚本：entrypoint.sh

entrypoint.sh 脚本是容器的入口点，负责：

1. 解析 service_conf.yaml.template，并将环境变量占位符替换到活跃的 service_conf.yaml 中。
2. 根据 API_PROXY_SCHEME（python、go 或 hybrid）选择适当的 Nginx 配置文件。
3. 编排以下服务的启动：
   • Web 服务（使用 Quart 框架的 ragflow_server.py）
   • 后台任务执行器（task_executor.py）
   • 管理服务（admin_server.py，如果启用）
   • MCP 服务（如果启用）
4. 支持通过 CLI 标志配置启动选项，例如启用/禁用 Web 服务、任务执行器、数据同步、管理服务、MCP 服务以及超级用户初始化。

该脚本还负责设置主机 ID、初始化日志记录，以及在失败时管理服务重启。

来源：docker/entrypoint.sh:1-216，api/ragflow_server.py:140-160

部署流程

前置条件检查

• 硬件要求：
  • CPU：最低 4 核（x86_64 架构）
  • 内存：最低 16 GB（Elasticsearch 和 OceanBase 为内存密集型）
  • 磁盘：最低 50 GB 可用空间
• 软件要求：
  • Docker >= 24.0.0
  • Docker Compose >= v2.26.1
• 系统内核设置：
  • Elasticsearch 和 Infinity 要求主机内核参数 vm.max_map_count 至少为 262144：

$ sysctl vm.max_map_count
# 如果小于 262144，请设置：
$ sudo sysctl -w vm.max_map_count=262144

如需永久设置，请将 vm.max_map_count=262144 添加到 /etc/sysctl.conf 文件中。

来源：README_zh.md:162-181，docs/quickstart.mdx:44-82

标准部署步骤

1. 克隆 RAGFlow 仓库并进入 docker 目录：

git clone https://github.com/infiniflow/ragflow.git
cd ragflow/docker

1. 根据需要配置 .env 变量，特别是：

• RAGFLOW_IMAGE – Docker 镜像标签/版本
• DOC_ENGINE – 文档引擎选择（默认为 elasticsearch）
• DEVICE – cpu 或 gpu

1. 启动 Docker Compose 环境：

docker compose up -d

这将启动整个 RAGFlow 服务栈，包括依赖服务和应用容器。

来源：README.md:183-203，docs/quickstart.mdx:186-203

网络和端口映射

RAGFlow 在主机上暴露多个端口，这些端口映射到容器内的服务：

来源：docker/.env:148-156，docker/docker-compose.yml:31-38，docker/docker-compose-base.yml:154

卷和数据持久化

持久化数据使用 Docker 命名卷和绑定挂载来存储：

• ragflow-logs：挂载到 /ragflow/logs，用于应用日志。
• service_conf.yaml.template：挂载到 /ragflow/conf/service_conf.yaml.template，用于外部化配置模板编辑。
• mysql_data：持久化 MySQL 数据库文件。
• minio_data：存储 MinIO 对象存储数据（上传的文档和图片）。
• esdata01：存储 Elasticsearch 索引数据。
• infinity_data：持久化 Infinity 数据库数据。

这些卷确保了数据在容器重启后的持久性。

来源：docker/docker-compose.yml:39-45，docker/docker-compose-base.yml:1-245

故障排查

• 架构支持：官方 RAGFlow Docker 镜像仅为 x86_64 平台构建。如果在 ARM64 上运行，您必须按照构建指南自行构建 Docker 镜像 README.md:191-193，docs/quickstart.mdx:23-26。
• 内存要求：Elasticsearch、OceanBase 和其他文档引擎需要足够的内存。请确保至少有 16GB 可用内存；并相应地在 .env 中配置 MEM_LIMIT。
• 超级用户初始化：在 Docker Compose 覆盖中，将 --init-superuser 传递给 entrypoint.sh 命令，以预填充管理员用户。
• 沙箱运行时：运行代码执行器组件需要在主机上安装 gVisor，并在 Docker Compose 中启用 sandbox profile docker/docker-compose-base.yml:148-174，docs/quickstart.mdx:34。
• Elasticsearch 配置（vm.max_map_count）：如果遇到与 ES 集群的连接错误，请按照上述说明检查内核设置。

来源：README.md:152-193，docs/quickstart.mdx:23-34，docker/entrypoint.sh:11-33，docker/docker-compose-base.yml:148-174

本详细指南涵盖了 RAGFlow 容器化服务的完整 Docker Compose 部署流程、配置和架构布局。有关高级部署策略，包括 Kubernetes 和 Helm，请参阅 Kubernetes 和 Helm 部署。