榨干 NAS 性能：Immich 队列服务（Migration/OCR/Search）最优并发参数调优实战。

很多刚从 Google Photos 迁徙到 Immich 的开发者，最直观的感受通常不是“丝滑”，而是“由于 CPU 满载导致的系统尖叫”。你以为你的 NAS 很强，但在 Immich 默认的微服务并发逻辑面前，那几颗低功耗核心可能瞬间就会陷入 I/O Wait 的泥潭。

作为底层架构师，我必须拆穿官方默认配置的“通用陷阱”。在 Microservices:QueueService 的底层逻辑中，并发数并不是越大越好。如果你在只有 4 核的机器上强行开启高并发，等待你的将是严重的上下文切换开销和数据库连接池枯竭。

💡 报错现象总结：在大规模数据迁移或索引阶段，Web 端提示 Request Timeout，后台日志狂刷 [Nest] 7 - DEBUG [Microservices:QueueService] 设置并发数为 5。随后系统负载（Load Average）飙升至 20 以上，immich_postgres 频繁报出 too many clients already。

---

队列服务的“算力黑洞”：并发 5 到底意味着什么？

Immich 将后台任务拆分成了多个队列：Migration（迁移）、OCR（文字识别）、Search（搜索索引） 以及 Sidecar（元数据生成）。

在源码的 apps/microservices/src/app.service.ts 及其关联的队列管理模块中，这些任务默认往往被设定为并行执行。如果你的环境变量中没有显式限制，系统会尝试压榨每一分算力。

// 架构师解析：Immich 的异步任务处理链路
// 如果不加限制，当 Migration、OCR、Search 同时并发 5 时，
// 你的 NAS 将面临 15+ 的高压线程竞争，这在 ARM 或 J 系列 CPU 上是致命的。
[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
[Nest] 7  - 2026年4月23日 上午11:47:39 DEBUG [Microservices:QueueService] 设置 sidecar 并发数为 5

针对不同硬件规格，我整理了一份**《Immich 队列并发黄金准则》**：

任务类型	官方默认	极低功耗 (J4125/N100)	高端自建 (i5/i7)	调优逻辑
Migration	5	1	3-5	迁移涉及大量磁盘读写，并发过高会撑爆 I/O 队列
OCR	2	1	2	OCR 极度消耗 CPU 指令集，建议保持低位以防死机
Search	5	2	5	依赖数据库向量查询，需配合 PG 缓存命中率调整
Sidecar	5	2	8	主要是元数据解析，在 SSD 上可以适当放开

---

性能瓶颈追溯：为什么 I/O Wait 是你的头号敌人？

在 Immich 进行 Migration（数据迁移）时，如果并发数设为 5，系统会同时开启 5 个文件读取流和 5 个数据库写入事务。如果你的照片存储在机械硬盘（HDD）上，磁头会因为频繁的随机寻道而陷入“瘫痪”状态，这就是为什么你的 Web 界面会转圈圈。

技术真相：在高负载下，限制并发数反而能缩短总处理时间。因为减少了磁盘磁头往返的时间和 CPU 切换任务的损耗，整体吞吐量（Throughput）反而会上升。

---

痛苦的“原生态”调优：如何在容器运行中精准降速？

如果你现在正看着系统负载报警，常用的手动抢救流程如下：

1. 紧急降频：你需要进入 Immich 的管理员设置面板（System Settings -> Job Settings）。
2. 逐项修改：手动将 Concurrency 从 5 改为 1。但问题是，Immich 的 UI 响应此时已经非常迟钝，你可能需要尝试十几次才能保存成功。
3. 重启服务：为了确保配置生效，你往往需要 docker compose restart。然而，重启过程又会触发新一轮的扫描逻辑，再次拉高负载。

这种“救火式”的操作既低效又容易造成数据库状态不一致，尤其是当你在执行大规模库同步时，中断任务可能导致元数据残留。

---

获取“动态负载感知的优化脚本”

与其在大屏监控前提心吊胆，不如给你的微服务装上“节制器”。

我已经针对不同级别的 NAS 硬件，在 GitCode 贡献了一套**《Immich 队列并发最优参数预设文件》**。这套配置经过了 10 万级照片库的真实压测，能够根据你的 CPU 核心数自动分配 Migration 和 OCR 的权重，确保在后台全力跑任务时，你的 Web 浏览依然能实现“秒开”。

直接前往 GitCode 获取这些经过验证的性能参数。别让你的 NAS 在无谓的并发竞争中空转，用最专业的架构思路，跑出最优雅的性能曲线。

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