RAGFlow v0.17.2 → v0.25.6

目标

将 RAGFlow v0.17.2 中的知识库、所属用户关系、配置参数及所有文档文件，迁移到 v0.25.6 并重新触发文档解析，最后验证解析结果和权限。

设计原则

以下对比基于 api/db/db_models.py 中 Peewee ORM 模型定义。v0.17.2 共 28 个模型类，v0.25.6 共 50 个。

v0.25.6 官方提供了 tools/scripts/mysql_migration.py 来执行这个三步迁移（tenant_model_provider → tenant_model_instance → tenant_model），仅用于"原地升级"场景。API 导入方式无需执行此脚本。

本节说明通过 v0.25.6 REST API 重新创建后，各类标识符的保留/变化情况。

v0.17.2 的 KB 参数可通过 API 在创建或更新 dataset 时传入：

Phase 1 (export_files.py) ⸻⸻⸻⸻⸻⸻⸻⸻⸻⸻⸻⸻⸻⸻ Phase 2 (import_to_v0256.py) ⸻⸻⸻⸻⸻⸻⸻ Phase 3 (verify_migration.py)

数据查询链路

SELECT id, name, description FROM knowledgebase WHERE status='1'
       ↓ 对每个 kb_id
SELECT id, name, location, type FROM document WHERE kb_id=? AND status='1'
       ↓
SELECT document_id, file_id FROM file2document WHERE document_id IN (...)
       ↓
SELECT id, name FROM file WHERE id IN (...)
       ↓
MinIO: fget_object(bucket=kb_id, key=doc.location, local_path)

API 调用时序

# Step 1: 检查已有 datasets（避免重复创建）
GET /api/v1/datasets?page=1&page_size=1000

# Step 2: 对每个 KB（如不存在则创建）
POST /api/v1/datasets
  Body: {"name": "产品文档", "description": "..."}

# Step 3: 批量上传文件（自动触发解析）
POST /api/v1/datasets/{dataset_id}/documents
  Content-Type: multipart/form-data
  Body: file=@需求规格.pdf, file=@用户手册.docx

核对维度（数量级）

迁移后需要验证文档确实被正确解析且检索可用。验证分三个层次：

1. 按 chunk_method 分类抽样：每种 parser 类型各抽 2-3 个文档
2. 调用检索 API：

   POST /api/v1/searches
   Body: {
     "dataset_ids": ["{id}"],
     "query": "文档中的关键字或摘要句",
     "top_k": 5
   }
   → 返回 [{content, score, document_name, ...}]

3. 人工检查：返回的 chunk content 是否语义相关、文本是否完整（无截断、无乱码）
4. 对比旧版：如有 v0.17.2 仍可查询，用相同 query 对比两个版本返回的 chunk 数量和内容相似度

两个版本的权限模型基本一致：

# config.yaml
source:
  mysql:
    host: "localhost"
    port: 3306
    user: "root"
    password: ""
    database: "rag_flow"
  storage:
    type: "minio"
    host: "localhost:9000"
    access_key: "minioadmin"
    secret_key: "minioadmin"
    secure: false

target:
  base_url: "http://localhost:9380"
  api_key: "ragflow-xxxx"       # 从 v0.25.6 Web UI → API 获取
  timeout: 300

temp_dir: "/tmp/ragflow_migration"
batch_size: 10

前置条件

执行步骤

# Step 0: 准备
cd tools/scripts/migrate_v0172_to_v0256
vim config.yaml           # 填实际参数
pip install -r requirements.txt

# Step 1: 导出
python export_files.py -c config.yaml
  # 检查输出: /tmp/ragflow_migration/manifest.json

# Step 2: 导入
python import_to_v0256.py -c config.yaml
  # 文件上传成功后会立即触发解析

# Step 3: 基础核对
python verify_migration.py -c config.yaml
  # 如 PENDING 数 > 0，等待后重跑

# Step 4: 内容验证（手动/半自动）
  # 4a. 检查 FAIL 状态的文档
  # 4b. 抽样检索验证 chunk 质量
  # 4c. 对比 source/target chunk_count 分布

# Step 5: 权限验证
  # 5a. 用不同用户 API Key 测试 me/team 隔离
  # 5b. 确认检索 API 可用

执行时间估算

回滚

本方案不修改 v0.17.2 任何数据，回滚非常简单：

1. 删除 v0.25.6 中的 datasets — Web UI 或 DELETE /api/v1/datasets
2. rm -rf /tmp/ragflow_migration
3. v0.17.2 原环境完全不受影响