agentic_huge_data_base / wiki
页面 RAGFlow · 2 快速开始与部署·DeepWiki 中文全文译文
DeepWiki 中文译文 / RAGFlow / 2

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

复杂文档理解与引用检索 · 聚焦本章的模块关系、源码依据与实现要点。

项目RAGFlow 章节2 状态全文译文 模块安装与启动、测试、发布与运维、配置治理、系统架构
项目要点页2.5 参考项目 项目章节目录RAGFlow DeepWiki 原始章节Getting Started and Deployment 上一章1 下一章2.1
源码线索
  • .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
模块标签
  • 安装与启动
  • 测试、发布与运维
  • 配置治理
  • 系统架构
  • 界面与交互

章节正文

快速开始与部署

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

入门指南与部署

相关源文件

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

  • .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 容器中运行。该系统由应用服务和支撑数据基础设施服务组成。

基于容器的服务架构
RAGFlow · 基于容器的服务架构 · 图 1
RAGFlow · 基于容器的服务架构 · 图 1

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

配置文件关系
RAGFlow · 配置文件关系 · 图 2
RAGFlow · 配置文件关系 · 图 2

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

先决条件

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

硬件要求
组件最低规格
CPUx86 架构，≥ 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

服务架构与数据流

容器服务映射
RAGFlow · 容器服务映射 · 图 3
RAGFlow · 容器服务映射 · 图 3

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

端口暴露矩阵
服务容器名称内部端口外部端口（默认）用途
RAGFlow Webragflow-cpu-18080HTTP 访问
RAGFlow APIragflow-cpu-193809380直接 Python API 访问
Go APIragflow-cpu-193849384直接 Go API 访问
Elasticsearches0192001200文档引擎
MySQLmysql33063306元数据数据库
MinIO APIminio90009000对象存储

来源： 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