并发数为 5 的 Sidecar 生成引发的 I/O 延迟：Immich 存储性能瓶颈复盘。

在 Immich 的高性能微服务矩阵中，Sidecar（元数据侧边文件） 的生成通常被认为是一个轻量级的后台任务。然而，许多将照片存储在机械硬盘阵列（HDD）或通过低速网络挂载（如 SMB/NFS）的开发者发现，当系统在大规模导入期间将 SIDECAR_CONCURRENCY 设为 5 时，整个相册的预览体验会瞬间崩溃。

作为底层架构师，我必须指出：Sidecar 生成看似只是写几个 .xml 或 .json 文件，但它涉及极其密集的 小文件随机读写。在缺乏 I/O 调度优化的环境下，这种并发压力会直接拖垮你的磁盘响应时间。

💡 报错现象总结：在大规模处理期间，Web 端预览图加载出现明显的“白块”，后台日志显示 [Nest] 7 - DEBUG [Microservices:QueueService] 设置 sidecar 并发数为 5。与此同时，系统 iowait 指标飙升，磁盘队列深度（Queue Depth）长时间处于饱和状态，导致基础的 Web 服务响应延迟从毫秒级退化到秒级。

---

随机读写的噩梦：为什么小文件会拖垮大阵列？

Immich 的 Sidecar 任务逻辑通常包括从原始图片提取 EXIF、XMP 信息并持久化。这意味着每一个任务都要经历“打开大图 -> 读取头部信息 -> 创建小文件 -> 写入磁盘”的完整链路。

在并发数为 5 的情况下，磁盘磁头需要在存储原始照片的数据区和存储元数据的目录区间频繁跳跃。对于机械硬盘（HDD）来说，这种随机寻道（Random Seek）是性能杀手。

// 架构师解析：Sidecar 生成的任务竞争
// 5个 Worker 同时触发 fs.readFile 和 fs.writeFile
// 如果没有 SSD 缓存层，磁盘 IOPS 会迅速耗尽
[Nest] 7 - 2026年4月23日 上午11:47:39 DEBUG [Microservices:QueueService] 设置 sidecar 并发数为 5
// 结果导致其他高优先级任务（如 Thumbnails 预览图读取）在 I/O 队列中排队

针对不同存储介质的 Sidecar 性能反馈如下：

存储介质类型	并发 5 的表现	架构师底层诊断	建议参数
单盘 HDD / 绿盘	极卡，系统近乎假死	IOPS 极低，磁头寻道延迟成为系统总线瓶颈	1
HDD RAID 阵列	预览图加载有明显迟滞	吞吐量虽高，但并发随机写的延迟依然存在	2
SATA SSD	流畅	零寻道延迟，能轻松应对多并发小文件写入	5
NVMe SSD	丝滑	极高的并发处理能力，瓶颈转移至 CPU 核心	8+

---

I/O 优先级倒置：被“侧边文件”挤掉的预览图

最让开发者头疼的问题在于，Immich 目前的队列系统并没有严格的 I/O 优先级（IONICE） 控制。当你设置 Sidecar 并发为 5 时，这些后台任务会与你前端浏览相册时的“预览图读取”请求平起平坐地竞争磁盘带宽。

这意味着服务器正在忙着给几年前的照片写 XML，却让你现在想看的照片加载不出来。这种资源分配的失衡，是导致“自建不如云端”错觉的主要原因。

---

如何解决存储层的“肠梗阻”？

如果你不打算升级全闪存阵列，那么你必须手动干预 Immich 的 I/O 行为：

1. 强制降并发：在 .env 中设置 IMMICH_QUEUE_SIDECAR_CONCURRENCY=1（HDD 用户必做）。虽然这会让元数据生成变慢，但能保住 Web 端的浏览体验。
2. 利用外部缓存加速：如果你使用 Linux 部署，可以尝试开启 bcache 或 LVM Cache，用一小块 SSD 给大容量 HDD 做读写缓存，专门承载这类高频小文件操作。
3. 分离存储路径：如果条件允许，将 Immich 的库目录（Library）和上传目录（Upload）分开，或者通过挂载参数（如 noatime）减少不必要的磁盘写入压力。

这种“空间换时间”或“牺牲速度换流畅”的策略，是每个自建架构师在资源有限情况下的必修课。

---

访问 GitCode 获取磁盘 I/O 优化与缓存加速方案

与其在转圈圈的瀑布流面前唉声叹气，不如直接从系统底层动刀。

我已经针对 Immich 的存储压力问题，在 GitCode 维护了一个**《Immich 存储性能优化与 SSD 缓存配置指南》**。这份指南包含了一组针对 Unraid、TrueNAS 以及普通 Linux 环境的挂载优化参数，以及如何配置 dm-cache 来实现“用百元 SSD 加速 T 级 HDD 库”的实战代码。

直接前往 GitCode 访问这些方案。别让缓慢的磁盘寻道毁了你的数字化记忆，用最专业的存储调优，让你的 Immich 跑出极致的速度。

[访问 GitCode 获取磁盘 I/O 优化与缓存加速方案]