Tubesync项目MariaDB数据库迁移问题分析与解决方案

问题背景

Tubesync是一款优秀的媒体同步工具，近期部分用户在使用MariaDB作为数据库后端时遇到了表结构迁移失败的问题。具体表现为在容器启动过程中出现"Table sync_metadata already exists"错误，导致服务无法正常启动。

问题根源分析

经过深入排查，发现该问题主要由以下几个因素共同导致：

1. UUID字段类型不匹配：Tubesync最新版本要求使用原生UUID类型作为主键，而早期版本中使用了char(32)类型存储UUID字符串。

2. MariaDB事务处理差异：与MySQL不同，MariaDB在执行迁移时未能完整支持事务回滚机制，导致迁移过程中断后数据库处于不一致状态。

3. 表结构残留问题：迁移过程中部分表(sync_metadata、sync_metadataformat等)已创建但未完成完整迁移流程，导致后续迁移尝试失败。

详细解决方案

准备工作

在进行任何修复操作前，强烈建议先备份数据库。可以通过Django的dumpdata命令或直接导出数据库。

修复步骤

1. 回滚到迁移前状态

python3 /app/manage.py migrate -v 3 sync 0030_alter_source_source_vcodec

2. 清理残留表结构

DROP TABLE IF EXISTS `new__sync_media_metadata_format` CASCADE;
DROP TABLE IF EXISTS `new__sync_media_metadata` CASCADE;
DROP TABLE IF EXISTS `sync_media_metadata_format` CASCADE;
DROP TABLE IF EXISTS `sync_media_metadata` CASCADE;

DROP TABLE IF EXISTS `new__sync_metadataformat` CASCADE;
DROP TABLE IF EXISTS `new__sync_metadata` CASCADE;
DROP TABLE IF EXISTS `sync_metadataformat` CASCADE;
DROP TABLE IF EXISTS `sync_metadata` CASCADE;

3. 修正UUID字段类型

ALTER TABLE `sync_media` 
DROP FOREIGN KEY `sync_media_source_id_36827e1d_fk_sync_source_uuid`;

ALTER TABLE `sync_media` 
MODIFY COLUMN `uuid` UUID NOT NULL;

ALTER TABLE `sync_media` 
MODIFY COLUMN `source_id` UUID NOT NULL;

ALTER TABLE `sync_source` 
MODIFY COLUMN `uuid` UUID NOT NULL;

ALTER TABLE `sync_media`
ADD CONSTRAINT `sync_media_source_id_36827e1d_fk_sync_source_uuid`
FOREIGN KEY (`source_id`) REFERENCES `sync_source` (`uuid`);

4. 执行完整迁移

python3 /app/manage.py migrate -v 3 sync 0031_squashed_metadata_metadataformat

5. 等待数据迁移完成

迁移过程可能需要较长时间(根据数据量可能需要数小时)，请耐心等待。

最新修复工具

Tubesync项目已提供专用修复工具简化上述流程：

python3 /app/manage.py fix-mariadb --uuid-columns

该工具提供以下功能：

• --dry-run：模拟执行，不实际修改数据库
• --delete-table：安全删除特定表
• 自动检测并修复UUID字段类型问题

技术建议

1. 数据库选型：对于新部署，建议优先考虑PostgreSQL或MySQL，它们对Django迁移的支持更完善。

2. 迁移监控：大规模数据迁移时应监控数据库性能，必要时调整MariaDB配置参数。

3. 备份策略：在执行任何数据库结构调整前，确保有完整的备份方案。

4. 版本控制：保持Tubesync和数据库系统的版本同步更新，避免兼容性问题。

总结

Tubesync与MariaDB的兼容性问题主要源于UUID字段类型和迁移事务处理的特殊性。通过系统性的表结构调整和迁移流程控制，可以有效解决此类问题。项目团队已提供专用工具简化修复流程，未来版本将进一步优化数据库兼容性。对于生产环境，建议在非高峰期执行此类维护操作，并确保有完整的回滚方案。