2 · 快速开始与部署（Getting Started and Deployment）

快速开始与部署（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/infiniflow/ragflow/2-getting-started-and-deployment

翻译时间：2026-05-27T08:44:30.469Z

翻译模型：deepseek-chat

原文字符数：13141

项目：RAGFlow (ragflow)

--- 好的，作为一名资深技术文档翻译专家，我将严格遵循您的要求，对这份 DeepWiki 技术文档进行全文翻译和润色。

---

入门指南与部署

相关源文件

以下文件被用作生成此 Wiki 页面的上下文：

• .github/workflows/release.yml
• .github/workflows/tests.yml
• AGENTS.md
• CLAUDE.md
• Dockerfile
• Dockerfile.deps
• 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-base.yml
• docker/docker-compose.yml
• docker/entrypoint.sh
• docker/infinity_conf.toml
• docs/guides/manage_files.md
• docs/quickstart.mdx
• download_deps.py
• helm/values.yaml
• mcp/client/client.py
• mcp/client/streamable_http_client.py
• mcp/server/server.py
• pyproject.toml
• sdk/python/pyproject.toml
• sdk/python/uv.lock
• uv.lock

本文档概述了 RAGFlow 的部署选项和初始设置流程。内容涵盖系统先决条件、主要部署方法以及运行 RAGFlow 所需的基本配置文件。有关特定部署方法的详细信息，请参阅 Docker Compose 部署、配置管理、文档引擎选择、构建系统与持续集成/持续部署（CI/CD） 以及 Kubernetes 与 Helm 部署。

部署架构总览

RAGFlow 采用容器化的微服务架构，每个服务都在独立的 Docker 容器中运行。该系统由应用服务和支撑数据基础设施服务组成。

基于容器的服务架构

graph TB
    subgraph "应用容器"
        RAGFlow["ragflow-cpu-1<br/>主应用<br/>端口: 80/9380"]
    end

    subgraph "数据基础设施容器"
        ES["es01<br/>Elasticsearch<br/>端口: 1200"]
        MySQL["mysql<br/>MySQL 数据库<br/>端口: 3306"]
        MinIO["minio<br/>对象存储<br/>端口: 9000/9001"]
        Redis["redis<br/>Valkey 缓存/队列<br/>端口: 6379"]
    end

    subgraph "可选容器"
        Infinity["infinity<br/>向量数据库<br/>端口: 23817/23820"]
        Sandbox["sandbox-executor-manager<br/>代码执行<br/>端口: 9385"]
        TEI["tei<br/>嵌入向量服务<br/>端口: 6380"]
    end

    RAGFlow --> ES
    RAGFlow --> MySQL
    RAGFlow --> MinIO
    RAGFlow --> Redis
    RAGFlow -.->|"DOC_ENGINE=infinity"| Infinity
    RAGFlow -.->|"Profile: sandbox"| Sandbox
    RAGFlow -.->|"Profile: tei-cpu"| TEI

    ES -.->|"替代方案"| Infinity

来源： docker/docker-compose-base.yml:1-240, docker/.env:1-175, README.md:141-145

配置文件关系

graph LR
    ENV[".env<br/>环境变量<br/>DOC_ENGINE, DEVICE,<br/>MYSQL_PASSWORD 等"]

    TEMPLATE["service_conf.yaml.template<br/>服务配置模板<br/>使用 ${ENV_VARS}"]

    COMPOSE["docker-compose.yml<br/>服务编排<br/>容器定义"]

    RUNTIME["service_conf.yaml<br/>运行时配置<br/>启动时生成"]

    ENV -->|"变量用于"| TEMPLATE
    ENV -->|"变量用于"| COMPOSE
    TEMPLATE -->|"填充以创建"| RUNTIME

    COMPOSE -->|"启动容器<br/>容器读取"| RUNTIME

来源： docker/.env:1-162, docker/docker-compose-base.yml:10-144

先决条件

部署 RAGFlow 前，必须满足特定的硬件和软件要求。

硬件要求

组件	最低规格
CPU	x86 架构，≥ 4 核
内存	≥ 16 GB
磁盘	≥ 50 GB 可用空间

重要提示： 官方 Docker 镜像仅针对 x86 平台构建 README.md:191-193。ARM64 平台需要自行构建自定义 Docker 镜像 docs/quickstart.mdx:23-26。

来源： README.md:149-155, docs/quickstart.mdx:29-34, README_zh.md:151-155

软件要求

软件	版本要求
Docker	≥ 24.0.0
Docker Compose	≥ v2.26.1
gVisor	可选，仅代码执行器（沙箱）功能需要

来源： README.md:154-155, docs/quickstart.mdx:33-34

系统配置要求

启动 RAGFlow 前，必须配置 vm.max_map_count 内核参数。此设置对 Elasticsearch 和 Infinity 组件的正常运行至关重要 docs/quickstart.mdx:49-51。

所需值： vm.max_map_count ≥ 262144

# 检查当前值
sysctl vm.max_map_count

# 临时设置（重启后失效）
sudo sysctl -w vm.max_map_count=262144

# 永久设置
echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf

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

部署方法

RAGFlow 支持多种部署方法，其中 Docker Compose 是官方推荐的生产环境部署方式，Kubernetes/Helm 则适用于企业级规模。

Docker Compose 部署（推荐）

Docker Compose 部署使用预构建的 Docker 镜像，并编排所有必需的服务。

Docker 镜像选项：

镜像标签	描述	稳定性
v0.25.4	最新的稳定版本	稳定
nightly	持续集成构建版本	不稳定

注意： 从 v0.22.0 版本开始，RAGFlow 镜像不再包含嵌入向量模型，以保持镜像大小可控 docker/.env:161。

docker/.env:162 中的默认配置指定了：

RAGFLOW_IMAGE=infiniflow/ragflow:v0.25.4

有关详细的 Docker Compose 部署说明，请参阅 Docker Compose 部署。

来源： README.md:195-198, docker/.env:161-170, docs/quickstart.mdx:209-217

Kubernetes 与 Helm 部署

对于大规模或云原生环境，RAGFlow 提供了用于在 Kubernetes 上部署的 Helm Chart。这包含了所有核心服务和基础设施的模板 helm/values.yaml。

有关详细的 Kubernetes 部署说明，请参阅 Kubernetes 与 Helm 部署。

基于源码的部署

基于源码的部署直接从 Python 源代码运行 RAGFlow 服务，而支撑基础设施（MySQL、文档存储、MinIO、Redis）则在 Docker 中运行。此方法主要用于开发。

关键组件：

• 由 uv 管理的 Python 环境 Dockerfile:67-81, pyproject.toml:188-199
• 使用 uv.lock 进行依赖管理 uv.lock:1-14
• 多语言构建支持（Python、Go、C++）Dockerfile:45-57, .github/workflows/tests.yml:132-143

有关完整的基于源码的部署说明，请参阅 构建系统与持续集成/持续部署（CI/CD）。

来源： Dockerfile:67-81, pyproject.toml:1-167, README_zh.md:218-228

配置文件

RAGFlow 的行为由位于 docker/ 目录下的主要配置文件控制：

环境变量：.env

docker/.env 文件包含了基本的系统环境变量。关键类别包括：

文档引擎选择：

DOC_ENGINE=${DOC_ENGINE:-elasticsearch}  # 选项：elasticsearch, infinity, oceanbase, opensearch, seekdb

服务凭证：

MYSQL_PASSWORD=infini_rag_flow
MINIO_PASSWORD=infini_rag_flow
REDIS_PASSWORD=infini_rag_flow
ELASTIC_PASSWORD=infini_rag_flow

端口映射：

SVR_WEB_HTTP_PORT=80              # 外部 HTTP 端口
SVR_HTTP_PORT=9380                 # API 服务器端口
ES_PORT=1200                       # Elasticsearch 外部端口
EXPOSE_MYSQL_PORT=3306             # MySQL 外部端口

有关所有环境变量的完整文档，请参阅 配置管理。

来源： docker/.env:1-162, README.md:254-264

容器编排：docker-compose.yml

docker/docker-compose-base.yml 和 docker/docker-compose.yml 文件编排了所有 RAGFlow 服务。它使用 Compose profiles 根据 DOC_ENGINE 和 DEVICE 设置来控制启动哪些服务 docker/.env:28。

来源： docker/docker-compose-base.yml:1-240, docker/.env:28

快速启动步骤

步骤 1：克隆仓库并检出版本

git clone https://github.com/infiniflow/ragflow.git
cd ragflow/docker
git checkout -f v0.25.4

来源： README.md:183-187, docs/quickstart.mdx:186-197

步骤 2：配置系统设置

确保已配置 vm.max_map_count。可选地编辑 docker/.env 以自定义密码或文档引擎。

来源： README.md:162-181, docker/.env:1-111

步骤 3：启动服务

docker compose up -d

来源： README.md:198-209, docs/quickstart.mdx:200-203

步骤 4：验证服务状态

检查主应用容器的日志：

docker logs -f ragflow-server

来源： README.md:220-240, docs/quickstart.mdx:222-242

步骤 5：访问 RAGFlow

使用默认配置，通过 http://IP_OF_YOUR_MACHINE 访问 RAGFlow。

来源： README.md:242-248, docs/quickstart.mdx:244-248

服务架构与数据流

容器服务映射

graph TB
    subgraph "容器: ragflow-cpu-1"
        AppServer["ragflow_server.py<br/>Quart API 服务器<br/>端口: 9380"]
        TaskExec["task_executor.py<br/>后台工作进程<br/>Redis 消费者"]
        GoServer["cmd/server_main.go<br/>Go 后端层<br/>端口: 9384"]
    end

    subgraph "容器: mysql"
        MySQLDB[("MySQL 数据库<br/>rag_flow 模式<br/>元数据存储")]
    end

    subgraph "容器: es01 或 infinity"
        DocStore[("文档存储<br/>向量 + 全文<br/>片段与嵌入向量")]
    end

    subgraph "容器: redis"
        RedisCache[("Valkey/Redis<br/>会话、队列、<br/>任务流")]
    end

    AppServer --> MySQLDB
    AppServer --> DocStore
    AppServer --> RedisCache

    TaskExec --> DocStore
    TaskExec --> RedisCache

    AppServer -->|"发布任务到"| RedisCache
    RedisCache -->|"任务流"| TaskExec

来源： docker/docker-compose-base.yml:5-230, docker/.env:150-156, pyproject.toml:9-167

端口暴露矩阵

服务	容器名称	内部端口	外部端口（默认）	用途
RAGFlow Web	ragflow-cpu-1	80	80	HTTP 访问
RAGFlow API	ragflow-cpu-1	9380	9380	直接 Python API 访问
Go API	ragflow-cpu-1	9384	9384	直接 Go API 访问
Elasticsearch	es01	9200	1200	文档引擎
MySQL	mysql	3306	3306	元数据数据库
MinIO API	minio	9000	9000	对象存储

来源： docker/.env:32-156, docker/docker-compose-base.yml:8-191

文档引擎选择

RAGFlow 支持多种文档存储引擎，包括 Elasticsearch、Infinity、OceanBase、OpenSearch 和 SeekDB。通过 docker/.env:20 中的 DOC_ENGINE 环境变量选择引擎。有关详细的引擎配置和权衡，请参阅 文档引擎选择。

来源： docker/.env:13-20, README.md:276-297

构建与持续集成/持续部署（CI/CD）

该项目使用复杂的构建管线，支持多语言编译。

• Python： 由 uv 管理，实现高性能的依赖解析 Dockerfile:67-81。
• Go： 使用 build.sh --go 编译 .github/workflows/tests.yml:139。
• C++： 分词器和原生组件使用 build.sh --cpp 编译 .github/workflows/tests.yml:138。

更多详情，请参阅 构建系统与持续集成/持续部署（CI/CD）。

来源： Dockerfile:45-57, .github/workflows/tests.yml:132-143, pyproject.toml:188-199

初始设置故障排除

常见问题

问题： 文档解析停滞或 Elasticsearch 连接失败。

• 原因： vm.max_map_count 未正确配置 docs/quickstart.mdx:73-75。
• 解决方案： 验证并在 /etc/sysctl.conf 中永久设置 vm.max_map_count=262144。

问题： 容器因内存错误而无法启动。

• 原因： Docker 内存不足。
• 解决方案： 确保主机有 ≥ 16 GB 内存，并且 docker/.env:65 中的 MEM_LIMIT 设置适当。

来源： docs/quickstart.mdx:73-75, docker/.env:65, README.md:152