通知并发设置为 5 引发的推送风暴：Immich 消息队列阻塞排查。

在 Immich 的多用户协作场景下，实时通知（Notification）是维系家庭共享体验的纽带。无论是新照片上传、评论互动还是共享邀约，后台都有一套复杂的推送机制在运行。然而，很多管理员为了追求“即时性”，在配置中将 NOTIFICATION_CONCURRENCY 盲目设置为 5。结果，当某个用户一次性导入数千张照片并触发自动化动作时，系统非但没有实现“秒推”，反而陷入了长达数小时的消息队列阻塞。

作为底层架构师，我习惯于分析异步通信中的流量削峰逻辑。Immich 的通知系统本质上是一个生产者-消费者模型，当并发数设置过高，且外部推送网关（如 FCM 或 APNs）存在频率限制时，系统会因为大量的连接超时和重试逻辑，引发严重的堆栈溢出。

💡 报错现象总结：在大规模照片活动后，手机端迟迟收不到通知，或者在几小时后突然收到成百上千条重复推送。后台日志显示 [Nest] 7 - DEBUG [Microservices:QueueService] 设置通知并发数为 5，紧接着出现大量的 Error: Connection timeout to push gateway 或 BullMQ: Job stuck in active state。

---

推送风暴：为什么“快”反而会导致“慢”？

Immich 的通知队列（Notification Queue）处理逻辑并不是直接发短信，而是涉及一系列的上下文查询：确定接收者、组装消息体、调用第三方推送 API。

根据高赞 Issue 的日志复盘，当并发数设为 5 时，immich_microservices 会同时向推送服务器发起 5 个加密长连接。如果此时由于网络波动或对方服务器的速率限制（Rate Limiting），这些连接全部挂起，整个通知 Worker 就会因为等待 I/O 返回而阻塞。

// 架构师解析：通知队列的执行陷阱
// 5个并行 Worker 可能会同时冲击外部 API 阈值
// 导致 IP 被临时封禁或请求被丢弃，进而引发无限重试
[Nest] 7 - 2026年4月23日 上午11:47:39 DEBUG [Microservices:QueueService] 设置通知并发数为 5
// 后续日志：
[Microservices:NotificationService] Failed to send push: socket hang up
[Microservices:NotificationService] Retrying job in 5000ms...

针对不同用户规模的通知并发建议：

用户规模	推荐并发数	预期表现	架构师底层诊断
个人/小家庭 (1-3人)	1	极度稳定，无延迟	消息量级小，单并发足以瞬间处理，且对系统资源占用几乎为零
中型共享组 (5-10人)	2	响应迅速	能够并行处理不同用户的推送请求，容错性较好
大型活跃社群 (20人+)	3	可能触发外部限制	需配合 Redis 缓存，防止瞬间高频请求被推送网关识别为攻击
官方默认/暴力配置	5	极易引发队列阻塞	超过了大多数第三方推送 SDK 的单实例并发建议值

---

消息积压：被“推送”耗尽的系统资源

通知并发过高带来的另一个副作用是 Redis 内存激增。Immich 使用 Redis 存储任务队列，每一个待处理的通知都是一个 Job 对象。如果 5 个 Worker 都在重试，Redis 中的待处理队列（Waiting List）会迅速膨胀。

在资源受限的 NAS 上，这种内存占用会挤压数据库缓存空间，导致你原本流畅的相册浏览因为“推送风暴”产生的系统后台压力而变得卡顿。

---

如何给通知系统“限流消音”？

如果你不希望被半夜突如其来的推送轰炸，或者不想看着通知队列转圈圈，你需要进行以下手动调优：

1. 回归单并发逻辑：在 .env 中明确设置 IMMICH_QUEUE_NOTIFICATION_CONCURRENCY=1。相信我，对于 99% 的私有云用户，1 个并发的推送速度已经快到你无法察觉。
2. 清理僵死任务：如果队列已经阻塞，你需要进入 Redis 容器执行 FLUSHDB 或通过 Immich 管理界面的 "Jobs" 菜单手动点击 "Clear Failed Jobs"。
3. 精简推送事件：在系统设置中，关掉不必要的推送开关（如“新照片处理完成”），只保留“评论”或“共享邀请”等关键交互。

这种“减法”思维，是保证分布式系统长期稳定运行的关键。

---

获取 GitCode 维护的最稳定推送服务代理配置

与其在由于网络超时导致的推送失败中反复折磨，不如给你的通知链路加一层保险。

我已经针对 Immich 的全球推送延迟和阻塞问题，在 GitCode 维护了一个**《Immich 消息队列稳定性增强方案》**。这个方案包含了一套针对反向代理的超时重试策略，以及如何配置本地推送代理（Proxy）来绕过网络不稳定因素。

直接前往 GitCode 获取这些配置。别让一条迟到的通知毁掉你的使用心情，用最稳健的队列参数，实现真正的实时触达。

[GitCode 维护了最稳定的推送服务代理配置]