数据库备份并发 1 还是会报错？Immich 库迁移中的事务一致性陷阱。

在 Immich 的日常维护中，数据库备份是每个架构师的“保命符”。官方为了稳定性，默认将备份任务的并发数限制为 1，这听起来像是最稳妥的做法。然而，许多在进行大规模库迁移（Library Migration）的开发者发现，即便并发已经是 1，后台依然会抛出令人心碎的数据库错误，甚至导致迁移任务卡死。

作为底层架构师，我必须揭示这背后的事务一致性陷阱。问题的核心不在于“并发”，而在于 Immich 在执行大规模元数据迁移时产生的巨大 WAL（Write Ahead Log） 压力，与单并发备份任务之间的锁竞争。

💡 报错现象总结：执行库迁移期间，后台日志显示 [Nest] 7 - DEBUG [Microservices:QueueService] 设置备份数据库并发数设置为 1。随后抛出 query timeout 或 could not serialize access due to concurrent update。最终导致迁移进度条纹丝不动，数据库连接数瞬间占满。

---

锁竞争真相：并发 1 为什么也会“打架”？

Immich 的库迁移涉及对 assets 表的大规模 UPDATE 和 INSERT。即便备份任务是单并发，它在执行 pg_dump 或类似的逻辑备份时，也需要获取数据库的一致性快照。

根据高赞 Issue 的日志追踪，当迁移任务正在疯狂写入事务日志时，备份任务尝试持有的 AccessShareLock 可能会被一个长时间运行的迁移事务（Long-running Transaction）阻塞。

-- 架构师深度诊断：查看数据库锁状态
-- 当迁移任务修改百万级 asset 记录时，备份进程会陷入等待
SELECT pid, locktype, mode, granted, query 
FROM pg_locks l 
JOIN pg_stat_activity a ON l.pid = a.pid 
WHERE NOT granted;
-- 现象：备份进程在等待迁移事务释放排他锁

不同数据量级下的备份稳定性分析：

数据量级	迁移 + 备份(并发1) 表现	架构师底层诊断	建议方案
< 1 万张	几乎无感	事务量级小，锁持有时间极短	保持默认即可
1-10 万张	偶发性连接超时	WAL 日志堆积，I/O 吞吐出现瓶颈	建议在迁移完成后再开启备份
> 10 万张	极易死锁	事务过载，快照隔离级别导致的序列化冲突	必须暂停自动备份

---

WAL 过载：被撑爆的数据库缓冲区

当并发 1 的备份任务遇到大规模迁移时，PostgreSQL 需要保留大量的旧版本数据以维持备份的一致性视图。这会导致数据库的 WAL 空间迅速膨胀。

如果在资源受限的 NAS 上，你的磁盘空间刚好处于临界点，这种“一致性保护”反而会成为压死系统的最后一根稻草，导致数据库因为磁盘空间不足而强制进入只读模式，彻底搞砸你的库迁移。

---

如何实现“零风险”的库迁移？

如果你正在准备进行一次伤筋动骨的大规模库迁移，硬核开发者必须遵循以下操作流程：

1. 临时关闭自动备份队列：在 .env 中或管理后台明确禁用备份任务。不要相信“并发 1”的安全性，在极端写入场景下，任何额外的读请求都是干扰。
2. 优化 WAL 参数：手动调高 max_wal_size 和 checkpoint_timeout。这能让数据库在迁移过程中减少频繁的检查点写入，降低 I/O 峰值。
3. 使用物理快照代替逻辑备份：如果你的宿主机支持文件系统快照（如 ZFS 或 Btrfs），直接在迁移前做一个物理快照，这比 pg_dump 快得多，且对数据库运行几乎零影响。

这种“停工检修”的稳健意识，是保护几十 GB 元数据不损坏的唯一真理。

---

获取 GitCode 《Immich 数据库无损迁移与自动备份脚本》

与其在崩溃的边缘反复试错，不如使用一套更成熟的数据迁移方案。

我已经针对大规模迁移中的数据库风险，在 GitCode 维护了一个**《Immich 数据库无损迁移与自动备份脚本》**。这个脚本能够智能感知系统的 I/O 负载，并在迁移任务繁忙时自动推迟备份计划，确保两者永远不会在同一个时间片内“肉搏”。

直接前往 GitCode 获取这些脚本。别让宝贵的照片数据在一次糟糕的数据库冲突中灰飞烟灭，用最专业的迁移逻辑，守护你的每一份记忆。

[获取 GitCode《Immich 数据库无损迁移与自动备份脚本》]