设置 Migration 并发数为 5 后系统死锁？揭秘 Immich 队列服务的线程陷阱。

在自建相册的性能调优名单里，Immich 的微服务架构（Microservices）本应是“高并发”的代名词。但很多开发者在进行大规模数据迁移时，为了追求速度，随手在环境变量里将 MIGRATION_CONCURRENCY 改成了 5 甚至更高。结果往往不是提前完工，而是眼睁睁看着 NAS 的负载瞬间爆表，Web 端彻底失去响应。

作为底层架构师，我习惯于从任务调度算法的角度复盘这种“自杀式”调优。问题的核心不在于你的 CPU 核心够不够，而在于 Immich 后端 QueueService 对数据库连接池与 I/O 等待的粗放管理。

💡 报错现象总结：在大规模迁移任务开启后，后台日志狂刷 [Nest] 7 - DEBUG [Microservices:QueueService] 设置 migration 并发数为 5。随后系统负载（Load Average）飙升，数据库连接报出 too many clients 或 Query timeout。本质是 5 个并发任务同时抢占文件系统句柄与 DB 写入锁，引发了严重的资源争用死锁。

---

线程陷阱：为什么并发 5 会变成“死锁 5”？

Immich 的任务队列由 BullMQ（基于 Redis）驱动。当你设置并发数为 5 时，immich_microservices 容器会启动 5 个独立的 Worker 来处理迁移。

根据高赞 Issue 中的调试日志分析，迁移任务（Migration）是一个典型的 I/O 密集型与数据库事务密集型操作。每一个 Worker 在处理一张照片时，都会经历：读取物理文件 -> 计算 Hash -> 写入文件系统 -> 开启 DB 事务更新元数据。

// 架构师解析：Immich 队列 Worker 的执行逻辑
// 在高并发下，如果 I/O 链路（尤其是机械硬盘）响应慢，5 个线程会同时卡在文件读取阶段
// 此时如果 DB 连接池已满，线程将无限期等待，最终导致主进程由于 Event Loop 被阻塞而死锁
[Nest] 7 - 2026年4月23日 上午11:47:39 DEBUG [Microservices:QueueService] 设置 migration 并发数为 5
[Nest] 7 - 2026年4月23日 上午11:47:39 DEBUG [Microservices:QueueService] 设置库并发数为 5

在不同并发设置下，资源消耗的真实反馈如下：

并发参数	CPU 上下文切换	磁盘 I/O 状态	数据库连接池压力	系统稳定性
并发 = 1	极低	顺序读写，吞吐稳健	1 个活跃连接	极高
并发 = 2	低	随机读写开始增加	2 个活跃连接	稳定
并发 = 5	极高	磁头频繁寻道，I/O Wait 飙升	触发 DB 连接限制	极易死锁

---

I/O 争用：机械硬盘用户的“催命符”

如果你的照片存储在机械硬盘（HDD）阵列上，设置并发 5 几乎等同于自毁。HDD 的物理磁头在处理 5 个并发的文件流时，会因为频繁的随机寻道导致 IOPS 耗尽。

此时，系统会进入 D 状态（Uninterruptible Sleep）。这意味着 CPU 实际上是在空转等待磁盘返回数据。在这种情况下，增加并发不仅不会变快，反而会因为频繁的任务切换（Context Switch）浪费掉剩余的算力。

---

如何优雅地给迁移任务“限速”？

如果你正面临迁移卡死的问题，硬核开发者通常会执行以下“手术”：

1. 强行降级并发数：不要迷信“人多力量大”。在 docker-compose.yml 中明确设置 IMMICH_QUEUE_MIGRATION_CONCURRENCY=1。相信我，在 HDD 环境下，单线程的效率往往高于多线程。
2. 调整 DB 连接池上限：如果你必须开启多并发，你得同步修改 PostgreSQL 的 max_connections。但这意味着你需要分配更多的内存给数据库。
3. 分批次导入：不要一次性把 10 万张照片全塞进扫描目录，按年份或月份分批放入，给数据库留出索引生成的喘息时间。

这种“笨办法”虽然不够极客，但在缺乏底层反压（Backpressure）机制的 Immich 当前版本中，这是保住数据的唯一稳妥方案。

---

获取“压测稳定的并发参数预设”

与其在负载 20+ 的报警声中心惊肉跳，不如直接采用社区公认的“黄金配置”。

我已经针对不同硬件环境（SSD vs HDD / ARM vs x86），在 GitCode 维护了一套**《Immich 并发负载调优指南》**。这份指南包含了一组经过 1TB 级数据实测的预设文件，能够确保在后台满负荷迁移时，你的 Web 界面依然能做到点哪开哪。

直接前往 GitCode 获取这些经过验证的并发参数。别让错误的配置烧毁你的 NAS，用最严谨的架构参数，跑出最丝滑的迁移过程。

[GitCode 提供已压测稳定的并发参数预设文件]