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

问题背景

Immich是一款开源的图片管理应用，在最新版本1.128.0中，部分用户遇到了服务启动卡死的问题。经过分析，这是由于数据库迁移脚本执行时出现了性能问题，导致服务无法正常启动。

问题现象

当用户升级到Immich 1.128.0版本时，服务启动过程中会卡在初始化阶段，日志显示服务尝试启动API和微服务工作线程后便不再继续。经过测试，降级到1.127.0版本可以正常工作，初步排除了数据库损坏的可能性。

根本原因

深入分析后发现，问题出在数据库迁移脚本上。1.128.0版本引入了一个名为"AddUpdateIdColumns"的迁移脚本，该脚本需要执行以下操作：

1. 在13个表中添加新的updateId列
2. 为这些列填充基于时间戳的UUIDv7值
3. 将这些列设置为NOT NULL并设置默认值
4. 为这些列创建索引

对于拥有大量数据的用户（例如超过30万条记录），这个迁移过程可能需要数小时才能完成，而在此期间服务会表现为"卡死"状态。

技术细节

UUIDv7是一种新型的UUID版本，它基于时间戳生成，相比传统UUID具有更好的排序和索引性能。Immich采用这种UUID来优化数据同步和更新追踪。

迁移脚本中的关键函数immich_uuid_v7是一个PostgreSQL自定义函数，它能够生成符合UUIDv7规范的标识符。这个函数接收一个时间戳参数，将其转换为64位整数，并与随机生成的部分组合形成最终的UUID。

解决方案

对于遇到此问题的用户，可以采取以下两种解决方案：

方案一：等待迁移完成

如果数据量不大，可以耐心等待迁移完成。可以通过监控数据库进程来确认迁移是否仍在进行。

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

对于数据量较大的用户，建议手动执行迁移脚本：

1. 首先创建UUIDv7生成函数
2. 为所有相关表添加updateId列
3. 使用批量更新语句填充这些列
4. 设置列的约束和默认值
5. 创建必要的索引
6. 最后在migrations表中记录迁移完成

手动执行的优势是可以监控每个步骤的进度，并在必要时进行优化调整。

预防措施

为了避免类似问题，建议：

1. 在升级前备份数据库
2. 对于生产环境，先在测试环境验证升级过程
3. 监控数据库性能指标，特别是CPU和I/O使用情况
4. 考虑在低峰期执行大规模数据库迁移

总结

数据库迁移是应用升级过程中的关键环节，Immich 1.128.0版本引入的UUIDv7功能虽然带来了性能优势，但也带来了迁移挑战。通过理解问题的本质和掌握解决方案，用户可以顺利完成升级过程，享受新版本带来的改进。