三層語意

consumer 端需要同時處理三層語意：

1. delivery semantics：訊息是否被成功投遞與確認，包含 ack/nack、retry、DLQ。
2. processing semantics：業務副作用是否可承受重複、亂序與部分失敗。
3. recovery semantics：故障後是否能重播、補償與回復到一致狀態。

這三層拆開後，才能看清問題落在哪一層。訊息送達不代表副作用完成；副作用完成不代表系統可恢復。

consumer group、partition 與順序責任

consumer group 與 partition 定義了並行與順序邊界。順序要求高的流程要把同一鍵值固定在同一 partition；吞吐優先的流程可提高 partition 數並分散處理。

分區策略會直接影響恢復成本。分區鍵混亂時，重播與補償很難限定範圍，事故期間容易擴大影響面。

checkpoint、offset 與 idempotency

checkpoint 與 offset 的責任是標記「處理到哪裡」，不是「業務一定完成」。寫 checkpoint 的時機要晚於副作用提交，避免進度前移導致資料遺漏。

idempotency key 的責任是讓重試與重播可重入。付款、發票、通知、庫存變更都需要明確冪等鍵與去重儲存策略，讓「至少一次投遞」不會變成「多次業務結果」。

replay safety

replay safety 的核心是先定義可重播範圍，再定義副作用控制。常見做法包含：

1. 限定 replay window，避免一次重播跨越多個版本邊界。
2. 將副作用拆成可比對與可補償動作，保留對帳路徑。
3. 對 replay 期間的下游壓力設置節流與停損條件。

poison message 要獨立隔離。持續重試同一壞訊息會壓垮整體吞吐，穩定做法是送入 dead-letter queue，再走診斷與修復流程。

Queue 語意誤配是 broker 遷移最常見的失敗模式

Broker 遷移失敗的根因通常是 consumer 對舊 broker 行為的隱式依賴、不是 broker 本身效能。表面上訊息仍被送達、但業務資料開始出現重複扣款、重複寄信、狀態漏更新。

對應 3.C9 反例：Queue Semantics Mismatch Cutover — case 揭露切換後語意誤配三個方向：consumer 依賴特定 offset 行為、依賴特定重試節奏、依賴特定 idempotency 行為。失敗重播時、新系統即使提供相近 delivery semantics、結果可能不同。語意誤配會沿著下游資料寫入擴散、難以靠 queue depth 判斷。

典型誤配場景（基於通用 broker 行為知識展開、非 3.C9 case 原文具體列舉）：

• At-least-once 假設變成 exactly-once 依賴：consumer 假設 broker 僅送一次、靠記憶單次處理；新 broker 重送同一 message、consumer 處理兩次
• Offset 跳號處理差異：舊系統重啟後 offset 從特定位置開始、新系統可能從 latest / earliest 不同位置開始
• Consumer group rebalance 行為差異：rebalance 期間舊系統會 pause 處理、新系統可能繼續處理、產生並發寫入衝突
• DLQ retry 節奏差異：舊系統 DLQ message 預設不重試、新系統可能自動重試、製造重複副作用

回退判讀：回退前要先確認哪一段資料已經被新語意處理過。直接切回舊 broker 可能讓同一批事件再次被處理。穩定做法是先凍結新 consumer、保留 offset 對照與 replay 範圍、再決定補償或重播。

詳細處理 / 恢復語意分層見 3.6 processing-recovery-semantics。規模差異判讀（小 / 中 / 大型服務的 job queue 治理重點）見 3.8 queue-consumer-retry-replay-handoff — 中型服務常見問題是 lag/DLQ 長期累積、需具備定向 replay 能力、否則退回全 topic 重播會放大下游壓力。

三個工程議題要一起設計

Consumer idempotency + 重播流程 + 下游承載能力 三件事是 consumer design 的鐵三角、需同步落地。缺一個會在規模化時暴露成事故：

• Consumer idempotency 不完整：DLQ replay 後產生重複副作用、即使 broker 切換成功、業務帳本仍然錯亂
• 重播流程不完整：事故當下需具備定向 replay 能力、否則退回全 topic 重播會放大下游壓力
• 下游承載能力不足：consumer 跟 broker 都健康、但下游 DB / API 撐不住 replay 速率、形成新事故

Job queue 的拓樸分工是另一個獨立議題、跟鐵三角互補但不重疊 — 詳見 3.8 Job queue 拓樸分工、主寫 Slack Kafka + Redis 案例。consumer 內部三件事要做好之外、不同類工作（高吞吐 / 即時 / 持久）也應專注單一目標、其他目標拆到對應路徑。

判讀訊號

常見誤區

把 consumer 設計等同於「把 handler 寫完」，會漏掉恢復責任。consumer 的工程價值在於故障後仍可追蹤、可補償、可重播。

把 DLQ 當成終點，會讓問題在下次事件再出現。DLQ 的責任是隔離與診斷入口，最終要回到 schema、邏輯或依賴治理。

案例回寫

consumer 恢復語意可用 3.C9 反例 與 3.C3 LinkedIn：TopicGC 對照回寫。先判讀問題是 idempotency 失效、checkpoint 前移，還是 replay 邊界失控，再對應本章的 processing/recovery 段落。 這組案例主要支撐的是「處理恢復語意」判讀，不直接支撐 deployment drain 或 cache eviction；若根因在切流順序或快取容量，應轉到 5.3 或 2.3。

若重播成功但業務狀態仍不一致，先補副作用補償與對帳路徑，並把決策證據同步到 8.19 Incident Decision Log。

跨模組路由

consumer 設計是 01/03/04/06/08 的交界點。

1. 與 03 內部的交接：processing/recovery 語意完整定義在 3.6 processing-recovery-semantics；event contract 跟 replay boundary 在 3.7；規模差異判讀跟 job queue 拓樸分工在 3.8。
2. 與 01 的交接：交易與發布一致性回到 3.3 outbox pattern 與 1.3 transaction boundary。
3. 與 04 的交接：lag、retry、DLQ、duplicate 指標進入 Observability Evidence Package。
4. 與 06 的交接：重試與重播驗證進入 6.12 Idempotency 與 Replay 驗證。
5. 與 08 的交接：pause consumer、replay 決策與補償判斷記錄到 Incident Decision Log。

下一步路由

要看 processing / recovery 三層語意完整定義、接著讀 3.6 processing-recovery-semantics。要建立 broker 層投遞模型，接著讀 3.1 broker 基礎與投遞模型 與 3.2 durable queue。要看錯誤切換案例，接著讀 3.C9 反例。

本文是 NATS overview 的 implementation-layer deep article、定位在「要不要從 core NATS 跨進 JetStream」的決策入口。選型層（NATS vs Kafka / RabbitMQ）見 overview；本文只處理 core 與 JetStream 的邊界與基本 consumer 設定。決定採用 JetStream 後的完整實作（stream / consumer 每個旋鈕、跨區拓樸、多租戶）見 JetStream 設計與 supercluster / leaf node。JetStream 實機驗證於 nats:latest（-js）、最後檢查日 2026-06-16；機制以 NATS JetStream 官方文件 為準。

fire-and-forget 在 rolling deploy 那一刻掉訊息

Core NATS 的低延遲來自它什麼都不記——一則訊息發布出去，當下有訂閱者就送達、沒有就丟棄。沒有儲存、沒有 ack、沒有重送。這適合「即時但可丟」的場景（metrics、presence、即時通知）：訂閱者暫時離線錯過幾則無所謂，下一則馬上來。

但這個設計有一條清楚的邊界。Clarifai 用 NATS 跑 ML 模型訓練的非同步任務，任務從幾秒到幾分鐘，原本同步呼叫——結果每次 rolling deployment（pod 輪流重啟）就掉訊息：訊息發布的瞬間目標 worker 正在重啟，core NATS 找不到訂閱者就丟了。他們的解法是改用 NATS（當時是 NATS Streaming、JetStream 的前身）的 at-least-once delivery + redelivery + queue group，每日 100k+ 訊息、達成 100% uptime。這個案例揭露的邊界是——ML 長尾任務不能容忍 rolling deploy 掉訊息，core NATS 的 fire-and-forget 到此為止，要跨進 JetStream。

JetStream 在 core NATS 之上加了一層持久化的 stream + 可重送的 consumer。本文處理這條邊界：什麼時候 core 夠用、什麼時候要 JetStream、跨過去的 consumer 模型怎麼設才不會丟訊息或重投風暴。

核心概念：stream 與 consumer 的求值模型

JetStream 把「訊息儲存」跟「消費進度」拆成兩個獨立物件——stream（存什麼、留多久）跟 consumer（誰讀、怎麼 ack）。理解 JetStream 就是理解這兩者。

stream 決定訊息怎麼被儲存與保留。一個 stream 綁定一組 subject、把符合的訊息持久化。三個關鍵維度：storage（file 持久 / memory 重啟即失）、retention（limits 依大小/時間/數量保留、workqueue 消費後即刪、interest 有訂閱者才留）、limits（max-msgs / max-bytes / max-age）。retention 選錯是常見陷阱——workqueue 是「每則訊息只被一個 consumer 消費一次就刪」，limits 是「保留著、多個 consumer 各自讀」。

consumer 是 stream 上的一個可重播視圖。同一個 stream 可以有多個 consumer，各自維護自己的消費位置。consumer 的關鍵屬性：

• push vs pull：push 由 server 主動推給訂閱者；pull 由 client 主動拉（consumer next），pull 對流量控制與 worker pool 更可控
• durable vs ephemeral：durable consumer 的進度持久（重啟後從上次位置續讀），ephemeral 在 client 斷線後消失（進度丟失）
• ack policy：explicit（每則都要 ack、at-least-once 的基礎）/ all（ack 一則等於 ack 之前所有）/ none（不需 ack、近似 fire-and-forget）
• max_deliver + ack_wait：沒 ack 的訊息在 ack_wait 後重送，最多 max_deliver 次

at-least-once 來自「explicit ack + redelivery」。consumer 取出訊息、處理、明確 ack；沒 ack（處理失敗或 crash）的訊息在 ack_wait 逾時後重送。這就是 Clarifai 要的「rolling deploy 不丟訊息」——worker 重啟時沒 ack 的任務會被重送給其他 worker。

配置：durable pull consumer（實機驗證）

 1# 啟動 JetStream（server 加 -js）
 2# docker run -d --name nats nats:latest -js
 3
 4# 1. 建 stream：file storage、limits retention
 5nats stream add ORDERS --subjects "orders.>" --storage file --defaults
 6#   Subjects: orders.>   Storage: File   Retention: Limits   Replicas: 1
 7
 8# 2. publish
 9nats pub orders.new "order-1"   # Published 7 bytes to "orders.new"
10
11# 3. stream info 確認持久化
12nats stream info ORDERS
13#   Storage: File   Messages: 3   Bytes: 141 B   ← 訊息已落盤、consumer 重啟不丟
14
15# 4. durable pull consumer（explicit ack、可重送）
16nats consumer add ORDERS workers --pull --ack explicit --deliver all --defaults
17#   Pull Mode: true   Ack Policy: Explicit
18
19# 5. 拉取消費（worker pool 多個實例共用同一 durable consumer = queue group 語意）
20nats consumer next ORDERS workers --count 3
21#   order-1  order-2  order-3

實機驗證於 nats:latest（最後檢查日 2026-06-16）：file storage 的 stream 把訊息落盤（Messages: 3）、durable pull consumer 用 explicit ack 消費。多個 worker 連到同一個 durable pull consumer 形成 worker pool（訊息分給其中一個），這正是 Clarifai 的 queue group 模式。

判讀：

• worker pool 用同一個 durable pull consumer（共享進度、訊息分流），不是每個 worker 一個 consumer
• --ack explicit 是 at-least-once 的前提；處理成功才 ack
• pull 模式比 push 對 worker pool 更可控（worker 按自己能力拉、不會被 push 淹）

Production 故障演練

Case 1：用 core NATS 跑該持久的任務、rolling deploy 掉訊息

徵兆：平時正常，但每次部署（pod 輪流重啟）就有一批任務消失、沒有錯誤。

根因：用 core NATS（fire-and-forget）跑需要可靠處理的任務。發布瞬間目標訂閱者正在重啟，core NATS 找不到訂閱者就丟棄——這是 core 的設計，不是故障。正是 Clarifai 的原始問題。

修法：

1. 需要不丟的任務用 JetStream（持久 stream + durable consumer + explicit ack）
2. 訊息落盤後 consumer 重啟從上次位置續讀，rolling deploy 不丟
3. 釐清邊界：可丟的即時資料（metrics / presence）留 core NATS、不可丟的跨 JetStream
4. 不要用 core NATS 當任務隊列——它沒有持久化與重送

Case 2：ephemeral consumer 斷線、消費進度全丟

徵兆：consumer 重連後從頭重讀整個 stream、或漏掉斷線期間的訊息，進度不連續。

根因：用了 ephemeral consumer——它的進度不持久，client 斷線後 consumer 本身消失。重連是建一個全新 consumer，從 deliver policy 的起點開始（all 從頭、new 只看新的），不接續之前的進度。

修法：

1. 需要跨重啟接續的用 durable consumer（具名、進度持久）
2. ephemeral 只適合臨時、一次性的讀取（debug、一次性掃描）
3. worker pool 一定用 durable（多 worker 共享持久進度）
4. 確認 deliver policy（all / new / last）符合預期的起讀位置

Case 3：ack_wait 太短、處理還沒完就重送風暴

徵兆：長任務還在處理中就被重送給另一個 worker，同一任務被多個 worker 重複執行，負載放大。

根因：ack_wait（等 ack 的逾時）設得比任務處理時間短。JetStream 以為訊息處理失敗（沒在 ack_wait 內 ack），重送給別人——但其實第一個 worker 還在跑。ML 長尾任務（幾秒到幾分鐘）特別容易踩。

修法（本文層級的判讀）：ack_wait 必須涵蓋任務的 p99 處理時間，否則長任務會在處理中被重送。設值方法（量測 p99、長任務用 in-progress ack 延長 deadline、消費端冪等兜底）與實機重現（AckWait 設 1s 觀察 tries 1→2、Redelivered 計數）在 JetStream 設計與 supercluster/leaf node 的故障演練有完整步驟，採用 JetStream 後依該篇落地。

Case 4：retention 選 workqueue 但想多 consumer fanout

徵兆：想讓多個獨立服務各自消費同一 stream，但發現訊息被一個消費掉就消失、其他服務讀不到。

根因：stream retention 設成 workqueue——每則訊息只被消費一次就從 stream 刪除（隊列語意）。它不適合 fanout（多個 consumer 各自要完整一份）。fanout 要 limits 或 interest retention。

修法：

1. fanout（多服務各讀一份）用 limits retention（訊息保留、多 consumer 各自 offset）
2. 單一 worker pool 競爭消費用 workqueue（消費即刪、省空間）
3. 釐清需求：競爭消費（worker pool）vs 廣播消費（fanout）對應不同 retention
4. Clarifai 用「3 個獨立 NATS 實例做 fanout 隔離」是另一種 fanout 做法，按隔離需求選

Case 5：memory storage 的 stream 重啟全失

徵兆：broker 重啟後 stream 裡的訊息全沒了，consumer 從空的開始。

根因：stream storage 設成 memory——快但不持久，broker 重啟即失。誤把它當持久 stream 用。

修法：

1. 需要持久的 stream 用 file storage（落盤、重啟不丟，實機驗證過）
2. memory 只適合「快取式、可重建」的 stream（如即時聚合的中間狀態）
3. 要更高可靠性加 replicas（JetStream 用 Raft 跨節點複製 stream）
4. 容量規劃時 file storage 的磁碟與 memory 的 RAM 是不同維度

Capacity / cost 邊界

JetStream 的容量判讀：

撞牆後的路由判斷：

• 可丟的即時資料：不需要 JetStream 的持久化開銷，用 core NATS（更快更輕）。
• 超大吞吐 + 長期保留 + 複雜 replay：JetStream 適合中等規模可靠 messaging；超大規模 event streaming + 長期保留走 Kafka（log-based、生態成熟）。
• 複雜 routing / 任務隊列語意：JetStream 的 subject 是樹狀，複雜 routing + DLQ 拓樸用 RabbitMQ 更直接。
• 不想自管：NATS 的 managed 選項（Synadia Cloud）或其他 managed broker。

整合 / 下一步

JetStream 的邊界判斷是 NATS 使用的核心，它跟其他議題交織：

• 跟 3.4 consumer design：push/pull、durable/ephemeral、ack policy 是 consumer 設計的具體選項。
• 跟 3.2 durable queue：JetStream 的 file storage stream 是 NATS 的 durable queue 實現。
• 跟 6.12 idempotency / replay：at-least-once + redelivery 要求消費冪等，否則重送造成重複副作用。
• 跟 RabbitMQ DLQ deep article：max_deliver 達上限後的處理對應 RabbitMQ 的 DLQ，兩者都是「重試上限後往哪去」的問題。

相關連結

• 上游 vendor 頁：NATS
• 對照 vendor：RabbitMQ DLQ 與分層 retry、Kafka
• 對應案例：3.C38 Clarifai NATS ML 非同步任務
• 上游概念：3.4 consumer design、3.2 durable queue