ai

# Ragflow-Plus 系统架构教程

本文档详细描述了 Ragflow-Plus 的高层系统架构。Ragflow-Plus 是基于原始 Ragflow 框架构建的增强型 RAG（检索增强生成）系统。本文档涵盖双系统架构、核心服务组件、基础设施依赖和部署拓扑。

有关具体部署细节，请参阅部署与配置。有关各个子系统的详细实现，请参阅核心系统。

1. 架构概述 #

Ragflow-Plus 实现了双系统架构，将面向用户的功能与管理操作完全分离。系统通过 MinerU 集成增强了文档处理能力，并通过专用的管理界面提供全面的管理工具。

1.1 双系统架构设计 #

Ragflow-Plus 采用双系统架构，将系统分为两个独立但协作的部分：

┌─────────────────────────────────────────┐
│      用户面向系统 (User-Facing System)    │
│  ┌──────────────────────────────────┐  │
│  │  用户前端 (web/src/pages/)       │  │
│  │  - 聊天界面 (chat/)              │  │
│  │  - 知识库管理 (add-knowledge/)   │  │
│  │  - 文档编写 (write/)             │  │
│  └──────────────────────────────────┘  │
└─────────────────────────────────────────┘
              ↕
┌─────────────────────────────────────────┐
│      管理系统 (Management System)        │
│  ┌──────────────────────────────────┐  │
│  │  管理前端 (management/web/)       │  │
│  │  管理后端 (management/server/)    │  │
│  └──────────────────────────────────┘  │
└─────────────────────────────────────────┘
              ↕
┌─────────────────────────────────────────┐
│      基础设施层 (Infrastructure Layer)   │
│  - MySQL 数据库                         │
│  - Elasticsearch 集群                   │
│  - MinIO 对象存储                       │
│  - Redis 缓存                          │
└─────────────────────────────────────────┘

双系统架构的优势：

职责分离：用户功能与管理功能完全解耦，提高系统安全性
独立扩展：两个系统可以独立扩展，互不影响
权限控制：管理功能与用户功能分离，便于权限管理
维护便利：系统结构清晰，便于维护和升级

2. 核心服务组件 #

系统由三个主要服务层组成，分别处理 RAG 流程和系统管理的不同方面。

2.1 应用服务层 #

应用服务层包含前端应用和后端 API 服务：

┌─────────────────────────────────────────┐
│        前端应用 (Frontend Applications)   │
│  ┌──────────────┐  ┌──────────────┐    │
│  │ 用户前端     │  │ 管理前端     │    │
│  │ web/src/     │  │ management/ │    │
│  │ pages/       │  │ web/src/    │    │
│  └──────────────┘  └──────────────┘    │
└─────────────────────────────────────────┘
              ↕
┌─────────────────────────────────────────┐
│        后端服务 (Backend Services)       │
│  ┌──────────────┐  ┌──────────────┐    │
│  │ Ragflow API  │  │ 管理 API     │    │
│  │ api/         │  │ management/ │    │
│  │ ragflow_     │  │ server/      │    │
│  │ server       │  │ app.py       │    │
│  └──────────────┘  └──────────────┘    │
└─────────────────────────────────────────┘
              ↕
┌─────────────────────────────────────────┐
│      处理服务 (Processing Services)      │
│  ┌──────────────┐  ┌──────────────┐    │
│  │ MinerU 集成  │  │ 翻译服务     │    │
│  │ 增强文档解析  │  │ 跨语言支持   │    │
│  └──────────────┘  └──────────────┘    │
└─────────────────────────────────────────┘

应用服务组件详情 #

服务	容器名称	端口	用途
用户前端	`ragflowplus-server`	9380, 80, 443	主用户界面（聊天、知识管理）
管理前端	`ragflowplus-management-frontend`	8888	管理界面
管理后台	`ragflowplus-management-backend`	5000	管理 API 及 MinerU 集成

2.2 文档处理流水线 #

作为 Ragflow-Plus 的核心能力之一，增强型文档处理流水线支持以下完整流程：

┌─────────────────────────────────────────┐
│          输入层 (Input Layer)            │
│  ┌──────────────┐  ┌──────────────┐    │
│  │ 文件上传     │  │ 网页爬取     │    │
│  │ PDF, Word,  │  │ Web Crawling │    │
│  │ Excel 等     │  │              │    │
│  └──────────────┘  └──────────────┘    │
└─────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│        处理层 (Processing Layer)         │
│  ┌──────────────────────────────────┐  │
│  │ MinerU 解析器                    │  │
│  │ - OCR 引擎                       │  │
│  │ - 版面分析                        │  │
│  │ - 结构检测                        │  │
│  │ (magic-pdf.json 配置)            │  │
│  └──────────────────────────────────┘  │
│              ↓                          │
│  ┌──────────────────────────────────┐  │
│  │ 文档分块引擎                      │  │
│  │ - 多种分块策略                    │  │
│  └──────────────────────────────────┘  │
│              ↓                          │
│  ┌──────────────────────────────────┐  │
│  │ 嵌入向量生成                      │  │
│  │ - 向量转换                        │  │
│  └──────────────────────────────────┘  │
└─────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│          存储层 (Storage Layer)          │
│  ┌──────────────┐  ┌──────────────┐    │
│  │ MinIO 存储   │  │ ES 索引      │    │
│  │ 二进制文件   │  │ 可搜索块     │    │
│  │ 和图片       │  │              │    │
│  └──────────────┘  └──────────────┘    │
│  ┌──────────────────────────────────┐  │
│  │ MySQL 元数据                      │  │
│  │ 文档关系                          │  │
│  └──────────────────────────────────┘  │
└─────────────────────────────────────────┘

文档处理流程详解：

文件上传/网页爬取：支持多种文件格式（PDF、Word、Excel 等）或网页内容
MinerU 解析：使用 MinerU 解析器进行 OCR 和版面分析，配置文件为 magic-pdf.json
文档分块：根据文档类型选择合适的分块策略
嵌入向量生成：将文本块转换为向量表示
存储索引：
- 原始文件和图片存储到 MinIO
- 向量和文本块索引到 Elasticsearch
- 文档元数据和关系存储到 MySQL

3. 基础设施层 #

基础设施层提供持久化存储、搜索能力和缓存服务，同时支持用户面向系统和管理系统。

3.1 数据存储架构 #

系统采用多层次的存储架构：

┌─────────────────────────────────────────┐
│      持久化存储 (Persistent Storage)     │
│  ┌──────────────┐  ┌──────────────┐    │
│  │ MySQL 数据库 │  │ MinIO 存储   │    │
│  │ rag_flow     │  │ 对象存储     │    │
│  │ 用户数据     │  │ 二进制文件   │    │
│  │ KB 元数据    │  │ 图片         │    │
│  └──────────────┘  └──────────────┘    │
└─────────────────────────────────────────┘
              ↕
┌─────────────────────────────────────────┐
│      搜索与索引 (Search & Indexing)      │
│  ┌──────────────────────────────────┐  │
│  │ Elasticsearch 集群               │  │
│  │ es01 节点                        │  │
│  │ 向量和文本搜索                    │  │
│  └──────────────────────────────────┘  │
└─────────────────────────────────────────┘
              ↕
┌─────────────────────────────────────────┐
│      缓存与队列 (Caching & Queuing)      │
│  ┌──────────────────────────────────┐  │
│  │ Redis 缓存                       │  │
│  │ 会话数据、临时存储                │  │
│  │ 队列管理                         │  │
│  └──────────────────────────────────┘  │
└─────────────────────────────────────────┘
              ↕
┌─────────────────────────────────────────┐
│        配置 (Configuration)              │
│  ┌──────────────┐  ┌──────────────┐    │
│  │ .env 配置    │  │ Nginx 配置   │    │
│  │ 服务端点     │  │ 反向代理     │    │
│  │ 凭证         │  │ 负载均衡     │    │
│  └──────────────┘  └──────────────┘    │
└─────────────────────────────────────────┘

基础设施组件详情 #

组件	服务名称	端口	配置
MySQL	`mysql`	3306	数据库：`rag_flow`，密码：`infini_rag_flow`
Elasticsearch	`es01`	9200	版本：8.11.3，内存限制：8GB
MinIO	`minio`	9000	用户：`rag_flow`，控制台：9001
Redis	`redis`	6379	密码：`infini_rag_flow`

3.2 存储组件说明 #

MySQL 数据库：

存储用户数据、团队信息、知识库元数据
维护文档之间的关系和引用
使用 rag_flow 数据库模式

Elasticsearch 集群：

提供向量相似性搜索和全文搜索能力
存储文档块和向量索引
支持混合搜索和重新排序

MinIO 对象存储：

存储原始文档文件（PDF、Word、Excel 等）
存储提取的图片和图像
基于桶（Bucket）的组织方式

Redis 缓存：

存储会话数据
提供临时存储和队列管理
提升系统响应速度

4. 部署架构 #

Ragflow-Plus 支持通过 Docker Compose 编排进行 CPU 和 GPU 两种部署配置。

4.1 容器部署拓扑 #

系统采用容器化部署，所有服务运行在 Docker 容器中：

┌─────────────────────────────────────────┐
│           主机机器 (Host Machine)         │
│                                          │
│  ┌──────────────────────────────────┐  │
│  │    应用容器 (Application)         │  │
│  │  ┌──────────────┐               │  │
│  │  │ ragflowplus- │               │  │
│  │  │ server       │               │  │
│  │  │ RAGFLOW_     │               │  │
│  │  │ IMAGE        │               │  │
│  │  └──────────────┘               │  │
│  │  ┌──────────────────────────┐  │  │
│  │  │ ragflowplus-management-  │  │  │
│  │  │ backend                  │  │  │
│  │  │ MANAGEMENT_SERVER_IMAGE  │  │  │
│  │  └──────────────────────────┘  │  │
│  │  ┌──────────────────────────┐  │  │
│  │  │ ragflowplus-management-  │  │  │
│  │  │ frontend                 │  │  │
│  │  │ MANAGEMENT_WEB_IMAGE     │  │  │
│  │  └──────────────────────────┘  │  │
│  └──────────────────────────────────┘  │
│                                          │
│  ┌──────────────────────────────────┐  │
│  │  基础设施容器 (Infrastructure)     │  │
│  │  ┌──────────────┐               │  │
│  │  │ ragflow-mysql│               │  │
│  │  │ mysql:8.0.39 │               │  │
│  │  └──────────────┘               │  │
│  │  ┌──────────────┐               │  │
│  │  │ ragflow-es-01│               │  │
│  │  │ elasticsearch│               │  │
│  │  │ :8.11.3      │               │  │
│  │  └──────────────┘               │  │
│  │  ┌──────────────┐               │  │
│  │  │ ragflow-minio│               │  │
│  │  │ minio:RELEASE│               │  │
│  │  └──────────────┘               │  │
│  │  ┌──────────────┐               │  │
│  │  │ ragflow-redis│               │  │
│  │  │ valkey/valkey│               │  │
│  │  │ :8           │               │  │
│  │  └──────────────┘               │  │
│  └──────────────────────────────────┘  │
│                                          │
│  ┌──────────────────────────────────┐  │
│  │    卷挂载 (Volume Mounts)         │  │
│  │  - ./ragflow-logs                │  │
│  │  - ./ragflow-plus-logs           │  │
│  │  - ./nginx/                      │  │
│  │  - ./magic-pdf.json              │  │
│  └──────────────────────────────────┘  │
│                                          │
│  ┌──────────────────────────────────┐  │
│  │    GPU 资源 (GPU Resources)        │  │
│  │  ┌──────────────────────────┐    │  │
│  │  │ NVIDIA GPU               │    │  │
│  │  │ device_ids: ['0']        │    │  │
│  │  │ MinerU 加速              │    │  │
│  │  └──────────────────────────┘    │  │
│  └──────────────────────────────────┘  │
└─────────────────────────────────────────┘

4.2 CPU 部署 #

使用 docker/docker-compose.yml 进行标准资源分配的 CPU 部署。

特点：

适合没有 GPU 的环境
使用 CPU 进行文档解析和处理
资源需求较低，易于部署

4.3 GPU 部署 #

使用 docker/docker-compose_gpu.yml 进行 GPU 资源预留的部署，用于 MinerU 加速。

GPU 配置示例：

deploy:
  resources:
    reservations:
      devices:
        - driver: nvidia
          capabilities: [gpu]
          device_ids: ["0"]

特点：

利用 GPU 加速文档解析
提升 MinerU 处理性能
适合大规模文档处理场景

4.4 网络架构 #

所有服务通过 ragflow Docker 网络进行通信，通过容器名称进行服务发现：

┌─────────────────────────────────────────┐
│        外部访问 (External Access)        │
│  ┌──────────────┐  ┌──────────────┐    │
│  │ 用户         │  │ 管理员       │    │
│  │ :80, :443    │  │ :8888        │    │
│  └──────────────┘  └──────────────┘    │
│  ┌──────────────────────────────────┐  │
│  │ API 客户端                        │  │
│  │ :5000                             │  │
│  └──────────────────────────────────┘  │
└─────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│      反向代理层 (Reverse Proxy Layer)    │
│  ┌──────────────┐  ┌──────────────┐    │
│  │ Nginx (主)   │  │ Nginx (管理) │    │
│  │ ragflow.conf │  │ management_ │    │
│  │              │  │ nginx.conf   │    │
│  └──────────────┘  └──────────────┘    │
└─────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│        应用层 (Application Layer)        │
│  ┌──────────────┐  ┌──────────────┐    │
│  │ ragflowplus-│  │ management-  │    │
│  │ server      │  │ frontend     │    │
│  │ :9380       │  │ :80          │    │
│  └──────────────┘  └──────────────┘    │
│  ┌──────────────────────────────────┐  │
│  │ management-backend                │  │
│  │ :5000                             │  │
│  └──────────────────────────────────┘  │
└─────────────────────────────────────────┘

网络配置说明：

用户访问：通过端口 80 或 443 访问主应用，由 Nginx 主配置路由到 ragflowplus-server
管理员访问：通过端口 8888 访问管理界面，由 Nginx 管理配置路由到 management-frontend
API 访问：通过端口 5000 直接访问管理后端 API
内部通信：所有容器通过 Docker 网络 ragflow 进行内部通信

5. 配置管理 #

系统使用基于环境的配置，通过 Docker Compose 变量替换实现。

5.1 关键配置文件 #

文件	用途	关键变量
`docker/.env`	主配置	`RAGFLOW_IMAGE`、数据库凭证、服务端口
`docker/nginx/ragflow.conf`	主应用代理	前端路由、SSL 配置
`docker/nginx/management_nginx.conf`	管理代理	API 路由到后端
`magic-pdf.json` / `magic-pdf-gpu.json`	MinerU 配置	GPU/CPU 解析设置

5.2 环境变量 #

系统主要环境变量包括：

# 核心镜像
RAGFLOW_IMAGE=zstar1003/ragflowplus:v0.5.0
RAGFLOWPLUS_MANAGEMENT_WEB_IMAGE=zstar1003/ragflowplus-management-web:v0.5.0
RAGFLOWPLUS_MANAGEMENT_SERVER_IMAGE=zstar1003/ragflowplus-management-server:v0.5.0

# 管理系统
MANAGEMENT_ADMIN_USERNAME=admin
MANAGEMENT_ADMIN_PASSWORD=12345678
MANAGEMENT_JWT_SECRET=20250409

# 文件上传限制
MAX_CONTENT_LENGTH=10737418240  # 10GB

5.3 配置管理最佳实践 #

环境变量管理：使用 .env 文件管理敏感信息，不要提交到版本控制
配置文件分离：将不同环境的配置分离，便于管理
配置验证：启动前验证关键配置项是否正确
配置文档化：记录所有配置项的含义和默认值

6. 架构设计原则 #

Ragflow-Plus 的架构设计遵循以下原则：

6.1 分层架构 #

系统采用清晰的分层架构：

表示层：前端应用（用户前端和管理前端）
应用层：后端 API 服务（Ragflow API 和管理 API）
业务层：文档处理、NLP 处理、RAG 引擎
数据层：存储服务（MySQL、Elasticsearch、MinIO、Redis）

6.2 微服务设计 #

系统采用微服务架构：

每个服务独立部署和扩展
服务间通过 API 通信
故障隔离，单个服务故障不影响整体系统

6.3 可扩展性 #

系统设计支持水平扩展：

无状态服务设计，易于横向扩展
存储层支持集群部署
负载均衡支持多实例部署

6.4 安全性 #

系统注重安全性设计：

用户系统与管理系统分离
权限控制和访问控制
敏感信息加密存储

7. 总结 #

Ragflow-Plus 通过双系统架构、分层服务设计和容器化部署，构建了一个现代化、可扩展、易维护的 RAG 系统。系统架构的主要特点包括：

双系统分离：用户功能与管理功能完全解耦，提高安全性和可维护性
分层设计：清晰的分层架构，便于开发和维护
容器化部署：支持 CPU 和 GPU 两种部署方式，灵活适应不同环境
可扩展性：微服务设计支持独立扩展，满足不同规模需求
增强处理：MinerU 集成提供强大的文档处理能力

通过这种架构设计，Ragflow-Plus 能够满足企业级知识管理和文档处理的各种需求，为中文应用场景提供了完整的解决方案。

导航菜单