RAGFlow-00-总览

0. 摘要

项目目标与核心能力

RAGFlow 是一款领先的开源检索增强生成（Retrieval-Augmented Generation, RAG）引擎，通过融合前沿的 RAG 技术与 Agent 能力，为大型语言模型提供卓越的上下文层。该项目为企业提供端到端的 RAG 工作流，支持从个人应用到大规模企业级应用的全场景部署。

核心能力包括：

  • 基于深度文档理解的知识提取，支持 PDF、Word、Excel、PPT、图片等多种复杂格式
  • 模板化文本切片与可视化调整，保证输出可控与可解释
  • 向量检索与全文检索融合，支持多路召回与重排序
  • 可编排的 Agent 工作流，支持工具调用、代码执行等高级能力
  • 图 RAG（GraphRAG）与知识图谱抽取，提供结构化知识表示
  • 可编程的数据处理 Pipeline，支持自定义解析、分割、提取逻辑

问题域与边界

核心问题域：

  • 非结构化文档的深度理解与知识提取
  • 大规模文本的高效索引与精准检索
  • RAG 流程的端到端自动化与可观测性
  • 多模态内容（文本、图片、表格）的统一处理
  • 企业级知识库的管理与权限控制

非目标：

  • 不提供 LLM 模型训练能力，依赖外部 LLM 服务
  • 不处理实时流式数据，专注于文档型知识管理
  • 不提供独立的向量数据库实现，依赖 Elasticsearch/Infinity

运行环境与部署形态

技术栈：

  • 后端语言：Python 3.10-3.12
  • Web 框架：Flask + Flask-Login + Flask-Session
  • 前端：React + TypeScript + Ant Design
  • 数据存储：MySQL/PostgreSQL（元数据）、Elasticsearch/Infinity（向量与全文）、MinIO/S3（对象存储）、Redis（缓存与任务队列）
  • 异步处理：Trio（异步框架）、Redis Stream（任务队列）
  • 容器化：Docker + Docker Compose

部署形态：

  • 标准部署：Docker Compose 多容器部署（ragflow-server、task-executor、MySQL、ES、Redis、MinIO）
  • 源码启动：开发模式下可直接运行 Python 服务
  • 可选组件：Sandbox 执行器（gVisor 隔离）、Infinity 向量引擎

资源要求：

  • CPU >= 4 核
  • 内存 >= 16 GB
  • 磁盘 >= 50 GB
  • GPU（可选，用于加速 Embedding 与 DeepDoc）

1. 整体架构图

flowchart TB
    subgraph "客户端层"
        WebUI[Web 前端<br/>React SPA]
        SDK[Python SDK]
        API_Client[API 客户端]
    end

    subgraph "API 网关层"
        Flask[Flask Server<br/>ragflow_server.py]
        Auth[认证授权<br/>Flask-Login + JWT]
        Router[路由分发<br/>Blueprint]
    end

    subgraph "业务服务层"
        UserSvc[用户/租户服务<br/>UserService]
        KBSvc[知识库服务<br/>KnowledgebaseService]
        DocSvc[文档服务<br/>DocumentService]
        DialogSvc[对话服务<br/>ConversationService]
        CanvasSvc[Agent 画布服务<br/>Canvas]
        PluginMgr[插件管理<br/>PluginManager]
    end

    subgraph "核心引擎层"
        RAGEngine[RAG 引擎<br/>rag/]
        AgentEngine[Agent 引擎<br/>agent/canvas.py]
        DeepDoc[文档解析引擎<br/>deepdoc/parser/]
        GraphRAG[图 RAG 引擎<br/>graphrag/]
        Pipeline[数据 Pipeline<br/>rag/flow/pipeline.py]
    end

    subgraph "LLM 抽象层"
        ChatModel[对话模型<br/>ChatModel]
        EmbedModel[Embedding 模型<br/>EmbeddingModel]
        RerankModel[重排模型<br/>RerankModel]
        CVModel[视觉模型<br/>CVModel]
    end

    subgraph "任务执行层"
        TaskExecutor[任务执行器<br/>task_executor.py]
        RedisQueue[Redis Stream<br/>任务队列]
        Sandbox[代码沙箱<br/>sandbox/executor_manager]
    end

    subgraph "数据存储层"
        MySQL[(MySQL/PG<br/>元数据)]
        ES[(Elasticsearch/Infinity<br/>向量+全文)]
        MinIO[(MinIO/S3<br/>文件存储)]
        Redis[(Redis<br/>缓存+队列)]
    end

    WebUI --> Flask
    SDK --> Flask
    API_Client --> Flask

    Flask --> Auth
    Auth --> Router
    Router --> UserSvc
    Router --> KBSvc
    Router --> DocSvc
    Router --> DialogSvc
    Router --> CanvasSvc
    Router --> PluginMgr

    KBSvc --> RAGEngine
    DocSvc --> DeepDoc
    DocSvc --> Pipeline
    DialogSvc --> RAGEngine
    DialogSvc --> AgentEngine
    CanvasSvc --> AgentEngine
    KBSvc --> GraphRAG

    RAGEngine --> ChatModel
    RAGEngine --> EmbedModel
    RAGEngine --> RerankModel
    AgentEngine --> ChatModel
    DeepDoc --> CVModel
    GraphRAG --> EmbedModel

    DocSvc -.推送任务.-> RedisQueue
    RedisQueue --> TaskExecutor
    TaskExecutor --> DeepDoc
    TaskExecutor --> Pipeline
    TaskExecutor --> GraphRAG
    AgentEngine -.代码执行.-> Sandbox

    UserSvc --> MySQL
    KBSvc --> MySQL
    DocSvc --> MySQL
    DialogSvc --> MySQL

    RAGEngine --> ES
    GraphRAG --> ES
    Pipeline --> ES

    DeepDoc --> MinIO
    DocSvc --> MinIO

    TaskExecutor --> Redis
    AgentEngine --> Redis
    Auth --> Redis

架构要点说明

1. 分层职责

  • API 网关层：统一请求入口，处理认证、路由、限流、CORS；Flask 多 Blueprint 架构，按业务域拆分路由（user_app、kb_app、dialog_app 等）
  • 业务服务层：封装业务逻辑，操作数据模型，调用核心引擎；Service 层采用 Peewee ORM 操作 MySQL，提供事务与原子性保证
  • 核心引擎层：独立的功能模块，无状态设计，可被多处复用；RAG/Agent/DeepDoc/GraphRAG 互相解耦，通过明确接口交互
  • LLM 抽象层：统一的模型调用接口，屏蔽 OpenAI/Azure/本地模型差异；支持模型切换、流式输出、Token 计数、缓存
  • 任务执行层：异步任务处理，避免阻塞 API 请求；Redis Stream 实现分布式任务队列，支持多消费者、故障重试
  • 数据存储层：职责分离，MySQL 存元数据，ES/Infinity 存向量+倒排索引，MinIO 存原始文件，Redis 存缓存与会话

2. 数据流与控制流

  • 同步路径：Web UI → API → Service → MySQL → 返回（用户/知识库管理）
  • 异步路径：API → 推送任务到 Redis → TaskExecutor 消费 → DeepDoc 解析 → Pipeline 切片 → ES 索引
  • 查询路径：API → RAG Engine → ES 检索 → Rerank → LLM 生成 → 流式返回
  • Agent 路径：API → Agent Engine → 执行 Graph DSL → 工具调用/代码执行 → LLM → 返回结果

3. 跨进程/跨线程边界

  • 进程边界：ragflow_server（API）与 task_executor（任务执行）为独立进程，通过 Redis 通信
  • 线程边界：Flask 线程池处理 HTTP 请求；Trio nursery 管理 Agent/Pipeline 异步任务
  • 协程边界：Agent 与 Pipeline 使用 Trio 异步框架，避免阻塞 I/O

4. 高可用与扩展性

  • 无状态设计：ragflow_server 无状态，可水平扩展；Session 存储在 Redis，支持多实例负载均衡
  • 任务队列：Redis Stream 支持消费者组，多个 task_executor 并行消费，提高吞吐
  • 数据分片：Elasticsearch 自带分片能力，支持集群部署
  • 缓存策略：LLM 响应缓存、Embedding 缓存、文档元数据缓存，降低延迟与成本

5. 状态管理

  • 用户状态：Flask-Session + Redis 存储 Session，支持登录态保持
  • 任务状态：Task 表记录任务进度（progress）、状态（status）、错误信息（error_message）
  • 对话状态：Conversation 表存储多轮对话上下文，Message 表记录消息历史
  • Agent 状态：Graph DSL 中 globals 存储全局变量，history 存储执行路径

2. 全局时序图（主要业务闭环）

2.1 文档上传与解析时序

sequenceDiagram
    autonumber
    participant U as 用户/Web UI
    participant API as Flask API
    participant DocSvc as DocumentService
    participant MinIO as MinIO 存储
    participant Redis as Redis 队列
    participant TaskExec as TaskExecutor
    participant DeepDoc as DeepDoc 解析器
    participant Pipeline as Pipeline
    participant ES as Elasticsearch

    U->>API: POST /v1/documents/upload
    API->>DocSvc: save_file()
    DocSvc->>MinIO: 上传文件
    MinIO-->>DocSvc: 返回文件路径
    DocSvc->>MySQL: 插入 Document 记录
    DocSvc->>Redis: 推送解析任务
    DocSvc-->>API: 返回 doc_id
    API-->>U: 201 Created

    Redis->>TaskExec: 拉取任务
    TaskExec->>MinIO: 下载文件
    TaskExec->>DeepDoc: 调用解析器（PDF/Docx/Excel）
    DeepDoc-->>TaskExec: 返回解析结果（文本+布局）

    TaskExec->>Pipeline: 运行 Pipeline DSL
    Pipeline->>Pipeline: Tokenizer 分词
    Pipeline->>Pipeline: Splitter 切片
    Pipeline->>Pipeline: Extractor 提取实体
    Pipeline->>EmbedModel: 批量 Embedding
    EmbedModel-->>Pipeline: 返回向量

    Pipeline->>ES: 批量索引 chunks
    ES-->>Pipeline: 确认索引成功
    Pipeline->>MySQL: 更新 Document.progress
    TaskExec->>Redis: 更新任务状态
    TaskExec-->>U: （WebSocket/Polling）通知完成

时序要点说明：

  1. 入口鉴权：API 层通过 @login_required 或 @token_required 装饰器校验用户身份，从 Session/Authorization Header 提取用户信息
  2. 幂等性：Document 表有唯一约束（tenant_id + name），重复上传同名文件会返回已存在记录，避免重复解析
  3. 异步解耦：API 立即返回，TaskExecutor 后台处理；用户通过轮询 /documents/{doc_id} 查询进度（progress 字段 0-1）
  4. 回退策略：解析失败时 Task.progress = -1，error_message 记录详情；用户可重试或删除文档
  5. 重试点：Redis Stream 支持 ACK 机制，TaskExecutor 崩溃后未 ACK 的任务会被重新分配
  6. 超时设定：TaskExecutor 使用 @timeout 装饰器，单文档解析超时 3 小时；Pipeline 组件有独立超时（如 Embedding 20 秒）
  7. 资源上界：Pipeline 批量 Embedding 时限制 batch_size（默认 64），避免 OOM；ES bulk 索引限制单批次大小（10MB）

2.2 RAG 对话查询时序

sequenceDiagram
    autonumber
    participant U as 用户/Web UI
    participant API as Flask API
    participant DialogSvc as ConversationService
    participant RAG as RAG Engine
    participant ES as Elasticsearch
    participant Rerank as Rerank 模型
    participant LLM as ChatModel
    participant MySQL as MySQL

    U->>API: POST /v1/chats/{chat_id}/completions
    API->>DialogSvc: create_message(question)
    DialogSvc->>MySQL: 插入 Message 记录
    DialogSvc->>RAG: retrieval(query, kb_ids)

    RAG->>RAG: 改写查询（关键词提取）
    RAG->>ES: 混合检索（vector + full-text）
    ES-->>RAG: 返回候选 chunks（top 200）

    RAG->>Rerank: 重排序（query + chunks）
    Rerank-->>RAG: 返回重排结果（top 10）

    RAG->>LLM: chat(system_prompt, history, chunks)
    LLM-->>RAG: 流式返回（SSE）
    RAG-->>API: 流式响应
    API-->>U: SSE stream

    LLM->>DialogSvc: 保存 Assistant 回复
    DialogSvc->>MySQL: 更新 Message.answer

时序要点说明：

  1. 幂等键策略：Message 表的 id 为客户端生成的 UUID，重复提交相同 id 会返回已存在结果，避免重复计费
  2. 并发控制：对话级别无锁，允许多用户并发查询；知识库级别使用 Redis 分布式锁，防止并发修改配置
  3. 失败重试：ES 查询失败重试 3 次（指数退避），LLM 调用失败根据错误码决定是否重试（429/503 重试，400 不重试）
  4. 超时策略：ES 检索超时 30 秒，Rerank 超时 10 秒，LLM 流式超时 5 分钟；任一环节超时返回降级响应
  5. 流式边界：LLM 使用 SSE 流式返回，前端逐 Token 渲染；后端在流结束后统一保存完整答案到数据库

2.3 Agent 工作流执行时序

sequenceDiagram
    autonumber
    participant U as 用户
    participant API as Flask API
    participant Agent as AgentEngine (Graph)
    participant Begin as Begin 组件
    participant Tool as Tool 组件
    participant LLM as LLM 组件
    participant Sandbox as Sandbox 执行器
    participant Answer as Answer 组件

    U->>API: POST /v1/agents/{agent_id}/run
    API->>Agent: Graph.run(query, files)
    Agent->>Begin: 初始化全局变量
    Begin-->>Agent: 输出 query

    loop 执行路径
        Agent->>LLM: invoke(system, history)
        LLM->>LLM: 判断是否需要工具调用
        alt 需要工具
            LLM-->>Agent: 返回工具名与参数
            Agent->>Tool: invoke(tool_name, args)
            alt 代码执行工具
                Tool->>Sandbox: execute_code(code, language)
                Sandbox-->>Tool: 返回执行结果
            else 检索工具
                Tool->>ES: 检索知识库
                ES-->>Tool: 返回结果
            end
            Tool-->>Agent: 输出工具结果
            Agent->>LLM: invoke(history + tool_result)
        else 无需工具
            LLM-->>Agent: 返回最终答案
        end
    end

    Agent->>Answer: invoke(final_answer)
    Answer-->>Agent: 格式化输出
    Agent-->>API: 返回结果
    API-->>U: 200 OK

时序要点说明：

  1. Graph DSL：Agent 采用有向无环图（DAG）表示工作流，每个节点是一个组件（Component），边表示数据流
  2. 状态传递：组件间通过 output() 方法传递数据，上游输出作为下游 invoke() 的 **kwargs 输入
  3. 条件分支：Switch 组件根据条件选择下游路径；Categorize 组件实现多分类路由
  4. 循环控制：Iteration 组件支持循环执行子图，直到满足退出条件（如工具调用结束）
  5. 错误处理：组件执行失败时 error() 返回错误信息，Graph 捕获后终止执行并返回错误
  6. 可观测性：每次组件调用记录日志到 Redis，前端可实时获取执行轨迹

3. 模块边界与交互图

3.1 模块清单

序号 模块名称 目录路径 核心职责 对外 API 提供方式 主要依赖
01 API 模块 api/ HTTP API 网关、路由、认证、业务服务编排 REST API（Flask Blueprint） MySQL, Redis, Service 层
02 RAG 模块 rag/ 向量检索、重排、生成、NLP 预处理 Python 函数库 ES/Infinity, LLM, Embedding
03 Agent 模块 agent/ Agent 工作流引擎、组件编排 Python 类库 LLM, Redis, Sandbox
04 DeepDoc 模块 deepdoc/ 文档解析（PDF/Docx/Excel/PPT） Python 函数库 CV Model, OCR, Layout 模型
05 GraphRAG 模块 graphrag/ 知识图谱抽取、社区发现、图检索 Python 函数库 ES, LLM, Embedding
06 Admin 模块 admin/ 管理后台服务（独立微服务） gRPC/REST API MySQL, Redis
07 Sandbox 模块 sandbox/ 代码执行沙箱（Docker + gVisor） gRPC API Docker, gVisor
08 Plugin 模块 plugin/ 插件管理、LLM 工具插件 Python 插件接口 PluginLib

3.2 模块交互矩阵

调用方 → 被调方 API RAG Agent DeepDoc GraphRAG Admin Sandbox Plugin
API - ✓ 同步 ✓ 同步 ✗（通过 Task） ✗（通过 Task） ✓ HTTP ✗ ✓ 同步
RAG ✗ - ✗ ✗ ✗ ✗ ✗ ✗
Agent ✗ ✓ 同步 - ✗ ✗ ✗ ✓ gRPC ✓ 同步
DeepDoc ✗ ✗ ✗ - ✗ ✗ ✗ ✗
GraphRAG ✗ ✓ 同步 ✗ ✗ - ✗ ✗ ✗
TaskExecutor ✗ ✓ 同步 ✗ ✓ 同步 ✓ 同步 ✗ ✗ ✗

交互说明：

  • ✓ 同步：函数调用，同进程内
  • ✓ 异步：通过消息队列/事件
  • ✓ HTTP/gRPC：跨进程 RPC 调用
  • ✗：无直接调用关系

3.3 关键交互场景

场景 1：文档上传与解析

API（同步）→ DocumentService → 推送任务到 Redis
TaskExecutor（异步消费）→ DeepDoc → Pipeline → ES
  • 一致性：最终一致，Task 表记录进度
  • 错误语义：解析失败不回滚文档记录，允许重试

场景 2：RAG 对话

API（同步）→ ConversationService → RAG Engine → ES/LLM → 流式返回
  • 一致性：强一致，事务内完成 Message 记录
  • 错误语义：LLM 失败返回错误码，前端展示错误提示

场景 3：Agent 工具调用

API（同步）→ AgentEngine → Tool 组件 → Sandbox（gRPC）→ 返回结果
  • 一致性：无需持久化，内存状态
  • 错误语义：Sandbox 超时/失败时返回错误，Agent 继续执行或终止

场景 4：GraphRAG 构建

TaskExecutor（异步）→ GraphRAG → LLM（抽取实体）→ ES（存储图谱）
  • 一致性：最终一致，增量更新图谱
  • 错误语义：抽取失败跳过当前 chunk，不影响其他

4. 关键设计与权衡

4.1 数据一致性

强一致性场景：

  • 用户登录态：Session 存储在 Redis，单点写入，读写一致
  • 对话消息：Message 表插入后立即可查询，事务保证
  • 权限控制：基于 tenant_id 的行级权限，查询时强制过滤

最终一致性场景：

  • 文档解析进度：Task 表异步更新，前端轮询获取最新进度
  • 向量索引：ES 写入后有短暂延迟（refresh_interval 1s），检索可能不包含最新数据
  • 统计信息：知识库文档数、Token 数等定期更新，非实时

事务边界：

  • MySQL 事务：单个 Service 方法内，保证元数据原子性（如创建知识库+初始化配置）
  • 无分布式事务：文件上传到 MinIO 与 MySQL 记录插入非事务，依赖幂等重试

4.2 锁与并发策略

Redis 分布式锁：

  • 文档解析任务：避免同一文档被多个 TaskExecutor 同时处理
  • 知识库配置更新：防止并发修改 parser_config
  • 实现：RedisDistributedLock 基于 SET NX EX，支持超时自动释放

乐观并发控制：

  • Document.update_time 作为版本标识，更新时校验 WHERE update_time = old_time
  • 失败时返回 409 Conflict，客户端需重新读取后重试

无锁设计：

  • ES 查询无锁，支持高并发读
  • LLM 调用无状态，可并发请求
  • Agent 执行为独立 Graph 实例，互不干扰

4.3 性能关键路径与可观测性

P95 延迟目标：

  • 文档上传（小于 10MB）：< 2 秒
  • RAG 检索（不含 LLM）：< 500ms
  • LLM 生成（流式首 Token）：< 3 秒
  • Agent 单轮执行：< 10 秒

内存峰值：

  • DeepDoc 解析单个 PDF：< 2GB
  • Embedding 批处理：batch_size * vector_dim * 4 bytes（如 64 * 768 * 4 = 196KB）
  • Agent Graph：< 100MB（大型复杂工作流）

I/O 热点：

  • ES 检索：混合查询需同时访问向量与倒排索引，优化 shard 数量与副本数
  • MinIO 下载：大文件下载慢，TaskExecutor 使用流式读取
  • Redis：LLM 缓存命中率影响 QPS，设置合理 TTL（1 小时）

可观测性指标：

  • API 层：请求 QPS、延迟分布（P50/P95/P99）、错误率（4xx/5xx）
  • Task 层：队列深度、任务执行时长、失败率
  • ES 层：查询延迟、索引速率、集群健康状态
  • LLM 层：Token 消耗量、缓存命中率、错误类型分布

指标采集：

  • 日志：Python logging 模块，结构化日志（JSON）输出到文件
  • 监控：可集成 Prometheus（需自行实现 exporter）
  • 追踪：Langfuse 集成（可选），记录 LLM 调用链路

4.4 配置项与可变参数

核心配置文件：

  • docker/.env：环境变量（端口、密码、镜像版本）
  • docker/service_conf.yaml.template：服务配置（LLM API Key、Embedding 模型、数据库连接）
  • api/settings.py：运行时配置（日志级别、超时、限流）

影响行为的关键配置：

配置项 默认值 影响 调优建议
DOC_ENGINE elasticsearch 向量引擎选择（elasticsearch/infinity） Infinity 性能更高，需单独部署
EMBEDDING_BATCH_SIZE 64 Embedding 批处理大小 根据 GPU 显存调整，越大吞吐越高
DOC_MAXIMUM_SIZE 256MB 单文档最大大小 超大文档拆分后上传
MAX_CONTENT_LENGTH 1GB HTTP 请求体上限 根据文件大小需求调整
SVR_QUEUE_NAME ragflow_svr Redis 队列名 多租户可用不同队列隔离
LLM_TIMEOUT 300s LLM 调用超时 长文本生成需增大

5. 典型使用示例与最佳实践

5.1 最小可运行入口示例

场景：快速启动并创建第一个知识库与对话

# 1. 启动服务
cd ragflow/docker
docker compose up -d

# 2. 等待服务就绪
docker logs -f ragflow-server | grep "Running on all addresses"

# 3. 访问 Web UI
# 浏览器打开 http://localhost
# 注册用户并登录

# 4. 使用 Python SDK
pip install ragflow-sdk

from ragflow_sdk import RAGFlow

# 初始化客户端
client = RAGFlow(api_key="YOUR_API_KEY", base_url="http://localhost/api/v1")

# 创建知识库
kb = client.create_dataset(
    name="我的知识库",
    embedding_model="BAAI/bge-large-zh-v1.5",
    chunk_method="naive"
)

# 上传文档
doc = kb.upload_file(file_path="./example.pdf")

# 等待解析完成
while doc.progress < 1.0:
    doc.refresh()
    time.sleep(2)

# 创建对话
chat = client.create_chat(name="测试对话", dataset_ids=[kb.id])

# 提问
response = chat.ask(question="文档的主要内容是什么?")
print(response.answer)

5.2 扩展点/插件接入标准流程

场景：自定义 LLM 工具插件

# 1. 创建插件文件 plugin/embedded_plugins/my_tool.py
from plugin.common import ToolBaseModel, ToolResponseModel
from pydantic import Field

class MyToolInput(ToolBaseModel):
    """我的工具输入"""
    query: str = Field(..., description="查询关键词")
    limit: int = Field(10, description="返回数量")

class MyTool:
    """自定义工具实现"""
    
    def __init__(self):
        self.name = "my_tool"
        self.description = "我的自定义工具"
        
    def __call__(self, query: str, limit: int = 10, **kwargs) -> ToolResponseModel:
        """工具执行逻辑"""
        # 实现自定义逻辑
        results = self.do_search(query, limit)
        
        return ToolResponseModel(
            content="\n".join(results),
            metadata={"count": len(results)}
        )
    
    def do_search(self, query: str, limit: int):
        """具体搜索实现"""
        # 调用外部 API 或本地检索
        return [f"结果 {i}: {query}" for i in range(limit)]

# 2. 注册插件（plugin/__init__.py）
from plugin.embedded_plugins.my_tool import MyTool

EMBEDDED_PLUGINS = {
    "my_tool": MyTool,
    # ... 其他插件
}

# 3. 在 Agent 中使用
# Web UI → Agent 画布 → 添加 Tool 组件 → 选择 my_tool

插件规范：

  • 输入参数使用 Pydantic BaseModel 定义，提供 JSON Schema
  • 返回 ToolResponseModel，包含 content（文本）与 metadata（结构化数据）
  • 支持异步（定义为 async def）或同步
  • 错误通过抛出异常传递，Agent 会捕获并记录

5.3 规模化/上线注意事项清单

部署架构：

  • 小规模（< 1000 用户）：单机 Docker Compose，4 核 16GB 足够
  • 中等规模（1000-10000 用户）：
    • ragflow-server 水平扩展（2-4 实例），Nginx 负载均衡
    • task-executor 独立部署（2-4 实例），增加并发处理能力
    • MySQL 读写分离，Redis 哨兵模式
    • ES 集群（3 节点，1 主 2 副本）
  • 大规模（> 10000 用户）：
    • Kubernetes 部署，HPA 自动扩缩容
    • MySQL 分库分表（按 tenant_id 分片）
    • ES 独立集群（> 5 节点），使用 ILM 管理索引生命周期
    • MinIO 分布式集群，使用 CDN 加速

性能调优：

  • ES 优化：增加 shard 数、启用 adaptive replica selection、调整 refresh_interval
  • Redis 优化：使用 Redis Cluster，避免单点瓶颈；设置 maxmemory-policy allkeys-lru
  • LLM 优化：启用缓存、设置合理的 max_tokens、使用批量 API
  • Embedding 优化：使用 GPU 加速、增大 batch_size、启用模型量化

安全加固：

  • 网络隔离：MySQL/Redis/ES 仅内网可访问，不暴露公网端口
  • 数据加密：MinIO 启用服务端加密（SSE），HTTPS 传输
  • 权限控制：API Token 定期轮换，Session 超时时间 7 天
  • 审计日志：记录敏感操作（删除知识库、修改配置）到独立日志

监控告警：

  • 关键指标：
    • API 5xx 错误率 > 1% 告警
    • Task 队列积压 > 1000 告警
    • ES 集群健康状态非 green 告警
    • LLM 调用失败率 > 5% 告警
  • 日志聚合：使用 ELK/Loki 统一收集日志，支持全文检索
  • 追踪分析：集成 Langfuse/LangSmith 分析 LLM 调用链路与成本

备份恢复：

  • MySQL：每日全量备份 + binlog 增量备份，保留 30 天
  • ES：使用 Snapshot API 定期快照到 S3/MinIO，支持按知识库恢复
  • MinIO：启用版本控制，定期同步到异地存储
  • 配置文件：纳入 Git 版本管理，使用 GitOps 部署

灰度发布：

  • 使用蓝绿部署，先发布到灰度环境验证
  • 按 tenant_id 比例灰度（如 5% → 20% → 50% → 100%）
  • 监控灰度期间错误率与延迟，有问题快速回滚

6. 版本信息与演进

当前版本：v0.21.0（2025-10-15）

主要演进历程：

  • v0.21.0：支持可编排的数据管道（Pipeline）
  • v0.20.0：支持 Agentic 工作流与 MCP 协议
  • v0.19.0：新增 Python/JS 代码执行器（Sandbox）
  • v0.18.0：支持跨语言查询（Cross-language）
  • v0.17.0：PDF/DOCX 图片多模态解析
  • v0.16.0：Deep Research 推理能力（结合 Tavily 搜索）

技术债务与优化方向：

  • 统一异步框架：当前 Flask（同步）与 Trio（异步）混用，计划迁移到 FastAPI
  • 服务拆分：Admin 模块已独立，计划将 TaskExecutor 拆分为独立微服务
  • 可观测性：完善 OpenTelemetry 集成，支持分布式追踪
  • 测试覆盖：增加集成测试与性能回归测试