ai

# Ragflow-Plus Docker 部署教程

本文档详细介绍了 Ragflow-Plus 基于 Docker 的部署方法，包括 CPU 和 GPU 两种部署配置、容器架构、网络配置和配置管理。

有关环境变量配置详情，请参阅环境配置。有关外部服务设置（包括 MySQL、Elasticsearch、MinIO 和 Redis），请参阅外部服务设置。

1. 容器架构概述 #

Ragflow-Plus 采用多容器 Docker 架构，将主应用、管理系统和基础设施服务分离到不同的容器中。部署支持仅 CPU 和 GPU 加速两种配置，以增强文档处理能力。

1.1 容器架构图 #

┌─────────────────────────────────────────┐
│      外部访问层 (External Access)        │
│  ┌──────────┐  ┌──────────┐  ┌──────┐  │
│  │ 用户     │  │ 管理员   │  │ API  │  │
│  │ :80, :443│  │ :8888    │  │:5000 │  │
│  └──────────┘  └──────────┘  └──────┘  │
└─────────────────────────────────────────┘
              ↕
┌─────────────────────────────────────────┐
│      应用容器层 (Application Containers)  │
│  ┌──────────────────────────────────┐  │
│  │ ragflowplus-server                │  │
│  │ Port: 9380, 80, 443               │  │
│  └──────────────────────────────────┘  │
│  ┌──────────────────────────────────┐  │
│  │ ragflowplus-management-frontend  │  │
│  │ Port: 8888                       │  │
│  └──────────────────────────────────┘  │
│  ┌──────────────────────────────────┐  │
│  │ ragflowplus-management-backend    │  │
│  │ Port: 5000                       │  │
│  └──────────────────────────────────┘  │
└─────────────────────────────────────────┘
              ↕
┌─────────────────────────────────────────┐
│   基础设施容器层 (Infrastructure)        │
│  ┌──────┐  ┌──────┐  ┌──────┐  ┌────┐ │
│  │mysql │  │es01  │  │minio │  │redis│ │
│  │:5455 │  │:1200 │  │:9000 │  │:6379│ │
│  └──────┘  └──────┘  └──────┘  └────┘ │
└─────────────────────────────────────────┘
              ↕
┌─────────────────────────────────────────┐
│    GPU 资源 (可选) (GPU Resources)      │
│  ┌──────────────────────────────────┐  │
│  │ NVIDIA GPU                       │  │
│  │ device_ids: ['0']                │  │
│  └──────────────────────────────────┘  │
└─────────────────────────────────────────┘

2. CPU 部署配置 #

标准 CPU 部署使用 docker-compose.yml，基于 docker-compose-base.yml 的基础配置。此设置包括三个主要应用容器及其基础设施依赖。

2.1 CPU 部署服务 #

标准部署包含以下服务：

服务	容器名称	镜像	端口	关键卷挂载
`ragflow`	`ragflowplus-server`	`${RAGFLOW_IMAGE}`	`${SVR_HTTP_PORT}:9380`, `80:80`, `443:443`	nginx 配置、日志
`management-frontend`	`ragflowplus-management-frontend`	`${RAGFLOWPLUS_MANAGEMENT_WEB_IMAGE}`	`8888:80`	nginx 配置
`management-backend`	`ragflowplus-management-backend`	`${RAGFLOWPLUS_MANAGEMENT_SERVER_IMAGE}`	`5000:5000`	日志、magic-pdf 配置

2.2 服务依赖关系 #

ragflow 服务依赖于 mysql（健康检查通过）
management-backend 服务依赖于 mysql（健康检查通过）
management-frontend 服务依赖于 management-backend

2.3 卷挂载配置 #

卷挂载	用途	容器
`./ragflow-logs:/ragflow/logs`	应用日志	`ragflowplus-server`
`./ragflow-plus-logs:/app/logs`	管理后端日志	`ragflowplus-management-backend`
`./nginx/ragflow.conf:/etc/nginx/conf.d/ragflow.conf`	Nginx 配置	`ragflowplus-server`
`./nginx/proxy.conf:/etc/nginx/proxy.conf`	代理配置	`ragflowplus-server`
`./nginx/management_nginx.conf:/etc/nginx/conf.d/default.conf`	管理 nginx 配置	`ragflowplus-management-frontend`
`./magic-pdf.json:/root/magic-pdf.json`	CPU MinerU 配置	`ragflowplus-management-backend`

3. GPU 加速部署 #

GPU 部署配置在 docker-compose_gpu.yml 中启用 NVIDIA GPU 加速，专门用于管理后端的 MinerU 文档处理。主要区别是添加了 GPU 资源预留和使用 magic-pdf-gpu.json 配置。

3.1 GPU 配置详情 #

GPU 部署使用与 CPU 部署相同的服务结构，但添加了 GPU 资源分配：

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

3.2 GPU 配置差异 #

配置项	CPU 部署	GPU 部署
配置文件	`magic-pdf.json`	`magic-pdf-gpu.json`
GPU 资源	无	`device_ids: ['0']`
容器	`ragflowplus-management-backend`	`ragflowplus-management-backend` (GPU-enabled)

3.3 GPU 部署要求 #

NVIDIA GPU 驱动已安装
NVIDIA Container Toolkit 已安装
Docker 支持 GPU 访问
至少一个可用的 GPU 设备

4. 独立管理系统部署 #

管理系统也可以使用 management/docker-compose.yml 中的配置独立部署。此部署仅包括管理前端和后端，不包含主 Ragflow 应用。

4.1 独立管理系统组件 #

组件	容器名称	镜像	端口	网络
Frontend	`ragflowplus-management-frontend`	`zstar1003/ragflowplus-management-web:v0.5.0`	`8888:80`	`management_network`
Backend	`ragflowplus-management-backend`	`zstar1003/ragflowplus-management-server:v0.5.0`	`5000:5000`	`management_network`

4.2 独立部署场景 #

独立管理系统部署适用于以下场景：

仅需要管理系统功能
管理系统与主应用分离部署
多环境管理系统集中管理

5. 网络配置和端口映射 #

所有容器通过 ragflow Docker 网络进行通信。系统为不同服务和管理访问暴露多个端口。

5.1 端口映射配置 #

外部端口	容器内部端口	服务	说明
`80`	`80`	`ragflowplus-server`	HTTP
`443`	`443`	`ragflowplus-server`	HTTPS
`9380`	`9380`	`ragflowplus-server`	Ragflow API
`8888`	`80`	`ragflowplus-management-frontend`	管理界面
`5000`	`5000`	`ragflowplus-management-backend`	管理 API
`5455`	`3306`	`mysql`	MySQL 数据库
`1200`	`9200`	`es01`	Elasticsearch
`9000`	`9000`	`minio`	MinIO API
`9001`	`9001`	`minio`	MinIO Console
`6379`	`6379`	`redis`	Redis（仅内部）

5.2 网络架构 #

网络名称：ragflow
网络类型：bridge
服务通信：所有服务在同一网络中，可通过服务名访问

6. 卷挂载和数据持久化 #

部署使用多个卷挂载用于配置、日志和数据持久化，确保容器重启后数据不丢失。

6.1 卷挂载列表 #

卷挂载	用途	容器
`./ragflow-logs:/ragflow/logs`	应用日志	`ragflowplus-server`
`./ragflow-plus-logs:/app/logs`	管理后端日志	`ragflowplus-management-backend`
`./nginx/ragflow.conf:/etc/nginx/conf.d/ragflow.conf`	Nginx 配置	`ragflowplus-server`
`./nginx/proxy.conf:/etc/nginx/proxy.conf`	代理配置	`ragflowplus-server`
`./nginx/management_nginx.conf:/etc/nginx/conf.d/default.conf`	管理 nginx 配置	`ragflowplus-management-frontend`
`./magic-pdf.json:/root/magic-pdf.json`	CPU MinerU 配置	`ragflowplus-management-backend`
`./magic-pdf-gpu.json:/root/magic-pdf.json`	GPU MinerU 配置	`ragflowplus-management-backend` (GPU)

6.2 数据卷 #

系统使用 Docker 命名卷来持久化数据：

mysql_data：MySQL 数据
esdata01：Elasticsearch 数据
minio_data：MinIO 对象存储数据
redis_data：Redis 数据

7. 环境配置集成 #

部署使用 .env 文件中的环境变量和额外的运行时环境设置。关键配置类别包括：

7.1 核心镜像配置 #

RAGFLOW_IMAGE：主应用镜像（zstar1003/ragflowplus:v0.5.0）
RAGFLOWPLUS_MANAGEMENT_WEB_IMAGE：管理前端镜像
RAGFLOWPLUS_MANAGEMENT_SERVER_IMAGE：管理后端镜像

7.2 运行时环境变量 #

TZ=${TIMEZONE}：系统时区
HF_ENDPOINT=${HF_ENDPOINT}：Hugging Face 镜像端点
MACOS=${MACOS}：macOS 兼容性标志
FLASK_ENV=development：Flask 环境模式
CORS_ALLOWED_ORIGINS：跨域请求配置

7.3 管理系统认证 #

MANAGEMENT_ADMIN_USERNAME：默认管理员用户名
MANAGEMENT_ADMIN_PASSWORD：默认管理员密码
MANAGEMENT_JWT_SECRET：JWT 令牌加密密钥

8. 部署命令 #

根据您的需求，使用以下命令之一进行部署：

8.1 CPU 部署 #

docker-compose -f docker/docker-compose.yml up -d

8.2 GPU 部署 #

docker-compose -f docker/docker-compose_gpu.yml up -d

8.3 独立管理系统部署 #

docker-compose -f management/docker-compose.yml up -d

8.4 停止服务 #

# 停止 CPU 部署
docker-compose -f docker/docker-compose.yml down

# 停止 GPU 部署
docker-compose -f docker/docker-compose_gpu.yml down

# 停止独立管理系统
docker-compose -f management/docker-compose.yml down

8.5 查看日志 #

# 查看所有服务日志
docker-compose -f docker/docker-compose.yml logs -f

# 查看特定服务日志
docker-compose -f docker/docker-compose.yml logs -f ragflow

8.6 重启服务 #

# 重启所有服务
docker-compose -f docker/docker-compose.yml restart

# 重启特定服务
docker-compose -f docker/docker-compose.yml restart ragflow

9. 健康检查和重启策略 #

部署包含健康检查和重启策略（restart: on-failure），以确保服务可靠性和从故障中自动恢复。

9.1 健康检查配置 #

MySQL：使用 mysqladmin ping 检查数据库连接
Elasticsearch：使用 curl http://localhost:9200 检查服务状态
服务依赖：使用 condition: service_healthy 确保依赖服务就绪

9.2 重启策略 #

重启策略：on-failure（仅在失败时重启）
重试次数：根据服务类型配置
检查间隔：10 秒

10. 常见问题排查 #

10.1 端口冲突 #

如果遇到端口冲突，请检查：

# 检查端口占用
netstat -tuln | grep <端口号>

# 修改 .env 文件中的端口配置

10.2 容器启动失败 #

检查容器日志：

docker-compose -f docker/docker-compose.yml logs <服务名>

10.3 GPU 不可用 #

检查 GPU 驱动和 Docker GPU 支持：

# 检查 NVIDIA 驱动
nvidia-smi

# 检查 Docker GPU 支持
docker run --rm --gpus all nvidia/cuda:11.0-base nvidia-smi

10.4 数据持久化问题 #

确保卷挂载路径存在且有正确权限：

# 创建必要的目录
mkdir -p ragflow-logs ragflow-plus-logs nginx

# 设置权限
chmod -R 755 ragflow-logs ragflow-plus-logs

11. 总结 #

Ragflow-Plus 的 Docker 部署提供了灵活的配置选项：

CPU 部署：适合大多数开发和测试场景
GPU 部署：提供增强的文档处理能力
独立管理系统：支持管理系统独立部署
健康检查：确保服务可靠启动
数据持久化：通过卷挂载确保数据安全

通过合理配置环境变量和网络设置，可以轻松部署和管理 Ragflow-Plus 系统。

导航菜单