备份与迁移 (Backup & migration)

数据迁移
从多存储桶模式迁移到单存储桶模式

数据迁移

鸣谢

本文档由我们的社区贡献者 TreeDy 贡献。我们可能不会主动维护本文档。

一个常见的场景是在性能强劲的实例（例如带 GPU 的服务器）上处理大型数据集，然后将整个 RAGFlow 服务迁移到其他生产环境（例如仅包含 CPU 的服务器）。本指南将介绍如何使用我们提供的迁移脚本安全地备份和恢复数据。

识别您的数据

默认情况下，RAGFlow 使用 Docker 数据卷（Docker volumes）来存储所有持久化数据，包括您的数据库、上传的文件和搜索索引。您可以通过运行以下命令来查看这些数据卷：

docker volume ls

输出将类似于：

DRIVER    VOLUME NAME
local     docker_esdata01
local     docker_minio_data
local     docker_mysql_data
local     docker_redis_data

这些数据卷包含了您需要迁移的所有数据。

注意

数据卷名称前缀（如 docker_）来自 Docker Compose 的项目名称。默认情况下，它是 docker（派生自目录名称）。如果您是用 docker compose -p <project_name> 启动 RAGFlow 的，您的高频数据卷则会以前缀 <project_name>_ 命名，例如 ragflow_mysql_data。

步骤 1：停止 RAGFlow 服务

在开始迁移之前，您必须在源机器上停止所有运行的 RAGFlow 服务。导航到项目的根目录并运行：

docker compose -f docker/docker-compose.yml down

如果您使用自定义项目名称（例如 docker compose -p ragflow）启动了 RAGFlow，请在命令中包含它：

docker compose -p ragflow -f docker/docker-compose.yml down

**重要提示：**切勿使用 -v 标志（例如 docker compose down -v），因为这会删除您所有的数据卷。迁移脚本中包含检查逻辑，如果服务处于活跃状态，它将阻止您运行备份。

步骤 2：备份您的数据

我们提供了一个便捷的脚本，可将您所有的数据卷打包到一个备份文件夹中。

如需快速查阅该脚本的命令和选项，可以运行：

bash docker/migration.sh help

要创建备份，请在项目的根目录运行以下命令：

bash docker/migration.sh backup

这将在您的项目根目录下创建一个 backup/ 文件夹，其中包含您数据卷的压缩存档文件。

您也可以为备份文件夹指定自定义名称：

bash docker/migration.sh backup my_ragflow_backup

这将改为创建名为 my_ragflow_backup/ 的文件夹。

如果您使用自定义项目名称（例如 docker compose -p ragflow）启动了 RAGFlow，请使用 -p 标志，以便脚本能够找到正确的数据卷：

bash docker/migration.sh -p ragflow backup
bash docker/migration.sh -p ragflow backup my_ragflow_backup

步骤 3：传输备份文件夹

将整个备份文件夹（例如 backup/ 或 my_ragflow_backup/）从源机器复制到目标机器上的 RAGFlow 项目目录中。您可以使用 scp、rsync 等工具或物理磁盘进行传输。

步骤 4：恢复您的数据

在目标机器上，确保 RAGFlow 服务未在运行。然后，使用迁移脚本从备份文件夹恢复您的数据。

如果您的备份文件夹名称为 backup/，请运行：

bash docker/migration.sh restore

如果您使用了自定义名称，请在命令中指定它：

bash docker/migration.sh restore my_ragflow_backup

如果目标机器使用了自定义项目名称，请使用 -p 标志以确保创建的数据卷带有正确的前缀：

bash docker/migration.sh -p ragflow restore
bash docker/migration.sh -p ragflow restore my_ragflow_backup

脚本将自动创建所需的 Docker 数据卷并解压数据。

**注意：**如果脚本检测到目标机器上已存在同名的 Docker 数据卷，它会警告您恢复操作将覆盖现有数据，并在继续之前要求您进行确认。

步骤 5：启动 RAGFlow 服务

恢复过程完成后，您可以在新机器上启动 RAGFlow 服务：

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

如果您使用自定义项目名称：

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

**注意：**如果您之前已经通过 Docker Compose 构建过服务，您可能需要按照上面的指南为目标机器备份数据，然后运行类似于以下命令：

# 在执行下一行命令之前，请先通过 bash docker/migration.sh backup backup_dir_name 进行备份。
# !!! 这一行的 -v 标志将会删除原始的 Docker 数据卷
docker compose -f docker/docker-compose.yml down -v
docker compose -f docker/docker-compose.yml up -d

您的 RAGFlow 实例现已启动并运行，其中包含原始机器中的所有数据。

从多存储桶模式迁移到单存储桶模式

鸣谢

本文档由我们的社区贡献者 arogan178 贡献。我们可能不会主动维护本文档。

默认情况下，RAGFlow 为每个知识库/数据集（dataset）创建一个存储桶（bucket），并为每个用户文件夹创建一个存储桶。这在以下情况下可能会产生问题：

您的云服务商按存储桶数量收费
您的 IAM 策略限制了存储桶的创建
您希望将所有数据整理在具有目录结构的单个存储桶中

**单存储桶模式（Single Bucket Mode）**允许您配置 RAGFlow 使用具有目录结构的单个存储桶，而不是多个存储桶。

工作原理

默认模式（多存储桶）

bucket: kb_12345/
  └── document_1.pdf
bucket: kb_67890/
  └── document_2.pdf
bucket: folder_abc/
  └── file_3.txt

单存储桶模式（带有 prefix_path）

bucket: ragflow-bucket/
  └── ragflow/
      ├── kb_12345/
      │   └── document_1.pdf
      ├── kb_67890/
      │   └── document_2.pdf
      └── folder_abc/
          └── file_3.txt

配置

MinIO 配置

编辑您的 service_conf.yaml 或设置环境变量：

minio:
  user: "your-access-key"
  password: "your-secret-key"
  host: "minio.example.com:443"
  bucket: "ragflow-bucket" # 默认存储桶名称
  prefix_path: "ragflow" # 可选前缀路径

或者使用环境变量：

export MINIO_USER=your-access-key
export MINIO_PASSWORD=your-secret-key
export MINIO_HOST=minio.example.com:443
export MINIO_BUCKET=ragflow-bucket
export MINIO_PREFIX_PATH=ragflow

S3 配置（已支持）

s3:
  access_key: "your-access-key"
  secret_key: "your-secret-key"
  endpoint_url: "https://s3.amazonaws.com"
  bucket: "my-ragflow-bucket"
  prefix_path: "production"
  region: "us-east-1"

IAM 策略示例

使用单存储桶模式时，您只需要针对单个存储桶的权限：

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["s3:*"],
      "Resource": [
        "arn:aws:s3:::ragflow-bucket",
        "arn:aws:s3:::ragflow-bucket/*"
      ]
    }
  ]
}

从多存储桶迁移到单存储桶

如果您正在从多存储桶模式迁移到单存储桶模式：

设置环境变量以匹配新配置
重启 RAGFlow 服务
迁移现有数据（可选）：

# 使用 mc (MinIO 客户端) 的示例
mc alias set old-minio http://old-minio:9000 ACCESS_KEY SECRET_KEY
mc alias set new-minio https://new-minio:443 ACCESS_KEY SECRET_KEY

# 列出所有知识库存储桶
mc ls old-minio/ | grep kb_ | while read -r line; do
    bucket=$(echo $line | awk '{print $5}')
    # 将每个存储桶复制到新的结构中
    mc cp --recursive old-minio/$bucket/ new-minio/ragflow-bucket/ragflow/$bucket/
done

在两种模式之间切换

启用单存储桶模式

minio:
  bucket: "my-single-bucket"
  prefix_path: "ragflow"

禁用（使用多存储桶模式）

minio:
  # 将 bucket 和 prefix_path 留空或注释掉
  # bucket: ''
  # prefix_path: ''

问题排查

问题：Access Denied（拒绝访问）错误

解决方案：确保您的 IAM 策略授予了对配置中指定的存储桶的访问权限。

问题：切换模式后找不到文件

解决方案：这两种模式之间的路径结构发生了变化。您需要迁移现有的数据。

问题：HTTPS 连接失败

解决方案：确保在 MinIO 连接中设置了 secure: True（端口 443 会自动处理）。

支持的存储后端

✅ MinIO - 单存储桶模式下提供完全支持
✅ AWS S3 - 单存储桶模式下提供完全支持
✅ 阿里云 OSS - 单存储桶模式下提供完全支持
✅ Azure Blob - 使用基于容器的结构（不同的范式）
⚠️ OpenDAL - 取决于底层的存储后端

性能考量

单存储桶模式在列出存储桶对象（bucket listing）操作的性能上可能会略好一些
多存储桶模式在大型部署中能提供更好的隔离性和组织性
请根据您的具体需求和基础架构限制进行选择