MoviePilot/MIGRATION_README.md

SiteUserData表userid字段类型迁移说明

概述

本次迁移将 SiteUserData 表中的 userid 字段从 Integer 类型改为 String 类型，以支持更灵活的用户ID格式。

变更内容

1. 数据模型变更

文件: app/db/models/siteuserdata.py

# 变更前
userid = Column(Integer)

# 变更后  
userid = Column(String)

2. Schema定义变更

文件: app/schemas/site.py

# 变更前
userid: Optional[Union[int, str]] = None

# 变更后
userid: Optional[str] = None

3. 数据库迁移脚本

文件: database/versions/a946dae52526_2_2_1.py

• 版本号: 2.2.1
• 修订ID: a946dae52526
• 前置版本: 5b3355c964bb (2.2.0)

迁移功能

1. PostgreSQL数据库迁移:

   • 创建临时列 userid_new (VARCHAR类型)
   • 将现有数据转换为字符串并复制到新列
   • 删除旧列 userid
   • 重命名新列为 userid

2. SQLite数据库迁移:

   • 创建新表结构，userid字段为VARCHAR类型
   • 复制现有数据，将userid转换为字符串
   • 删除旧表并重命名新表
   • 重新创建索引

降级功能

1. PostgreSQL数据库降级:

   • 创建临时列 userid_old (INTEGER类型)
   • 将字符串转换为整数（仅转换数字字符串）
   • 删除旧列并重命名新列

2. SQLite数据库降级:

   • 创建新表结构，userid字段为INTEGER类型
   • 复制数据，仅转换数字字符串为整数
   • 删除旧表并重命名新表
   • 重新创建索引

4. 代码兼容性修复

修复的文件

1. app/modules/indexer/parser/nexus_rabbit.py

   # 修复前
   "data": {"type": "seeding", "id": int(self.userid)},
   
   # 修复后
   "data": {"type": "seeding", "id": int(self.userid) if self.userid and str(self.userid).isdigit() else 0},
   

2. app/modules/synologychat/synologychat.py

   # 修复前
   payload_data['user_ids'] = [int(userid)]
   
   # 修复后
   payload_data['user_ids'] = [int(userid) if str(userid).isdigit() else userid]
   

迁移步骤

1. 备份数据库

在执行迁移前，请务必备份数据库：

# SQLite数据库备份
cp user.db user.db.backup

# PostgreSQL数据库备份
pg_dump -h localhost -U username -d database_name > backup.sql

2. 执行迁移

# 进入项目目录
cd /path/to/project

# 执行数据库迁移
python -m alembic upgrade head

3. 验证迁移

运行测试脚本验证迁移是否成功：

python test_migration.py

影响分析

正面影响

1. 灵活性提升: 支持非数字格式的用户ID
2. 兼容性增强: 适应不同站点的用户ID格式
3. 数据完整性: 保持原有数据不丢失

潜在风险

1. 性能影响: 字符串类型可能比整数类型占用更多存储空间
2. 查询性能: 字符串比较可能比整数比较稍慢
3. 数据验证: 需要确保应用程序正确处理字符串类型的userid

兼容性说明

1. 向后兼容: 迁移脚本包含降级功能，可以回滚到Integer类型
2. 代码兼容: 已修复所有直接使用userid的代码
3. API兼容: Schema变更保持了API的向后兼容性

测试验证

功能测试

1. 数据插入测试: 验证整数和字符串类型的userid都能正常插入
2. 数据查询测试: 验证按域名、日期等条件查询功能正常
3. 数据更新测试: 验证userid字段更新功能正常
4. API测试: 验证相关API接口正常工作

性能测试

1. 查询性能: 验证查询性能无明显下降
2. 存储空间: 验证存储空间使用情况
3. 并发性能: 验证并发操作正常

回滚方案

如果迁移出现问题，可以执行降级操作：

# 降级到上一个版本
python -m alembic downgrade 5b3355c964bb

注意事项

1. 备份重要: 执行迁移前必须备份数据库
2. 测试环境: 建议先在测试环境验证迁移
3. 监控日志: 迁移过程中注意观察日志输出
4. 数据验证: 迁移完成后验证数据完整性

联系信息

如有问题，请联系开发团队或查看项目文档。