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

问题背景

Immich是一款开源的图片管理应用，在最新版本1.128.0中，部分用户遇到了服务启动卡死的问题。经过分析，这是由于数据库迁移脚本执行时间过长导致的，特别是对于拥有大量图片数据的用户。

问题现象

当用户升级到Immich 1.128.0版本时，服务启动过程会在执行数据库迁移时停滞，日志中仅显示初始化信息而没有进一步的错误提示。相比之下，回退到1.127.0版本或设置DB_SKIP_MIGRATIONS=true参数时，服务可以正常启动。

根本原因

1.128.0版本引入了一个重要的数据库变更，需要为多个表添加updateId列并填充数据。这个迁移操作涉及以下步骤：

1. 为13个表添加新的updateId列
2. 使用自定义函数immich_uuid_v7为所有现有记录生成并填充UUID值
3. 将updateId列设置为NOT NULL并设置默认值
4. 为updateId列创建索引

对于拥有数十万甚至数百万记录的大型数据库，这个迁移过程可能需要数小时才能完成，而在此期间服务会表现为"卡死"状态。

技术细节

immich_uuid_v7是一个自定义的PostgreSQL函数，它基于时间戳生成UUID v7格式的标识符。这种UUID版本7的特点是包含时间信息，有利于按时间排序。

迁移脚本的核心操作包括：

• 创建immich_uuid_v7函数
• 为13个表添加updateId列
• 使用immich_uuid_v7函数为所有现有记录填充updateId值
• 设置updateId列为NOT NULL并设置默认值
• 为updateId列创建索引

解决方案

对于遇到此问题的用户，有以下几种解决方案：

方案一：等待迁移完成

如果服务只是看起来卡住而没有真正崩溃，可以耐心等待迁移完成。对于大型数据库，这可能需要数小时。

方案二：手动执行迁移脚本

1. 连接到PostgreSQL数据库
2. 依次执行以下SQL命令：
   • 创建immich_uuid_v7函数
   • 为各表添加updateId列
   • 为现有记录填充updateId值
   • 设置列约束和默认值
   • 创建索引
3. 在migrations表中记录迁移完成

方案三：跳过迁移

在环境变量中设置DB_SKIP_MIGRATIONS=true可以跳过迁移步骤，但这可能导致某些新功能不可用。

最佳实践建议

1. 对于生产环境，建议在低峰期执行升级
2. 升级前做好数据库备份
3. 对于大型数据库，考虑使用手动迁移方式
4. 监控数据库性能指标，确保迁移过程正常进行

总结

Immich 1.128.0的数据库迁移虽然设计合理，但对于大型数据库执行时间过长的问题需要用户特别注意。通过理解迁移机制和采用适当的解决方案，用户可以顺利完成升级并享受新版本带来的功能改进。