# https://github.com/infiniflow/ragflow 项目说明书

生成时间：2026-06-08 05:09:36 UTC

## 目录

- [系统架构与核心 RAG 引擎](#page-1)
- [Agent 系统、组件与编排](#page-2)
- [数据源、文档解析与接入管道](#page-3)
- [部署、配置与运维管理](#page-4)

<a id='page-1'></a>

## 系统架构与核心 RAG 引擎

### 相关页面

相关主题：[Agent 系统、组件与编排](#page-2), [数据源、文档解析与接入管道](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/infiniflow/ragflow/blob/main/README.md)
- [deepdoc/README.md](https://github.com/infiniflow/ragflow/blob/main/deepdoc/README.md)
- [internal/engine/README.md](https://github.com/infiniflow/ragflow/blob/main/internal/engine/README.md)
- [mcp/server/server.py](https://github.com/infiniflow/ragflow/blob/main/mcp/server/server.py)
- [tools/es-to-oceanbase-migration/src/es_ob_migration/schema.py](https://github.com/infiniflow/ragflow/blob/main/tools/es-to-oceanbase-migration/src/es_ob_migration/schema.py)
- [admin/client/README.md](https://github.com/infiniflow/ragflow/blob/main/admin/client/README.md)
- [internal/cli/README.md](https://github.com/infiniflow/ragflow/blob/main/internal/cli/README.md)
- [internal/cli/filesystem/README.md](https://github.com/infiniflow/ragflow/blob/main/internal/cli/filesystem/README.md)
- [tools/firecrawl/README.md](https://github.com/infiniflow/ragflow/blob/main/tools/firecrawl/README.md)
- [tools/chatgpt-on-wechat/plugins/README.md](https://github.com/infiniflow/ragflow/blob/main/tools/chatgpt-on-wechat/plugins/README.md)
</details>

# 系统架构与核心 RAG 引擎

## 概述与设计定位

RAGFlow 是一款开源的检索增强生成（RAG）引擎，将前沿 RAG 与 Agent 能力融合，为大语言模型提供统一的"上下文层"。它面向从个人到大型企业的多种部署规模，主打"Quality in, quality out"——即通过深度文档理解、模板化分块与可追溯引用降低幻觉风险。资料来源：[README.md:1-50](https://github.com/infiniflow/ragflow/blob/main/README.md#L1-L50)。

核心能力由三类特性支撑：
- **深度文档解析**：基于 [deepdoc/README.md](https://github.com/infiniflow/ragflow/blob/main/deepdoc/README.md) 中描述的 *Deep*Doc 视觉与解析引擎，集成 OCR、版面识别（10 种基础布局元素）与表格结构识别（TSR），支持 Word、Excel、PPT、图片、扫描件、结构化数据、网页等异构数据源。
- **模板化分块**：可解释、可干预的智能分块模板，配合可视化的人工干预能力。
- **多路召回与融合重排**：通过 LLM 与 Embedding 模型的可配置组合，实现多次召回 + 融合 rerank。

## 核心 RAG 引擎架构

```mermaid
flowchart LR
    A[异构数据源] --> B[DeepDoc 解析]
    B --> C[模板化分块]
    C --> D[Doc Engine 索引]
    D --> E[多路召回]
    E --> F[融合 Rerank]
    F --> G[LLM 生成]
```

RAGFlow 的核心 RAG 引擎由三层组成：

1. **解析与分块层**：使用 *Deep*Doc 进行视觉与版式识别（OCR / Layout / TSR），再使用 RAGFlow 自带的分块器生成结构化文本块；用户可在界面中查看分块结果并进行人工干预。资料来源：[deepdoc/README.md:15-50](https://github.com/infiniflow/ragflow/blob/main/deepdoc/README.md#L15-L50)。

2. **Doc Engine（文档引擎）**：在 `internal/engine/` 中实现，定义了统一的 `DocEngine` 接口与工厂方法，支持 Elasticsearch 与 Infinity 两种后端；Elasticsearch 实现已完整，Infinity 仍为占位符等待官方 SDK。配置示例（位于 `conf/service_conf.yaml`）如下：

   | 字段 | 说明 | 示例值 |
   |------|------|--------|
   | `doc_engine.type` | 后端类型 | `elasticsearch` / `infinity` |
   | `doc_engine.es.hosts` | ES 节点地址 | `http://localhost:9200` |
   | `doc_engine.es.username` | ES 用户名 | `elastic` |
   | `doc_engine.es.password` | ES 密码 | `infini_rag_flow` |
   | `doc_engine.infinity.uri` | Infinity 服务地址 | `localhost:23817` |

   资料来源：[internal/engine/README.md:1-50](https://github.com/infiniflow/ragflow/blob/main/internal/engine/README.md#L1-L50)。

3. **检索与融合层**：通过 MCP 协议对外暴露检索能力。`mcp/server/server.py` 中的 `ragflow_retrieval` 工具支持 `dataset_ids`、`document_ids`、`question`、`similarity_threshold`、`vector_similarity_weight`、`keyword`、`top_k`、`rerank_id`、`force_refresh` 等参数；后端通过 `GET /datasets` 列出可用数据集，并提供 `resolve_dataset_ids` 进行跨页合并解析。资料来源：[mcp/server/server.py:30-180](https://github.com/infiniflow/ragflow/blob/main/mcp/server/server.py#L30-L180)。

## 数据模型与存储迁移

RAGFlow 在 Elasticsearch 与 Infinity 中存储文档块、关键词与权重。`tools/es-to-oceanbase-migration/src/es_ob_migration/schema.py` 定义了从 ES 到 OceanBase 的字段映射，涵盖 `content_with_weight`（LONGTEXT，原文）、`content_ltks` / `content_sm_ltks`（长文本与细粒度 tokens）、`important_kwd`（ARRAY 关键词）、`question_kwd`（ARRAY 问题）、`tag_feas`（JSON 标签特征）、`pagerank_fea`（Integer 优先级）等关键字段，便于在不同数据库后端之间进行无损迁移。资料来源：[tools/es-to-oceanbase-migration/src/es_ob_migration/schema.py:1-30](https://github.com/infiniflow/ragflow/blob/main/tools/es-to-oceanbase-migration/src/es_ob_migration/schema.py#L1-L30)。

## 运维、扩展与社区演进

- **Admin Service**：独立的 Python 后端服务，提供对 RAGFlow 服务、Task Executor、MySQL、Infinity、Elasticsearch、Redis、MinIO 等依赖组件的实时监控与故障重启能力，并支持用户与 Agent 资源管理。资料来源：[admin/client/README.md:1-40](https://github.com/infiniflow/ragflow/blob/main/admin/client/README.md#L1-L40)。
- **CLI 与虚拟文件系统**：`internal/cli/` 中的虚拟文件系统将 RAGFlow RESTful API 抽象为 `ls`、`cat`、`search`、`install-skill` 等类 shell 命令，并实现了基于正则的多类别安全扫描（信息泄露、注入、破坏性操作、持久化、网络通信、混淆）。资料来源：[internal/cli/filesystem/README.md:1-80](https://github.com/infiniflow/ragflow/blob/main/internal/cli/filesystem/README.md#L1-L80)；CLI 解析器采用手写递归下降实现，与 Python 版本完全兼容。资料来源：[internal/cli/README.md:1-60](https://github.com/infiniflow/ragflow/blob/main/internal/cli/README.md#L1-L60)。
- **第三方集成**：`tools/firecrawl/` 提供 Firecrawl 网页抓取集成，支持单页抓取、整站爬取与批量处理；资料来源：[tools/firecrawl/README.md:1-40](https://github.com/infiniflow/ragflow/blob/main/tools/firecrawl/README.md#L1-L40)。`tools/chatgpt-on-wechat/plugins/` 提供 WeChat/WeCom 的 RAG 聊天插件，将知识检索能力注入到对话场景。资料来源：[tools/chatgpt-on-wechat/plugins/README.md:1-40](https://github.com/infiniflow/ragflow/blob/main/tools/chatgpt-on-wechat/plugins/README.md#L1-L40)。
- **近期演进（社区相关）**：
  - v0.25.6 引入 RAPTOR AHC 模式（Ψ-RAG），将语义从文档级扩展到更细粒度。资料来源：[Release v0.25.6](https://github.com/infiniflow/ragflow/releases/tag/v0.25.6)。
  - v0.25.5 通过移除昂贵的向量获取与 rerank 相似度计算，将数据集检索路径延迟降低 50–100%。资料来源：[Release v0.25.5](https://github.com/infiniflow/ragflow/releases/tag/v0.25.5)。
  - v0.24.0 新增 Memory API/SDK 与 PageIndex（原 ToC）功能。资料来源：[Release v0.24.0](https://github.com/infiniflow/ragflow/releases/tag/v0.24.0)。
  - 社区反馈 Issue #15714 指出 `service.RetrievalTestRequest.TenantRerankID` 与 `SearchBotRetrievalTestRequest.TenantRe…` 在 Go 服务中应为 `*int` 而非 `*string`，提示跨语言协议演进时需关注类型一致性。资料来源：[Issue #15714](https://github.com/infiniflow/ragflow/issues/15714)。
  - Roadmap #4214（v0.21–v0.23）已完成的里程碑包括 Pipeline 编排、MinerU 文档解析集成、Memory 支持等，社区讨论主要集中在 Kubernetes 部署（#864）与 Ollama Rerank 能力（#4406）上。

## See Also

- [项目主页与功能总览](https://github.com/infiniflow/ragflow/blob/main/README.md)
- [DeepDoc 视觉与解析引擎](https://github.com/infiniflow/ragflow/blob/main/deepdoc/README.md)
- [Go Doc Engine 与 Elasticsearch/Infinity 后端](https://github.com/infiniflow/ragflow/blob/main/internal/engine/README.md)
- [MCP 检索服务](https://github.com/infiniflow/ragflow/blob/main/mcp/server/server.py)
- [Admin Service 运维与监控](https://github.com/infiniflow/ragflow/blob/main/admin/client/README.md)
- [CLI 虚拟文件系统与技能管理](https://github.com/infiniflow/ragflow/blob/main/internal/cli/filesystem/README.md)

---

<a id='page-2'></a>

## Agent 系统、组件与编排

### 相关页面

相关主题：[系统架构与核心 RAG 引擎](#page-1), [数据源、文档解析与接入管道](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [agent/canvas.py](https://github.com/infiniflow/ragflow/blob/main/agent/canvas.py)
- [agent/component/base.py](https://github.com/infiniflow/ragflow/blob/main/agent/component/base.py)
- [agent/component/agent_with_tools.py](https://github.com/infiniflow/ragflow/blob/main/agent/component/agent_with_tools.py)
- [agent/component/begin.py](https://github.com/infiniflow/ragflow/blob/main/agent/component/begin.py)
- [agent/component/llm.py](https://github.com/infiniflow/ragflow/blob/main/agent/component/llm.py)
- [agent/component/retrieval.py](https://github.com/infiniflow/ragflow/blob/main/agent/component/retrieval.py)
</details>

# Agent 系统、组件与编排

## 1. 概述与定位

RAGFlow 中的 Agent 子系统是项目面向"上下文引擎 + Agent 能力"融合的核心载体。它允许开发者把 RAG 检索、LLM 推理、工具调用、记忆（Memory）等能力以可视化、可编排的方式组合成可执行的智能体工作流（Agent Canvas），从而将复杂数据处理任务转化为生产可用的 AI 应用 [README.md:1-30]()。

按照 v0.24.0 起官方路线图的描述，Agent 系统持续扩展：

- 引入 Memory 提取与 SDK，便于 Agent 拥有长时记忆能力 [v0.24.0 release notes]()；
- 在 v0.25.4 增加了 Agent 标签管理与筛选能力，强化多 Agent 协作时的组织方式 [v0.25.4 release notes]()；
- 在 v0.25.6 中新增了 **Browser** 组件，使 AI 可自主浏览并操作网页，进一步扩展 Agent 可用工具的边界 [v0.25.6 release notes]()。

整体上，Agent 子系统由三层组成：编排画布（Canvas）、组件基类与具体组件实现、以及驱动组件运行的后端执行引擎。

## 2. 编排画布：Agent Canvas

### 2.1 画布职责

`agent/canvas.py` 定义了 Agent Canvas，是用户在前端搭建 Agent 工作流的运行时模型。Canvas 将一系列"组件节点"组织成一个有向无环图（DAG），并负责：

- 保存节点、边与参数配置；
- 在用户发起对话时按拓扑顺序调度各个组件；
- 将组件输出沿连线传递到下游节点。

### 2.2 典型编排结构

一个最简的 RAG Agent 通常包含三类节点：

| 节点类型 | 作用 |
|---------|------|
| Begin   | 入口节点，接收用户问题与会话上下文 |
| Retrieval | 调用 RAG 检索接口，从数据集召回相关 chunk |
| LLM     | 基于召回内容与提示词模板生成最终回答 |

更复杂的工作流可以加入 Agent 节点、工具调用节点、Memory 节点或 Browser 节点，形成多步推理链。

## 3. 组件基类与执行模型

`agent/component/base.py` 提供了所有 Agent 组件的抽象基类 `ComponentBase`，统一了组件的输入、输出、运行参数和异常处理接口。组件需要实现 `run()` 方法以执行业务逻辑，框架则负责将上游参数注入并把结果派发到下游。

具体组件实现如下：

- `agent/component/begin.py`：Begin 组件，标识工作流的入口与初始变量；
- `agent/component/retrieval.py`：Retrieval 组件，封装对 RAG 检索服务的调用，支持 dataset_ids、document_ids、相似度阈值、top_k、是否启用关键词检索等参数；
- `agent/component/llm.py`：LLM 组件，负责与底层大语言模型交互，执行提示词渲染与对话管理；
- `agent/component/agent_with_tools.py`：Agent 组件的高级形式，能够自主决定是否调用外部工具（Tools）以完成任务，是实现 ReAct 风格推理的关键。

每个组件都遵循统一的输入输出约定，从而可以自由组合，形成可复用的工作流模板。

## 4. 端到端运行流程

下图展示了用户向 Agent 发起一次请求时，各组件的协作时序：

```mermaid
sequenceDiagram
    participant U as 用户
    participant C as Canvas
    participant B as Begin
    participant R as Retrieval
    participant L as LLM/Agent
    U->>C: 提交问题
    C->>B: 初始化上下文
    B-->>C: 输出 user_input
    C->>R: 调用检索服务
    R-->>C: 返回 top-k chunks
    C->>L: 注入 chunks + prompt
    L-->>C: 生成最终回答
    C-->>U: 渲染回答与引用
```

若在 LLM 节点处使用的是 Agent 组件（例如 `agent_with_tools.py`），则 LLM 节点可以根据需要再次调用 Retrieval 节点或外部工具，形成多轮工具调用循环，从而实现"思考—行动—观察"的 Agent 行为模式。

## 5. 与 RAG / Memory / Browser 的协同

Agent 子系统并不是孤立的，它与 RAGFlow 的其他模块紧密协同：

- 与 RAG 检索的协同：`agent/component/retrieval.py` 复用了统一的检索接口，从而可以把任何已接入 RAGFlow 的数据集纳入 Agent 知识库；
- 与 Memory 的协同：根据 v0.24.0 与 v0.23.1 的发布说明，Agent 框架已经支持 Memory 提取与展示，Memory 抽取日志可以在控制台中查看，便于调试和追踪 [v0.24.0 release notes]() [v0.23.1 release notes]()；
- 与 Browser 的协同：v0.25.6 引入的 Browser 组件（[#14888](https://github.com/infiniflow/ragflow/pull/14888)）使 Agent 可以自主导航并与网页交互，进一步扩展了 Agent 的可用工具集合 [v0.25.6 release notes]()。

## 6. 常见失败模式与注意事项

- 组件顺序错误：Canvas 中若存在环路，框架会拒绝执行并提示拓扑错误。`资料来源：[agent/canvas.py:1-120]()`；
- 检索为空：当数据集尚未建立索引或过滤条件过严时，Retrieval 组件会返回空结果，LLM 节点将仅基于用户问题作答，可能产生幻觉；
- Agent 工具调用超时：`agent_with_tools.py` 在调用外部工具时需设置合理的超时与重试策略，否则会阻塞整个工作流；
- Memory 提取失败：v0.23.1 修复了"空 Memory 对象导致服务无法启动"的问题，升级前应清空异常的 Memory 记录 [v0.23.1 release notes]()。

## 7. See Also

- [README.md](https://github.com/infiniflow/ragflow/blob/main/README.md)
- [DeepDoc README](https://github.com/infiniflow/ragflow/blob/main/deepdoc/README.md)
- [MCP Server](https://github.com/infiniflow/ragflow/blob/main/mcp/server/server.py)
- [Release Notes v0.25.6](https://github.com/infiniflow/ragflow/releases/tag/v0.25.6)
- [Release Notes v0.24.0](https://github.com/infiniflow/ragflow/releases/tag/v0.24.0)

---

<a id='page-3'></a>

## 数据源、文档解析与接入管道

### 相关页面

相关主题：[系统架构与核心 RAG 引擎](#page-1), [Agent 系统、组件与编排](#page-2), [部署、配置与运维管理](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [deepdoc/README.md](https://github.com/infiniflow/ragflow/blob/main/deepdoc/README.md)
- [README.md](https://github.com/infiniflow/ragflow/blob/main/README.md)
- [tools/firecrawl/README.md](https://github.com/infiniflow/ragflow/blob/main/tools/firecrawl/README.md)
- [mcp/server/server.py](https://github.com/infiniflow/ragflow/blob/main/mcp/server/server.py)
- [tools/es-to-oceanbase-migration/src/es_ob_migration/schema.py](https://github.com/infiniflow/ragflow/blob/main/tools/es-to-oceanbase-migration/src/es_ob_migration/schema.py)
- [internal/engine/README.md](https://github.com/infiniflow/ragflow/blob/main/internal/engine/README.md)
- [internal/cli/README.md](https://github.com/infiniflow/ragflow/blob/main/internal/cli/README.md)
- [docker/README.md](https://github.com/infiniflow/ragflow/blob/main/docker/README.md)
</details>

# 数据源、文档解析与接入管道

## 概述

RAGFlow 的接入管道由三层组成：**数据源连接器层**（抓取原始文件）、**DeepDoc 文档解析层**（OCR / 版面识别 / TSR 与模板分块）以及 **Doc Engine 存储索引层**（将切块写入 Elasticsearch / Infinity 等后端）。三层通过统一的 Ingestion Pipeline 模板串联，再经 REST API、MCP Server 与虚拟文件系统对外暴露检索能力。整体流水线如下图所示：

```mermaid
flowchart LR
    A[外部数据源<br/>Notion / S3 / Confluence / Firecrawl / SFTP] --> B[Connector Runner]
    B --> C[DeepDoc Vision + Parser]
    C --> D[Template-based Chunking]
    D --> E[Doc Engine<br/>Elasticsearch / Infinity]
    E --> F[REST API / MCP Server / VFS CLI]
```

资料来源：[README.md:1-50]()

## 文档解析（DeepDoc）

DeepDoc 是 RAGFlow 的核心解析模块，由 **vision** 与 **parser** 两部分组成：

- **vision**：负责 OCR、版面识别和 TSR。OCR 从图像或 PDF 中提取文字；版面识别覆盖 Text、Title、Figure、Table、Header、Footer、Reference、Equation 等 10 类元素；TSR 进一步还原表格结构。可通过 `python deepdoc/vision/t_ocr.py` 与 `t_recognizer.py` 单独验证。
- **parser**：基于 vision 结果，按文档模板（论文、简历、书籍等）进行可解释的分块，是 "Template-based chunking" 能力的底层支撑。

DeepDoc 是 RAGFlow 强调 "Quality in, quality out" 与 "Grounded citations" 的关键前提。v0.25.1 又新增了 [OpenDataLoader](https://github.com/opendataloader-project/opendataloader-pdf) PDF 后端，进一步加强解析能力。

资料来源：[deepdoc/README.md:1-60]()

## 数据源连接器

连接器负责将外部系统的文件拉入 RAGFlow。以 `tools/firecrawl` 集成为例，一个标准连接器通常包含：

| 模块 | 职责 |
|---|---|
| `firecrawl_connector.py` | 与上游 API 通信（URL 抓取、整站爬取） |
| `firecrawl_config.py` | API Key、限流与重试配置 |
| `firecrawl_processor.py` | 内容清洗、Markdown 化、转为 RAGFlow 内部文档格式 |
| `firecrawl_ui.py` | 在 RAGFlow UI 中暴露为可选数据源 |

从 v0.25.0 起官方陆续新增 **Seafile、RSS、DingTalk AI Sheet** 等数据源；v0.25.2 引入轻量级快照机制同步 8 种数据源（含 Moodle、钉钉智能表格、RSS）的删除；v0.25.3 为 S3 数据源加入 **ETag 增量同步**；v0.25.4 抽象出 **通用、配置驱动的 RESTful API 数据源连接器**；v0.25.5 在管理面板加入 local 与 SSH provider。

资料来源：[tools/firecrawl/README.md:1-50]()；[v0.25.0 Release Notes](https://github.com/infiniflow/ragflow/releases/tag/v0.25.0)；[v0.25.3 Release Notes](https://github.com/infiniflow/ragflow/releases/tag/v0.25.3)

## Doc Engine 与 chunk schema

解析后文档被切分并写入可检索字段。Go 端 `internal/engine` 定义了 `DocEngine` 接口并提供 Elasticsearch 与 Infinity 两种实现：

```yaml
doc_engine:
  type: elasticsearch
  es:
    hosts: "http://localhost:9200"
    username: "elastic"
    password: "infini_rag_flow"
```

参考 `tools/es-to-oceanbase-migration/src/es_ob_migration/schema.py`，每个 chunk 至少包含：`content_with_weight`（原文）、`content_ltks`/`content_sm_ltks`（全文与细粒度分词）、`important_kwd`/`important_tks`（关键词）、`question_kwd`/`question_tks`（自动生成问题）、`tag_kwd`/`tag_feas`（标签与特征）、`pagerank_fea`（文档优先级）。这些字段共同支撑 RAGFlow 的多路召回与融合重排。

资料来源：[internal/engine/README.md:1-50]()；[tools/es-to-oceanbase-migration/src/es_ob_migration/schema.py:1-40]()

## 外部访问接口

接入管道最终通过三种方式对外暴露：

1. **REST API**：由 Web 后端统一提供，自 v0.25.0 起逐步统一为 RESTful 规范，同时保留对历史端点的向后兼容。
2. **MCP Server**：`mcp/server/server.py` 提供 `list_datasets`、`ragflow_retrieval` 等工具，调用 `/datasets` 解析可访问的 `dataset_ids`，并支持 `document_ids`、`similarity_threshold`、`vector_similarity_weight`、`rerank_id`、`force_refresh` 等参数。失败时统一以 `TextContent` 异常抛出错误消息。
3. **CLI + 虚拟文件系统**：`internal/cli/filesystem` 将 REST API 封装为 `ls`、`cat`、`search` 等命令，路径形如 `/datasets/{name}/{doc}`，便于运维与脚本化操作。

资料来源：[mcp/server/server.py:1-60]()；[internal/cli/README.md:1-40]()

## 常见配置与排错

- **Docker 部署**：使用 `docker/docker-compose.yml` 启动 RAGFlow 主服务，`docker-compose-base.yml` 拉起 Elasticsearch、MySQL、MinIO、Redis 等依赖；`.env` 中 `STACK_VERSION`、`ES_PORT`、`ELASTIC_PASSWORD` 控制 ES 版本与对外暴露端口。资料来源：[docker/README.md:1-40]()
- **OCR / TSR 异常**：先单独运行 `t_ocr.py` 与 `t_recognizer.py` 复现，确认是否属于版面类型未覆盖或图像质量过差。
- **数据源同步遗漏**：检查 v0.25.2 引入的 snapshot 机制是否覆盖该数据源；S3 类型可借助 v0.25.3 的 ETag 优化减少误判。
- **MCP 检索失败**：当 `/datasets` 返回非 200 或 `code != 0` 时，MCP Server 会抛出带 `message` 的异常，外部客户端需据此展示。

## 参见

- DeepDoc 模块说明：[deepdoc/README.md](https://github.com/infiniflow/ragflow/blob/main/deepdoc/README.md)
- Doc Engine 实现：[internal/engine/README.md](https://github.com/infiniflow/ragflow/blob/main/internal/engine/README.md)
- MCP Server：[mcp/server/server.py](https://github.com/infiniflow/ragflow/blob/main/mcp/server/server.py)
- Docker 部署：[docker/README.md](https://github.com/infiniflow/ragflow/blob/main/docker/README.md)
- Firecrawl 集成示例：[tools/firecrawl/README.md](https://github.com/infiniflow/ragflow/blob/main/tools/firecrawl/README.md)
- 路线图讨论：[#4214 ROADMAP 2025](https://github.com/infiniflow/ragflow/issues/4214) 与 [#162 ROADMAP 2024](https://github.com/infiniflow/ragflow/issues/162)

---

<a id='page-4'></a>

## 部署、配置与运维管理

### 相关页面

相关主题：[系统架构与核心 RAG 引擎](#page-1), [数据源、文档解析与接入管道](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/infiniflow/ragflow/blob/main/README.md)
- [internal/engine/README.md](https://github.com/infiniflow/ragflow/blob/main/internal/engine/README.md)
- [internal/cli/README.md](https://github.com/infiniflow/ragflow/blob/main/internal/cli/README.md)
- [internal/cli/filesystem/README.md](https://github.com/infiniflow/ragflow/blob/main/internal/cli/filesystem/README.md)
- [tools/scripts/README.md](https://github.com/infiniflow/ragflow/blob/main/tools/scripts/README.md)
- [mcp/server/server.py](https://github.com/infiniflow/ragflow/blob/main/mcp/server/server.py)
</details>

# 部署、配置与运维管理

RAGFlow 是一个融合 RAG 与 Agent 能力的开源引擎，提供从文档解析、知识抽取到检索增强生成的完整工作流。本页面聚焦于 RAGFlow 的部署形态、配置管理以及日常运维相关的核心内容，帮助运维人员与开发者快速搭建和管理生产环境。

## 部署形态与系统架构

RAGFlow 的部署由多个组件构成：API 服务层、任务调度层、文档解析层、向量检索层以及管理控制台。

```mermaid
graph TB
    A[客户端应用] --> B[API 网关]
    B --> C[RAGFlow 后端服务]
    C --> D[文档引擎]
    C --> E[LLM 提供方]
    C --> F[关系型数据库]
    D --> G[Elasticsearch/Infinity]
    F --> H[MySQL/PostgreSQL]
```

RAGFlow 主要通过 Docker Compose 提供一键部署，根目录的 `docker/docker-compose.yml` 与 `docker/docker-compose-base.yml` 编排了所有依赖服务。资料来源：[README.md:35-45]()。

社区讨论 #864 长期关注 Kubernetes 部署能力，希望通过 Helm Charts 或原生 YAML 方式进行生产部署。截至当前主线版本，官方推荐仍以 docker-compose 为主。资料来源：[Issue #864](https://github.com/infiniflow/ragflow/issues/864)。

## 配置管理

### 文档引擎配置

RAGFlow 的文档引擎（Doc Engine）通过 `conf/service_conf.yaml` 进行配置，目前支持 Elasticsearch 与 Infinity 两种后端。资料来源：[internal/engine/README.md:1-10]()。

Elasticsearch 配置示例：

```yaml
doc_engine:
  type: elasticsearch
  es:
    hosts: "http://localhost:9200"
    username: "elastic"
    password: "infini_rag_flow"
```

Infinity 配置示例：

```yaml
doc_engine:
  type: infinity
  infinity:
    uri: "localhost:23817"
    postgres_port: 5432
    db_name: "default_db"
```

需要注意：Infinity 实现目前为占位状态（等待官方 Go SDK），仅 Elasticsearch 完全可用。资料来源：[internal/engine/README.md:25-35]()。

引擎在服务启动时自动初始化，初始化入口位于 `cmd/server_main.go`。资料来源：[internal/engine/README.md:35-40]()。

### 模型与提供商

近期版本在配置层面持续扩展：v0.25.5 在管理面板新增本地与 SSH 提供商；v0.25.4 加入了 gpt-5.4-mini 与 gpt-5.4-nano；v0.25.6 为 Agent 新增了 Browser 组件。LLM、Embedding、Rerank 等模型均通过声明式配置进行管理，运维人员可在不重启服务的情况下通过管理面板调整部分参数。

## 运维工具

### 数据库 Schema 同步

`tools/scripts/db_schema_sync.py` 提供数据库 schema 同步能力，版本号采用 `vxx.xx.xx` 格式（例如 `v0.25.6`），迁移文件位于 `tools/migrate/{version_dir}/`。资料来源：[tools/scripts/README.md:1-20]()。

常用命令示例：

```bash
# 列出所有迁移
python db_schema_sync.py --list \
    --host localhost --port 3306 --user root --password xxx --database rag_flow \
    --version v0.25.6

# 创建自动检测的迁移
python db_schema_sync.py --create \
    --host localhost --port 3306 --user root --password xxx --database rag_flow \
    --version v0.25.6
```

`--drop` 参数将包含已删除字段的 `DROP COLUMN` 操作（具破坏性，会永久删除数据），生产环境使用前务必备份。资料来源：[tools/scripts/README.md:15-25]()。

### 命令行管理

RAGFlow 提供 SQL 风格的 CLI 工具，覆盖认证、用户、服务、角色、Dataset、模型配置等能力。资料来源：[internal/cli/README.md:1-30]()。

```sql
LOGIN USER 'admin@example.com';
LIST SERVICES;
STARTUP SERVICE 1;
SET DEFAULT LLM 'gpt-4';
```

CLI 解析器采用手写的递归下降方法，未使用 go-yacc，以便更好地控制错误信息、便于扩展与维护，并兼容 Python 版本语法。资料来源：[internal/cli/README.md:30-40]()。

### Skill 管理

`install-skill` 命令支持从本地路径、GitHub、ClawHub、skills.sh 等来源安装技能，实施纵深防御安全策略，包括来源验证（HTTPS + SSL 校验）、隔离、静态扫描（100+ 威胁模式、6 大类）、信任分级、用户确认与审计日志。资料来源：[internal/cli/filesystem/README.md:1-50]()。

技能安装受严格约束：总大小不超过 50 MB、单个文件不超过 5 MB、仅允许文本文件、技能名必须为小写字母数字及连字符/下划线，并自动忽略隐藏文件。资料来源：[internal/cli/filesystem/README.md:50-70]()。

## MCP 服务集成

RAGFlow 提供 MCP（Model Context Protocol）服务器，便于其他 AI 客户端调用其检索能力。`mcp/server/server.py` 实现了与后端 API 的集成，工具 `ragflow_retrieval` 支持 `dataset_ids`、`document_ids`、`question`、`similarity_threshold`、`vector_similarity_weight`、`keyword`、`top_k`、`rerank_id`、`force_refresh` 等参数。资料来源：[mcp/server/server.py:1-50]()。

启动时支持 `HOST` 模式，启用 `AuthMiddleware` 对 API Key 进行认证。`list_datasets` 方法通过分页遍历 `/datasets` 端点（默认 `page_size=1000`）收集可访问数据集 ID，为 MCP 检索提供回退。资料来源：[mcp/server/server.py:50-80]()。

## 部署与运维常见问题

| 类别 | 描述与处理建议 |
|------|----------------|
| Kubernetes 部署 | 社区 #864 讨论了 Helm Charts 需求；当前推荐 docker-compose，K8s 部署需自行编写清单 |
| Elasticsearch 启动失败 | 确认 `conf/service_conf.yaml` 中 `doc_engine.type` 与对应后端配置匹配 |
| 数据库迁移失败 | 检查版本号格式是否为 `vxx.xx.xx`，并避免在生产环境直接使用 `--drop` |
| 模型不可用 | 0.25.4 起新增 gpt-5.4-mini/nano；0.25.5 起新增本地与 SSH 提供商 |
| MCP 检索失败 | 检查 `resolve_dataset_ids` 是否能成功访问 `/datasets`，并核对 API Key 权限 |

## See Also

- [RAGFlow 官方文档](https://ragflow.io/docs/dev/)
- [RAGFlow 路线图](https://github.com/infiniflow/ragflow/issues/12241)
- [GitHub Releases](https://github.com/infiniflow/ragflow/releases)
- [Issue #864: Kubernetes 部署讨论](https://github.com/infiniflow/ragflow/issues/864)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：infiniflow/ragflow

摘要：发现 20 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：配置坑 - 来源证据：[Go] tenant_rerank_id type mismatch: *string should be *int — retrieval_test。

## 1. 配置坑 · 来源证据：[Go] tenant_rerank_id type mismatch: *string should be *int — retrieval_test

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Go] tenant_rerank_id type mismatch: *string should be *int — retrieval_test
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_7154f1df73d9467aa3d747477287e392 | https://github.com/infiniflow/ragflow/issues/15714 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 2. 安全/权限坑 · 来源证据：[Question]: Title Chunker Failure after upgrading to v0.25.6

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Question]: Title Chunker Failure after upgrading to v0.25.6
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_8d8565f17f754fe3a6f7ad1f3b4be33d | https://github.com/infiniflow/ragflow/issues/15525 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

## 3. 安装坑 · 来源证据：Go test files not compiled in CI — missing import undetected

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Go test files not compiled in CI — missing import undetected
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_408303dfb4fb43a781b7dc14724082b9 | https://github.com/infiniflow/ragflow/issues/15751 | 来源类型 github_issue 暴露的待验证使用条件。

## 4. 配置坑 · 失败模式：configuration: v0.23.1

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v0.23.1
- 对用户的影响：Upgrade or migration may change expected behavior: v0.23.1
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.23.1. Context: Observed when using docker
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_38f958bf7c9ad232f6049339e1321be7 | https://github.com/infiniflow/ragflow/releases/tag/v0.23.1 | v0.23.1

## 5. 配置坑 · 失败模式：configuration: v0.24.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v0.24.0
- 对用户的影响：Upgrade or migration may change expected behavior: v0.24.0
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.24.0. Context: Observed when using docker
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_0ca2840fc49d848176cce456864aafa3 | https://github.com/infiniflow/ragflow/releases/tag/v0.24.0 | v0.24.0

## 6. 配置坑 · 失败模式：configuration: v0.25.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v0.25.0
- 对用户的影响：Upgrade or migration may change expected behavior: v0.25.0
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.25.0. Context: Observed when using python, docker
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_7154c897fed0437e0ca58d1f443b8d97 | https://github.com/infiniflow/ragflow/releases/tag/v0.25.0 | v0.25.0

## 7. 配置坑 · 失败模式：configuration: v0.25.1

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v0.25.1
- 对用户的影响：Upgrade or migration may change expected behavior: v0.25.1
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.25.1. Context: Observed during version upgrade or migration.
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_12ff69cd8f090474bcc8768ed255e16a | https://github.com/infiniflow/ragflow/releases/tag/v0.25.1 | v0.25.1

## 8. 配置坑 · 失败模式：configuration: v0.25.2

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v0.25.2
- 对用户的影响：Upgrade or migration may change expected behavior: v0.25.2
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.25.2. Context: Observed when using python
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_7f58552889f29288945720d487e8fbb7 | https://github.com/infiniflow/ragflow/releases/tag/v0.25.2 | v0.25.2

## 9. 配置坑 · 失败模式：configuration: v0.25.3

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v0.25.3
- 对用户的影响：Upgrade or migration may change expected behavior: v0.25.3
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.25.3. Context: Observed when using docker
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_14af37b03860695c40160c241d23e5b1 | https://github.com/infiniflow/ragflow/releases/tag/v0.25.3 | v0.25.3

## 10. 配置坑 · 失败模式：configuration: v0.25.4

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v0.25.4
- 对用户的影响：Upgrade or migration may change expected behavior: v0.25.4
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.25.4. Context: Source discussion did not expose a precise runtime context.
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_026d052ebdc28ef87ab4152d11b96502 | https://github.com/infiniflow/ragflow/releases/tag/v0.25.4 | v0.25.4

## 11. 配置坑 · 失败模式：configuration: v0.25.5

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v0.25.5
- 对用户的影响：Upgrade or migration may change expected behavior: v0.25.5
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.25.5. Context: Observed when using python
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_57690c932d554b7b2b477b7e4564f3f5 | https://github.com/infiniflow/ragflow/releases/tag/v0.25.5 | v0.25.5

## 12. 配置坑 · 失败模式：configuration: v0.25.6

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v0.25.6
- 对用户的影响：Upgrade or migration may change expected behavior: v0.25.6
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.25.6. Context: Observed when using python, cuda
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_e1befbd52e751833a5dab041663c4bf0 | https://github.com/infiniflow/ragflow/releases/tag/v0.25.6 | v0.25.6

## 13. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:730534580 | https://github.com/infiniflow/ragflow | README/documentation is current enough for a first validation pass.

## 14. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:730534580 | https://github.com/infiniflow/ragflow | last_activity_observed missing

## 15. 安全/权限坑 · 下游验证发现风险项

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:730534580 | https://github.com/infiniflow/ragflow | no_demo; severity=medium

## 16. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:730534580 | https://github.com/infiniflow/ragflow | no_demo; severity=medium

## 17. 能力坑 · 失败模式：capability: [Go] tenant_rerank_id type mismatch: *string should be *int — retrieval_test

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: [Go] tenant_rerank_id type mismatch: *string should be *int — retrieval_test
- 对用户的影响：Developers may hit a documented source-backed failure mode: [Go] tenant_rerank_id type mismatch: *string should be *int — retrieval_test
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Go] tenant_rerank_id type mismatch: *string should be *int — retrieval_test. Context: Observed when using python
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_a84cfda4f8786aaff3acbf0072fb4c08 | https://github.com/infiniflow/ragflow/issues/15714 | [Go] tenant_rerank_id type mismatch: *string should be *int — retrieval_test

## 18. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:730534580 | https://github.com/infiniflow/ragflow | issue_or_pr_quality=unknown

## 19. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:730534580 | https://github.com/infiniflow/ragflow | release_recency=unknown

## 20. 维护坑 · 失败模式：maintenance: nightly

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: nightly
- 对用户的影响：Upgrade or migration may change expected behavior: nightly
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: nightly. Context: Source discussion did not expose a precise runtime context.
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_57bc13a92eaec92fbf9f0b315ce0baec | https://github.com/infiniflow/ragflow/releases/tag/nightly | nightly

<!-- canonical_name: infiniflow/ragflow; human_manual_source: deepwiki_human_wiki -->