本文是 Kafka overview「進階主題」的 implementation-layer deep article，承接 overview「Consumer lag 暴增」與「Rebalance storm」兩段判讀原則的展開。Overview 給判讀方向，本文給 protocol 機制、診斷指令與故障演練。

Rebalance 是 consumer group 重新分配 partition 所有權的協調過程

Rebalance 是 consumer group coordinator 把 topic 的 partition 重新分配給 group 內 consumer 的協調動作，承擔「在成員數變動時維持每個 partition 恰好被一個 consumer 消費」這個責任。觸發條件是 group membership 改變：consumer 加入、consumer 離開、consumer 被判定失效，或 topic partition 數增加。Rebalance 完成前，受影響的 partition 暫停消費，這段空窗就是 rebalance 對 lag 的直接代價。

Consumer group 是 Kafka 把「一份 event stream 分給多個 worker 平行處理」與「同一份 stream 給多個獨立應用各自 replay」兩種需求統一的抽象。同一個 group 內的 consumer 瓜分 partition、彼此不重複消費；不同 group 各自維護 offset、互不干擾。Rebalance 只在 group 內部發生，調整的是 group 內 partition 對 consumer 的 mapping。本文聚焦 group 內 rebalance 的機制與診斷，group 概念本身見 consumer group 知識卡。

實機觀察 partition 如何在兩個 consumer 間分配：同一 group 起兩個 consumer，coordinator 把 3 個 partition 拆給它們。

1GROUP    CONSUMER-ID    CLIENT-ID    #PARTITIONS  CURRENT-ASSIGNMENT
2live-cg  consumer-A-... consumer-A   2            orders:0,1
3live-cg  consumer-B-... consumer-B   1            orders:2
4
5GROUP    ASSIGNMENT-STRATEGY  STATE    #MEMBERS
6live-cg  range                Stable   2

consumer-A 拿到 partition 0、1，consumer-B 拿到 partition 2，STATE 是 Stable 代表 rebalance 已收斂。ASSIGNMENT-STRATEGY 顯示 range，是預設的 partition 分配演算法。

Eager 與 cooperative incremental 是兩種 rebalance protocol

Rebalance protocol 決定「rebalance 期間 consumer 要不要交出手上全部 partition」，這個選擇直接決定 rebalance 的 stop-the-world 範圍。Kafka 提供兩種：eager 與 cooperative incremental。

Eager rebalance 是早期預設行為：rebalance 觸發時，group 內所有 consumer 先放棄手上全部 partition（revoke all），等 coordinator 算完新分配後再各自重新 assign。代價是 rebalance 期間整個 group 完全停止消費，即使某個 consumer 的 partition 在新舊分配中根本沒變，它也得先放掉再拿回。Group 規模越大、partition 越多，這個全停窗口越痛。

Cooperative incremental rebalance 改成「只 revoke 真正要換手的 partition」。Consumer 先回報自己想保留的 partition，coordinator 算出哪些 partition 需要從 A 搬到 B，只有這些 partition 經歷一次 revoke + reassign，其餘 partition 持續消費不中斷。代價是一次完整 rebalance 可能需要兩輪（第一輪 revoke、第二輪 assign），但每輪只影響少數 partition，整體可用性遠高於 eager。Kafka 2.4 起的 CooperativeStickyAssignor 實作這套協議。

實機驗證 cooperative-sticky 可由 consumer 端 config 啟用，ASSIGNMENT-STRATEGY 欄位反映實際生效的策略：

1kafka-console-consumer.sh --topic orders --bootstrap-server localhost:9092 \
2  --group coop-cg \
3  --consumer-property partition.assignment.strategy=org.apache.kafka.clients.consumer.CooperativeStickyAssignor

1GROUP    ASSIGNMENT-STRATEGY  STATE    #MEMBERS
2coop-cg  cooperative-sticky   Stable   1

選 protocol 的判準是 group 規模與消費中斷的容忍度：

對 partition 數上百、consumer 數十的 group，eager 的全停窗口會讓每次 deploy 都產生明顯 lag spike。Walmart 每天 trillions of message、25K+ consumer 跑在 K8s，pod scaling 與 deploy 觸發的 rebalance 是最大痛點（3.C17）；這種規模下 eager 的全停代價無法接受，cooperative 把中斷限縮到換手 partition 是基本要求。但 Walmart 進一步發現，即使換成 cooperative，partition-consumer 1:1 模型本身在 K8s 規模仍撞到擴張極限，最終把 consumer 解耦成 stateless service。Protocol 選擇降低單次 rebalance 代價，架構解耦才解決 rebalance 頻率本身。

切換 protocol 不能直接全量改：eager 與 cooperative 的 consumer 不能在同一 group 共存。滾動升級時，consumer 需先支援兩種 protocol、再分批切換 config，否則混用會導致 rebalance 失敗或 assignment 不一致。

三個 timeout 各自負責不同的失效判定

Consumer 存活由三個 timeout 共同把關，每個負責不同層次的失效訊號，混為一談是 rebalance 誤判的主要來源。

session.timeout.ms 是 coordinator 等待 consumer heartbeat 的上限。Consumer 背景執行緒週期性送 heartbeat，coordinator 在這個時間內沒收到就判定 consumer 死亡、觸發 rebalance。預設 45 秒（早期版本 10 秒）。值太小，短暫 GC pause 或網路抖動就誤判離線；值太大，真正死掉的 consumer 要拖很久才被踢出，lag 持續累積。

heartbeat.interval.ms 是 consumer 送 heartbeat 的頻率，必須明顯小於 session.timeout.ms，慣例設成 1/3。它決定 coordinator 多快能感知 consumer 變化，也決定 rebalance 訊號的傳播速度。值太大，session window 內 heartbeat 次數不足，容錯空間消失。

max.poll.interval.ms 是兩次 poll() 呼叫之間的上限，負責偵測「consumer 活著但卡住」。Consumer 主執行緒在 poll() 之間處理拉到的訊息，如果單批處理太久（下游 I/O 慢、batch 太大、業務邏輯重）超過這個時間，coordinator 判定 consumer 失去處理能力、把它踢出 group。預設 5 分鐘。它跟 session.timeout.ms 的分工是：heartbeat 偵測「行程是否還在」，max.poll.interval 偵測「行程是否還在前進」。

這三個值的常見錯配，是把處理變慢誤當成 consumer 死亡。下游 DB 變慢導致每批處理超過 max.poll.interval.ms，consumer 被踢出觸發 rebalance，partition 搬到別的 consumer，那個 consumer 同樣被同一個慢下游拖垮，再次被踢，形成連環 rebalance。這種情況調 session.timeout.ms 沒用，因為 heartbeat 執行緒一直正常送；要調的是 max.poll.interval.ms 或縮小 max.poll.records 讓單批更快做完。

Static group membership 讓 consumer 重啟不觸發 rebalance

Static membership 給 consumer 一個固定身分 group.instance.id，讓 coordinator 在 consumer 短暫離線後保留它的 partition 分配，承擔「滾動重啟與短暫中斷不觸發 rebalance」的責任。沒有 static membership 時，consumer 每次重啟都產生一個新的 member id，coordinator 視為「舊成員離開、新成員加入」、觸發兩次 rebalance。

設定方式是給每個 consumer 一個跨重啟穩定的 group.instance.id。Coordinator 看到帶 instance id 的 consumer 離線時，不立即 revoke 它的 partition，而是等到 session.timeout.ms 真正超時才判定永久離線。在這個窗口內 consumer 帶同一個 instance id 回來，直接接回原本的 partition，不觸發 rebalance。

實機驗證 group.instance.id 生效後，--members 輸出多出 GROUP-INSTANCE-ID 欄位：

1kafka-console-consumer.sh --topic orders --bootstrap-server localhost:9092 \
2  --group static-cg --consumer-property group.instance.id=static-member-1

1GROUP      CONSUMER-ID            GROUP-INSTANCE-ID  CLIENT-ID  #PARTITIONS
2static-cg  static-member-1-...    static-member-1    static-A   3

static membership 的關鍵搭配是把 session.timeout.ms 設得比預期的重啟時間長。K8s 滾動更新一個 pod 重啟可能 10-30 秒，session.timeout.ms 要涵蓋這段，否則 pod 還在重啟、coordinator 已判定永久離線、partition 已搬走，static membership 失去意義。代價是真正死掉的 consumer 也要拖到 session.timeout.ms 才被踢出，這段 partition 無人消費。Static membership 用「容忍較長的真實故障偵測延遲」換「消除重啟造成的 rebalance」，適合重啟頻繁但硬故障罕見的環境。

用 kafka-consumer-groups.sh 讀 lag 分布

診斷 lag 的起點是 kafka-consumer-groups.sh --describe，它逐 partition 列出 current offset、log end offset 與兩者差值 lag，承擔「定位 lag 集中在哪、規模多大」的責任。Lag 是某 partition 已產出的最新 offset 減去 consumer 已 commit 的 offset，代表還沒被消費的訊息量。

實機製造 lag：produce 30 筆訊息、consumer 只消費 12 筆就停掉，--describe 顯示逐 partition 的消費進度落後：

1kafka-consumer-groups.sh --bootstrap-server localhost:9092 --describe --group analytics-cg

1GROUP         TOPIC   PARTITION  CURRENT-OFFSET  LOG-END-OFFSET  LAG  CONSUMER-ID
2analytics-cg  orders  0          9               9               0    -
3analytics-cg  orders  1          3               9               6    -
4analytics-cg  orders  2          0               12              12   -

這份輸出本身就是診斷的第一個分岔點：lag 是均勻分布還是集中在少數 partition。這裡 partition 0 lag=0、partition 1 lag=6、partition 2 lag=12，明顯集中在後兩個 partition，指向 partition 層的不平衡而非整體 consumer 不足。

--state 看 group 的健康狀態與分配策略，--members --verbose 看每個 consumer 實際拿到哪些 partition：

1kafka-consumer-groups.sh --bootstrap-server localhost:9092 --describe --group live-cg --state

1GROUP    COORDINATOR (ID)     ASSIGNMENT-STRATEGY  STATE    #MEMBERS
2live-cg  localhost:9092 (1)   range                Stable   2

STATE 的取值是診斷訊號：Stable 代表分配已收斂正常消費；PreparingRebalance / CompletingRebalance 代表正在 rebalance；Empty 代表 group 沒有 active member（offset 還在但沒人消費），對應上面 lag 輸出裡 CONSUMER-ID 全是 - 的情況。看到 lag 持續累積又長期停在 rebalance 狀態，問題就在 rebalance 本身而非消費速度。

Lag 均勻分布與集中單一 partition 指向不同根因

Lag 的分布形狀是診斷的主軸：均勻分布指向消費總能力不足，集中在少數 partition 指向 key 分布或單 partition 的局部問題。同樣是 lag 高，這兩種形狀的修法完全相反，先讀分布再決定方向。

Lag 均勻分布在所有 partition，代表 consumer group 整體消費速度跟不上 producer 寫入速度。根因在消費側的總吞吐：consumer 數量不足、單 consumer 處理慢（CPU / GC / 下游 I/O）、或 producer 突發流量超過 group 設計容量。修法是擴消費能力：加 consumer（上限是 partition 數）、優化單筆處理、或對下游加 batch。如果 lag 隨時間線性成長且各 partition 同步成長，是穩態的容量不足，要重新評估 partition 數與 consumer 數。

Lag 集中在少數 partition、其餘 partition lag 接近零，代表負載不均，根因通常在 key 分布。Producer 用 key 決定 partition（hash(key) % partition_count），如果某些 key 是熱點（例如某個大客戶的 id、某個 null key 全落同一 partition），對應 partition 的訊息量遠高於其他，負責它的 consumer 再快也追不上，而其他 consumer 閒著。加 consumer 不解決這個問題，因為瓶頸 partition 仍只能被一個 consumer 消費。修法在 key 設計：拆熱點 key、加 salt 打散、或對熱點走獨立 topic。

Airbnb 的 logging pipeline 遇到的正是 partition 層 skew：event size 從幾百 bytes 到幾百 KB、QPS 跨數個量級，Spark 一個 partition 對一個 task，造成 data skew，catch-up 一個 4 小時 lag 要再花 4 小時（3.C15）。它的解法揭露一個關鍵判準：partition 數不該等同 consumer parallelism。當 lag 集中在少數重 partition，加 consumer 受限於 partition 數的天花板無效，要把 parallelism 從 partition 數解耦、按 event volume × size 重新分派 work。這把「lag 集中」的診斷從 key 分布延伸到了 work 分派模型本身。

判讀順序固定：先 --describe 看分布形狀，再決定往「擴容」還是「重分布」走。跳過分布判讀直接加 consumer，遇到熱點 partition 場景會白花資源還解不了 lag。

Production 故障演練

Case 1：consumer 處理慢被踢出 group 形成 rebalance 連環

徵兆：consumer log 反覆出現 Member ... sending LeaveGroup request 與 Attempt to heartbeat failed since group is rebalancing；lag 持續成長；group STATE 在 Stable 與 PreparingRebalance 之間反覆跳；同一批 partition 在不同 consumer 間反覆搬移。

根因：下游 I/O 變慢（DB 連線池打滿、外部 API 延遲升高），consumer 單批 poll() 後處理超過 max.poll.interval.ms（預設 5 分鐘），coordinator 判定該 consumer 失去處理能力、踢出 group、觸發 rebalance。partition 搬到另一個 consumer，後者面對同樣慢的下游、同樣超時被踢，rebalance 連環觸發，每次 rebalance 又讓所有 consumer 暫停消費，lag 加速惡化。

修法：

1. 確認瓶頸是處理慢而非 heartbeat 中斷：consumer log 若有正常 heartbeat 但仍被踢，問題在 max.poll.interval.ms 不是 session.timeout.ms。
2. 縮小 max.poll.records：一次拉少一點，讓單批在 max.poll.interval.ms 內做完，這是不改下游就能止血的第一步。
3. 拉高 max.poll.interval.ms：給單批更長處理時間，但這只是延後而非解決，要搭配下游修復。
4. 修復下游根因：DB 連線池、外部 API 超時、batch 寫入策略，這才是消除連環 rebalance 的根本。

Case 2：lag 集中單一 partition、加 consumer 無效

徵兆：--describe 顯示一兩個 partition lag 數十萬、其餘 partition lag 接近零；加了 consumer 之後 lag 不降，新 consumer 處於閒置（--members 顯示它分到的 partition 都沒 lag）。

根因：producer 的 key 分布有熱點，大量訊息落在同一 partition。Partition 是 Kafka 平行消費的最小單位，一個 partition 只能被 group 內一個 consumer 消費，熱點 partition 的消費速度被單 consumer 鎖死，加再多 consumer 都分不到這個 partition 的工作。

修法：

1. --describe 確認 lag 集中形狀，排除「整體容量不足」的均勻分布情境。
2. 找出熱點 key：抽樣訊息看 key 分布，常見是 null key（全落同一 partition）或單一大租戶 id。
3. 重設計 key：對熱點加 salt 打散到多 partition，或讓熱點走獨立 topic 用更多 partition。
4. 若 work 本身有 skew（單筆訊息處理成本差異大），把 parallelism 從 partition 數解耦，按工作量重新分派，如 Airbnb 的 balanced reader（3.C15）。

key 重分布需要 producer 端配合改 key 策略，對既有 topic 是破壞性變更（舊訊息 key 不變），通常搭配新 topic 切換。本文未實機驗證 producer key 重設計的線上切換流程，依官方分區語義說明。

Case 3：deploy 每次都產生 lag spike

徵兆：每次滾動部署 consumer 服務，lag 在部署窗口內明顯上升、部署完成後緩慢回落；group STATE 在部署期間進入 rebalance；部署越頻繁，累積 lag 越明顯。

根因：每個 consumer pod 重啟，coordinator 看到舊 member 離開、新 member 加入，觸發 rebalance；若用 eager protocol，每次 rebalance 全 group 停止消費；滾動部署逐個重啟 N 個 pod 就觸發 N 次 rebalance，每次全停，lag 在這串全停窗口中累積。

修法：

1. 啟用 static membership：給每個 consumer 固定 group.instance.id，重啟時帶同一身分回來、不觸發 rebalance。
2. 把 session.timeout.ms 設得比 pod 重啟時間長：涵蓋 K8s 重啟一個 pod 的 10-30 秒，否則 static membership 在窗口內失效。
3. 切換到 cooperative incremental protocol：即使仍有 rebalance，只有換手 partition 中斷，未換手 partition 持續消費。
4. 控制部署並行度：一次重啟太多 pod 會放大同時 rebalance 的影響，分批滾動。

Walmart 在 25K+ consumer 規模下，正是 pod scaling / deploy / heartbeat fail 三類事件持續觸發 rebalance lag spike（3.C17）；static membership 與 cooperative 降低單次代價，但它最終把 consumer 解耦成可獨立 auto-scale 的 stateless service，從架構層消除 rebalance 與 partition 數的綁定。

Case 4：scale-to-zero 後冷啟動 lag

徵兆：低流量時段 consumer 被縮到 0，流量回來時 lag 已累積一批、需要一段 catch-up；autoscaler 若看 CPU / memory 反應遲鈍，因為 sink 多為 I/O bottleneck、CPU 平坦不觸發擴容。

根因：event-driven workload 的工作量是 backlog（lag）而非 resource usage。用 CPU / memory 當 scaling signal，在 I/O-bound 的 sink consumer 上失靈：訊息堆積但 CPU 不高，autoscaler 不動，lag 持續成長。

修法：

1. 用 consumer lag 當 scaling signal：lag 超過閾值就擴 consumer、lag 清空就縮，直接對齊工作量。
2. 接受 scale-to-zero 的冷啟動 lag 為設計取捨：minReplicaCount=0 省下 idle 成本，代價是流量回來時的 catch-up 窗口，對非即時 sink 可接受。
3. 設 lag 閾值與擴容步長：閾值太高 catch-up 久、太低頻繁擴縮，依 SLA 對 backlog 的容忍度設定。

Trivago 跨 3 region 跑 50+ Kafka sink、每個 always-on 用 1 CPU + 1 GB，CPU/mem autoscaling 對 I/O-bound sink 無效；改用 KEDA 以 consumer lag 為 scaling signal、minReplicaCount=0 達到 scale-to-zero，daily replica-hour 從 50 降到 1-2（3.C22）。這個案例的判準是 resource usage 不等於工作量，event-driven 場景該看 backlog signal。

Capacity 與 cost

Rebalance 與 lag 的容量規劃圍繞三個變數：partition 數、consumer 數、單次 rebalance 的中斷成本。partition 數是消費平行度的天花板，consumer 數超過 partition 數時多出的 consumer 閒置，所以 partition 數要按峰值需要的平行度規劃，但 partition 過多會推高 metadata 壓力與 rebalance 計算成本。

實務 default：partition 數按峰值平行度設、保留成長餘量但不過度分區；consumer 數對齊 partition 數、用 lag 而非 CPU 當 autoscaling signal；rebalance 頻繁的環境優先 static membership + cooperative，再評估是否需要把 consumer 從 partition 解耦。加 partition 是單向操作（無法縮回），且改變既有 key 的 partition 對應，要在規劃期一次設足而非事後頻繁調整。

整合與下一步

Rebalance 與 lag 診斷接在 consumer 設計與交付語義之上：commit 策略決定 lag 的計算基準與 rebalance 後的重複消費風險，交付語義決定 rebalance 中斷期間訊息是否可能丟失或重放。

跟 consumer 設計對位

3.4 consumer 設計 涵蓋 commit 策略（auto vs manual）、commit 時機與 partition 分配的整體設計。本文的 rebalance 是 consumer 設計在「成員變動」維度的展開，lag 是 commit 進度的可觀測量。commit 策略選錯會在 rebalance 後放大重複消費或丟失。

跟交付與復原語義對位

3.6 processing 與 recovery 語義 涵蓋 rebalance 中斷期間的 at-least-once / at-most-once 行為。rebalance revoke partition 時，未 commit 的進度會在新 consumer 接手後重放（at-least-once）；commit 太早則可能在 rebalance 中丟失（at-most-once）。idempotency 與 replay 的整體設計見 6.12 idempotency / replay。

相關案例

• 3.C15 Airbnb Spark Streaming — partition-task 1:1 造成 data skew、parallelism 從 partition 數解耦
• 3.C17 Walmart MPS — 25K+ consumer 在 K8s 的 rebalance storm、consumer 解耦成 stateless service
• 3.C22 Trivago KEDA — consumer lag 驅動 scale-to-zero、backlog signal 取代 resource usage

相關連結

• 上游 vendor 頁：Apache Kafka
• 知識卡：consumer lag、consumer group、partition
• 下游能力：3.4 consumer 設計、3.6 processing 與 recovery 語義

本文是跨 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 深度技術文章的寫作方法論

本文是 Kafka overview「Replication 與 exactly-once 升級」段的 implementation-layer deep article。Overview 已給出 partition / replication 的選型定位、本文展開 寫入承諾 跟 處理語義 兩條獨立軸線怎麼設、邊界在哪、成本是什麼。對應反例 3.C9 Queue 語義誤配。

寫入承諾與處理語義是兩條獨立軸線

Kafka 的可靠性拆成兩個彼此正交的問題、混在一起談是多數誤配的起點。第一條軸線是 寫入承諾：一筆訊息寫進 broker 後、在多少 replica 落地才算「成功」、broker 掛掉時這筆訊息會不會消失。這條軸線由 replication factor、ISR、acks 與 min.insync.replicas 共同決定、屬於 broker 端的耐久性保證。第二條軸線是 處理語義：同一筆訊息在 producer 重送、consumer 重啟、partition rebalance 等情境下、會不會被寫進去兩次或被處理兩次。這條軸線由 producer idempotence、transaction 與 consumer 端的 commit 設計決定、屬於端到端的正確性保證。

兩條軸線可以獨立調整：可以有「寫入承諾很強但處理語義是 at-least-once」的配置（acks=all + 非冪等 consumer）、也可以有「寫入承諾較弱但已開冪等」的配置。把 exactly-once 當成單一開關去找、是因為沒看出這兩條軸線存在。本文先講第一條（replication / ISR / acks）、再講第二條（idempotence / transaction）、最後談兩者疊起來能達成什麼、達不成什麼。

這個拆分對映 delivery semantics 與 idempotency 兩張知識卡：前者描述 broker 承諾的送達次數、後者描述處理端怎麼讓「送達多次」不等於「生效多次」。

ISR：誰算「跟得上」的副本

ISR（in-sync replica、同步副本集）是一個 partition 當前「跟得上 leader」的 replica 集合、是 Kafka 把 replication factor 這個 靜態配置 轉成 動態保證 的關鍵概念。Replication factor = 3 只說明這個 partition 有 3 份 replica；但任一時刻真正跟得上 leader 的可能只有 2 份或 1 份。ISR 就是這個「當前實際同步」的集合、寫入承諾的判斷都基於 ISR、不是基於 replication factor。

一個 follower 留在 ISR 內的條件是：它在 replica.lag.time.max.ms（預設 30 秒）內持續向 leader 拉取資料、且追上 leader 的 log end offset。當 follower 因為 broker 慢、網路抖動、GC 停頓或 disk 壓力而落後超過這個時間窗、leader 會把它移出 ISR — 這就是 ISR shrink（收縮）。當它恢復、重新追上、再被加回 ISR — 這是 ISR expand（擴張）。

ISR 收縮本身不是故障、是 Kafka 對「這個 follower 暫時不可信」的誠實表態。真正的風險在於：ISR 收縮到某個程度後、acks=all 的寫入承諾會無法滿足 min.insync.replicas 而開始拒絕寫入。下一段的 acks 取捨直接建立在 ISR 這個概念上。

實機看 ISR 的方式是 kafka-topics.sh --describe、Isr 欄位列出當前同步的 broker id：

1# RF=3、min.insync.replicas=2 的 topic、三 broker 都同步時
2kafka-topics.sh --describe --topic repl-demo --bootstrap-server kafka1:9092
3# Topic: repl-demo  PartitionCount: 1  ReplicationFactor: 3  Configs: min.insync.replicas=2
4#   Topic: repl-demo  Partition: 0  Leader: 2  Replicas: 2,3,1  Isr: 2,3,1

Replicas 欄位是 配置上 的 3 份副本、Isr 欄位是 當前實際同步 的集合。兩者一致代表健康；Isr 比 Replicas 短代表有副本落後。日常巡檢用 kafka-topics.sh --describe --under-replicated-partitions 直接列出 Isr 短於 Replicas 的 partition。

acks 與 min.insync.replicas：寫入承諾的兩個旋鈕

寫入承諾由 producer 端的 acks 跟 broker / topic 端的 min.insync.replicas 共同決定、兩者必須一起設才有意義。acks 決定 producer 在收到「成功」回應前、要等多少 replica 確認；min.insync.replicas 決定 broker 在 ISR 不足時是否拒絕寫入。前者是 producer 的等待策略、後者是 broker 的拒絕底線。

acks 三個值對應遞增的耐久性與遞增的延遲成本：

acks=0 適用「丟一兩筆無所謂」的場景、例如高頻 metric 上報、log shipping 的非關鍵層。它把網路往返成本壓到最低、代價是 producer 完全不知道 broker 有沒有收到。任何牽涉金流、訂單、狀態變更的訊息都不該用 acks=0。

acks=1 是一個容易被誤以為安全的中間值。它只等 leader 寫入本地、不等 follower 同步。多數時候運作正常、但存在一個明確的資料遺失窗口：leader 回了成功、follower 還沒拉到這筆訊息、此時 leader 所在 broker 崩潰、新 leader 從 follower 中選出 — 那筆「已回成功」的訊息在新 leader 上不存在、producer 卻以為寫成功了。這個窗口在正常運行時很窄、但在 broker 滾動重啟、硬體故障、AZ 中斷時會被放大。

acks=all 是耐久性配置的正解、但只有搭配 min.insync.replicas ≥ 2 才完整。單獨設 acks=all、若 min.insync.replicas=1、那麼當 ISR 收縮到只剩 leader 一份時、acks=all 等同 acks=1 — 「所有 ISR 確認」這個條件在 ISR 只剩 1 份時形同虛設。min.insync.replicas=2 補上這個漏洞：它要求 ISR 至少有 2 份才接受 acks=all 寫入、否則直接拒絕、把「靜默遺失」轉成「明確拒絕」。

min.insync.replicas 是 topic-level 可動態調整的配置、不需重啟 broker：

1# 動態調整單一 topic 的 min.insync.replicas
2kafka-configs.sh --alter --topic repl-demo \
3  --add-config min.insync.replicas=2 \
4  --bootstrap-server kafka1:9092
5
6# 查當前值、synonyms 會顯示 topic override 蓋過 broker default
7kafka-configs.sh --describe --topic repl-demo --bootstrap-server kafka1:9092
8# min.insync.replicas=2 synonyms={DYNAMIC_TOPIC_CONFIG:min.insync.replicas=2,
9#   DYNAMIC_DEFAULT_BROKER_CONFIG:min.insync.replicas=1, DEFAULT_CONFIG:min.insync.replicas=1}

RF=3 + acks=all + min.insync.replicas=2 是業界對「不能丟資料」topic 的標準三件組：3 份副本提供冗餘、acks=all 要求同步確認、min.insync=2 在容忍一台 broker 掛掉的同時仍保證每筆寫入落在至少兩份 replica。容忍度的算術是 RF - min.insync.replicas：3 - 2 = 1、代表可以掉一台 broker 仍正常寫入、掉兩台則寫入被拒（但已寫入的資料不丟）。

Producer idempotence：去掉重送造成的重複

Producer idempotence（冪等生產者、enable.idempotence=true）解決的是 producer 重送 造成的 broker 端重複。它讓「producer 因為沒收到 ack 而重送同一筆訊息」這件事、在 broker 端被去重、不會寫進兩筆。這是處理語義軸線的第一塊、獨立於前面的寫入承諾。

問題的根源是：producer 送出訊息後、若因網路超時沒收到 broker 的 ack、它無法分辨是「訊息沒送到」還是「訊息送到了但 ack 在回程丟了」。預設行為是重送。在沒有冪等保護時、若實際是後者、broker 就收到兩筆相同訊息、partition 裡出現重複。

冪等機制的做法是給每個 producer 分配一個 producer ID（PID）、並為每個 partition 維護一個遞增的 sequence number。Broker 記住每個 (PID, partition) 已接受的最大 sequence；重送的訊息帶相同 sequence、broker 認出是重複、直接丟棄並回成功。這個保證的範圍是 單一 producer session 內、單一 partition 的精確一次寫入。

開啟方式是 producer 端設 enable.idempotence=true。在較新版 Kafka 這已是預設值、且它會隱含要求 acks=all、retries > 0、max.in.flight.requests.per.connection ≤ 5 — 因為冪等去重依賴這些前提。冪等的成本極低（broker 多維護 PID/sequence 的少量 metadata）、幾乎沒有理由關閉。

需要明確的邊界是：冪等只覆蓋 同一個 producer session。Producer 重啟後拿到新的 PID、broker 無法把新舊 session 的訊息關聯起來。跨 session 的去重、以及「寫多個 partition 要嘛全成功要嘛全失敗」的需求、要靠下一段的 transaction。

Kafka transaction 與 read_committed：跨 partition 的原子寫入

Kafka transaction（交易）解決的是 跨多個 partition 的原子寫入 與 consume-process-produce 的原子提交。它讓一組寫入（可能跨多個 topic / partition）以及對應的 consumer offset commit、要嘛全部對下游可見、要嘛全部不可見。這是處理語義軸線的第二塊、建立在冪等之上。

典型場景是 stream processing 的 consume-process-produce 迴圈：consumer 讀入一批訊息、處理後產出結果寫到另一個 topic、然後 commit 讀取進度。若這三步不是原子的、崩潰時可能出現「結果已產出但 offset 沒 commit」（重啟後重複處理、重複產出）或「offset 已 commit 但結果沒寫成功」（訊息遺失）。Transaction 把「產出結果」跟「commit offset」綁成一個原子操作、消除這個窗口。

啟用 transaction 需要 producer 設一個穩定的 transactional.id、並在程式碼中走完整的 transaction 生命週期：

1producer.initTransactions()      // 向 transaction coordinator 註冊、fence 掉舊 session
2producer.beginTransaction()
3  producer.send(record1)          // 跨多個 topic/partition 的寫入
4  producer.send(record2)
5  producer.sendOffsetsToTransaction(offsets, groupMetadata)  // consumer 進度也納入交易
6producer.commitTransaction()      // 全部原子提交；失敗則 abortTransaction()

transactional.id 提供跨 session 的 fencing（隔離）：同一個 transactional.id 的新 producer 啟動時、coordinator 會 fence 掉舊的、避免「殭屍 producer」在崩潰後復活還繼續寫。這是冪等的 PID 機制做不到的跨 session 保證。

實機限制：kafka-console-producer.sh 帶 --producer-property transactional.id=... 不會自動呼叫 initTransactions()、會直接報 IllegalStateException: Cannot add partition ... before completing a call to initTransactions。完整 transaction 生命週期只能在 client code 中驗證、無法用 console 工具演示。本文的 transaction 行為描述依官方 producer API 語義、生命週期程式碼未經本地 client 實機跑通。

Transaction 的另一半在 consumer 端：isolation.level=read_committed。預設的 read_uncommitted 會讀到尚未 commit、甚至最終被 abort 的 transactional 訊息。設成 read_committed 後、consumer 只會看到已 commit 的 transactional 訊息、abort 的訊息對它不可見、未 commit 的訊息會被擋在 last stable offset（LSO）之前等待。

1# consumer 以 read_committed 隔離級別讀取、只看已 commit 的 transactional 訊息
2kafka-console-consumer.sh --topic repl-demo --from-beginning \
3  --isolation-level read_committed \
4  --bootstrap-server kafka1:9092

需要注意：對非 transactional 的普通訊息、read_committed 跟 read_uncommitted 行為相同 — 普通訊息一律可見。隔離級別只對 transactional 訊息產生差異。這也是為什麼若上游沒有任何 transactional producer、把 consumer 改成 read_committed 不會有任何可觀察的效果。

端到端 exactly-once 的邊界與成本

端到端 exactly-once 的意思是：訊息從 producer 到 consumer 處理結果、整條路徑上「不重不漏」。它由前面所有零件疊出來、但有明確的適用邊界、不是萬用保證。

Kafka 原生能提供 exactly-once 的範圍是 Kafka-to-Kafka 的封閉迴圈：consume from Kafka、process、produce to Kafka、commit offset、整個用 transaction 綁定。Kafka Streams 框架把這套封裝成 processing.guarantee=exactly_once_v2 一個配置、底層就是 transaction + 冪等 + read_committed 的組合。在這個封閉迴圈內、exactly-once 是真實成立的。

邊界出現在 離開 Kafka 的那一刻。當處理結果要寫進外部系統（資料庫、HTTP API、第三方服務、寄信、扣款）、Kafka 的 transaction 管不到外部系統的提交。一筆訊息「已扣款但 offset commit 前崩潰」這種跨系統不一致、Kafka transaction 無法消除 — 它只保證 Kafka 內部的原子性。跨系統的 exactly-once 要靠外部系統自己的冪等鍵（idempotency key）、或 outbox pattern、或兩階段提交、由應用層補上、不是 Kafka 送的。

成本方面、exactly-once 不是免費的耐久性升級：

務實的判斷是：先確認需求真的是 exactly-once、還是「at-least-once + 下游冪等」就夠。多數業務（包括金流）用 at-least-once 送達 + 下游用業務冪等鍵去重、就達到了「效果上不重複」、且吞吐與複雜度成本遠低於完整 transaction exactly-once。完整的 Kafka transaction exactly-once 留給 Kafka-to-Kafka 的 stream processing pipeline、那是它的甜蜜點。這個取捨對映 3.6 processing-recovery-semantics 對「在哪一層放冪等」的判讀。

故障演練

可靠性配置的價值在故障時才顯現。以下演練在 3-broker KRaft 叢集（RF=3、min.insync.replicas=2）上跑、用停 broker 製造 ISR 收縮、觀察各配置的真實行為。

ISR 收縮到低於 min.insync.replicas 時 acks=all 被拒

演練：起 3-broker 叢集、建 RF=3 / min.insync.replicas=2 的 topic、初始 ISR = 三台全在。依序停掉兩個 follower broker、觀察 ISR 收縮、再用 acks=all produce。

初始狀態（ISR 三份全在、acks=all 正常）：

1Topic: repl-demo  Partition: 0  Leader: 2  Replicas: 2,3,1  Isr: 2,3,1
2# acks=all produce → exit=0

停一個 follower（broker 3）、ISR 收縮到 2 份、仍滿足 min.insync=2：

1Topic: repl-demo  Partition: 0  Leader: 2  Replicas: 2,3,1  Isr: 2,1
2# acks=all produce → exit=0（ISR=2 仍 >= min.insync=2、寫入接受）

再停一個 follower（broker 1）、ISR 收縮到只剩 leader 1 份、低於 min.insync=2：

1# acks=all produce → broker 拒絕：
2[Producer] Got error produce response ... Error: NOT_ENOUGH_REPLICAS, retrying
3org.apache.kafka.common.errors.NotEnoughReplicasException:
4  Messages are rejected since there are fewer in-sync replicas than required.

判讀：這正是 min.insync.replicas 的設計意圖在運作。ISR 不足時、broker 選擇 明確拒絕寫入（NOT_ENOUGH_REPLICAS）、而不是降級成 acks=1 默默接受。對 producer 而言、寫入失敗會觸發 retry、retry 耗盡後拋例外、上游應用感知到「現在寫不進去」、可以 fail-fast 或 backpressure — 而不是寫了一筆只在單一 broker 上、隨時可能隨那台 broker 一起消失的「假成功」訊息。把資料遺失轉成可觀測的寫入拒絕、是這個配置的全部目的。

恢復：重啟兩個 broker、ISR 自動 expand 回三份、acks=all 恢復接受寫入：

1Topic: repl-demo  Partition: 0  Leader: 2  Replicas: 2,3,1  Isr: 1,2,3

附帶觀察：在 KRaft 模式下、controller 也是 quorum（本演練三台都兼任 controller）。同時停掉兩台、controller quorum 失去多數、kafka-topics.sh --describe 對 metadata 的查詢會 timeout（DisconnectException）。production 叢集應把 controller 數量與 broker 故障域分開規劃、避免 broker 故障連帶打垮 metadata 平面。

Unclean leader election 的取捨

當一個 partition 的所有 ISR replica 都不可用、只剩一個 曾經落後、已被踢出 ISR 的 replica 還活著、Kafka 面臨一個無法兩全的選擇。unclean.leader.election.enable=false（預設）會選擇 不選 leader：這個 partition 進入不可用狀態、拒絕讀寫、直到某個 ISR replica 恢復。unclean.leader.election.enable=true 會選擇 把那個落後的 replica 提為 leader：partition 立刻恢復可用、代價是那個 replica 上缺失的訊息（leader 掛掉前已 commit 但它還沒同步到的部分）永久遺失。

判讀：這是一個 可用性 vs 耐久性 的直接取捨、沒有正確答案、只有對映業務的選擇。對金流、訂單、審計這類「丟一筆都不行」的 topic、保持 false、寧可 partition 短暫不可用也不接受靜默資料遺失。對 metric、log、可重算的衍生資料、開 true 換可用性、丟幾筆可接受。預設 false 是合理的安全預設、但要意識到它的代價是「所有 replica 都不在 ISR 時、partition 會卡住不可用」、這在多 broker 同時故障時會發生。

Idempotent producer 對重送去重

演練：producer 開 enable.idempotence=true、acks=all、模擬 ack 丟失導致的重送。

判讀：冪等開啟後、producer 因網路超時重送的訊息帶相同 (PID, partition, sequence)、broker 認出 sequence 重複、丟棄重送並回成功、partition 內不出現重複。實機上 enable.idempotence=true 的 produce 寫入正常（exit=0）、消費端讀回的訊息數等於實際送出的邏輯訊息數、重送不放大。要記住的邊界仍是：這只覆蓋單一 producer session；producer 重啟換 PID 後、跨 session 的重複要靠 transaction 或下游冪等鍵處理。

Transaction 中途失敗的 read_committed 隔離

演練：transactional producer 在 beginTransaction 後寫入若干訊息、然後 abortTransaction（模擬處理中途失敗）；consumer 分別用 read_uncommitted 與 read_committed 讀取。

判讀：read_committed 的 consumer 看不到被 abort 的訊息 — 中途失敗的 transaction 對它等於沒發生過、不會讀到「處理一半的髒資料」。read_uncommitted 的 consumer 則會讀到這些最終被 abort 的訊息、若據此處理就產生了不該發生的副作用。這是 transaction 隔離的核心價值：把「transaction 失敗」的可見性控制在 commit 邊界內。

本段的 abort 行為依官方 transaction 語義描述。本地以 kafka-console-consumer.sh --isolation-level read_committed 驗證了隔離級別參數可用、且對已 commit 的普通訊息 read_committed 與 read_uncommitted 輸出一致（普通訊息一律可見、隔離級別只對 transactional 訊息產生差異）；完整的 begin/abort transaction 生命週期需 client code、未用 console 工具跑通。

Capacity / cost

各配置的容量與成本影響、決定它適用的規模與 topic 類別：

務實 default：

• 業務 topic 一律 RF=3 + acks=all + min.insync.replicas=2、idempotence 預設開
• 容忍度算術 RF - min.insync.replicas 要 ≥ 1、否則單台 broker 維護就會中斷寫入
• 完整 transaction exactly-once 只給 Kafka-to-Kafka pipeline；跨系統用 at-least-once + 下游冪等鍵
• unclean.leader.election 保持 false、除非該 topic 明確可丟資料換可用性

整合 / 下一步

跟 processing-recovery-semantics 對位

寫入承諾保證訊息留在 broker、但 處理 的不重不漏在 consumer 端。3.6 processing-recovery-semantics 展開 consumer 的 commit 時機、崩潰恢復的 replay 範圍、以及「冪等放在哪一層」的判讀 — 跟本文的 transaction exactly-once 邊界互補：本文界定 Kafka 能送什麼、那篇界定處理端怎麼接才不放大重複。

跟 event-contract-replay-boundary 對位

Exactly-once 的封閉迴圈假設訊息格式穩定、replay 可重現。3.7 event-contract-replay-boundary 展開 schema 演進與 replay 邊界 — 當 transaction 提供的原子性遇上 schema 變更、replay 舊訊息的可重現性會受 contract 影響、是 exactly-once 在時間維度上的延伸限制。

對應反例 3.C9

3.C9 Queue 語義誤配 是本文兩條軸線混淆的真實後果：broker 遷移後「名稱上相近的 delivery semantics」在失敗重播時產生不同結果、出現重複扣款與狀態漏更新。判讀路徑正是本文的拆分 — 先確認是寫入承諾（acks / ISR）還是處理語義（idempotence / commit 時機）出問題、不要用 queue depth 這種寫入承諾層的指標去判斷處理語義層的故障。

對應案例 3.C21 Goldman Sachs MSK 遷移

3.C21 Goldman Sachs MSK 遷移 揭露遷移時可靠性配置的細節風險集中在 client 端的 timeout / flush / LB 配置、而非 broker 本身。本文的 acks=all 在 ISR 不足時拒絕寫入、若 client 端的 retry 與 timeout 沒對齊（如 flush timeout 太短）、會把「broker 正常的 backpressure」誤判成「遷移失敗」。可靠性配置與 client 容錯參數要一起驗證。

下一步路由

• 上游概念：delivery semantics、idempotency 知識卡
• 同 vendor：Kafka overview 的 producer / consumer 設計段
• 下游能力：3.6 processing-recovery-semantics、3.7 event-contract-replay-boundary、6.12 idempotency / replay
• 方法論：Vendor 深度技術文章的寫作方法論

本文是跨 vendor migration playbook、cross-link Kafka 跟 AWS MSK。跑 migration-playbook-methodology 6 維 audit 後對映 Operational = High（self-managed → AWS managed）→ Type C operational redesign hybrid。

$15K/month operational cost 拆解

跟 Datadog → Grafana Stack（H cost variant）同 framing — 用 cost 拆解開頭、不是「為什麼遷」driver list：

最大成本塊是 operational FTE、不是 infrastructure。MSK 把 50-80% operational 工作轉嫁 AWS、留 application + cost monitoring 給 SRE。

跑 6 維 diff dimension audit：

Operational = High（其他 Low-Medium）→ Type C operational redesign hybrid。

為什麼遷：FTE / availability / consistency 三條 driver

• Operational FTE：Kafka self-managed + ZooKeeper / KRaft + Prometheus 端到端 ops 是 0.5-1 FTE、MSK 把 patch / HA / backup 全託管
• Availability：MSK 自動 multi-AZ broker + auto-recovery、self-managed 自管 broker 故障 RTO 30 分鐘-2 小時
• Consistency with cloud stack：已 deep on AWS（RDS / S3 / Lambda）、MSK 進 same VPC + IAM auth、降低 cross-vendor 設置成本

反向 driver（MSK → self-managed）：

• Throughput / GB 規模大時 MSK 跨 broker cost 反轉（cost > self-managed）
• 需要 Kafka 客製化（custom plugin / kraft early adopter / 非 AWS region）
• Multi-cloud / hybrid 架構不想 vendor lock

Operational redesign 對位

跟 PostgreSQL → Aurora / MongoDB → Atlas 同 Type C pattern：

每行 operational concept 都需要 migration plan、application code 不變但 運維知識體系全換。

4-phase migration（Type C 標準流程）

Phase 0：Pre-migration audit

• Workload sizing → MSK broker class：當前 throughput / partition count / topic count
• Application connection pattern audit：客戶端 producer / consumer 用 SASL / mTLS / plaintext？哪個 application
• Topic config audit：retention / replication factor / cleanup policy
• Backup pattern audit：有 MirrorMaker / cross-cluster mirror 嗎

Phase 1：MSK cluster 建置（2-3 週）

 1resource "aws_msk_cluster" "main" {
 2  cluster_name           = "production"
 3  kafka_version          = "3.6.0"
 4  number_of_broker_nodes = 3
 5
 6  broker_node_group_info {
 7    instance_type   = "kafka.m5.large"
 8    client_subnets  = var.private_subnets
 9    security_groups = [aws_security_group.msk.id]
10    storage_info {
11      ebs_storage_info {
12        volume_size = 1000
13        provisioned_throughput {
14          enabled           = true
15          volume_throughput = 500
16        }
17      }
18    }
19  }
20
21  client_authentication {
22    sasl {
23      iam = true        # IAM auth (推薦)
24      scram = false
25    }
26  }
27
28  configuration_info {
29    arn      = aws_msk_configuration.main.arn
30    revision = aws_msk_configuration.main.latest_revision
31  }
32
33  encryption_info {
34    encryption_in_transit {
35      client_broker = "TLS"
36    }
37  }
38
39  logging_info {
40    broker_logs {
41      cloudwatch_logs {
42        enabled   = true
43        log_group = aws_cloudwatch_log_group.msk.name
44      }
45    }
46  }
47}

Phase 2：Data migration（MirrorMaker 2.0）

1Self-managed Kafka ──(MM2)──→ MSK
2                       │
3                consumer offset sync
4                       │
5                topic config sync

MM2 跑 1-7 天、依 topic 量 + retention 期間；replica.lag 對齊後進 cutover。

Phase 3：Cutover

• Application 端切 bootstrap.servers 從 self-managed → MSK
• Producer 漸進切（10% → 50% → 100%）
• Consumer 切換時 offset 從 MM2 sync 過的位置開始
• Self-managed cluster read-only standby 2 週

Production 故障演練

Case 1：IAM auth 沒設、application 連不上

徵兆：cutover 後 application 報 SaslAuthenticationException: Access denied；MSK 端 cloudWatch log 顯示 IAM principal 不認。

根因：MSK IAM auth 要求 client 跑 MSK IAM auth library（Java 用 aws-msk-iam-auth、Python 用 aws-msk-iam-sasl-signer-python）；application 端用 standard Kafka client、不知道怎麼 sign IAM signature。

修法：

 1# Python kafka-python + IAM auth
 2from aws_msk_iam_sasl_signer import MSKAuthTokenProvider
 3from kafka import KafkaProducer
 4
 5class AwsMskIamProvider(MSKAuthTokenProvider):
 6    def token(self):
 7        return self.generate_auth_token('us-east-1')[0]
 8
 9producer = KafkaProducer(
10    bootstrap_servers='b-1.mycluster.kafka.us-east-1.amazonaws.com:9098',
11    security_protocol='SASL_SSL',
12    sasl_mechanism='OAUTHBEARER',
13    sasl_oauth_token_provider=AwsMskIamProvider(),
14)

EKS pod 必須有 IAM role（IRSA）對 MSK cluster kafka-cluster:Connect action。

Case 2：Version pinning、3.6.0 跟 self-managed 行為差

徵兆：cutover 到 MSK 3.6.0 後、某些 consumer 跑舊 client 失敗；新 broker 改 default inter.broker.protocol.version 但 client 不認。

根因：MSK 升 Kafka version 後 broker config 變動、舊 client（< 2.8）跟新 broker 協議不對；self-managed 端可能用更舊 broker version 跑、看不出問題。

修法：

1. Pre-migration：所有 client 升 Kafka client library 2.8+
2. MSK kafka_version 對齊 self-managed：先建 MSK 3.0 / 3.5、跟 self-managed 一致、cutover 後再升
3. Phase rollout：用 Tiered Storage + retention 策略保留舊資料、新 producer / consumer 用新 version

Case 3：Metric pipeline 失效、SOC dashboard 無數據

徵兆：cutover 後 Grafana dashboard 顯示 MSK metric 0；舊 JMX exporter 抓不到 MSK；CloudWatch 有 metric 但 SOC 端不接 CloudWatch。

根因：MSK 不暴露 JMX、metric 走 CloudWatch / open monitoring (Prometheus + Grafana)、跟自建 JMX-based pipeline 不對等。

修法：

1. Open monitoring enabled：MSK config 設 open_monitoring.prometheus.jmx_exporter.enabled = true、跑 Prometheus 對 MSK broker 拉 metric
2. CloudWatch → Prometheus：用 cloudwatch-exporter 拉 CloudWatch metric 進 Prometheus
3. Dashboard refresh：Grafana dashboard 對 MSK-specific metric name 重寫（kafka_server_* → aws_kafka_* 或統一 alias）

Case 4：Cross-cluster mirror（MM2 → MSK）配置複雜

徵兆：MM2 跑了 1 週、self-managed 跟 MSK consumer offset 沒同步；application 切過去後 重新讀整批舊資料、duplicate processing。

根因：MM2 consumer offset sync 需要 跨 cluster mapping、source 端 offset 跟 target 端 offset 不直通；MM2 預設 offset sync 沒打開。

修法：

1# MM2 config
2source.consumer.bootstrap.servers=self-managed-kafka:9092
3target.consumer.bootstrap.servers=msk-cluster:9098
4target.security.protocol=SASL_SSL
5sync.group.offsets.enabled=true       # 必須打開
6emit.checkpoints.enabled=true
7checkpoints.topic.replication.factor=3

Architecture：consumer 切換時讀 MM2 checkpoint topic、不直接讀 internal offset；application 端用 idempotent + dedup key、avoid duplicate processing。

Case 5：MSK billing 暴漲、Tiered Storage / cross-AZ 沒控

徵兆：MSK 第一個月帳單比預估高 50%；breakdown 後發現 cross-AZ traffic（producer/consumer 跨 AZ）+ Tiered Storage 退到 S3 的 hot tier。

根因：

• MSK auto multi-AZ deployment 不可避免 cross-AZ traffic、producer 寫 partition leader 可能跨 AZ
• Tiered Storage 對 hot data（retention < 24 小時）會多 storage cost；cold data 才 cost-effective

修法：

1. Application AZ-aware routing：producer 走 same-AZ broker（用 rack-aware producer config）、降 cross-AZ
2. Retention 對齊 hot tier：< 24 小時 retention 用 broker local storage、24 小時+ 才走 Tiered Storage
3. Reserved instance：MSK 不直接 reserved、但 EBS / data transfer 可預付、降 10-20%

Capacity / cost

判讀：< 50 broker organization MSK ROI 通常 6-12 月持平、之後省 FTE；50+ broker 大 organization 自管 cost 可能反而低。

整合 / 下一步

跟 Kafka ↔ NATS migration 對位

兩條 Kafka 出路：

• MSK：operational simplification、protocol drop-in、cost 中等漲；適合 繼續用 Kafka paradigm 的 organization
• NATS：paradigm shift、application 必須改、適合 單純 messaging 不要 event sourcing 的 use case

多數 organization 不需要 paradigm shift、MSK 更合理；真正需要 lightweight messaging 才走 NATS。

跟 Confluent Cloud 對位

Confluent Cloud 是另一個 managed Kafka、跨 cloud（AWS / GCP / Azure）；MSK 是 AWS-only、但跟 IAM / VPC 整合更深。Multi-cloud organization 走 Confluent、AWS-deep organization 走 MSK。

跟 IAM / Secrets Manager 整合

MSK + IAM auth + Secrets Manager（連 Vault → AWS Secrets Manager migration）是 AWS-deep stack 的標準組合；short-lived credential + IRSA 是 production best practice。

反向 migration（MSK → self-managed）

少見、通常是 cost 反轉（大 scale）或 multi-cloud strategy；流程鏡像對稱、注意 MSK Tiered Storage data 不直接 export、需要 先 disable tiered storage + recall data。

下一步議題

• MSK Connect：managed Kafka Connect、降 connector 運維、但 plugin ecosystem 比 self-managed Connect 少
• MSK Serverless：burst workload 適合、steady workload 反而貴
• Cost monitoring playbook：MSK billing 拆解每月跑一次、catch unexpected egress / tiered storage cost

相關連結

• Source vendor：Kafka
• 平行 migration playbook (Type C)：PostgreSQL → Aurora / MongoDB → Atlas
• 平行 H cost variant：Datadog → Grafana Stack
• 平行 paradigm shift：Kafka ↔ NATS
• Methodology：Migration playbook methodology

本文是 Kafka overview 的 implementation-layer deep article、聚焦保留與分層儲存。選型層的「該不該選 Kafka」「跟其他 broker 差在哪」見 overview；本文回答「保留策略怎麼設、log compaction 怎麼運作、冷熱分層怎麼讓容量跟保留期解耦、踩哪些坑」。配置段在 Apache Kafka KRaft 單節點實機驗證；tiered storage 段標註未實機驗證的範圍。

Retention 是 replay window 的物理邊界

Retention 的核心責任是決定「一筆訊息在 broker 上能存活多久」、而這條邊界直接界定 consumer 能往回重播多遠。Kafka 的 log 是 append-only 的事件序列、訊息寫入後不會被原地修改；retention 是唯一會把舊訊息從磁碟移除的機制。設多久、用什麼條件刪、刪掉之後 consumer 還能不能讀到，全由保留策略決定。

這條邊界之所以重要、是因為 Kafka 的多 consumer 模型讓「重播」變成一級能力。同一個 topic 可以被多組 consumer 各自從任意 offset 開始讀、每組維護自己的進度；只要訊息還在 retention 範圍內、新加入的 consumer 或出事後要補算的 consumer 都能從頭重讀。一旦訊息超過 retention 被刪、replay window 就到此為止、補償只能改走資料庫或上游來源。

Kafka 提供兩條獨立的保留軸、可單獨用也可同時用：

時間軸對齊的是 replay 需求：把 retention 設成「事故從發生到偵測到修復的最長時間」、確保發現要補算時事件還在。容量軸對齊的是成本與磁碟保護：避免某個突發高流量 topic 把 broker 磁碟寫滿、拖垮同 broker 上其他 partition。兩者同時設時是「誰先觸發誰生效」、所以容量軸常常會在高流量時段提前砍掉本來預期能保留 7 天的事件——這個交互是後面故障演練的重點之一。

實機建立一個同時設兩軸的 topic、--describe 會把保留配置直接列在 Configs：

1# CLI 在容器內 /opt/kafka/bin/、bootstrap-server 指向 broker
2kafka-topics.sh --create --topic ret-delete --partitions 1 \
3  --config retention.ms=60000 \
4  --config retention.bytes=10485760 \
5  --config segment.ms=10000 \
6  --bootstrap-server localhost:9092
7
8kafka-topics.sh --describe --topic ret-delete --bootstrap-server localhost:9092
9# Configs: retention.ms=60000,retention.bytes=10485760,segment.ms=10000,...

retention 不是寫死在建 topic 當下、線上可以用 kafka-configs.sh --alter 動態調整、立即生效不需重啟 broker：

1kafka-configs.sh --alter --entity-type topics --entity-name ret-delete \
2  --add-config retention.ms=3600000 \
3  --bootstrap-server localhost:9092
4# Completed updating config for topic ret-delete.
5
6kafka-configs.sh --describe --entity-type topics --entity-name ret-delete \
7  --bootstrap-server localhost:9092
8# retention.ms=3600000 sensitive=false synonyms={DYNAMIC_TOPIC_CONFIG:retention.ms=3600000}

動態調整的 retention 屬於 DYNAMIC_TOPIC_CONFIG、優先於 broker 層的 log.retention.* 預設值；synonyms 欄位會把覆蓋關係列出來、排查時可確認當前生效的是哪一層。

Segment 是刪除的最小單位

Retention 刪資料的最小單位是 log segment、不是單筆訊息。理解這一點才能解釋「為什麼設了 retention.ms 之後，過期的訊息有時還在」。每個 partition 的 log 在磁碟上被切成多個 segment 檔、只有 active segment（當前正在寫入的那一個）以外、已經 roll over 的 segment 才會被 retention 檢查並整段刪除。

Segment 何時 roll over 由兩個條件決定：segment.bytes（檔案大到上限、預設 1 GB、最小 1 MB）或 segment.ms（檔案存在時間超過設定）。實機寫入 ~6 MB 資料到一個 segment.bytes=1048576（1 MB）的 topic、磁碟上會看到 6 個 roll 過的 segment：

100000000000000000000.log   1045229   # 已 roll，可被 retention 刪
200000000000000001024.log   1046336   # 已 roll
300000000000000002048.log   1046336   # 已 roll
400000000000000003072.log   1046336   # 已 roll
500000000000000004096.log   1037748   # 已 roll
600000000000000005112.log    904737   # active segment，不會被刪

Retention 的實際刪除動作由背景執行緒週期性執行、頻率是 broker 層的 log.retention.check.interval.ms、預設 300000 毫秒（5 分鐘）。這代表「過期」跟「被刪」之間有最長一個檢查週期的延遲：訊息超過 retention.ms 的瞬間不會立刻消失、要等下一次檢查跑到、且該訊息所在的 segment 已經 roll over、整段才會被刪。實機把 retention.bytes 設成 2 MB、寫進 6 MB（6 個 segment）、在 5 分鐘檢查週期內查 earliest offset 仍是 0——超量的 segment 還沒被回收、因為檢查執行緒還沒跑到下一輪。

這個機制有兩個操作後果。其一、磁碟用量會在「超過 retention 上限」到「下一次檢查」之間短暫超標、容量規劃要把這段 overshoot 算進緩衝。其二、把 retention.ms 設得比 segment.ms 還短沒有意義：訊息要等所在 segment roll 才可能被刪、active segment 永遠刪不掉、所以實際最短保留時間是 max(retention.ms, segment 尚未 roll 的時間)。

cleanup.policy：delete 與 compact 是兩種回收語意

cleanup.policy 決定 retention 用哪種語意回收空間、是保留策略最關鍵的分岔。預設值 delete 是時間或容量到期就整段刪除、適合事件流（event stream）：訊息代表「發生過的事實」、過了 replay window 就沒有保留價值。另一個值 compact 是 log compaction、語意完全不同：它保留每個 key 的最新值、刪除同 key 的歷史版本、適合「狀態快照」型資料。

兩者的判準是這份 log 表達的是「事件序列」還是「最終狀態」。訂單建立、付款完成、商品瀏覽這類事件、每一筆都是獨立事實、用 delete；使用者個人設定、商品庫存當前值、CDC 同步出來的資料表鏡像這類「同一個 key 不斷被覆寫、只關心最新值」的資料、用 compact。Kafka 內部的 __consumer_offsets topic 就是 compact——它只需要每個 consumer group 的最新 offset、不需要歷史 commit 記錄。

兩者可以同時開（cleanup.policy=compact,delete）：先按 key 壓縮保留最新值、同時對壓縮後的結果再套時間 / 容量上限。用 kafka-configs.sh 切換時、逗號分隔的值要用中括號群組、否則會被解析成兩個獨立 config：

1kafka-configs.sh --alter --entity-type topics --entity-name ret-delete \
2  --add-config 'cleanup.policy=[compact,delete]' \
3  --bootstrap-server localhost:9092
4# Completed updating config for topic ret-delete.
5# describe: cleanup.policy=compact,delete

Log compaction 用最新值取代歷史

Log compaction 的核心責任是讓一個 topic 收斂成「每個 key 的最新狀態」、同時保有 Kafka 的 log 重播能力。它的運作方式是背景的 log cleaner 執行緒掃描已 roll 的 segment、對每個 key 只保留 offset 最大的那筆、把同 key 的舊版本標記移除、再把存活的記錄重寫成新 segment。Compaction 後、新加入的 consumer 從頭讀一次、拿到的就是整個 keyspace 的最新快照、而非完整變更歷史。

實機驗證最直接：建一個 compact topic、對 3 個 key 各寫 2 個版本（舊值在前、新值在後）、等 compaction 跑完、從頭消費：

 1kafka-topics.sh --create --topic ret-compact --partitions 1 \
 2  --config cleanup.policy=compact \
 3  --config min.cleanable.dirty.ratio=0.01 \
 4  --config segment.ms=5000 \
 5  --config delete.retention.ms=100 \
 6  --bootstrap-server localhost:9092
 7
 8# 寫 k1/k2/k3 各舊值一筆、再各新值一筆（key:value 用冒號分隔）
 9printf 'k1:v1-old\nk2:v1-old\nk3:v1-old\nk1:v2-new\nk2:v2-new\nk3:v2-new\n' | \
10  kafka-console-producer.sh --topic ret-compact \
11  --property parse.key=true --property key.separator=: \
12  --bootstrap-server localhost:9092
13
14# 等 segment roll + compaction，再從頭消費
15kafka-console-consumer.sh --topic ret-compact --from-beginning \
16  --property print.key=true --property print.offset=true \
17  --timeout-ms 6000 --bootstrap-server localhost:9092
18# Offset:3  k1  v2-new
19# Offset:4  k2  v2-new
20# Offset:5  k3  v2-new

寫進 6 筆、從頭只讀到 3 筆——k1/k2/k3 的 v1-old（offset 0-2）被壓縮移除、只留每個 key 的 v2-new。關鍵細節：offset 沒有重新編號、留存記錄保留原始 offset（3、4、5）、log 的位置語意不變、其他 consumer 的 offset 進度不會錯位。

Compaction 的觸發不是即時的、由幾個參數共同決定。min.cleanable.dirty.ratio 是「髒比例」門檻、髒記錄（已被新版本取代但還沒清掉的舊版本）佔 log 比例超過這個值、cleaner 才會處理該 partition、預設 0.5（驗證時調成 0.01 加速觸發）。segment.ms 控制 active segment 多久 roll、只有 roll 過的 segment 能被 compact。delete.retention.ms 控制 tombstone（value 為 null 的刪除標記）保留多久——compaction topic 用 null value 表示「這個 key 已刪除」、tombstone 要保留夠久讓所有 consumer 都讀到刪除事件、之後才清掉。

Tombstone 是 compaction 表達「刪除」的方式：寫一筆 key 存在、value 為 null 的記錄、compaction 會把該 key 的所有歷史連同這筆 tombstone 在 delete.retention.ms 之後一起清除。這讓 compact topic 能表達「key 從存在到被刪」的完整生命週期、而不只是「永遠累積最新值」。

Tiered Storage 讓容量與保留期解耦

以下 tiered storage 段落依 Apache Kafka 官方文件（KIP-405）與 Pinterest / LinkedIn 公開案例敘述、未在本文的 KRaft 單節點環境實機驗證。Apache Kafka 的原生 tiered storage（remote.storage.enable）在當前版本屬 early-access、需要額外的 RemoteStorageManager plugin 與 broker 設定；正式採用前以官方文件版本標註為準。

Tiered storage 的核心責任是把 broker 的「儲存容量」跟「保留期長度」解耦。傳統 Kafka 的保留期受限於 broker 本機磁碟：想保留 30 天、就得讓每個 broker 的 local disk 容納 30 天的全量資料、retention 拉長等於 broker 數量或單機磁碟線性增長、而 broker 的 CPU / 記憶體 / 網路其實沒用到那麼多。Tiered storage 把 log 分成兩層：熱資料（近期、頻繁讀）留在 broker local disk（local tier）、冷資料（過期門檻之外、偶爾 replay）卸載到遠端物件儲存如 S3（remote tier）。Broker 只需放得下熱資料、保留期可以拉到數月甚至更久、成本變成 S3 的物件儲存費而非 broker 機群。

分層的觸發由 local.retention.ms / local.retention.bytes（本機保留多久 / 多大、超過就卸到 remote）跟整體的 retention.ms / retention.bytes（含 remote 的總保留邊界、超過才真正刪除）共同界定。一筆訊息的生命週期變成：寫入 local tier、超過 local retention 卸到 remote tier、超過整體 retention 從 remote 刪除。Replay window 因此可以遠大於 broker local disk 容量。

讀取路徑分熱冷兩條、效能特性不同。Consumer 讀近期 offset、資料在 local tier、走的是 Kafka 一向的 page cache + 順序讀路徑、低延遲高吞吐。Consumer 讀很舊的 offset（例如出事後從幾週前重播）、資料在 remote tier、broker 要先從 S3 把對應 segment 拉回來才能 serve、第一次讀的延遲明顯高於熱路徑、吞吐受 S3 頻寬與 broker 拉取並行度限制。這個熱冷讀差異是 tiered storage 的核心取捨——也是故障演練要處理的場景。

業界對 tiered storage 有兩條不同的工程路線、對應不同的 broker 角色定位：

Pinterest 的 broker-decoupled 做法把 ~200 TB/day 熱資料卸到 S3、讓 consumer 直接從 S3 拉冷資料、broker 不再是冷讀的熱路徑。它揭露的設計判讀是「broker 運算資源」跟「跨 AZ 網路成本」其實該分開治理、而不是綁在 broker 容量擴張上——保留期變長不該等於 broker 機群變大。

LinkedIn 的分層叢集策略是另一個層次的「分層」：把不同業務特性與可靠性需求的 workload 拆到不同叢集（依關鍵程度分群、例如關鍵 / 一般 / 實驗性，分層名稱為示意而非案例原文用詞）、避免混在同一叢集時故障與資源競爭互相放大。這裡的「分層」指叢集隔離、不是儲存的冷熱分層。兩種「分層」常被混談、但解的是不同問題：tiered storage 解單一 topic 的儲存成本、tiered clusters 解多 workload 的隔離治理。

故障演練

Retention 太短、replay window 不夠補事故

徵兆：下游 consumer 出 bug、產出錯誤的衍生資料、幾天後才被對帳發現；要從原始事件重播修復時、發現最舊的事件已經被刪、replay 從某個時間點之後才有資料、之前的修不回來。

根因：retention.ms 設得比「事故從發生到偵測到開始修復的最長時間」短。Replay window 由 broker retention 與 consumer checkpoint 共同界定、retention 是其物理上限；偵測延遲一旦超過 retention、要補算時原始事件已過期。常見的隱性誘因是把 retention 按「正常 consumer 跟得上的進度」來設（例如 consumer 通常落後幾分鐘、就設 1 天保險）、卻沒按「最壞情況下多久才會發現問題」來設。

修法：

1. 把 retention.ms 對齊事故偵測到修復的最長時間、而非 consumer 正常落後量；對帳 / 審計類 pipeline 的偵測週期常以天計、retention 要跟著拉到對應天數。
2. 對「偵測延遲可能很長」的關鍵 topic、在下游另留可重算的來源（資料庫快照、上游 source of truth）、不把 Kafka retention 當唯一補償依據。
3. 用 kafka-configs.sh --alter 動態延長 retention 是即時生效的、但只對「還沒被刪」的訊息有用——已刪的救不回來；所以調整要趁事故升級前、發現偵測週期被低估的當下就改、不是等出事才改。
4. Replay 邊界對齊見 3.7 Event Contract 與 Replay Boundary：replay 要能指定 time range、超出 retention 的 time range 直接無效。

Compaction 開了、磁碟卻沒回收

徵兆：topic 設了 cleanup.policy=compact、預期同 key 舊版本會被清掉、磁碟用量卻持續上漲、--describe 看 partition log 一直變大；從頭消費仍讀到大量同 key 的歷史版本。

根因：compaction 觸發條件沒滿足。log cleaner 只處理已 roll 的 segment、active segment 永遠不壓縮；min.cleanable.dirty.ratio 預設 0.5、髒比例沒到一半 cleaner 不動手；如果寫入集中在少數 key、active segment 遲遲不 roll（segment.bytes / segment.ms 都沒到）、髒記錄全積在 active segment 裡、compaction 看不到它們。另一個常見原因是 broker 的 log cleaner 執行緒數（log.cleaner.threads）不足以跟上高寫入量、cleaner backlog 累積。

修法：

1. 確認 active segment 會適時 roll：對寫入量不大但需要及時壓縮的 topic、設 segment.ms（例如數小時）強制 roll、讓髒記錄離開 active segment 進入可壓縮範圍。
2. 視壓縮急迫度調 min.cleanable.dirty.ratio：要更積極壓縮就調低（驗證時用 0.01）、但調太低會讓 cleaner 頻繁重寫 segment、增加 I/O——這是壓縮及時性跟 cleaner 開銷的取捨。
3. 監控 cleaner backlog：看 broker 的 log-cleaner 相關 metric、backlog 持續成長代表 cleaner 執行緒不夠、加 log.cleaner.threads。
4. 確認沒有把 compact 用在「其實該 delete」的事件流上——事件流每筆 key 多半唯一、compaction 沒有舊版本可壓、磁碟自然不會降；那種情況該用 delete 加 retention。

Cold tier 讀延遲拖垮 replay

徵兆：開了 tiered storage、平時讀近期資料正常、一旦發起從幾週前的舊 offset 大規模 replay、consumer 的吞吐驟降、p99 拉取延遲飆高、broker S3 拉取頻寬打滿、同 broker 上其他正常 consumer 也跟著受影響。

根因：舊 offset 的資料在 remote tier、每次讀要先從 S3 把 segment 拉回 broker、第一次冷讀延遲遠高於 local tier 的順序讀。大規模 replay 等於一次要從 S3 拉大量冷 segment、S3 頻寬與 broker 拉取並行成為瓶頸；broker-coupled 架構下這些拉取流量全經過 broker、會排擠到熱路徑的正常服務。

修法：

1. 把大規模冷 replay 排到低流量時段、避免跟線上熱路徑爭 broker 資源與 S3 頻寬。
2. 控制 replay 的並行度與範圍：依 replay boundary 指定 time range / tenant / partition、分批拉冷資料、不要一次全量回放整個保留期。
3. 評估 broker-decoupled 架構（如 Pinterest 做法）：consumer 直接從 S3 拉冷資料、把冷讀流量從 broker 熱路徑移開、保護線上服務。
4. 容量規劃把「冷讀延遲」算進 RTO：replay window 拉很長能補很久以前的事故、但補的速度受 cold tier 吞吐限制、事故修復時間估算要把這段拉取時間算進去。

retention.bytes 在高流量時段提早刪

徵兆：retention.ms 明明設了 7 天、某次流量突增後、consumer 卻發現幾小時前的事件就已經被刪、replay 拿不到本該還在的資料；earliest offset 在沒人預期的時候大幅前移。

根因：retention.ms 與 retention.bytes 同時設時是「誰先觸發誰生效」。流量突增讓 partition log 在遠不到 7 天時就撞到 retention.bytes 容量上限、容量軸先觸發、舊 segment 被提前刪除——時間軸的 7 天承諾在高流量下失效。常見於「按平均流量估容量上限、卻遇到尖峰流量」、或多個 topic 共享磁碟時為了保護磁碟把每 topic 容量上限壓得偏低。

修法：

1. 釐清這個 topic 的保留承諾是時間還是容量主導：以 replay window 為準的關鍵 topic、容量上限要按「尖峰流量 × 保留天數」估、而非平均流量、否則尖峰時容量軸會偷走時間承諾。
2. 監控 earliest offset 與 log 大小的變化率：earliest offset 在非預期時間前移、就是 retention.bytes 提前觸發的訊號、加進告警。
3. 要硬保證時間保留、就把 retention.bytes 設成 -1（不限容量、純時間軸）、改用獨立的磁碟告警與容量規劃來防磁碟塞爆、而不是用 retention.bytes 兼做兩件事。
4. 評估 tiered storage：把保留壓力從 broker local disk 移到 remote tier、local 只留熱資料、就不必為了保護 broker 磁碟而把 retention.bytes 壓低、時間承諾不再被容量上限侵蝕。

容量與成本

實務 default：

• 事件流 topic 用 delete、retention.ms 對齊事故偵測到修復的最長時間、retention.bytes 設 -1 或按尖峰流量估、不讓容量軸偷走時間承諾。
• 狀態快照 / CDC 鏡像 topic 用 compact、確認 active segment 會適時 roll、監控 cleaner backlog。
• 需要長保留期（數月以上）且 broker 磁碟成本敏感時、評估 tiered storage、把冷資料移到 S3、broker 只放熱資料。
• 任何 retention 調整前先確認當前生效層級（kafka-configs.sh --describe 看 synonyms）、避免 broker 預設與 topic 動態配置混淆。

整合與下一步

跟 replay 邊界對齊

Retention 是 replay window 的物理上限、但 replay 能不能正確執行還要看 event contract 是否齊備（event id / schema version / occurred time / dedup key）。保留策略設計要跟 3.7 Event Contract 與 Replay Boundary 一起看：retention 決定「能不能讀到」、event contract 決定「讀到了能不能正確重播」、兩者缺一 replay 都不成立。相關概念見 retention 與 offset 知識卡。

跟分層叢集治理對位

本文的 tiered storage 解的是單一 topic 的儲存成本；3.C4 LinkedIn 分層叢集解的是多 workload 的隔離——把不同可靠性需求的 topic 拆到不同叢集、避免資源競爭互相放大。保留策略在分層叢集裡會按層差異化：critical 叢集拉長 retention 保 replay、experimental 叢集縮短 retention 控成本。

跟 broker-decoupled 架構的取捨

3.C11 Pinterest broker-decoupled tiered storage 把冷讀流量從 broker 熱路徑移開、是「cold tier 讀延遲拖垮 replay」故障演練的架構級解法；它跟 3.C12 Pinterest Shallow Mirror 揭露的「跨區同步是 CPU + memory + 網路三維壓力」一起、構成 Pinterest 在儲存與複製兩條路徑上的成本治理。

回上游

• 上游 vendor 頁：Apache Kafka（「Tiered storage」與「Cross-region 與分層叢集」段）
• 平行 deep article：consumer rebalance 與 lag 診斷 / replication、ISR 與 exactly-once（同 vendor 其他實作層議題）
• 下游能力：3.4 consumer 設計 / 6.12 idempotency / replay

本文是 Apache Kafka overview「KRaft 與 Schema Registry」段的 implementation-layer deep article。Overview 已交代 Schema Registry 在事件總線中的定位；本文聚焦 怎麼設 compatibility、wire format 長什麼樣、schema 怎麼安全演進、演進設錯會打掛什麼。對應 Event Schema Compatibility 知識卡的 implementation 展開。

為什麼事件總線需要一個獨立的 schema 治理元件

Schema Registry 是把「event 的結構契約」從 producer 與 consumer 的程式碼裡抽出來、集中存放並強制版本相容性的元件。它承擔的責任是讓不同 service、不同部署節奏的 producer 與 consumer 在 schema 改版時仍能互通，而不需要全體同時上線。Kafka broker 本身只存 bytes、不理解 payload 結構；一旦多個團隊往同一個 topic 寫事件、又各自獨立發版，schema 漂移就會在 consumer 端炸開。

這個責任在單一 service 內部不存在。一個 service 自己 produce、自己 consume，schema 改版同一個 deploy 就同步了，序列化用什麼格式都行。Schema Registry 解的是 跨 service、跨團隊、跨部署時間 的契約問題：A 團隊升級了訂單事件加一個欄位，B 團隊的對帳服務還跑舊版 consumer，C 團隊的風控服務跑更舊版——三方不同步演進，靠的就是 registry 在 producer 註冊新 schema 時先擋下破壞相容性的改動。

Yelp 的 Schematizer 案例 把這個責任拉到極端：一天數十億訊息、數百個 service、數千個 schema，自建 registry 強制所有 message 走 Avro、訊息只帶 schema ID。它揭露 schema 治理是 data pipeline 的核心責任、不是 add-on——當規模到了數千 schema，沒有集中強制的相容性檢查，跨服務事件契約會在某次發版後悄悄斷掉，而 broker 不會報任何錯。

Confluent Schema Registry 是業界事實標準的實作；Apicurio 是 CNCF 生態的開源替代，額外支援 OpenAPI / AsyncAPI artifact、且提供 Confluent-compatible API endpoint，遷移成本低。兩者都把 schema 存進一個 Kafka topic（Confluent 用 _schemas，single-partition、compacted），registry 自己是無狀態的，掛掉重啟後從該 topic rebuild。

Schema ID 嵌進訊息的 wire format

Confluent wire format 在每筆訊息的 value（或 key）前面加 5 個 byte：1 個 magic byte（固定 0x00）加 4 個 big-endian byte 的 schema ID，後面才接序列化後的 payload。Consumer 拿到訊息先讀這 5 個 byte，用 schema ID 去 registry 查對應 schema，再用該 schema 反序列化。這是「訊息只帶 schema ID、不帶 schema 本體」的機制——schema 本體只在 registry 存一份，訊息裡放的是指標。

本文用 OrbStack 起 confluentinc/cp-kafka + confluentinc/cp-schema-registry，用 Avro console producer 寫一筆 {"id":1,"name":"alice"}，再 dump 出 raw bytes 驗證 wire format：

1000000 00 00 00 00 01 02 0a 61 6c 69 63 65 0a   >.......alice.<

逐 byte 拆解：

• 00：magic byte，標識這是 Confluent wire format
• 00 00 00 01：4-byte big-endian schema ID = 1，consumer 拿這個去 registry 查 schema
• 02：Avro 把 id（long）以 zigzag varint 編碼，1 編成 0x02
• 0a 61 6c 69 63 65：name（string）長度 5（zigzag 0x0a）加 UTF-8 的 alice

這個格式有兩個工程後果。第一，consumer 反序列化任何訊息前都要能連到 registry——registry 掛掉，已 cache schema ID 的 consumer 還能跑，但遇到沒見過的 schema ID 就卡住。第二，schema ID 是全域單調遞增的整數、跨 subject 共用：同一份 schema 被多個 topic 註冊只會有一個 ID。實機驗證可以看到，先註冊到 user-value 的 schema 拿到 id:1，之後用同樣結構寫 users-demo topic 時，registry 認出是同一份 schema、複用 id:1：

1{"subject":"users-demo-value","version":1,"id":1,"schemaType":"AVRO", ...}

version 是 subject 內的序號（每個 subject 從 1 開始）、id 是全域的。除錯時看到某筆訊息反序列化失敗，第一步就是讀那 4-byte schema ID、去 registry 撈出它指向哪個 schema、跟 consumer 預期的對不對。

序列化格式取捨：Avro、Protobuf、JSON Schema

Schema Registry 支援三種格式，差異不只是語法、而是演進規則與生態的取捨。

Avro 的演進靠 reader schema 與 writer schema 分離：訊息用 writer schema（寫入時的版本）序列化，consumer 用自己的 reader schema（讀取時的版本）反序列化，registry 提供兩者做 schema resolution。這是 Avro 在 data pipeline 場景的核心優勢——欄位帶 default 時，舊資料用新 schema 讀會自動填 default，新資料用舊 schema 讀會自動忽略多出來的欄位。Yelp、多數 Kafka-native data platform 都選 Avro，正是因為它的演進語意最完整。

Protobuf 用 field number 而非欄位名做 wire 識別：欄位改名不破壞相容性（number 沒變即可），刪欄位要 reserve 掉 number 避免重用。已經用 gRPC 的團隊讓 RPC 與事件共用同一份 .proto，省一套 schema 維護。代價是 Protobuf 的 default 語意較弱（proto3 沒有 explicit presence 的 scalar 一律有 zero value），某些演進判斷不如 Avro 直觀。

JSON Schema 適合既有系統已經大量用 JSON、且看重人類可讀與 validation keyword（required、minimum、pattern）的場景。代價是 payload 較大（欄位名重複出現在每筆訊息）、型別保證弱於前兩者。當吞吐量大、payload size 敏感時，JSON Schema 的頻寬成本會顯著高於 Avro 的 binary 編碼。

選型判準：data pipeline 為主、重演進安全 → Avro；已有 gRPC、RPC 與事件共用 → Protobuf；既有 JSON 生態、重可讀性而吞吐量不極端 → JSON Schema。三者可在同一個 registry 並存（每個 subject 各自標 schemaType），但同一個 subject 內不能混用格式。

Subject naming strategy 決定相容性檢查的邊界

Subject 是 registry 裡做版本管理與相容性檢查的基本單位；naming strategy 決定「哪些 schema 被歸進同一個 subject、因而要互相相容」。選錯 strategy 會讓相容性檢查管太寬或太窄，是後面故障演練的根源之一。

TopicNameStrategy 是預設，subject 名就是 <topic>-value。實機驗證可以看到，用 Avro producer 寫 users-demo topic 時，registry 自動建立 users-demo-value subject：

1["user-value","users-demo-value"]

預設策略的隱含假設是「一個 topic 只承載一種事件型別」。這對多數 topic 成立，但當業務要把多種相關事件（例如 OrderCreated 與 OrderCancelled）放進同一個 topic 以保證跨事件 ordering 時，TopicNameStrategy 會把兩種 record 當成同一個 subject 的版本演進、互相做相容性檢查——這幾乎一定失敗，因為兩種事件結構本來就不同。

這時要改 RecordNameStrategy（subject = record 全名，跨 topic 同名 record 共用一份演進歷史）或 TopicRecordNameStrategy（subject = topic + record 名，同 topic 多型別各自獨立演進）。判準：一個 topic 一種事件 → 預設即可；一個 topic 多種事件且要保 ordering → TopicRecordNameStrategy；同一種 record 散在多個 topic 要強制全域一致 → RecordNameStrategy。Producer 與 consumer 必須設成同一個 strategy，否則 consumer 會用錯 subject 去查 schema。

Compatibility level：四種基礎 × transitive

Compatibility level 是 registry 在 producer 註冊新 schema 時套用的相容性規則，決定哪些 schema 改動會被擋下。它回答的問題是「新 schema 跟既有 schema 比，誰應該能讀誰寫的資料」。設定可以是全域預設、也可以 per-subject 覆寫。

BACKWARD 是 Confluent 預設，實機驗證可以確認：

1{"compatibilityLevel":"BACKWARD"}

BACKWARD 保護的是「consumer 先升級」的演進順序——新版 consumer 必須能讀舊版 producer 還在寫的舊資料。它允許的安全改動是「加帶 default 的欄位」與「刪欄位」：新 schema 讀舊資料時，舊資料缺的新欄位用 default 補；新 schema 不要的欄位讀舊資料時忽略。它擋下的是「加沒有 default 的必填欄位」——舊資料沒這欄位、新 consumer 又要求它存在，就讀不出來。

FORWARD 反過來保護「producer 先升級」：舊版 consumer 要能讀新版 producer 寫的資料。它允許「刪帶 default 的欄位」與「加欄位」。當演進順序是 producer 先上、consumer 慢慢跟（例如先讓 producer 開始寫新欄位、consumer 之後才用）時選 FORWARD。

FULL 同時滿足兩者，代價是只能做「加帶 default 的欄位」與「刪帶 default 的欄位」這類雙向安全的改動，演進自由度最低但最安全。當 producer 與 consumer 的升級順序無法協調（大型組織、多團隊各自排程）時，FULL 把演進約束到怎麼改都不會斷。

四種各有一個 transitive 變體（BACKWARD_TRANSITIVE 等）。非 transitive 只檢查新 schema 對 最近一版；transitive 檢查新 schema 對 該 subject 所有歷史版本。差別在這個場景：v1 → v2 相容、v2 → v3 相容，但 v3 對 v1 不相容。非 transitive 會放行 v3（因為只比 v2）；transitive 會擋下。當 consumer 可能 replay 很舊的歷史資料（Kafka 的長期保留 + replay 正是常態），transitive 才能保證任何歷史版本都讀得出來。3.7 event contract / replay boundary 講的 replay 邊界，在 schema 層的對應就是 transitive compatibility。

安全演進規則：實機驗證註冊與拒絕

把上面的規則落到實際操作。在預設 BACKWARD 下，註冊 v1（id + name）後，加一個帶 default 的 email 欄位是安全的，registry 接受並記為 v2：

1{"id":2,"version":2,"schemaType":"AVRO", ...}

user-value 的版本列表確認累積成兩版：

1[1,2]

接著嘗試加一個 沒有 default 的 age（int）必填欄位——這破壞 BACKWARD，因為新 consumer 讀舊資料時 age 沒值也沒 default。registry 回 HTTP 409 並指出確切原因：

1{"error_code":40901,"message":"Schema being registered is incompatible with an earlier schema for subject \"user-value\", details: [{errorType:'READER_FIELD_MISSING_DEFAULT_VALUE', description:'The field 'age' at path '/fields/3' in the new schema has no default value and is missing in the old schema', ...}], compatibility: 'BACKWARD'}

READER_FIELD_MISSING_DEFAULT_VALUE 精確命中規則：reader（新 schema）多了一個舊資料沒有、又無 default 的欄位。registry 另外提供 compatibility check API，可以在不真正註冊的前提下先問「相不相容」，給 CI pipeline 在 PR 階段擋下破壞性改動：

1{"is_compatible":false}

由此導出兩條安全演進的操作規則。加欄位：一律帶 default（BACKWARD / FULL 都要），舊資料才能用新 schema 讀出。沒有合理 default 的「必填新欄位」不能直接加——要嘛在 producer 端先全部開始寫該欄位、確認資料齊全後再 promote，要嘛走新 topic / 新 record 而非原地演進。刪欄位：分步做。先讓所有 consumer 停止依賴該欄位（部署一輪），確認沒人讀之後，下一輪才從 schema 拿掉。一步到位刪掉還在被讀的欄位，會在 FORWARD / FULL 下被擋、在 BACKWARD 下放行但打掛還沒升級的 consumer。

Production 故障演練

Case 1：producer 加必填欄位無 default，打掛舊 consumer

徵兆：某團隊 producer 發版後，另一團隊的舊 consumer 開始大量反序列化失敗、SerializationException 或 AvroTypeException: Found X, expecting Y，consumer lag 暴衝、訊息卡在 poll 階段。producer 端與 broker 端完全沒報錯——訊息照寫成功。

根因：subject 的 compatibility level 被設成 NONE（或該欄位走了 FORWARD 不檢查 reader 缺欄位的路徑）。producer 加了一個沒有 default 的必填欄位、registry 沒擋，新訊息帶新 schema ID 寫進 topic。舊 consumer 用自己的舊 reader schema 去反序列化新 writer schema 的資料，遇到自己不認識又無從補值的結構就炸。問題不在 producer 也不在 broker，在 registry 沒在註冊時擋下這次演進。

修法：

1. 把 compatibility level 改回至少 BACKWARD：實機驗證過 NONE 會直接放行破壞性 schema——把 compatibility 設成 NONE 後，前面被 409 拒絕的破壞性 schema 立刻被接受成 v3。NONE 等於把演進安全完全交給人，多團隊場景幾乎一定出事。
2. 回退 producer：先讓 producer 退回舊 schema 止血，恢復舊 consumer 可讀。
3. 重新演進：欄位帶 default 重發，或若該欄位語意上必填、走「先讓 producer 寫、consumer 升級、再 promote」的分步路徑。
4. CI 防線：把 compatibility check API（/compatibility/subjects/<s>/versions/latest）接進 producer repo 的 CI，PR 階段就用 is_compatible:false 擋掉，不等到 production 註冊時才發現。

Case 2：compatibility level 設錯，放行破壞性變更

徵兆：team 以為有 registry 把關所以放心演進，某次刪掉一個還在被下游讀的欄位、registry 接受了，下游服務隔天開始拿到 null / 缺欄位、business logic 走錯分支，但沒有任何 exception——資料「看起來正常」只是少了東西。

根因：compatibility level 設成了 FORWARD 而需求其實是 BACKWARD，或設成 NONE。實機驗證可以看到 per-subject 覆寫的行為——對 user-value 單獨 PUT FORWARD 後查 config 回 {"compatibilityLevel":"FORWARD"}，這個 subject 的檢查方向就跟全域預設不同了。FORWARD 允許刪帶 default 的欄位（保護 producer 先升級的順序），但團隊實際的演進順序是 consumer 後升級——方向錯配，registry 放行的正是會打掛 consumer 的那類改動。

修法：

1. 依演進順序選 level，不是隨手設：consumer 先升級選 BACKWARD；producer 先升級選 FORWARD；順序無法協調選 FULL。把這個決策寫進 topic ownership 文件、不是留給註冊當下的人臨時判斷。
2. 可能 replay 歷史就用 transitive：Kafka 長期保留 + replay 是常態，非 transitive 只擋最近一版、replay 舊資料時舊 schema 仍可能讀不出。長期保留的 topic 預設用 *_TRANSITIVE。
3. per-subject 覆寫要留審計：全域預設外的每一個 per-subject 覆寫都是一個風險點，要能查出「誰、何時、為什麼把這個 subject 改成跟預設不同」。

Case 3：schema ID 對不上，consumer 反序列化失敗

徵兆：consumer 報 Schema not found; error code: 40403 或反序列化拿到亂碼、欄位錯位。某些訊息正常、某些失敗，跟特定 producer 或特定時間段相關。

根因有幾種，靠讀訊息前 5 byte 的 schema ID 定位：

• registry 換過、ID 不一致：跨環境（dev / staging / prod）各自一套 registry，schema ID 全域遞增的順序不同，同一份 schema 在不同環境是不同 ID。如果有人把 prod 的訊息 mirror 到 staging 而沒搬 schema，staging consumer 拿 prod 的 schema ID 去 staging registry 查就 404。
• 訊息根本不是 Confluent wire format：有 producer 沒走 schema-aware serializer、直接寫 raw bytes，前 5 byte 不是 magic + ID。consumer 把第一個 byte 當 magic、後 4 byte 當 ID 去查，撈到不存在或錯誤的 schema。
• registry 不可達或 cache 失效：consumer 端 schema cache 沒命中、又連不上 registry。

修法：

1. 讀 wire format 確認：dump 訊息 raw bytes，確認第一個 byte 是 00、接下來 4 byte 解出來的 ID 在目標 registry 查得到。本文驗證過 00 00 00 00 01 對應 schema id 1，這是除錯的第一手證據。
2. 跨環境 schema 搬遷：mirror 訊息時用 registry 的 import / export，或 MirrorMaker 搭配 schema 同步，不要只搬資料不搬 schema。
3. 隔離非 schema-aware producer：用 ACL 或 topic 命名規範強制所有 producer 走 schema serializer，避免 raw bytes 混進 schema-managed topic。

Case 4：subject naming strategy 衝突

徵兆：把第二種事件型別寫進既有 topic 時，producer 直接註冊失敗報 incompatible，或多 producer 寫同 topic 互相把對方的 schema 判成不相容、彼此發版互相擋。

根因：用 TopicNameStrategy（預設）卻往同一個 topic 放多種 record。subject 是 <topic>-value、整個 topic 共用一條演進線，registry 拿 OrderCancelled 去跟既有的 OrderCreated 做相容性檢查——兩種結構不同的事件當然不相容。strategy 的隱含假設（一 topic 一事件型別）跟實際用法（一 topic 多事件保 ordering）衝突。

修法：

1. 改 strategy 配合用法：一 topic 多事件 → TopicRecordNameStrategy，subject 變成 <topic>-<record 全名>，每種 record 各自一條演進線、不互相檢查。
2. producer 與 consumer 設同一個 strategy：strategy 不一致時 consumer 會用錯 subject 查 schema，拿到 null 或錯 schema。這是部署層的硬約束，要在共用 config 統一。
3. 若只是不小心寫錯 topic：那不是 strategy 問題、是路由問題，修 producer 的 topic 選擇邏輯，別為了繞過檢查改成 RecordNameStrategy。

容量與運維邊界

實務 default：data pipeline 場景選 Avro + 至少 BACKWARD；長期保留 + replay 的 topic 用 transitive；compatibility check 接進 CI 在 PR 階段擋破壞性改動，不依賴註冊當下把關；一 topic 一事件型別當預設、要多型別才動 naming strategy。Schema Registry 自己也是個要 HA 的元件——production 跑多副本、_schemas topic 的 replication factor 拉高，registry 是事件總線的單點時要當關鍵基礎設施對待。

整合與下一步

跟 CDC pipeline 的銜接

Shopify Debezium CDC 案例 跑在 100+ MySQL shard、150 個 Debezium connector 的規模（該案例記載的重點是 lock-free snapshot 與 oversized record 處理）。CDC pipeline 有一個一般性的 schema 演進壓力，以下依 CDC 機制推導、非該案例的結論：上游 DDL 一改，Debezium 產生的 Kafka record schema 跟著變，下游 consumer 受影響。Schema Registry 的 compatibility 檢查就是把這道衝擊在進 Kafka 時攔下的關卡——選錯 compatibility level，一次 ALTER TABLE 就可能透過 CDC 打穿整條 pipeline。Debezium 與 Kafka Connect 原生整合 Schema Registry，connector 設定裡指定 registry URL 與 naming strategy。

跟 replay 邊界與事件契約

3.7 event contract / replay boundary 講的是事件契約能 replay 多遠；schema 層的對應就是本文的 transitive compatibility。Replay 跨越多個 schema 版本時，只有 transitive 能保證任何歷史版本都讀得出來。兩者一起界定「這條事件流的契約能安全回放到多久以前」。

下游能力

• 概念索引：Event Schema Compatibility 知識卡（本文的 implementation 來源）
• 上游 vendor 頁：Apache Kafka（KRaft 與 Schema Registry 段）
• 對應案例：3.C14 Yelp Schematizer（schema 治理拉到平台層）、3.C13 Shopify Debezium CDC（CDC 場景的 schema evolution）
• 方法論：Vendor 深度技術文章的寫作方法論

本文是 Apache Kafka overview「Multi-tenant 與配額治理」「Topic 生命週期治理」兩段的 implementation-layer deep article。Overview 說明這些議題對應哪些案例跟子議題、本文展開具體的 quota / ACL 配置、授權模型推導、故障徵兆與修法。

共享叢集的治理問題：一個叢集、多個互不信任的租戶

Multi-tenant Kafka 的核心問題是把一個物理叢集切成多個彼此隔離的邏輯空間、讓每個團隊用同一組 broker 卻不互相干擾。當 Kafka 從單一團隊的工具長成全公司的事件總線、叢集承載的不再是一條 pipeline、而是數十到數百個團隊的 producer 跟 consumer。這時叢集的瓶頸從「broker 夠不夠快」轉成「怎麼防止某個團隊的流量、權限、或 topic 失控波及其他所有人」。

Uber 的 Kafka 平台演進把這個轉換描述為「從單隊列問題提升到平台治理問題」。當事件平台服務眾多團隊、重點是配額、隔離、觀測與運維標準化、而非只擴 broker。擴 broker 解決的是總容量、解決不了「單一租戶吃光共享資源」這類隔離問題。

共享叢集的治理分三個獨立的軸、各自處理不同的失控來源：

三軸正交：quota 設好不代表權限對、ACL 鎖好不代表 topic 不會爆炸。下面逐軸展開、每軸都對應 production 踩過的失控場景。本文 quota 與 ACL 操作以 Kafka 4.2.0（KRaft 模式、apache/kafka:latest）實機驗證。

Quota：把頻寬與 request 容量切給租戶

Quota 是 broker 端對 client 的流量上限、由 broker 在超限時主動 throttle（延遲回應）而非拒絕、讓單一租戶無法把共享頻寬吃光。Kafka 的 quota 是 broker-side 強制、不依賴 client 自律 —— 即使 client 不配合、broker 也會在回應裡插入 throttle 延遲、把該 client 的有效吞吐壓回配額內。

三類 quota 度量

Kafka quota 度量三種資源、對應三類飽和：

前兩個 byte rate 防的是頻寬類飽和、適合「大訊息、穩定流量」的租戶。request_percentage 防的是另一種失控 —— 某租戶送大量極小的 request（例如每筆一個 byte、每秒幾萬筆）、byte rate 看起來很低、卻把 broker 的 request handler thread 佔滿。這種「請求數爆炸但流量不大」的攻擊型 pattern 只有 request_percentage 抓得到。一個 broker 預設有 N 個 request handler thread、request_percentage=200 代表允許該 client 用掉 2 條 thread 的時間（100% = 1 條）。

三種套用層級

Quota 可以套在三種 entity 上、精度遞增：

層級的選擇取決於認證模型。沒開認證的叢集只能用 client-id —— 但 client.id 由 client 自行宣告、可偽造、只適合內部信任環境的粗略區分。開了 SASL 認證後、user 才是可信的租戶邊界、quota 綁 user 才有隔離意義。最細的 user + client-id 組合用在「同一個租戶內、batch 匯入服務跟即時 API 服務要分開限流」這種情境：整個 billing 租戶有一個總配額、但裡面的 batch-importer 再單獨壓低、避免夜間批次把租戶配額吃光、害同租戶的即時服務沒頻寬。

設定與查詢（實機驗證）

設 client-id 層級、同時給 producer 跟 consumer byte rate：

1kafka-configs.sh --bootstrap-server localhost:9092 --alter \
2  --add-config 'producer_byte_rate=1048576,consumer_byte_rate=2097152' \
3  --entity-type clients --entity-name svc-orders
4# Completed updating config for client svc-orders.

設 user 層級、含 request_percentage：

1kafka-configs.sh --bootstrap-server localhost:9092 --alter \
2  --add-config 'producer_byte_rate=5242880,consumer_byte_rate=10485760,request_percentage=200' \
3  --entity-type users --entity-name tenant-billing
4# Completed updating config for user tenant-billing.

設 user + client-id 組合層級（同租戶內單獨壓低 batch 服務）：

1kafka-configs.sh --bootstrap-server localhost:9092 --alter \
2  --add-config 'producer_byte_rate=524288' \
3  --entity-type users --entity-name tenant-billing \
4  --entity-type clients --entity-name batch-importer
5# Completed updating config for user tenant-billing.

查詢時 entity 指定要對齊設定時的層級。查 user 層級：

1kafka-configs.sh --bootstrap-server localhost:9092 --describe \
2  --entity-type users --entity-name tenant-billing
3# Quota configs for user-principal 'tenant-billing' are
4#   consumer_byte_rate=1.048576E7, request_percentage=200.0, producer_byte_rate=5242880.0

組合層級要兩個 entity 都帶、否則查不到：

1kafka-configs.sh --bootstrap-server localhost:9092 --describe \
2  --entity-type users --entity-name tenant-billing \
3  --entity-type clients --entity-name batch-importer
4# Quota configs for user-principal 'tenant-billing', client-id 'batch-importer' are
5#   producer_byte_rate=524288.0

不帶 --entity-name 而只給 --entity-type clients 會列出所有 client-id 層級的 quota、適合稽核整個叢集的 quota 分布。

ACL：把存取權限綁到 principal

ACL 是 broker 對每個操作的授權檢查、把「誰（principal）能對什麼資源（resource）做什麼操作（operation）從哪裡來（host）」綁成一條規則、broker 在每次 produce / fetch / admin 操作前比對。Quota 管的是「用多少」、ACL 管的是「能不能用」—— 兩者正交、quota 不限制權限、ACL 不限制流量。

授權模型四要素

一條 ACL 由四個維度構成、四個維度交集才決定一次操作是否放行：

resource 的 pattern type 是隔離設計的關鍵：LITERAL 精確匹配單一資源名、PREFIXED 匹配整個前綴。多租戶的 topic 隔離靠 prefixed ACL 加命名規範 —— 給 tenant-billing 一條 billing. 前綴的 All 權限、它就能自由管理所有 billing. 開頭的 topic、卻碰不到 orders. 或別租戶的命名空間。命名規範在這裡不只是整潔、是授權邊界本身。

operation 的選擇要對齊角色。一個 producer 需要 topic 的 Write 跟 Describe（描述 partition metadata）；一個 consumer 需要 topic 的 Read Describe 加上 consumer group 的 Read Describe（commit offset 要對 group 有權）。漏掉 group 的 ACL 是常見錯誤：consumer 能讀到訊息、卻 commit 不了 offset、表現成不斷重複消費。

KRaft 的 StandardAuthorizer

ACL 的儲存與判定由 broker 的 authorizer 負責。KRaft 模式用 org.apache.kafka.metadata.authorizer.StandardAuthorizer、ACL 存在 metadata log（取代 ZooKeeper 時代的 AclAuthorizer 把 ACL 存在 ZK）。預設的 apache/kafka 容器不開 authorizer —— 不開時所有操作放行、ACL 指令也無從生效。啟用需要在 broker 設三項：

1authorizer.class.name=org.apache.kafka.metadata.authorizer.StandardAuthorizer
2super.users=User:admin
3allow.everyone.if.no.acl.found=false

super.users 列出繞過所有 ACL 檢查的管理身分、用來開機跟救援；少了它、開 authorizer 後第一個操作就會把自己鎖在外面。allow.everyone.if.no.acl.found=false 是隔離的前提 —— 設 true 時「沒有任何 ACL 的資源對所有人開放」、等於 deny-list 模式、漏設一個 topic 就全公司可讀。多租戶必須走 false 的 allow-list 模式：預設拒絕、明確授權才放行。

本文 ACL 操作以實機驗證：用上述三項 env（KAFKA_AUTHORIZER_CLASS_NAME / KAFKA_SUPER_USERS='User:ANONYMOUS' / KAFKA_ALLOW_EVERYONE_IF_NO_ACL_FOUND=false）配完整 KRaft single-node 設定起容器、PLAINTEXT 連線的 principal 為 User:ANONYMOUS、設為 super user 後即可用 kafka-acls.sh 操作。

ACL 配置（實機驗證）

給 producer 對單一 topic 的 write + describe：

1kafka-acls.sh --bootstrap-server localhost:9092 --add \
2  --allow-principal User:svc-orders \
3  --operation Write --operation Describe \
4  --topic orders.events

給 consumer topic 的 read + describe、外加 consumer group 的權限（一條指令同時建兩個 resource 的 ACL）：

1kafka-acls.sh --bootstrap-server localhost:9092 --add \
2  --allow-principal User:svc-fulfillment \
3  --operation Read --operation Describe \
4  --topic orders.events \
5  --group fulfillment-workers

prefixed ACL 把整個命名空間授權給一個租戶：

1kafka-acls.sh --bootstrap-server localhost:9092 --add \
2  --allow-principal User:tenant-billing \
3  --operation All \
4  --resource-pattern-type prefixed \
5  --topic billing.
6# Adding ACLs for resource
7#   `ResourcePattern(resourceType=TOPIC, name=billing., patternType=PREFIXED)`

host 限制把同一 principal 的權限綁到特定來源 IP：

1kafka-acls.sh --bootstrap-server localhost:9092 --add \
2  --allow-principal User:svc-orders \
3  --allow-host 10.0.3.21 \
4  --operation Write \
5  --topic orders.events

deny 規則的優先序高於 allow —— 同一 principal 即使有 allow、命中 deny 就拒絕。用來在大範圍 allow（如 prefixed All）之上挖一個例外：

1kafka-acls.sh --bootstrap-server localhost:9092 --add \
2  --deny-principal User:svc-orders \
3  --deny-host 10.0.9.99 \
4  --operation Write \
5  --topic orders.events

列出特定 topic 的全部 ACL、用於稽核：

1kafka-acls.sh --bootstrap-server localhost:9092 --list --topic orders.events

Topic 生命週期治理：命名、ownership 與回收

Topic 生命週期治理把「topic 的建立、歸屬、淘汰」變成有規則的流程、避免死 topic 累積與 partition 數爆炸壓垮叢集的 metadata 面。Kafka 的每個 partition 都是 controller 要追蹤的 metadata 單位；topic 只增不減時、partition 總數隨團隊數線性成長、最終 controller 的 metadata 處理、broker 的 leader election、client 的 metadata fetch 都跟著變慢。

命名規範劃出 ownership

Topic 命名規範把 ownership 跟隔離邊界編碼進名字本身。一個可治理的命名規範通常含三段：租戶 / 領域前綴、語意名、版本。例如 billing.invoices.v1 —— billing. 前綴對齊 prefixed ACL 的隔離邊界跟 quota 的租戶歸屬、invoices 是語意、v1 給 schema 演進留出平行存在的空間。命名規範在多租戶不是風格問題、是三個治理軸的共同錨點：ACL 靠前綴授權、quota 靠前綴歸屬、回收靠前綴找 owner。

實機建 topic 時 Kafka 4.2.0 對 . 跟 _ 混用會出 metric 名稱碰撞警告：

1WARNING: Due to limitations in metric names, topics with a period ('.')
2or underscore ('_') could collide. To avoid issues it is best to use
3either, but not both.

成因是 metric 名把 topic 名裡的 . 跟 _ 都正規化掉、billing.invoices 跟 billing_invoices 可能對映到同一條 metric。命名規範應在 . 跟 _ 之間選一個當分隔符、全叢集一致、避免監控數據互相污染。

活躍判準與自動回收

死 topic 的回收靠可量化的活躍判準。LinkedIn 的 TopicGC以自動治理取代手動清理未使用 topic、降低 metadata 壓力並改善 produce / consume 效能。它的判讀是：當 queue 規模擴大、僅靠容量擴充不夠、topic 生命週期與治理自動化會成為可靠性關鍵。

TopicGC 是 LinkedIn 的內部系統、不是 Kafka 內建指令；它揭示的是一套可借鏡的回收流程結構：

1. 定義活躍判準：以 last produce / last consume timestamp 判斷 topic 是否仍在使用、設一段觀察窗（例如 N 天無寫入且無讀取）。
2. 分級回收：先標記（soft）、進入待回收狀態並通知 owner、保留一段 grace period、無人認領才真正刪除（hard）。兩段式避免誤刪仍有低頻流量的 topic。
3. 保留稽核：每次標記與刪除留紀錄、回收前後比對 controller log、partition 數量、produce / consume 效能指標、確認治理有效且無誤傷。

回收條件的設定要對齊業務節奏。純看 produce timestamp 會誤判「低頻但關鍵」的 topic（如月結批次）；活躍判準要同時看 produce 跟 consume、且觀察窗要長於最長的合法閒置週期。

Production 故障演練

Case 1：單一租戶暴衝吃滿頻寬（quota 缺位）

徵兆：某團隊上線一支新 backfill job、開始全速寫入；同叢集其他租戶的 producer 端 request-latency p99 從個位數 ms 跳到數百 ms、consumer lag 全面上升；broker network out 打到網卡上限、但 CPU 不高。受害的不是暴衝者自己、是所有共用 broker 的鄰居。

根因：叢集沒設任何 producer quota、或只對部分租戶設了 quota。沒有 broker-side throttle 時、單一 client 能用滿 broker 的 network / disk I/O、把共享頻寬擠光。byte rate 飽和的特徵是 network 打滿但 CPU 不高 —— 區別於 request_percentage 缺位導致的 CPU 飽和。

修法：

1. 立即對暴衝 client 設 producer_byte_rate、broker 即時 throttle、無需重啟。
2. 建立 quota 預設值：對所有 client-id（或 user）設一個保守的 default byte rate、新租戶上線自動受限、避免「漏設就無限」。
3. 區分 byte rate 與 request_percentage 飽和：network 打滿設 byte rate、CPU 打滿（高頻小訊息）補 request_percentage。
4. 容量規劃：把各租戶 quota 總和對齊 broker 的 network / disk 容量、留 headroom、避免「每個 quota 都合理但加總超過物理上限」。

Case 2：ACL 設太鬆或太緊

徵兆（太鬆）：稽核發現某 consumer 服務能讀到不屬於它的租戶 topic；或某 topic 被預期外的 principal 寫入、資料被污染。最壞情況是 allow.everyone.if.no.acl.found=true 下漏設 ACL 的 topic 對全叢集可讀寫。

徵兆（太緊）：consumer 能讀訊息卻不斷重複消費、log 顯示 commit offset 被拒；或 producer 報 TOPIC_AUTHORIZATION_FAILED、明明該有權限。

根因：太鬆來自 deny-list 心態 —— allow.everyone.if.no.acl.found=true 把「沒設 ACL」當成「開放」、漏設就外洩。太緊通常是漏掉 operation 或 resource：consumer 只給了 topic 的 Read、漏給 consumer group 的 Read Describe、於是讀得到但 commit 不了、表現成重複消費；producer 漏給 Describe、拿不到 partition metadata。

修法：

1. 走 allow-list：allow.everyone.if.no.acl.found=false、預設拒絕、明確授權才放行。
2. ACL 對齊角色模板：producer = topic Write + Describe；consumer = topic Read + Describe 加 group Read + Describe；漏 group ACL 是重複消費的常見根因。
3. 用 prefixed ACL 而非逐 topic 設、把授權邊界對齊命名規範前綴、減少漏設。
4. 稽核流程：定期 kafka-acls.sh --list 比對預期授權矩陣、把 ACL 納入版本控制與 review、而非手動逐條加。

Case 3：Topic 數量爆炸壓垮 metadata 面

徵兆：叢集 topic / partition 總數隨團隊增長爬到數萬以上；controller failover 時間從秒級拉長到分鐘級；broker 啟動載入 metadata 變慢；client 的 metadata fetch 變大變慢、rebalance 期間出現連鎖延遲。容量沒滿、但整個叢集的 control plane 變鈍。

根因：partition 是 controller 要追蹤的 metadata 單位、數量只增不減。每個團隊隨手建 topic、每個 topic 又開高 partition 數、總 partition 數線性甚至超線性成長、壓垮 metadata 處理。KRaft 相比 ZooKeeper 提高了 metadata 上限、但上限仍存在、不是無限。

修法：

1. Partition 數規劃納入 topic 建立流程：partition 數對應並行度上限、不是越多越好；多餘 partition 是純 metadata 成本。詳見 Partition 卡。
2. 回收死 topic 釋放 partition slot：見 Case 4 與生命週期治理段。
3. 監控 metadata 壓力訊號：controller log、partition 總數、controller failover 時間設告警、在壓垮前介入。
4. 規模化路徑：單叢集 metadata 逼近上限時、評估分群（依關鍵程度分多叢集）、見 overview 的 Cross-region 與分層叢集段與 LinkedIn Tiered Clusters案例。

Case 4：Unused topic 未回收

徵兆：叢集裡大量 topic 數月無 produce 也無 consume、卻持續佔 partition slot 跟 metadata；沒人記得某些 topic 屬於哪個團隊、不敢刪；新 topic 想建時撞到 partition 上限、被迫先擴叢集而非先回收。

根因：沒有活躍判準與回收流程、topic 只建不刪。歸屬資訊沒編碼進命名、回收時找不到 owner、於是「不敢刪」成為預設、死 topic 無限累積。這是 Case 3（metadata 爆炸）的慢性來源。

修法：

1. 建立活躍判準：以 last produce / last consume timestamp 加觀察窗判定死 topic、觀察窗長於最長合法閒置週期（避免誤刪月結類低頻 topic）。
2. 兩段式回收：先 soft 標記並通知 owner、grace period 內無人認領才 hard 刪除、避免誤刪。
3. 命名規範補 ownership：前綴對齊團隊、回收時能直接找到 owner、消除「不敢刪」。
4. 自動化加稽核：參考 TopicGC的流程結構、回收前後比對 metadata 與效能指標、留稽核紀錄。

容量與規模邊界

Quota 與 ACL 是 broker-side 即時生效、不需重啟、可隨租戶調整、運維成本低。生命週期治理是持續流程、不是一次性操作 —— 死 topic 會持續產生、回收要常態化。三軸的共同前提是命名規範：沒有可治理的命名、quota 找不到歸屬、ACL 邊界對不齊、回收找不到 owner。多租戶治理的第一步是先把命名規範立起來、再談 quota 與 ACL。

整合與下一步

跟 overview 與案例的對位

• 上游 vendor 頁：Apache Kafka —— 本文展開其「Multi-tenant 與配額治理」「Topic 生命週期治理」兩段
• 平台治理案例：3.C6 Uber Kafka 事件平台 —— 單隊列問題提升到平台治理
• 生命週期案例：3.C3 LinkedIn TopicGC —— 自動回收與 metadata 壓力
• 規模化分群：3.C4 LinkedIn Tiered Clusters —— metadata 逼近上限時的多叢集路徑
• 自管轉 managed 的 ACL cutover：3.C2 VMware → MSK

跟安全模組對位

ACL 是 Kafka 內建的授權層、處理 broker 級的 principal × resource 授權。完整的 secret 管理（SASL 認證憑證怎麼發、輪替、撤銷）屬於 07 資料保護與安全模組的範疇 —— ACL 綁的 principal 從哪來、由認證層決定、ACL 只負責「這個 principal 能做什麼」。多租戶的完整信任鏈是「認證確認身分（07）→ ACL 授權操作（本文）→ quota 限制用量（本文）」三層。

下一步議題

• Schema 治理：跨租戶共用 topic 時、schema compatibility 是另一層契約治理、見 overview 的 KRaft 與 Schema Registry段
• Consumer group ACL 細節：跟 Consumer group rebalance 的互動
• Quota 與 delivery semantics：throttle 延遲對 producer timeout / retry 的影響

相關連結

• 上游 vendor 頁：Apache Kafka
• 對位 deep article（同模組）：本模組其他 Kafka deep article 見 vendor 頁進階主題段
• 跨模組授權鏈：07 資料保護與安全模組
• 方法論：Vendor 深度技術文章的寫作方法論
• 知識卡：Topic、Partition、Consumer group