本文是 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

本文是跨 vendor migration playbook、cross-link 到 Kafka 跟 NATS。跟前四篇 migration（schema 差 / drop-in / operational redesign / multi-tool 拆分）對照、本篇是 paradigm shift — 兩端不是「同類產品的不同實作」、是 不同抽象層的 messaging system。

「Kafka → NATS migration」字面上不成立

前面四篇 migration 都隱含一個前提：source 跟 target 是 同類產品、只是不同實作或 deployment 模型。「Kafka → NATS」字面上看起來也是 messaging migration、但實際上：

Kafka 跟 NATS Core 是 不同類產品 — 一個是 durable event log、一個是 transient pub/sub。「migration」需要先決定 target 是 NATS Core 還是 JetStream、然後判斷 application 模式能否重設計 對應。

什麼情境真的能換、什麼不能

判讀：

• Microservice async messaging + 低延遲需求 → NATS Core 更合適、是 真正的 migration
• Event sourcing + replay → JetStream 部分對等、但 partition / offset 觀念變了
• Log collection / event streaming → 不該遷、保留 Kafka

為什麼會考慮這個 paradigm shift

實務上觸發評估 NATS 通常三條 driver：

1. Cost + operational complexity：Kafka cluster + ZooKeeper（或 KRaft）+ Schema Registry + Connect 是重資產、3-5 broker + ops 1+ FTE；NATS 單 binary、無依賴、輕量
2. Latency 要求 < 1ms：Kafka 對單 message latency 不是 SLA、NATS Core 是
3. Multi-tenant / multi-region 簡化：NATS 內建 account + leaf node 拓樸、跨 region 是 first-class

但這三條 driver 都 只在特定 application 模式有效。不是普世 better、是 某類 workload 適合。

Migration 結構：application 重設計 + 部分 stream cutover

跟前面四篇 migration 結構都不同、Kafka ↔ NATS 是 混合：

1. Phase 0：scope 判讀 — 列 application、區分「適合 NATS」vs「保留 Kafka」
2. Phase 1：application code 重設計 — 不是 SDK 換、是 messaging pattern 改（event sourcing → message bus / consumer group → durable consumer）
3. Phase 2：部分 stream parallel run — 新 application 走 NATS、舊 application 持續 Kafka
4. Phase 3：cutover 適合的 stream
5. Phase 4：長期混合架構 — Kafka 跟 NATS 共存、不消滅一邊

整體不是 一次 migration、是 漸進拆分。多數 production 環境 永遠 是混合架構。

Application 重設計範例：consumer group → durable consumer

 1// Kafka 端 consumer group pattern
 2consumer := kafka.NewConsumer(&kafka.ConfigMap{
 3    "bootstrap.servers": "kafka:9092",
 4    "group.id":          "myapp-orders",
 5    "auto.offset.reset": "earliest",
 6})
 7consumer.SubscribeTopics([]string{"orders"}, nil)
 8
 9for {
10    msg, err := consumer.ReadMessage(-1)
11    // process msg.Value
12    consumer.CommitMessage(msg)
13}

 1// NATS JetStream durable consumer
 2js, _ := nc.JetStream()
 3sub, _ := js.PullSubscribe("orders.>", "myapp-orders",
 4    nats.AckExplicit(),
 5    nats.MaxAckPending(100),
 6)
 7
 8for {
 9    msgs, _ := sub.Fetch(10, nats.MaxWait(5*time.Second))
10    for _, msg := range msgs {
11        // process msg.Data
12        msg.Ack()
13    }
14}

差異：

• Kafka auto.offset.reset → NATS DeliverPolicy（多種選項）
• Kafka commit message → NATS explicit Ack（per message）
• Kafka partition → NATS subject hierarchy（orders.> 通配）
• Kafka rebalance → NATS 不需要、durable consumer 跨 instance 共享

Application 邏輯改動 30-60%、不是 SDK 換。

Production 故障演練

Case 1：Consumer offset 觀念差，replay 不對等

徵兆：application 設計「跑歷史 7 天事件 catch-up」、Kafka 設 auto.offset.reset=earliest + seek_to(timestamp) 跑；換 NATS JetStream 後找不到 seek_to 等價 API、catch-up 失敗。

根因：Kafka offset 是 broker-side 維護 + consumer-side commit；NATS JetStream 用 sequence number + DeliverPolicy.ByStartTime、但 time-based seek 精度低、且 application code 必須改。

修法：

1. 預先設計：NATS JetStream 用 DeliverPolicy.ByStartSequence + 自管 sequence-time mapping
2. 保留 Kafka 給 replay-heavy use case：不是所有 application 都遷
3. 混合架構：歷史 replay 走 Kafka、新事件流走 NATS、application 處理雙來源

Case 2：Retention model 差異、磁碟使用炸

徵兆：NATS JetStream stream 設 retention=interest（subscriber 收到就刪）、cutover 後 disk 持續長大；預期跟 Kafka log retention 7 天類似、實際資料留 30+ 天沒清。

根因：NATS JetStream retention 有 3 種：limits / interest / workqueue。interest 是 至少一個 subscriber 還沒 ack 就保留；application 端 silent consumer（已下線但沒 unsubscribe）讓 message 永留。

修法：

1. 預設 retention=limits：用 MaxAge / MaxBytes 跟 Kafka log retention 對應、明確控制
2. interest retention 慎用：只在 確認所有 subscriber lifecycle 受控 場景
3. Subscriber cleanup：application graceful shutdown 必須主動 unsubscribe、不留 zombie consumer

Case 3：Exactly-once 假設不對等

徵兆：cutover 後發現某 application（payment processor）開始出現 duplicate transaction；Kafka 端用 transactional producer + idempotent consumer 跑了 2 年沒問題。

根因：Kafka exactly-once 是 producer transaction + consumer offset commit atomic；NATS JetStream exactly-once 概念不一樣 — 是 publish ack + consumer ack 跨層 atomic、application 端要主動處理 idempotency。

修法：

1. 重新審視 application 端 idempotency：用 message ID + dedup store（Redis SETEX）顯式 dedup
2. NATS JetStream 對 exactly-once 不該假設「自動」：application 端責任、不是 broker 端
3. Payment / financial 場景慎遷：保留 Kafka transactional pattern 較穩

Case 4：Schema registry 缺位、ad-hoc schema 漂移

徵兆：NATS 部署 3 個月後、producer / consumer 間 schema 對不上、application bug；Kafka 端有 Confluent Schema Registry 強 enforce、NATS 沒對等服務。

根因：NATS 哲學是 minimalist、不內建 schema registry；application 自己決定 payload format。Kafka 生態的 Avro / Protobuf + Registry 模式不直接搬。

修法：

1. 外部 schema management：用 BSR（Buf Schema Registry）或自家 Git-based registry、producer / consumer build-time 驗證
2. NATS Object Store：JetStream 提供 K/V + Object Store、可存 schema 文件
3. 接受紀律性 trade-off：NATS 簡潔代價是 application 端紀律、不能靠 broker 強 enforce

Case 5：Fan-out 模式跟 Kafka 不一致

徵兆：同一 event 要送 5 個 downstream service、Kafka 端用 consumer group + 5 個 group 跑；NATS 端設計 5 個 durable consumer、結果某些 message 漏 fan-out。

根因：Kafka consumer group 對 同 group 內 partition 分配、不同 group 各自完整消費；NATS JetStream Durable consumer 預設行為跟 group 不同 — 單 durable consumer 是 shared subscription、要 fan-out 需多個獨立 durable。

修法：

1. 明確設計 fan-out：N 個 downstream 對應 N 個 獨立 durable consumer、不共用
2. 用 AckPolicy.None + push subscriber：不需要 ack 的 fan-out 場景、用 ephemeral push subscriber
3. 檢查 application stream config：fan-out 失敗多半是 consumer config 錯、不是 NATS bug

Capacity / cost 對照

判讀：簡單 messaging workload NATS 顯著便宜；complex event streaming（Schema Registry / Streams / Connect 重度用）Kafka 不替代。

整合 / 下一步

混合架構是 long-term default

多數 production 環境最終是 Kafka + NATS 共存：

1[event sourcing / log collection]        [microservice async messaging]
2         Kafka                                       NATS
3         │                                            │
4         └──────── Bridge (Connect / Custom) ────────┘

NATS 跑微服務間 messaging、Kafka 跑 event log / analytics pipeline；中間用 Kafka Connect NATS connector 或自寫 bridge 同步必要 stream。

跟 Logical Replication + Debezium 對位

CDC pipeline 設計：

• DB → Debezium → Kafka topic（event sourcing 主軸）
• Kafka → NATS bridge → microservice fan-out
• 不直接 DB → Debezium → NATS（Debezium 不原生支援 NATS sink）

跟前 4 篇 migration 的結構對照

結論：migration 結構由 最大差異維度 決定、不是 universal phased playbook。

相關連結

• Source / target vendor：Kafka / NATS
• 平行 vendor：RabbitMQ / Redis Streams
• 平行 migration playbook：Splunk → Elastic Security / Redis → DragonflyDB / PostgreSQL → Aurora / Datadog → Grafana Stack
• Methodology：Vendor 深度技術文章的寫作方法論

本文是 NATS overview 的 implementation-layer deep article。Overview 回答「NATS 該不該選、Core NATS vs JetStream 怎麼分」；要不要從 core NATS 跨進 JetStream 的決策入口見 core 到 JetStream 的邊界；本文回答「JetStream stream / consumer 的每個旋鈕怎麼設、設錯踩什麼坑、跨區拓樸怎麼鋪、多租戶怎麼隔離」。寫作結構依 Vendor 深度技術文章的寫作方法論 的 6 段框架。

JetStream 把 fire-and-forget 升級成 durable log

JetStream 是 NATS 內建的持久化層、責任是把 Core NATS 的 fire-and-forget subject 轉成 append-only 的 durable stream、並讓 consumer 能 ack、重投、replay。Core NATS 的訊息一旦沒有 active subscriber 就消失；JetStream 把符合特定 subject 的訊息攔截下來寫進 stream、即使沒有任何 consumer 在線也會留存到 retention 上限。

兩個概念要先分清楚、後面所有配置都掛在這個分界上。Stream 是 儲存 責任：定義「哪些 subject 的訊息要存、存多久、存多少、存哪裡」。Consumer 是 投遞 責任：定義「從 stream 的哪個位置開始讀、怎麼 ack、ack 不回來要不要重投、重投幾次」。同一個 stream 可以掛多個 consumer、各自有獨立的讀取游標跟重投狀態、互不影響。這個 stream / consumer 二分是 JetStream 跟 Kafka（topic / consumer group）對應、但跟 RabbitMQ（queue 本身就綁消費）不同的核心模型差異。

本文用一個訂單事件流當主線：subject 設計成 orders.created.<region>、stream 名 orders、subject filter orders.>。實機環境用單機 NATS server 加 -js、CLI 用 natsio/nats-box 容器；跨節點的 Cluster / quorum 段用 3 節點 docker compose 驗證、Supercluster / Leaf node 因拓樸複雜以 case 敘述加官方文件 caveat 標註。

Stream 設計：storage、retention、discard、容量上限

Stream 的設計責任是回答四個彼此獨立的問題：訊息存在哪種介質、用什麼規則決定保留、超過上限時丟哪一端、上限本身設多大。這四個旋鈕組合錯了不會在建立時報錯、而是在 production 流量打進來才以丟訊息或塞爆 disk 的形式爆出來。

Storage：file vs memory

Storage type 決定訊息寫在 disk 還是 RAM。file storage 把 stream 寫進 disk、server 重啟後資料還在、是需要 durability 的事件流預設選擇；memory storage 把 stream 放 RAM、吞吐跟延遲更好但 server 重啟即全失、適合短期 fan-out 或可重建的快取型資料。

實機建一個 file storage、limits retention、discard old 的 stream：

 1nats --server nats://localhost:4232 stream add orders \
 2  --subjects 'orders.>' \
 3  --storage file \
 4  --retention limits \
 5  --discard old \
 6  --max-msgs 1000 \
 7  --max-bytes 10MB \
 8  --max-age 1h \
 9  --replicas 1 \
10  --defaults

nats stream info orders 回報的配置確認旋鈕都生效：

1                     Subjects: orders.>
2                      Storage: File
3                    Retention: Limits
4               Discard Policy: Old
5             Maximum Messages: 1,000
6                Maximum Bytes: 10 MiB
7                  Maximum Age: 1h0m0s

選 memory 的判讀訊號：訊息可從上游重建（例如 metrics 採樣、可重抓的 snapshot）、或 consumer 一定在線且消費速度跟得上、且單 stream 資料量遠小於可用 RAM。一旦這三條有一條不成立、預設回到 file storage。

Retention：limits vs interest vs workqueue

Retention policy 決定「訊息什麼時候從 stream 移除」、是 stream 三種使用形態的分水嶺。

limits retention 是時間 / 容量驅動：訊息留到撞上 MaxMsgs / MaxBytes / MaxAge 任一上限才移除、跟有沒有人消費無關。這是「事件 log」形態、適合需要 replay、多個獨立 consumer 各讀各的場景。訂單事件流用 limits、因為審計、對帳、即時處理可能是三個獨立 consumer、訊息不能因為某個 consumer ack 了就消失。

interest retention 是訂閱驅動：當 stream 上 所有 已註冊的 consumer 都 ack 了某筆訊息、該訊息立刻移除。它介於 limits 跟 workqueue 之間、適合「只要所有關心的 consumer 都收到就不必再留」的扇出場景。

workqueue retention 是任務佇列形態：每筆訊息只會被 一個 consumer 成功 ack、ack 後立刻刪除。它把 stream 當成工作分派佇列、語意接近 RabbitMQ 的 work queue。實機驗證 workqueue 的 retention 在 info 反映：

1nats --server nats://localhost:4232 stream add wq \
2  --subjects 'wq.>' --storage memory --retention work \
3  --max-msgs 100 --replicas 1 --defaults
4# nats stream info wq → Retention: WorkQueue

判讀路由：需要多 consumer 各自 replay → limits；需要扇出且所有訂閱者收齊就清 → interest；需要競爭式單次消費的任務派工 → workqueue。選 workqueue 卻又掛兩個 filter 重疊的 consumer 會在建 consumer 時被拒、因為 workqueue 不允許同一筆訊息被兩個 consumer 認領。

Discard：old vs new

Discard policy 決定 stream 撞上 MaxMsgs / MaxBytes 上限後 丟哪一端。這個旋鈕的選擇直接對應業務對「舊資料」跟「新資料」誰更重要的判斷、選錯會靜默丟訊息。

discard old 在達上限時丟掉最舊的訊息、騰空間給新訊息。實機驗證：max-msgs 設 3、連發 5 筆、stream 留下最後 3 筆：

1discard old, max-msgs 3, published 5:
2                     Messages: 3
3               First Sequence: 3
4                Last Sequence: 5

最舊的 seq 1、2 被丟、保留 seq 3-5。這對應「新資料比舊資料重要」的場景：即時儀表板、最新狀態快照、寧可丟歷史也要保住最新。

discard new 在達上限時拒絕新訊息、保住已存的舊訊息。同樣 max-msgs 3、連發 5 筆：

1discard new, max-msgs 3, published 5:
2                     Messages: 3
3               First Sequence: 1
4                Last Sequence: 3

保留 seq 1-3、後到的 seq 4、5 進不來。這對應「舊資料是已承諾的工作、不能丟」的場景：任務佇列在塞滿時應拒收新任務（並對上游施加 backpressure）、而不是把排隊中的任務擠掉。

discard new 有個容易踩的投遞行為差異、見故障演練 Case 2。

容量上限：MaxMsgs / MaxBytes / MaxAge

三個上限是 OR 關係：任一撞到就觸發 discard / 移除。MaxMsgs 限筆數、MaxBytes 限總位元組、MaxAge 限訊息存活時間。實務上三者搭配使用：MaxAge 防止無限累積（例如事件流只保留 7 天）、MaxBytes 是 disk 的硬護欄（防單 stream 撐爆 volume）、MaxMsgs 在訊息大小均勻時當作粗略筆數控制。

容量規劃的判讀順序是先定 MaxAge（業務需要 replay 多久）、再用「平均訊息大小 × 預估 throughput × MaxAge」反推 MaxBytes 是否在 disk 預算內、超出就縮短 MaxAge 或拆 stream。把 MaxBytes 設成 unlimited 而只靠 MaxMsgs 是常見的容量事故來源：訊息大小一旦變大（例如 payload 夾帶了 base64 附件）、筆數沒到上限但 disk 已滿。

Consumer 設計：pull/push、ack、AckWait、MaxDeliver、replay

Consumer 的設計責任是控制「訊息怎麼從 stream 送到處理端、處理端怎麼確認、確認不回來怎麼辦」。它的每個旋鈕都圍繞同一個核心張力：在 at-least-once 投遞下、如何在「不漏處理」跟「不過度重投」之間取得平衡。對應的概念基礎見 Delivery Semantics 與 Processing Semantics 知識卡。

Pull vs push

Pull consumer 由處理端主動拉：consumer 發 pull request 帶 batch size、server 才送對應數量的訊息。流量控制天然落在消費端、消費端有多少處理能力就拉多少、是現代 JetStream 應用的預設模式。Push consumer 由 server 主動推到一個 delivery subject、處理端訂閱那個 subject、適合需要 server 端 flow control 或既有 Core NATS 訂閱模型遷移的場景。

實機建一個 pull consumer、explicit ack、AckWait 30s、MaxDeliver 5、replay instant：

1nats --server nats://localhost:4232 consumer add orders worker \
2  --pull \
3  --deliver all \
4  --ack explicit \
5  --wait 30s \
6  --max-deliver 5 \
7  --replay instant \
8  --filter 'orders.>' \
9  --defaults

nats consumer info orders worker 確認配置：

1                    Name: worker
2               Pull Mode: true
3          Deliver Policy: All
4              Ack Policy: Explicit
5                Ack Wait: 30.00s
6           Replay Policy: Instant
7      Maximum Deliveries: 5

push consumer 改用 --target <subject> 取代 --pull、info 會回報 Delivery Subject: 而非 Pull Mode。

AckPolicy：explicit 是預設選擇

Ack policy 決定 consumer 怎麼確認訊息已處理。explicit 要求對每一筆訊息單獨 ack、是 at-least-once 處理的基礎、production 預設選擇。all 用累積 ack：ack 第 N 筆等於 ack 了第 N 筆以前全部、吞吐高但一筆處理失敗會讓整段重投。none 完全不 ack、投遞即視為完成、語意退化成接近 fire-and-forget、只適合可容忍丟失的場景。

explicit ack 之所以是預設、是因為它讓每筆訊息的處理結果獨立可追蹤：哪筆 ack 了、哪筆還 outstanding、哪筆重投超限、都能在 consumer info 看到。實機發 3 筆訊息後、consumer info 的 Unprocessed Messages 反映 stream 中尚未投遞的 backlog：

1nats --server nats://localhost:4232 pub orders.created.us-1 "order-1"
2# 發 3 筆後：
3# nats consumer info orders worker →
4#     Unprocessed Messages: 3

拉出訊息但不 ack、consumer info 的 Outstanding Acks 反映已投遞但未確認的數量：

1        Outstanding Acks: 3 out of maximum 1,000

這兩個數字是診斷 consumer 健康的第一手訊號：Unprocessed 高代表 consumer 拉得太慢或停了（stream backlog）；Outstanding Acks 持續高代表訊息拉出去了但處理端沒 ack（處理慢或卡住）。這個區分對應 overview 排錯段的「pending 是 ack-pending 還是 stream backlog」判讀。

AckWait + MaxDeliver：重投的兩個邊界

AckWait 是 server 等待 ack 的時間窗：訊息投遞後、若 AckWait 內沒收到 ack、server 視為投遞失敗、重新投遞。MaxDeliver 是同一筆訊息的投遞次數上限：達到後不再重投、訊息進入 terminal 狀態（可導向 advisory / DLQ 機制）。

這兩個旋鈕共同定義重投行為。AckWait 要設成 略大於 consumer 處理一筆訊息的 p99 時間：太短會在 consumer 還在正常處理時就誤判失敗重投、造成重複處理（見故障演練 Case 1）；太長會讓真正卡死的訊息遲遲不重投、拖慢 recovery。MaxDeliver 是 poison message 的護欄：一筆訊息若處理永遠失敗（例如 payload 格式壞）、沒有 MaxDeliver 它會無限重投佔住 consumer。對應 Redelivery Loop 知識卡描述的失控重投。

Replay：instant vs original

Replay policy 只在 consumer 從歷史位置讀（例如 --deliver all 重讀整個 stream）時生效、決定投遞節奏。instant 以 server 最快速度投遞、是處理 backlog 或重建狀態的預設。original 按訊息 原始寫入的時間間隔 重放：若原始訊息間隔 1 秒寫入、replay 也間隔 1 秒投遞、用於需要重現時序的測試或模擬。實機兩種都可建：

1nats consumer add orders replayorig ... --replay original  # Replay Policy: Original

Cluster / Supercluster / Leaf node：三層拓樸

NATS 的拓樸分三層、各解一個不同尺度的問題：Cluster 解單區內的高可用、Supercluster 解跨區的延展、Leaf node 解邊緣到中心的連接。三者可組合、但職責不重疊。

Cluster：單區 Raft 高可用

Cluster 是同一 region 內多個 NATS server 用 full mesh route 互連、JetStream 的 stream 透過 Raft 在多個 replica 間複製。Replica 數（R1 / R3 / R5）決定容錯：R3 容忍 1 節點失效、R5 容忍 2 節點。Raft 要求多數派（quorum）才能寫入、所以 R3 需要至少 2 節點健康。

實機用 3 節點 docker compose 起 cluster、建 R3 stream、stream info 顯示 Raft group 與 replica 狀態：

1nats --server nats://n1:4222 stream add rep3 \
2  --subjects 'rep3.>' --storage file --retention limits \
3  --discard old --max-msgs 1000 --replicas 3 --defaults

1                     Replicas: 3
2Cluster Information:
3                Cluster Group: S-R3F-unEqlH8C
4                       Leader: n2 (222ms)
5                      Replica: n1, current, seen 217ms ago
6                      Replica: n3, current, seen 219ms ago

Leader 是 Raft 選出的寫入協調者、其餘 replica 跟隨。current 代表該 replica 與 leader 同步；落後會顯示 outdated 加落後的 operation 數。失去 quorum 的行為見故障演練 Case 4。

Supercluster：跨區 gateway 延展

Supercluster 用 gateway 連接多個 Cluster、形成跨 region / 跨雲的單一 NATS 邏輯網路。Gateway 之間是按需轉發、不是 full mesh：訊息只在有訂閱者的 region 之間流動、避免跨區頻寬被無謂的全量複製吃掉。Supercluster 讓 publisher 在任一 region 發訊息、訂閱者在另一 region 收到、同時讓每個 Cluster 維持自己的 JetStream Raft 群組與本地高可用。

以下 Supercluster 行為依 NATS 官方文件 描述、未在本文實機環境驗證（gateway 多區拓樸需要跨 region 部署）。

3.C35 Form3 是 Leaf node 跨雲橋接的代表案例（Supercluster 為相應的一般拓樸選項、case 本身明確點到的是 Leaf node）：服務 Tier-1 銀行、要求 500ms 端到端 SLA、AWS SNS/SQS 約 300ms 延遲吃掉預算。Form3 用 JetStream 跨雲橋接、達到約 6× 延遲改善、並做到「AWS 整個 region 掛掉時不喪失處理能力」。這個案例揭露的判讀是：金融支付的硬 latency 預算逼出特定拓樸選型、不是把 Kafka / SQS 通用化套上去。

Leaf node：邊緣連中心

Leaf node 是輕量 NATS server、跑在邊緣（工廠、店面、IoT gateway）、透過單一 leaf connection 連回中心 hub。它在邊緣本地提供完整的 NATS / JetStream 能力（本地 publish / subscribe / 本地持久化）、同時把需要的 subject 透過 leaf connection 雙向橋接到 hub。Leaf node 的價值在於：邊緣到中心的網路斷線時、邊緣端的本地 JetStream 持續收訊息、連線恢復後再同步、不丟資料。

以下 Leaf node 行為依 NATS 官方文件 與下列 case 描述、未在本文實機環境驗證（leaf 拓樸需要 hub + edge 雙端部署）。

3.C37 MachineMetrics 是 Leaf node 邊緣到雲端的完整案例：跨數百客戶廠區、數千機台、單機最高 1000Hz 採樣、工廠網路斷斷續續、Kinesis 等 cloud-only 工具無法跑在資源受限 edge。MachineMetrics 用 Leaf node 做 hub-and-spoke、edge 端用 JetStream 做本地持久化抵抗斷線。這個案例揭露的判讀是：broker 的功能集合（messaging + 本地持久化 + KV + Object Store + auth）決定它能不能取代邊緣的多套工具。

3.C41 i-flow 是多工廠 leaf node 拓樸的另一證據：每日 4 億筆 data operation、200+ OT/IT connector、用 leaf node hub-and-spoke 把多工廠接到 central、而不是每工廠自管一套 cluster。判讀：多工廠場景的運維成本由「每個邊緣點是不是要獨立維運一套 cluster」決定、leaf node 把邊緣端壓到單一 server。

Subject-based ACL 與多租戶

NATS 多租戶的主機制是 account：account 是完全隔離的 subject 命名空間、不同 account 之間預設互不可見、即使 subject 名稱相同也不會互通。Account 之內再用 subject-level permission 控制每個 user 能 publish / subscribe 哪些 subject。這兩層組合起來：account 給租戶硬隔離、subject permission 給租戶內的角色細分權限。

跨 account 的受控互通用 import / export：一個 account 把特定 subject export 出來、另一個 account 顯式 import、才會打通那條 subject。預設不通、互通是顯式授權的結果、這讓多租戶的資料流動可審計。對應 MachineMetrics 案例用 decentralized auth 隔離不同客戶廠區的設計：每個客戶是一個 account、廠區設備在 account 內用 subject permission 限定只能發自己廠區的 subject。

多租戶設計的判讀訊號：租戶之間要完全隔離、用 account；同租戶內的不同服務 / 角色要限權、用 subject permission；少數需要跨租戶共享的 subject（例如全域控制信號）、用 import / export 顯式打通、不要為了方便把不同租戶塞進同 account。

Production 故障演練

deep article 的差異化價值在故障演練。以下四個都是 JetStream stream / consumer / 拓樸層的典型事故、前兩個有本文實機驗證、後兩個結合實機（quorum）與 case 敘述。

Case 1：AckWait 太短造成重複處理

徵兆：consumer 正常運行、處理邏輯沒報錯、但下游出現大量重複副作用（重複扣款、重複寄信、重複寫入）。consumer info 的 Redelivered Messages 持續上升、即使處理端沒有任何 exception。

根因：AckWait 設得比 consumer 處理一筆訊息的實際耗時短。訊息投遞後 consumer 還在處理、AckWait 就到期、server 判定投遞失敗、把同一筆訊息重投給（可能是另一個）consumer 實例、於是同一筆訊息被處理兩次。實機重現：建一個 AckWait 1s 的 consumer、拉出訊息不 ack、過 1s 後再拉、tries 從 1 變 2：

1第一次拉：subj: orders.created.us-1 / tries: 1 / str seq: 1
2過 1s 後：subj: orders.created.us-1 / tries: 2 / str seq: 1
3consumer info → Redelivered Messages: 3

修法：

1. 量測再設值：AckWait 設成 consumer 處理 p99 時間的 2-3 倍、而不是拍腦袋設 30s。處理一筆要 5s 的 worker 配 AckWait 30s、處理一筆要 45s 的 worker 配 AckWait 30s 就會持續誤判重投。
2. 長任務用 in-progress ack：處理時間本就偏長且方差大的任務、處理端在處理中定期送 AckProgress（working ack）延長 AckWait、而不是把 AckWait 設成一個無法涵蓋最壞情況的固定大值。
3. 處理端做冪等：at-least-once 投遞下重複是常態而非異常、副作用以業務 key 去重（對應 Processing Semantics 的冪等要求）。AckWait 只能降低重複頻率、不能消除重複。

Case 2：discard policy 選錯靜默丟訊息

徵兆：上游 publisher 一切正常、沒收到任何 error、但下游 consumer 發現訊息有缺口（seq 跳號）、或最舊的歷史訊息神祕消失。對帳時帳目對不上、但日誌裡找不到任何失敗紀錄。

根因：兩種情況。其一、stream 用 discard old、流量超過 MaxMsgs / MaxBytes、最舊的訊息被靜默丟棄騰空間——這在「事件 log 需要完整 replay」的場景是資料遺失。其二、stream 用 discard new、滿了之後新訊息被拒、但 publisher 用的是 Core NATS publish（不等 stream ack）、所以 publisher 端看到「發送成功」、訊息其實沒進 stream。實機重現後者的危險：對一個 discard new 已滿的 stream 用 Core pub 與 JetStream-aware pub、結果完全不同：

1Core pub（不等 ack）：    Published 8 bytes to "dnew.x"        ← 看似成功、實際丟失
2JetStream pub（等 ack）： nats: error: maximum messages exceeded (10077)  ← 正確報錯

修法：

1. publisher 一律用 JetStream-aware publish：等 stream 的 PubAck 回來才算發送成功、才能在 stream 滿、quorum 失效、subject 不匹配時收到明確 error。用 Core pub 發進 JetStream subject 等於放棄所有投遞保證。
2. discard policy 對齊業務語意：事件 log（需要完整歷史）配 limits + 充足 MaxAge、絕不靠 discard old 當容量控制；任務佇列配 discard new + 上游 backpressure、滿了就讓 producer 慢下來而不是擠掉排隊任務。
3. 監控 discard 計數：stream 的 discard 不是錯誤狀態、不會觸發 alert。要主動監控訊息 seq 連續性與 stream 的訊息移除速率、把「非預期的 discard」變成可觀測訊號。

Case 3：Leaf node 斷線重連

徵兆：邊緣端（工廠 / 店面）到中心 hub 的網路抖動、leaf connection 反覆斷開重連、hub 端看到某些 subject 的訊息延遲尖刺、邊緣端 reconnect 計數持續累加。網路恢復後、邊緣累積的訊息一次湧入 hub、造成 hub 端短暫的處理尖峰。

根因：邊緣到中心是廣域網、品質不如資料中心內網。Leaf connection 斷線期間、邊緣端的本地 JetStream 持續收訊息並本地持久化（這正是 leaf node 的設計目的）；連線恢復後、累積的 backlog 一次同步到 hub、形成尖峰。若邊緣端沒有本地 JetStream、斷線期間的訊息直接丟失。

以下根因與修法依 NATS 官方 leaf node 文件與 MachineMetrics / i-flow case 描述、未在本文實機環境驗證。

修法：

1. 邊緣端必開本地 JetStream：把斷線容忍從「依賴網路不斷」改成「斷線期間本地持久化、恢復後同步」。這是 MachineMetrics 用 edge JetStream 取代 SQLite 的核心理由——工廠網路斷斷續續是常態、不是異常。
2. hub 端對同步尖峰做 flow control：恢復連線後的 backlog 同步用 consumer 端的 pull batch 限速、避免邊緣 backlog 一次打爆 hub 的處理能力。
3. 監控 reconnect 與 latency：leaf 連線的 reconnect 次數與 subject mapping latency 是邊緣網路品質的直接訊號（對應 overview 排錯段「leaf node 連線不穩」）。reconnect 頻繁代表網路或 hub 容量要處理、不是調 leaf 參數能解。

Case 4：Stream replica 失去 quorum

徵兆：R3 stream 突然無法寫入、publisher 的 JetStream publish 卡住後回 no responders available；stream info 顯示 Leader: 欄位空白、多數 replica 標 OFFLINE。讀取可能還能從存活節點拿到舊資料、但寫入完全停擺。

根因：JetStream 的 stream 用 Raft 複製、寫入需要多數派確認。R3 stream 需要至少 2 節點健康才有 quorum；同時失去 2 節點就只剩 1 節點、達不到多數、Raft 無法選出 leader、stream 變成無法寫入。實機重現：3 節點 cluster 的 R3 stream、停掉 2 個節點、stream info 顯示無 leader、JetStream publish 報錯：

1停 2 節點後 stream info：
2                       Leader:
3                      Replica: n1, current, seen 3.35s ago
4                      Replica: n2, outdated, OFFLINE, not seen
5                      Replica: n3, outdated, OFFLINE, not seen
6
7此時 JetStream publish：
8                      nats: error: nats: no responders available for request

恢復 1 個節點（回到 2/3 多數）後、Raft 立即重選 leader、stream 恢復可寫：

1啟動 n2 後：
2                       Leader: n1 (506ms)
3                      Replica: n2, current, seen 499ms ago
4                      Replica: n3, outdated, OFFLINE, not seen, 4 operations behind

修法：

1. replica 數對齊容錯目標：要容忍 1 節點失效用 R3、容忍 2 節點用 R5；不要為了省資源把關鍵 stream 設 R1（單點、節點掛了 stream 直接不可用）。
2. replica 跨 failure domain 散開：R3 的 3 個 replica 要落在不同 availability zone / rack、避免單一 AZ 故障同時帶走 2 個 replica 直接失去 quorum。
3. 監控 replica 健康而非只看 leader：stream info 的每個 replica 的 current / outdated / OFFLINE 狀態是 quorum 餘裕的直接訊號。R3 已經有 1 個 replica OFFLINE 時 quorum 餘裕只剩 0、要當成 P1 處理、不能等到第 2 個也掛才反應（對應 overview 排錯段「JetStream raft 不一致」）。

容量與規模判讀

JetStream 的配置在不同規模下適用性不同、超出範圍要換拓樸而非調參數。

單 Cluster R3 是多數中等規模服務的起點：單區內高可用、JetStream Raft 處理節點故障、運維只有一套 cluster。撞到天花板的訊號是單區頻寬或單節點 disk / CPU 到上限、此時先評估加節點重分配或把熱 stream 拆出去、而不是急著上 supercluster。

Supercluster 在訂閱者地理分散、或要求單區整個掛掉仍能服務時才值得引入。它的成本是跨區 gateway 的運維複雜度與跨區頻寬、不該為了「以後可能要跨區」提前鋪。Form3 的判讀是硬 SLA（500ms、region 全掛仍可用）逼出來的、不是預設架構。

Leaf node hub-and-spoke 在邊緣點多、邊緣網路不穩、邊緣要本地持久化 / KV / 計算能力時適用。當邊緣點數量大到每點獨立運維成本不可接受、評估走 managed NATS（Synadia Cloud）把運維外包、而不是自建更大的 hub。

整合與下一步

本文聚焦 JetStream stream / consumer / 拓樸的 implementation；以下是往上下游的銜接。

回 vendor overview 與相鄰章節

• 上游 vendor 頁：NATS overview——Core NATS vs JetStream 的選型判讀、排錯快速判讀、何時改走其他 broker
• 跨 vendor consumer 設計：3.4 consumer 設計——本文的 pull/push、ack、重投放回語言無關的 consumer 設計框架
• 投遞與處理語意基礎：Delivery Semantics / Processing Semantics / Redelivery Loop 知識卡

對應 case

• 3.C35 Form3——Supercluster + Leaf node 跨雲低延遲支付、硬 SLA 驅動拓樸
• 3.C37 MachineMetrics——Leaf node + edge JetStream + KV + Object Store + 多租戶 auth 的完整邊緣案例
• 3.C41 i-flow——多工廠 leaf node hub-and-spoke、運維成本驅動拓樸選型

後續可深入的議題

• JetStream KV / Object Store：基於 stream 的 key-value 與 blob 儲存、何時用 NATS KV vs 真的 KV 服務（Redis / etcd）、見 overview 進階主題段
• Leaf node 多節點實機驗證：本文 Supercluster / Leaf node 段以 case + 官方文件敘述；補一篇 hub + edge 雙端 compose 的實機演練（含斷線注入、backlog 同步觀測）是自然延伸
• Subject mapping 與 transform：leaf node 跨層的 subject 重映射、跨 account import / export 的細部配置