🔄 RAGFlow 数据迁移兼容性报告

👤 用户认证兼容性详解

2.1 密码哈希 — 完全兼容 ✅

2.2 User ID — 完全兼容 ✅

2.3 Email 唯一约束迁移 — 需确认 🟡

v0.25.6 将 user.email 从普通索引升级为 UNIQUE 约束。迁移函数 migrate_add_unique_email() 会自动处理：

1. 检测所有重复 email
2. 保留 superuser 或 最早创建 的账号
3. 其余重复账号重命名为 {email}_DUPLICATE_{id[:8]}
4. 添加 UNIQUE 约束

-- 迁移前
user1: admin@x.com  (superuser, 最早) → 保留
user2: admin@x.com                   → admin@x.com_DUPLICATE_a1b2c3d4

-- 日志输出
WARNING: Renamed duplicate user a1b2c3d4 email to admin@x.com_DUPLICATE_a1b2c3d4 during migration

2.4 登录认证框架变更 — 需重新登录 🔴

📚 知识库数据迁移详解

3.1 ID 和关键字段兼容性 ✅

3.2 Knowledgebase 表新增字段

3.3 TenantLLM 主键重构及其影响

这是本次升级最核心的架构变更，影响所有引用 LLM 模型的表：

3.4 FK 自动填充机制

v0.25.6 启动时 fix_empty_tenant_model_id() 自动执行以下映射：

-- 伪代码逻辑
# Tenant: 填充 6 个 FK
UPDATE tenant t
SET t.tenant_llm_id = (SELECT tl.id FROM tenant_llm tl
    WHERE tl.tenant_id = t.id AND tl.llm_name = t.llm_id)
WHERE t.tenant_llm_id IS NULL;

# Knowledgebase: 填充 tenant_embd_id
UPDATE knowledgebase kb
SET kb.tenant_embd_id = (SELECT tl.id FROM tenant_llm tl
    WHERE tl.tenant_id = kb.tenant_id AND tl.llm_name = kb.embd_id)
WHERE kb.tenant_embd_id IS NULL;

# Dialog: 填充 tenant_llm_id 和 tenant_rerank_id
UPDATE dialog d
SET d.tenant_llm_id = (SELECT tl.id FROM tenant_llm tl
    WHERE tl.tenant_id = d.tenant_id AND tl.llm_name = d.llm_id)
WHERE d.tenant_llm_id IS NULL;

# Memory: 填充 tenant_embd_id 和 tenant_llm_id
UPDATE memory m SET ... WHERE m.tenant_embd_id IS NULL;

3.5 字段重命名 — 数据完整保留 ✅

3.6 字段类型变更 — 无截断风险 ✅

🔑 API 接口兼容性详解

4.1 API Token 认证兼容性

4.2 检索/搜索接口兼容性

4.3 API Token 验证流程对比

v0.17.2 验证流程：

# api/utils/api_utils.py
def token_required(f):
    token = request.headers.get('Authorization').split()[1]
    obj = APIToken.query(token=token)  # 直接查表
    if not obj:
        return get_error_data_result("Authentication failed")

v0.25.6 验证流程：

# api/utils/api_utils.py (line 288+)
def token_required(f):
    token = request.headers.get('Authorization').split()[1]
    obj = APIToken.query(token=token)  # 先查表（与旧版相同）
    if obj:
        # token 有效
        return f(...)
    # 回退：尝试 JWT 解码（兼容旧 login token）
    user = UserService.query(access_token=token)
    ...

4.4 Token 格式差异对比

📋 迁移操作指南

预备检查清单

迁移步骤

# 完整数据库备份
mysqldump -u root -p ragflow > ragflow_v0172_backup.sql

# 如果使用 PostgreSQL
pg_dump -U ragflow ragflow > ragflow_v0172_backup.sql

cd /path/to/ragflow-0.17.2/docker
docker compose down

cd /path/to/ragflow-0.25.6/docker
docker compose -f docker-compose-base.yml up -d
# 等待 MySQL/Redis/ES/MinIO 全部 healthy
docker compose ps

docker compose -f docker-compose.yml up -d
# 监控启动日志
docker logs -f ragflow-server

# 查看日志中的迁移信息
docker logs ragflow-server 2>&1 | grep -E "(migrat|DUPLICATE|fix_empty|tenant_llm)"

# 验证用户数据
SELECT COUNT(*), COUNT(DISTINCT email) FROM user;

# 验证 FK 填充
SELECT COUNT(*) FROM tenant WHERE tenant_llm_id IS NOT NULL;
SELECT COUNT(*) FROM knowledgebase WHERE tenant_embd_id IS NOT NULL;
SELECT COUNT(*) FROM dialog WHERE tenant_llm_id IS NOT NULL;

回滚方案

# 1. 停止 v0.25.6
docker compose down -v

# 2. 恢复数据库备份
mysql -u root -p ragflow < ragflow_v0172_backup.sql

# 3. 重新启动 v0.17.2
cd /path/to/ragflow-0.17.2/docker
docker compose up -d