# Ragflow-Plus 部署与配置教程

本文档提供了 Ragflow-Plus 在各种环境下的部署和配置指南。Ragflow-Plus 采用容器化微服务架构，支持 CPU 和 GPU 两种部署模式。

有关系统架构信息，请参阅 系统架构概述。有关快速开始，请参阅 快速入门指南。

1. 部署架构概述 #

Ragflow-Plus 使用容器化微服务架构，包含多种部署配置选项。

1.1 容器架构 #

系统由以下核心容器组成：

┌─────────────────────────────────────────┐
│          Ragflow-Plus 容器架构            │
├─────────────────────────────────────────┤
│                                          │
│  ┌──────────────┐  ┌──────────────┐    │
│  │  ragflow     │  │  management  │    │
│  │  (主服务)    │  │  (管理系统)  │    │
│  └──────────────┘  └──────────────┘    │
│                                          │
│  ┌──────────────┐  ┌──────────────┐    │
│  │  mysql       │  │  es01        │    │
│  │  (数据库)    │  │  (搜索引擎)  │    │
│  └──────────────┘  └──────────────┘    │
│                                          │
│  ┌──────────────┐  ┌──────────────┐    │
│  │  minio       │  │  redis       │    │
│  │  (对象存储)  │  │  (缓存)      │    │
│  └──────────────┘  └──────────────┘    │
│                                          │
└─────────────────────────────────────────┘

1.2 部署配置矩阵 #

配置类型	文件	用途	GPU 支持
CPU 部署	docker/docker-compose.yml	标准 CPU 部署	否
GPU 部署	docker/docker-compose_gpu.yml	GPU 加速部署	是
独立管理	management/docker-compose.yml	仅管理系统	可选

2. 标准 Docker 部署 #

标准 Docker 部署适用于 CPU 环境，适合大多数开发和测试场景。

2.1 服务配置 #

标准部署包含以下服务：

• ragflow: 主应用服务，提供 RAG 功能和 API
• management-frontend: 管理前端界面
• management-backend: 管理后端 API
• mysql: MySQL 数据库
• es01: Elasticsearch 搜索引擎
• minio: MinIO 对象存储
• redis: Redis 缓存

2.2 卷挂载配置 #

服务	卷挂载	用途
ragflowplus-server	./ragflow-logs:/ragflow/logs	应用日志
ragflowplus-server	./nginx/ragflow.conf:/etc/nginx/conf.d/ragflow.conf	Nginx 配置
ragflowplus-management-backend	./ragflow-plus-logs:/app/logs	管理系统日志
ragflowplus-management-backend	./magic-pdf.json:/root/magic-pdf.json	MinerU 配置

2.3 端口映射 #

服务	内部端口	外部端口	说明
ragflow	9380	9380	主应用 API
ragflow	80, 443	80, 443	HTTP/HTTPS
management-frontend	80	8888	管理界面
management-backend	5000	5000	管理 API
mysql	3306	5455	数据库
es01	9200	1200	Elasticsearch
minio	9000, 9001	9000, 9001	MinIO API/Console
redis	6379	-	Redis（仅内部）

3. GPU 加速部署 #

GPU 部署配置扩展了标准设置，增加了 NVIDIA GPU 资源分配和专门的 MinerU 配置。

3.1 GPU 资源分配 #

GPU 部署包括 NVIDIA GPU 访问的资源预留：

deploy:
  resources:
    reservations:
      devices:
        - driver: nvidia
          capabilities: [gpu]
          device_ids: ['0']  # 指定使用第一块GPU

3.2 可选 VLLM 服务 #

GPU 配置包含可选的 VLLM 服务定义，用于本地模型托管：

服务	模型	用途	端口
vllm-bge	BGE-M3	嵌入生成	8000
vllm-deepseek	DeepSeek-R1-1.5B	语言模型推理	8001

3.3 MinerU GPU 配置 #

GPU 部署使用 magic-pdf-gpu.json 配置文件，针对 GPU 优化 MinerU 设置。

4. 环境配置 #

.env 文件包含所有可配置参数，按服务类别组织。

4.1 核心应用配置 #

核心应用配置包括：

• 镜像配置：

  • RAGFLOW_IMAGE: Ragflow 主镜像（默认：zstar1003/ragflowplus:v0.5.0）
  • RAGFLOWPLUS_MANAGEMENT_WEB_IMAGE: 管理前端镜像
  • RAGFLOWPLUS_MANAGEMENT_SERVER_IMAGE: 管理后端镜像

• 管理系统配置：

  • MANAGEMENT_ADMIN_USERNAME: 管理员用户名（默认：admin）
  • MANAGEMENT_ADMIN_PASSWORD: 管理员密码（默认：12345678）
  • MANAGEMENT_JWT_SECRET: JWT 密钥（默认：20250409）

• 网络配置：

  • SVR_HTTP_PORT: 主服务 HTTP 端口（默认：9380）
  • TIMEZONE: 时区（默认：Asia/Shanghai）
  • HF_ENDPOINT: HuggingFace 镜像端点（默认：hf-mirror.com）

4.2 基础设施服务配置 #

基础设施服务配置包括：

服务	主机变量	端口变量	密码变量	默认端口
MySQL	MYSQL_HOST=mysql	MYSQL_PORT=5455	MYSQL_PASSWORD=infini_rag_flow	5455
Elasticsearch	ES_HOST=es01	ES_PORT=1200	ELASTIC_PASSWORD=infini_rag_flow	1200
MinIO	MINIO_HOST=minio	MINIO_PORT=9000	MINIO_PASSWORD=infini_rag_flow	9000
Redis	REDIS_HOST=redis	REDIS_PORT=6379	REDIS_PASSWORD=infini_rag_flow	6379

4.3 文档引擎配置 #

系统支持 Elasticsearch 作为主要文档引擎：

DOC_ENGINE=${DOC_ENGINE:-elasticsearch}
COMPOSE_PROFILES=${DOC_ENGINE}

5. 网络和安全配置 #

5.1 端口映射策略 #

系统使用以下端口映射策略：

• 外部访问端口：

  • HTTP/HTTPS: 80, 443（用户前端）
  • Ragflow API: 9380（主应用 API）
  • Management UI: 8888（管理界面）
  • Management API: 5000（管理 API）

• 内部服务端口：

  • MySQL: 3306（容器内）
  • Elasticsearch: 9200（容器内）
  • MinIO: 9000, 9001（容器内）
  • Redis: 6379（容器内，不对外暴露）

5.2 服务健康检查 #

部署包含健康检查依赖，确保正确的服务启动顺序：

depends_on:
  mysql:
    condition: service_healthy
  es01:
    condition: service_healthy

6. 应用构建配置 #

6.1 Docker 镜像构建过程 #

Docker 镜像构建过程包括：

1. 基础镜像：使用 infiniflow/ragflow:v0.17.2-slim 作为基础镜像
2. 源代码复制：
   • ./api → /ragflow/api
   • ./conf → /ragflow/conf
   • ./rag → /ragflow/rag
   • ./graphrag → /ragflow/graphrag
   • ./web → /ragflow/web
3. 依赖安装：
   • Python 依赖：transformers==4.49.0, torch==2.7.0, torchvision==0.22.0
   • NPM 构建：npm install && npm run build
4. 配置文件：复制 service_conf.yaml.template
5. 入口点：设置 entrypoint.sh

6.2 Python 依赖 #

项目使用特定版本的依赖以确保兼容性：

包	版本	用途
transformers	4.49.0	Transformer 模型支持
torch	2.7.0	PyTorch 框架
torchvision	0.22.0	计算机视觉工具

7. 部署命令 #

7.1 标准 CPU 部署 #

# 启动所有服务（CPU 配置）
docker compose -f docker/docker-compose.yml up -d

# 检查服务状态
docker compose -f docker/docker-compose.yml ps

# 查看日志
docker compose -f docker/docker-compose.yml logs -f ragflow

7.2 GPU 加速部署 #

# 启动所有服务（GPU 配置）
docker compose -f docker/docker-compose_gpu.yml up -d

# 验证 GPU 分配
docker exec ragflowplus-management-backend nvidia-smi

# 监控 GPU 使用
docker stats ragflowplus-management-backend

7.3 仅管理系统 #

# 部署独立管理系统
docker compose -f management/docker-compose.yml up -d

# 访问管理界面：http://localhost:8888

8. 配置验证 #

8.1 服务健康验证 #

部署后，按以下顺序验证服务健康状态：

1. 检查 MySQL：

   docker exec mysql mysql -u root -p -e 'SHOW DATABASES;'

2. 检查 Elasticsearch：

   curl http://localhost:1200

3. 检查 Ragflow API：

   curl http://localhost:9380/api/v1/health

4. 检查管理 API：

   curl http://localhost:5000/api/health

5. 检查管理前端： 访问 http://localhost:8888，使用默认账号 admin/12345678 登录

8.2 配置验证最佳实践 #

1. 启动前验证：确保所有必需的环境变量已设置
2. 端口检查：确认所需端口未被占用
3. 资源检查：验证系统资源（内存、磁盘、GPU）是否充足
4. 网络检查：确认容器间网络连接正常
5. 日志监控：启动后监控日志，确保无错误

9. 硬件要求 #

建议部署硬件资源需满足以下配置：

• 内存要求：最低 16G 以上，推荐 32G 以上
• GPU 要求：Turing 及以后架构，6G 显存以上（GPU 部署）
• 磁盘空间要求：20G 以上，推荐使用 SSD

10. 常见问题 #

10.1 端口冲突 #

如果遇到端口冲突，可以：

1. 修改 .env 文件中的端口配置
2. 停止占用端口的其他服务
3. 使用不同的端口映射

10.2 镜像拉取失败 #

如果拉取镜像失败，可以：

1. 配置 Docker 镜像源加速
2. 使用网盘打包好的镜像资源文件
3. 使用 docker load 命令加载本地镜像

10.3 GPU 不可用 #

如果 GPU 不可用，检查：

1. NVIDIA 驱动是否正确安装
2. Docker 是否支持 GPU（需要安装 nvidia-container-toolkit）
3. GPU 设备 ID 是否正确配置

11. 总结 #

Ragflow-Plus 提供了灵活的部署选项，支持 CPU 和 GPU 两种模式。通过 Docker Compose，可以快速部署完整的系统。配置通过 .env 文件集中管理，便于不同环境的部署和维护。

关键要点：

• 使用 Docker Compose 简化部署流程
• 通过环境变量集中管理配置
• 支持 CPU 和 GPU 两种部署模式
• 提供健康检查确保服务正常启动
• 支持独立管理系统部署

有关更多部署细节和故障排除，请参阅项目文档和常见问题解答。