本文 不 展開 vendor 機制細節（partition key 設計 / consistency level / RU sizing / connection management 等）— 那些屬 per-vendor deep article 的責任、本文在每個軸後 cross-link 過去。本文也 不 比較三家「誰比較強」— 三 vendor 在 workload-by-workload 適配光譜上各有位置、寫成優劣比較會誤導讀者把選型壓成單軸。

問題情境：讀者進來時的真實壓力

典型啟動壓力分兩類：

第一類、團隊評估 document / KV / multi-model NoSQL 三家、文件都說「scalable schema-less」、看不出實際取捨。讀者徵兆是「我的資料是 document-shaped 還是 KV-shaped？」「partition key 該怎麼選？」「Atlas 跟 Cosmos DB MongoDB API 不一樣的點在哪？」「Cosmos DB multi-model 是真用得到還是行銷話術？」「on-demand vs provisioned 怎麼選？」

第二類、既有 PostgreSQL / MySQL workload 撞 connection limit（surge 下 1K-5K pool 是隱性天花板、F1.7）、想換 KV 但不知道是否適合。讀者徵兆是「我已經有 Memcached、還要再加 MongoDB cache 層嗎？」「DynamoDB 適合當 OLTP 嗎？」「換 NoSQL 是不是解 connection 問題的銀彈？」

這兩類讀者進來時的 真實問題 不在 vendor 之間、在 workload 自己屬哪一型。Case anchor 覆蓋六個 unique 角度：

• 多型 document workload — 9.C38 Toyota Connected（車載 sensor schema 隨車型演進、20 個 Atlas DB blast radius 切分）
• Document 跨雲 hedging — 9.C37 Forbes（自管 → Atlas、6 個月遷移、跨雲彈性）
• 同 model 換 vendor 的 dogfood signal — 9.C30 Microsoft 365（MongoDB → Cosmos DB MongoDB API、保留 driver、wire compat 限制）
• KV-as-buffer 正向用例 — 9.C15 Tixcraft（DynamoDB 寫入緩衝、6750x 彈性、後端慢消費）
• PK 天然均勻典範 — 9.C5 Amazon Ads（90M reads/sec 年度峰值、KV pattern 純粹）
• Federated DB 真實系統 — 9.C36 Coinbase（MongoDB + DynamoDB + Memcached + mongobetween + freshness token）

Workload shape × access pattern × consistency 三軸前置判讀

進三家 vendor 對比前先回答：你的 workload 屬哪一型？三軸的組合決定 vendor 候選清單、軸不識別清楚直接比 vendor 是把選型壓成「品牌偏好」、不是工程決策。

軸 1 — 資料形狀：document / KV / 不清楚

資料形狀的核心判讀是 aggregate root 邊界是否明確 跟 schema 是否會隨產品演進新增欄位。document 適合的場景是資料天然多型、單筆記錄欄位差異大、應用層用 aggregate root 模式存取；KV 適合的場景是資料形狀固定、access pattern 數量少（< 5 種）、固定 lookup by key。

第三列的「暫緩 NoSQL」是反指標。NoSQL（特別是 DynamoDB single-table design）的核心假設是「access pattern 在設計時已知、後續變動有限」。資料模型還在探索、access pattern 半年內會大幅增減的場景、PostgreSQL + JSONB 給的彈性遠高於 NoSQL — JSONB 欄位可以演進、ad-hoc query 可以用 SQL 跑、未來釐清穩定 access pattern 後再選 NoSQL 不遲。

軸 2 — Access pattern 穩定度（KV 適用度前置判讀）

KV 適用度的核心判讀是 partition key 天然均勻度。partition key 不均勻會讓 vendor 廣告的「scale infinitely」變成「scale 到 hot partition 為止」、單一 logical key 流量超過該 partition 上限就 throttle 或 latency spike（F1.1）。

• 天然均勻 PK + 穩定 access pattern（meeting_id / player_id / message_id / user_id）→ DynamoDB / Cosmos DB Table API 適用、PK 不需 composite key 修補。Amazon Ads 用 ad_id 撐 90M reads/sec、Zoom 用 meeting_id、Capcom 用 player_id、PayPay 用 message_id、Disney+ 用 user_id — 五個 case 都揭露同一 frame：業務天然存在均勻 key 時 KV 是最自然的選擇。
• 天然不均勻 PK（event_id 一場演唱會集中 / date 時間序集中）→ 需 composite key 或 write sharding 修補。Tixcraft（9.C15）用 event_id + user_id_hash composite key 把單一熱門演唱會的 6750x spike 攤平到 partition 上 — 不是 DynamoDB 自身彈性、是 partition key 均勻分散的結果（F1.2）。
• Access pattern 變動頻繁（探索期、< 5 種 query 還會增加）→ 不適合 DynamoDB single-table design、回 RDB。Single-table 把 access pattern 編進 PK / SK 結構、增加新 query 等於改 schema、改 schema 等於重新 load 資料、成本不對。

KV 適用度判讀的延伸細節（hot partition 反模式 / composite key 設計 / adaptive capacity）見 DynamoDB partition key antipatterns。

軸 3 — Consistency 需求是否可接受 eventual

Consistency 需求的核心判讀是 跨 partition / 跨 region transaction 是否為產品契約。三家 vendor 都支援單 partition / 單 region 強一致、但 cross-partition / cross-region transaction 的機制跟限制差異大。

• 可接受 eventual / session consistency：DynamoDB（default eventually consistent reads、可選 strong）、Cosmos DB（5 個 consistency level、default session）、MongoDB（read concern 多級）— 三家都可以、選擇看其他軸。多數 KV / document workload 屬此類（social timeline、watchlist、message queue、analytics aggregation）。
• 需要強一致 cross-partition transaction：DynamoDB 跨 partition transaction 限制（單一 transaction 最多 100 個 action、跨 region 不支援）、MongoDB 4.0+ 支援 multi-document transaction 但 sharded cluster 仍有 limitation、Cosmos DB 跨 logical partition transaction 受限 — 都不如 SQL／distributed SQL 自然、應回 DB4 entry point 評估 Aurora DSQL / Spanner / CockroachDB。
• 跨 region active-active write：三家機制完全不同 — Cosmos DB multi-region write 跟 Strong consistency 是 互斥 設定（CAP 取捨硬約束、見 Cosmos DB multi-region write conflict SSoT 主寫位置）；DynamoDB Global Tables 走 LWW（last-writer-wins）conflict resolution；MongoDB Atlas 跨 region 需手動 conflict 處理。三家不在同一光譜、選擇前必看各 vendor outline 的機制段。

Migration path 三型（跨 case 合成 frame）

本段是 跨 case 合成 frame、不是單一 case 揭露 — 從 Coinbase（9.C36）/ Forbes（9.C37）/ Microsoft 365（9.C30）三 case 萃取的共通結構（F2.1）。

讀者進來時通常不是綠地、是 既有系統演進。三型遷移路徑的風險、ROI、適用條件完全不同、選錯路徑會推到錯的 vendor。

第一型：保留原 DB + 補周邊工具

不換 vendor、加 connection proxy（mongobetween / pgbouncer 類）、加 cache（Memcached + freshness token）、加 predictive scaling — 主資料層不動、應用層跟 ops 層補強。

• 代表 case：Coinbase（9.C36）保留 MongoDB Atlas、自建 mongobetween 把 60K connections/min 降到 ~2K（一個量級）、用 Memcached + freshness token 撐 1.5M reads/sec、用 ML predictive scaling 把擴容時間從 70 → 25 分鐘提前 60 分鐘
• 路徑成本：中（自建工具、需要工程資源 build & operate proxy / cache layer / ML model）
• 風險：低（主資料層不動、回滾代價小）
• ROI：保留主資料 schema + access pattern、解 driver / 部署模型 / cache 一致性瓶頸
• 適合：MongoDB（或主 DB）資料層撐得住、但應用層 connection storm / cache miss / 擴容慢卡瓶頸；團隊有工程能力 build 跟 maintain 周邊工具

延伸實作細節見 MongoDB connection management（per-vendor article、cross-link 待寫稿）。

第二型：同 DB 換託管

自管 → managed（Atlas / Cosmos DB / DocumentDB）、保留 schema 跟 access pattern、遷移期 6 個月量級。

• 代表 case：Forbes（9.C37）自管 MongoDB → MongoDB Atlas、保留 CMS schema、6 個月遷移、揭露「TCO 改善 25%」
• 路徑成本：中（dual-write + shadow read 驗證、driver 行為差異、operation runbook 重寫）
• 風險：中（dual-write 期間雙寫一致性、cutover 時點選擇）
• ROI：operation transfer（DBA bandwidth 釋放給 schema design / query tuning）+ TCO 改善
• 適合：自管 ops burden 大（DBA bandwidth 被 backup / patching / replica lag 吃光）、不想換 model

Scope warning（Forbes 25% TCO）：「25% TCO 改善」是 Forbes 特定流量規模（120M MAU、70+ Atlas region）下的數字、不普適。引用要帶條件 — 不要寫成「Atlas 比自管便宜 25%」這種 vendor-neutral 結論。實際省多少要看自管當下的 license / hardware / ops 工時分配、跟 Atlas 在你流量規模下的 pricing tier。

第三型：換 vendor 保留 model

MongoDB → Cosmos DB MongoDB API、或 MongoDB → DocumentDB — wire protocol + driver 不變、底層架構整個換、ops 模型整個換。

• 代表 case：Microsoft 365（9.C30）MongoDB → Cosmos DB MongoDB API、保留 MongoDB driver
• 路徑成本：高（dual-write per query pattern 驗證、wire compat ≠ 100% 行為相同、aggregation pipeline 跟 transaction 行為要逐項驗證）
• 風險：高（每個 query pattern 都可能踩到不相容 edge case、cutover 點選擇難）
• ROI：跨 vendor 換（Azure 生態 / multi-model API / global distribution）+ 保留應用層 driver code

Scope warning（Microsoft 365 dogfood）：Microsoft 365 是 Microsoft 自家 dogfood、case 沒揭露具體 throughput / latency / cost 數字（F2.17）。dogfood 是 高權重 selection signal（雲商賭自家旗艦產品）、但 不是 production benchmark（沒公開數字可比對）。引用要明示「dogfood signal」而非「production proof」。

Scope warning（100% wire compat）：Cosmos DB MongoDB API 廣告「100% wire compatibility」是 vendor 行銷話術、實際是「在某些 query pattern 下相容」（F2.9）。遷移時必須 dual-write per query pattern 驗證 — 不是看 vendor 文件 spec list、是用 production query corpus 跑一遍實測行為。Phase 0 audit checklist 應列出 unsupported aggregation stage、transaction edge case、index behavior 差異、change stream 跟 Change Feed 對應關係。

延伸 Cosmos DB MongoDB API vs SQL API 選型見 Cosmos DB MongoDB API vs SQL API。

第四型不在 DB3 範圍：paradigm shift 換引擎

KV → SQL 或 SQL → distributed SQL 屬 paradigm shift、應進 DB4 entry point: Aurora DSQL / Spanner / CockroachDB decision tree。本文範圍是 DB3 三家內部選型、不展開 paradigm shift。

從 RDB 撞牆來的快速路徑

讀者若從 PostgreSQL / Aurora connection limit 撞牆過來、想評估 KV 替代、依撞牆訊號直接 route 到對應 article、不必先跑完三軸前置判讀：

• 撞 connection limit（surge 下 pool 1K-5K 隱性天花板、long-lived TCP 占滿）→ HTTP API 模型（no long-lived connection）的 KV 直接接寫入緩衝、進 dynamodb/single-table-design-pattern 的「durable queue / write buffer」段（Tixcraft 9.C15 路徑：DynamoDB 接訂單、傳統 server 慢消費）、或評估 Cosmos DB Table API
• 撞單 primary 寫入上限（單 leader 寫吞吐天花板、read replica 無法分擔寫）→ multi-primary distributed SQL 路徑、進 DB4 entry point: Aurora DSQL / Spanner / CockroachDB decision tree 的 Path A（DoorDash 1.636 M QPS 單主寫入撞牆）
• 撞單一 DB 撐不下 + 多 workload 形狀並存（read-heavy / write-heavy / analytics 混在一個 DB）→ federated DB 模式、看 9.C36 Coinbase（MongoDB + DynamoDB + Memcached + mongobetween）+ 9.C29 Lemino（PostgreSQL → DynamoDB 揭露 RDB connection limit 隱性 bottleneck）

進 dynamodb/single-table-design-pattern 前先確認軸 1 / 軸 2 的 access pattern 穩定度跟 PK 天然均勻度 — connection limit 訊號 必要但不充分、KV 適用度 4 軸還是要走完、避免「為了解 connection 把不穩定 access pattern 硬塞 single-table」反模式。

Federated DB + system role 視角（跨 case 合成 frame）

本段也是 跨 case 合成 frame（F2.18 + F1.6）— 三個 rich case（Coinbase / Toyota / Forbes）都揭露 production 系統是 DB + 周邊工具 組合、不是單一 DB monolithic 撐起來。

讀者常誤以為「全用 X」是正解 — 全用 MongoDB、或全遷 DynamoDB、或全換 Cosmos DB。真實 production case 揭露兩個更前置的事實：(a) production 系統是 federated（多 DB 按 workload 分流）、不是 monolithic；(b) 每個 vendor 在系統中扮演 特定角色（control plane vs data plane vs cache）、不是 all-purpose store。

Federated DB by workload

Coinbase（9.C36）production 配置：MongoDB Atlas（document 主資料、identity service）+ DynamoDB（部分固定 KV workload）+ Memcached（read cache）+ mongobetween（connection proxy）+ Kinesis（event stream）。不是「全用 MongoDB」也不是「全遷 DynamoDB」、是按 workload shape 分流。

Toyota Connected（9.C38）：MongoDB Atlas 20 個 DB（microservice 拆 blast radius）+ Lambda + Kinesis + Redis + Kubernetes。20 個 DB 不是吞吐撐不住（18B txn/月 ≈ 7K txn/sec、單一 cluster 撐得下）、是 microservice ownership + blast radius 切分（F2.6）。

Forbes（9.C37）：MongoDB Atlas + 中介 abstraction layer + 50+ microservice。abstraction layer 隔離 schema 變動、避免 50 個服務都依賴 DB schema 細節（F2.3）。

三 case 揭露的共同 frame 是：寫 production 系統時假設「DB 一個服務搞定」、忽略 cache / queue / proxy / abstraction layer 跨層責任、會撞 connection limit / cache miss / cross-region replication 等隱性瓶頸。

System role：control plane vs data plane

DynamoDB 在 surge 場景能撐 nearly infinitely 不是 DynamoDB 自己神奇、是 系統架構解耦 的結果（F1.6）：

• Control plane（metadata、state、user record）：DynamoDB / MongoDB / Cosmos DB 適合 — 流量是 small payload + high QPS pattern
• Data plane（影音、大型 BLOB、media stream）：CDN / S3 / object storage、不在 DB3 範圍 — 流量是 large payload + bandwidth-bound
• Cache layer：Redis / Memcached / DAX（DynamoDB 補位）— 跟主 DB 形成跨層架構、處理讀峰值 + read-your-own-write 一致性

三個 case 揭露同一 frame：Zoom 視訊 metadata 走 DynamoDB、影音走 WebRTC / edge servers；Disney+ watchlist 走 DynamoDB、影片串流走 CDN + S3；Capcom game state 走 DynamoDB + DAX、game server 走 EKS。把影音串流塞 DynamoDB 是違反 control plane vs data plane 分離、容量規劃會錯（每筆 1KB 的 KV vs 每筆 100MB 的 media chunk 是不同 workload）。

三 vendor 對比 10 軸

下表是三 vendor 在 selection 階段的 10 軸對比。每個軸後續都有 per-vendor deep article 展開機制、本文不重複展開。

軸的延伸子段

部署 topology / 跨雲 hedging：三家 topology 是 vendor lock-in 跟 跨雲彈性 的硬取捨。Forbes 選 Atlas 不是當下省錢（自管 MongoDB 也可以、TCO 改善是副作用）、是 未來雲商策略尚未底定 的 hedging — Atlas 提供 AWS / GCP / Azure 三家部署、未來換雲不用換 DB（F2.10）。對照 DynamoDB / Cosmos DB / Spanner / Aurora 都是單雲鎖定 — 選了就跟著該雲商生態走。團隊雲商策略已底定（深度用 AWS / Azure / GCP 其一）時、單雲 vendor 通常較划算（更好的 IAM 整合、更深的 ops 工具、單一 support 通道）。跨雲價值真正成立是 策略不確定 或 合規要求多雲 場景。

Capacity 抽象：三家 capacity 抽象的 思維遷移成本 可能高過 vendor 廣告的價差（F2.12）。MongoDB 用 CPU + IOPS + working set RAM 三軸思維、跟自管 PostgreSQL / MySQL 類似、團隊轉換成本低。DynamoDB 用 WCU/RCU 抽象、要學「估每個操作消耗多少 unit」、加上 on-demand / provisioned / adaptive capacity 三模式選擇。Cosmos DB 用 Request Unit（RU）抽象、1 RU ≈ 1 KB document 的 strong read 成本、寫 ~5 RU、複雜 query 數百 RU — 工程師要學會用 RU 思考、不是用 CPU 思考、團隊知識遷移成本可能高。容量規劃延伸見對應 vendor 的 sizing article。

Partition / shard key 可逆性：三家 不在同一光譜、是選 vendor 前必做的 access pattern audit 重點（F2.15）。MongoDB reshardCollection（4.4+）可改、但成本高、需要 cluster downtime 或長時間 background migration。DynamoDB partition key 技術上可改、實作上用 backfill（建新 table、新 PK、雙寫舊新、cutover）— ops 工作量大但可逆。Cosmos DB partition key 不可改、改 partition key 等於 export-recreate-import — 對 1TB+ 資料是大型 migration 工程。三家不可逆性遞增、選 Cosmos DB 前必須前期完整 access pattern audit、不能「先上 production 之後再調」。

Consistency model：三家機制設計哲學不同。MongoDB read concern 是 per-operation 選擇（同一 client connection 可以混用）；DynamoDB strong vs eventual 是 per-read 選項（write 端統一強一致）；Cosmos DB 5 個 level 是 account-level default + per-request override、且 Strong 跟 multi-region write 互斥（CAP 硬約束）。設計上 MongoDB 最 flexible、Cosmos DB 最 explicit、DynamoDB 介於中間。延伸機制細節見 Cosmos DB consistency levels engineering、Cosmos DB multi-region write conflict（SSoT 主寫位置）。

Multi-model 差異化：Cosmos DB 是 唯一單一服務支援 5 API 的雲商 DB（SQL / MongoDB / Cassandra / Gremlin / Table）— 對照 AWS 走多產品覆蓋（DynamoDB KV + DocumentDB MongoDB-compat + Neptune graph + Keyspaces Cassandra-compat）、GCP 走多產品覆蓋（Firestore + Spanner + Bigtable）。multi-model 的差異化價值是 減少多 DB 並存運維 — 一個產品團隊只養一個 service、一套 IAM、一套 backup / DR、一套 monitoring。但 是否真用上 multi-model 要看團隊實際 workload — 多數團隊只用 1-2 個 API、單一 model 的競品（DynamoDB / MongoDB）可能更專注（F2.16）。

失敗模式（cross-vendor 反模式）

下列七條是三 vendor 都會踩、跨 case 共通的反模式。Per-vendor 特定反模式（例如 DynamoDB on-demand 隱性 hot partition、MongoDB schema 三代並存）在 per-vendor deep article。

反模式 1：把 DynamoDB 當 OLTP

訊號：access pattern 還在探索期、5+ 種 query 還會增加、強一致 cross-partition transaction 是產品契約。應回 PostgreSQL / Aurora、不是繼續加碼 DynamoDB single-table design。

DynamoDB 的 正確 用法包含 control plane KV（Zoom / Disney+ / Capcom）跟 durable queue / write buffer（Tixcraft 9.C15 揭露的非 OLTP 正向用例、F1.3）— DynamoDB 接「訂單」寫入、不是即時生效、是讓 traditional server（金流 / 票庫）用自己能承受的速度消費。這層解耦讓「前端可以擴 130 倍、後端不用同步擴」。

反模式 2：把 MongoDB 當 KV

訊號：access pattern 固定、PK 天然均勻、不需要 aggregation pipeline、document 內部從不展開（只查 root 欄位）。

應改 DynamoDB / Cosmos DB Table API。MongoDB 在這場景的 overhead（document overhead / connection model / aggregation engine 未用上）不划算 — KV vendor 的單筆讀寫成本更低、scaling 模型更簡單。

反模式 3：把 Cosmos DB 當跨雲服務

訊號：團隊評估 multi-cloud DR / 跨雲 portability、看到 Cosmos DB 文件強調「global distribution」就以為支援跨雲。

Cosmos DB 是 Azure-only、global distribution 指 Azure 內跨 region。想跨雲應改 MongoDB Atlas。multi-model 差異化是 Azure 生態內 的價值（F2.16）— 一旦離開 Azure、Cosmos DB 的所有獨特優勢都不存在。

反模式 4：federated DB 假設「全用 X」

訊號：寫架構設計時假設「DB 一個服務搞定」、不規劃 cache / queue / proxy / abstraction layer。

Production 真實系統都是 federated（Coinbase / Toyota / Forbes 都是）。寫架構時假設一個 DB 搞定會撞 connection limit（surge 下 RDB 第一個爆點、F1.7）/ cache miss（單靠 DB 撐不住讀峰值）/ cross-region replication（跨 region 一致性處理錯）等隱性瓶頸。預先設計 federated topology + 跨層責任分配、不是事後補。

反模式 5：誤判 dogfood case 數字

訊號：引用 Microsoft 365 / Amazon Prime Day 等 dogfood case 時、把它當 production benchmark、抄具體數字當 sizing 依據。

Dogfood case 數字常 不公開 或 不適用 customer-facing（F2.17 + F1.10）— Amazon Prime Day 「90M reads/sec」是年度峰值最高一秒不是平均、Microsoft 365 直接沒給數字、Google Spanner「10 億 req/sec」是 Google 全使用者加總不是單客戶配額。寫架構時引用要明示 selection signal（雲商賭身家、值得當高權重 vendor 訊號）vs production benchmark（具體 sizing 數字）— 兩者不可混為一談。

反模式 6：partition key 一上 production 才發現不可逆

訊號：選 Cosmos DB / DynamoDB 時、partition key 設計沒做完整 access pattern audit、上 production 一段時間後發現 hot partition、想改 PK。

三家不在同一光譜（見前段對比表）— MongoDB shard key 4.4+ 可改但成本高、DynamoDB 可 backfill 改、Cosmos DB 不可改 必 export-recreate。選 Cosmos DB 前要前期完整 access pattern audit、列所有預期 query 跟對應 PK 訪問頻率、確認最熱 PK 流量在單一 partition 容量上限內（F2.15）。

反模式 7：wire compatibility 當 100% 行為相同

訊號：選 Cosmos DB MongoDB API 或 DocumentDB、看到「MongoDB compatible」就假設 MongoDB driver 跑得起來就是相容、跳過 query pattern 驗證。

Wire compat ≠ 行為 100% 相同（F2.9）。Cosmos DB MongoDB API 廣告「100% wire compatibility」是行銷話術、實際是「在某些 query pattern 下相容」— aggregation pipeline 某些 stage 不支援、transaction edge case 行為差異、index 行為差異都會踩到。遷移必須 dual-write per query pattern 驗證、不是看 vendor spec list。

不該選 DB3 的訊號（升 SQL / 升 distributed SQL 路徑）

下列四條訊號出現時、選擇應跳出 DB3 範圍。

• JOIN-heavy + 強 normalize workload：應留 PostgreSQL（包括 PostgreSQL + JSONB 混合方案）、不該塞 NoSQL 再 $lookup。aggregation pipeline 的 $lookup 性能遠不如 SQL JOIN、在 sharded cluster 還有限制。
• 強一致 cross-region transaction 是產品契約：應進 DB4 entry point 評估 distributed SQL（CockroachDB / Spanner / Aurora DSQL）。三家 NoSQL 的 cross-region transaction 都有 limitation、不該當主路徑。
• 大流量 + 跨業務 fleet 治理：Aurora 200 cluster 模式（9.C4 DraftKings 揭露的 business sharding fleet）可能更合適、進 Aurora fleet 治理。NoSQL 的 fleet 治理工具鏈（cluster lifecycle / cross-cluster query / unified IAM）通常不如 managed SQL 成熟。
• 資料模型還在探索 + access pattern 變動快：暫緩 NoSQL 選型、用 PostgreSQL + JSONB 過渡。JSONB 給 document-like flexibility、SQL 給 ad-hoc query power、未來釐清穩定 access pattern 後再選 NoSQL 不遲。

下一步路由（per-vendor outline 子組）

讀者識別 workload type（軸 1-3）+ migration path（三型）+ system role（federated / control plane）後、進對應 per-vendor 子組繼續深化。

MongoDB 子組

• 入門：schema design pattern（contract layer 三選一：DB 層 validator / app 層 abstraction / 混合）
• 容量：shard key selection（單 cluster vs 多 cluster blast radius、Toyota 20 DB 模式）
• Migration：migrate to Atlas（同 DB 換託管型）

DynamoDB 子組

• 入門：single-table design pattern（access pattern 設計 + 適用度前置判讀）
• 機制：consistency model optimization（strong vs eventually consistent 取捨）

Cosmos DB 子組

• 入門：MongoDB API vs SQL API（API model 選型、四層 framing）

跨層架構（federated DB / cache / proxy）

跨層架構的延伸內容見對應 per-vendor connection management / cache layer article（後續會寫）— 本文只在軸 2 / federated frame 點到、不展開機制。

進 DB4 evaluation

若需要強一致 cross-region SQL / paradigm shift（KV → distributed SQL 或 SQL → distributed SQL）、進 DB4 entry point: Aurora DSQL / Spanner / CockroachDB decision tree。

Knowledge card 路由

本文涉及的 knowledge card：

• document-store — document model 的核心概念跟 aggregate root 邊界
• hot-partition — KV vendor 的 partition 容量上限機制
• database-sharding — shard key 跟 partition key 設計
• consistency-level — strong / eventual / session 三類取捨
• vendor-lock-in — 單雲 vs 跨雲的 hedging 取捨
• distributed-sql — 跳出 DB3 進 DB4 的概念入口

本文是 Cloudflare WAF overview 的 implementation-layer deep article。Overview 已說明 Cloudflare WAF 在入口治理譜系的定位、本文聚焦 Page Shield 這個 client-side（browser）supply chain attack 防禦工具 — 跟 WAF 攔 server-side request 是不同層。

Attack pattern × Defense mechanism 對照

Client-side supply chain attack 不會被 WAF 看到 — 攻擊發生在 browser 渲染 page 時、不在 origin server 跟 client 之間的網路層。Page Shield 是 browser-side script execution 的監測 + 防禦層、跟 WAF 處理 server-side request inspection 互補不重疊。

三層防禦對應不同 attack 階段：

1. CSP（Content Security Policy）：browser-enforced policy、preventive、阻止違反 policy 的 script load / network request
2. SRI（Subresource Integrity）：load 階段 hash 驗證、detective + preventive、廠商 CDN 上 script 被改就 browser 拒載
3. Script monitoring：runtime 觀測、detective only、記錄頁面 load 哪些 third-party script、變動時 alert

三層各有 ceiling — CSP 擋 inline / unauthorized source 但擋不到 allowed source 被 compromise；SRI 擋已知 vendor 改 hash 但擋不到動態 loader；monitoring 看得到但攔不到。Production 三層疊用、不要單一 layer。

CSP 配置 step-by-step

從 Cloudflare dashboard 啟用 + 寫 policy

 1# Dashboard: Security → Page Shield → CSP
 2# 模式: Report-only（第一週）→ Enforced（驗證後）
 3
 4# 範例 policy
 5default-src 'self';
 6script-src 'self' 'nonce-{NONCE}' https://cdn.trusted.com https://www.googletagmanager.com;
 7style-src 'self' 'unsafe-inline' https://fonts.googleapis.com;
 8img-src 'self' data: https:;
 9connect-src 'self' https://api.myapp.com https://*.sentry.io;
10form-action 'self';
11frame-ancestors 'none';
12report-uri https://csp-report.cloudflare.com/cdn-cgi/script_monitor/report;
13report-to default;

關鍵直覺：

• 'nonce-{NONCE}'：origin server 每 request 生成 random nonce、注入 <script nonce="..."> 跟 CSP header；script tag 沒對應 nonce 就被 browser 拒跑、擋 XSS
• connect-src 精準寫：第三方 API endpoint 全列出；不寫 * 或 https: 是擋 exfiltration 的關鍵（Magecart 把信用卡送外部 endpoint 就是用 connect-src 攔）
• form-action：擋 form 被改 action attribute 送外部、formjacking 第一道防線
• report-uri + report-to：违反 policy 的 event 送 Cloudflare、Page Shield dashboard 看 violation report

Report-only mode 第一週

1Content-Security-Policy-Report-Only: <policy>
2Content-Security-Policy:             default-src 'self';   # 鬆 policy 仍 enforce

Report-only 期間 browser report 違反但不擋、production traffic 不受影響；SOC 看 report 找：

• 漏列的 legitimate third-party（marketing / analytics SDK 沒寫進 policy）
• 意外 inline script（dev 留下的 debug snippet）
• 跨 domain 的合法 connect（CRM / chat widget）

第一週後 dashboard 看 violation 數量趨穩 + 主要違規都已 whitelist、切 Enforced。

Enforced mode 切換 + canary

不要直接全站 enforced — 用 Cloudflare Page Rule 對 10% traffic enforced、90% report-only：

1URL pattern: example.com/*
2Page Rule: Add CSP header (enforced)
3Bypass: 90% by Cookie / IP hash

10% traffic 跑 24-48h、確認 zero legitimate violation、再擴大到 50% → 100%。canary 期間 monitor error-rate metric、不只是 violation report。

SRI 配置

Subresource Integrity 用 hash 驗證 CDN-hosted script 沒被改：

1<script src="https://cdn.example.com/widget.v1.2.3.js"
2        integrity="sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9rx7HNQlGYl1kPzQho1wx4JwY8wC"
3        crossorigin="anonymous"></script>

Browser load 時算 hash、跟 integrity 不符就拒跑。關鍵：

• Hash 一定要 version-pinned：用 widget.v1.2.3.js、不能用 widget.latest.js；廠商更新 latest 時 hash 變 → SRI 拒載 → 服務中斷
• 多 hash：寫 integrity="sha384-... sha512-..." 至少一個 match 就過、可在 vendor rotate hash 時平滑遷移
• crossorigin="anonymous" 必加：跨 origin script 預設 browser 不暴露 hash 失敗細節、anonymous 才允許 CORS-based hash check

Page Shield 自動產 SRI 提示

Dashboard → Page Shield → Scripts 列出所有偵測到的 script、含 建議 SRI hash；可以 export 整合進 build pipeline、自動把所有 vendor script 加 SRI。

故障演練

Case 1：CSP report flood，SOC noise

徵兆：切 Enforced 後、CSP violation report 從每天 ~500 漲到每分鐘 ~50K、Page Shield dashboard 變紅、SOC 收 alert 收到 silent。

根因：browser extension（廣告攔截 / spell checker / password manager）注入 inline script 跟 connect、被 CSP block 同時觸發 report；不是真實 attack、是 user 端 extension 行為。

修法：

1. CSP report-sample directive 限 sampling（只 report 10%）— spec 部分支援、不是所有 browser 都認
2. Page Shield 規則：filter out extension protocol（chrome-extension://、moz-extension://、safari-extension://）後再 alert
3. Report endpoint 自管 + aggregation：不直接接 SIEM、先 batch + dedupe、再送 SIEM
4. 接受 report flood 是 normal、focus 監測 unique violation pattern 不是 total volume

Case 2：Inline script 漏，舊頁面突然壞

徵兆：切 Enforced 後 X 個舊頁面壞、user feedback 提交 form 失敗、debugger 看到 console Refused to execute inline script because it violates...。

根因：legacy page 有 inline <script> 沒 nonce、CSP enforced 後 browser 拒跑；報表/管理後台/舊 admin page 常見。

修法：

1. Audit 所有 inline <script>、加 nonce attribute（server-side render 時注入）
2. 短期：對舊頁面用 unsafe-inline 寫進 CSP（接受降級）、page-specific CSP override
3. 長期：legacy page 改 build-time bundle、消除 inline script

Case 3：Dynamic script loader 繞過 SRI

徵兆：vendor script load 成功、但 Page Shield monitoring 看到該 vendor script load 後又動態 load 多個額外 script；額外 script 沒 SRI 保護、廠商側 compromise 直接過。

根因：第三方 SDK 用 document.createElement('script') + script.src = '...' runtime 動態 load；CSP script-src 可能允許這個來源、但 SRI 沒法在 runtime 注入。

修法：

1. CSP script-src 精準到 只允許特定 path、不是整個 domain（例：https://cdn.vendor.com/sdk/v3/ 而不是 https://cdn.vendor.com）
2. 評估 vendor 是否有 static-only 替代（多數 marketing / analytics SDK 不需要 dynamic loader、是 legacy 設計）
3. 不能消除 dynamic loader 時、Page Shield monitoring 設 new script alert、廠商加 sub-script 即刻通知

Case 4：SRI hash mismatch，vendor 偷偷更新

徵兆：第三方 widget 突然不顯示、Page Shield 顯示 SRI mismatch、廠商 status page 沒事故公告。

根因：廠商在 same URL（不是 versioned）下偷偷 push minor patch、hash 變了 → SRI 拒載；不是 attack、是 vendor 不遵守 immutable URL 慣例。

修法：

1. 強制要求廠商提供 versioned URL（widget.v1.2.3.js）、不收 widget.latest.js
2. 廠商不配合時、build pipeline 加 daily hash check、廠商偷改 SRI hash 自動更新 + Slack alert
3. 評估換 vendor — 不遵守 immutable URL 的廠商 supply chain integrity 信用低

容量 + cost

Page Shield 是 Enterprise plan + Page Shield add-on、cost 維度：

Page load 影響：

• CSP header ~1-2KB（policy 寫越精準越長、不是越短越好）
• SRI 比對 ~5-10ms / script、現代 browser cache decoded hash、不重複算
• Script monitoring beacon ~100 byte / script load、async 不阻塞 page render

實務 default：

• Critical e-commerce / fintech：CSP enforced + SRI 全 vendor + monitoring all、SOC review weekly
• 一般 SaaS：CSP report-only ongoing + SRI critical vendor only + monitoring 主域
• Marketing / blog：CSP default-src 'self' minimum + monitoring only

整合 / 下一步

跟 dev workflow 整合

CSP 寫進 deploy pipeline、不是 dashboard 手動配：

1. Repo 內 csp-policy.yml、跟 code 同 lifecycle
2. CI 跑 CSP linter（如 csp-evaluator）、檢查 policy 弱點
3. Deploy 時 push 到 Cloudflare API、自動 versioning + rollback

跟 WAF 互補

Page Shield 跟 Cloudflare WAF 不重疊但互補：

• WAF 攔 server-side request injection（SQL / command / path traversal）
• Page Shield 攔 client-side script execution（XSS / supply chain）
• 共同 dashboard + alert routing、不要分開 SOC team 看

跟 supply chain SBOM

Page Shield 偵測的 client-side dependency 可進 SBOM、跟 Snyk / Dependabot 的 server-side SBOM 合併、得到完整 dependency graph。

下一步議題

• Trusted Types：browser-side template injection 的下一代防禦、Chrome 已支援、Firefox / Safari 進度不一
• CSP Level 3 + strict-dynamic：減少 maintenance burden、用 nonce 動態信任 nested script
• Reporting API v1：standard report endpoint + Reporting-Endpoints header 取代 report-uri

相關連結

• 上游 vendor 頁：Cloudflare WAF
• 上游 chapter：7.3 入口治理與伺服器防護、7.12 供應鏈完整性
• 對照案例：British Airways 2018 Magecart / Macy’s 2019 skimmer（公開 supply chain 案例）
• 平行 vendor：AWS WAF / Fastly Next-Gen WAF
• 平行 deep article：Vault Dynamic Credential / Splunk RBA
• Methodology：Vendor 深度技術文章的寫作方法論

本文是 HashiCorp Vault overview 的 implementation-layer deep article。Overview 已說明 Vault 在 secrets / credentials 治理譜系的定位（跟 cloud-native secrets manager / cert-manager 的取捨）、本文聚焦 dynamic credential engine 的實作層：怎麼配 database engine、application 怎麼 renew lease、production 踩過哪些坑、跟 cloud-native vault 跟 vault-agent injector 怎麼整合。

問題情境

Long-lived database credential 寫進 application config 是 production 環境最常見的 secret hygiene 失敗：credential 一旦外洩、輪替成本是 跨團隊協調 + 多服務同步重啟、實務上半年才換一次、credential 在 git history / log / dump file 留下軌跡。動態憑證（dynamic credential）的核心承諾是 credential 生命週期跟 application session 對齊、用完就 revoke、外洩窗口從幾個月縮到幾分鐘。

但 dynamic credential 不是「換個 SDK 就好」、它把 credential 治理 從 secret rotation 問題轉成 lease lifecycle 問題。lease TTL 設多久、renewal 怎麼跑、DB 端 user 創建會不會撞 max_connections、Vault sealed 時 application 怎麼降級 — 每個都是 production-grade 議題、無法靠 vendor doc 預設值直接上線。

核心概念：lease lifecycle 跟 secrets engine 模型

Vault dynamic credential 由三個元件協作：

跟 static secret（K/V store）對照、dynamic credential 的關鍵差異是 credential 在 read 時才產生、且 Vault 追蹤每個 outstanding lease；application 必須 主動 renew 或接受 credential 失效。

Lease 的兩個 TTL：

• default_ttl：credential 初始有效期、application 不 renew 就到期
• max_ttl：credential 最長有效期、不管 renew 幾次都不能超過

實務 default 配置：default_ttl: 1h + max_ttl: 24h、application 每 30-45 分鐘 renew 一次、credential 最多活 24 小時必換新的。

Step-by-step 配置

Vault server 啟用 database secrets engine

 1# 1. enable secrets engine
 2vault secrets enable -path=database database
 3
 4# 2. 配置 PostgreSQL connection
 5vault write database/config/myapp-prod \
 6  plugin_name=postgresql-database-plugin \
 7  allowed_roles="myapp-reader,myapp-writer" \
 8  connection_url="postgresql://{{username}}:{{password}}@db.internal:5432/myapp?sslmode=require" \
 9  username="vault_root" \
10  password="<vault_root_pw>"
11
12# 3. 創建 role
13vault write database/roles/myapp-reader \
14  db_name=myapp-prod \
15  creation_statements="CREATE ROLE \"{{name}}\" WITH LOGIN PASSWORD '{{password}}' VALID UNTIL '{{expiration}}'; \
16                       GRANT SELECT ON ALL TABLES IN SCHEMA public TO \"{{name}}\";" \
17  default_ttl="1h" \
18  max_ttl="24h"

關鍵：vault_root 是 Vault 用來創建其他 user 的 bootstrapping account、權限要含 CREATEROLE、但不需要 SUPERUSER；creation_statements 必須含 VALID UNTIL '{{expiration}}'、否則 DB 端 user 不會自動過期、Vault revoke 失敗時會留 zombie account。

Application 取得 credential

1# Read 動態 credential（每次 read 都產生新 user）
2vault read database/creds/myapp-reader
3# Key                Value
4# lease_id           database/creds/myapp-reader/abc123
5# lease_duration     1h
6# username           v-myapp-reader-x7y8z9-1747512345
7# password           A1b2C3d4E5f6...

Application 從 response 拿三個值：lease_id（用來 renew / revoke）、username + password（DB 連線）、lease_duration（決定何時 renew）。

Renew lease

1# 在 lease 到期前 renew（推薦在 50-70% TTL 跑）
2vault lease renew database/creds/myapp-reader/abc123
3# Key                Value
4# lease_id           database/creds/myapp-reader/abc123
5# lease_duration     1h    # renew 後重置回 default_ttl

lease_duration 在 renew 後 重置回 default_ttl、但 不會超過 max_ttl。例：default 1h / max 24h、application 連 renew 23 小時後、第 24 次 renew Vault 拒絕、application 必須拿新 credential。

Revoke lease（application shutdown 時）

1# Graceful shutdown 時主動 revoke
2vault lease revoke database/creds/myapp-reader/abc123

Application 結束時 revoke 是 credential hygiene 的最後一道閘門 — 即使 lease 還有時間、主動 revoke 讓 DB 端 user 立刻消失、避免 credential 在 application crash dump / log 內被翻出時還能用。

故障演練 / 邊界 case

Case 1：Lease renewal race，credential 中途失效

徵兆：application log 突然出現 FATAL: role "v-myapp-reader-x7y8z9-..." does not exist、且時間點接近某個整點 / 半點。

根因：application 用 lease_duration 推算 renew 時機、但用了 系統時間 而非 lease 簽發時間；application 啟動晚於 lease 簽發 30 秒、renew 跑在 lease 過期後 5 秒、Vault 已 revoke credential、DB 端 user 已刪除。

修法：用 server 回傳的 lease_duration 反推 renew 時機、留 20-30% buffer。例：lease_duration 3600 秒、application 在 2400-2520 秒（66-70%）開始 renew、不要拖到 3500 秒。Vault SDK 多數有 LifetimeWatcher（Go SDK）或 Renewer（Python hvac）這類 helper、優先用 SDK 不要自管 ticker。

Case 2：DB max_connections 撞牆

徵兆：application 在流量高峰開始大量 FATAL: too many connections for role、Vault audit log 顯示新 credential 還在發、PostgreSQL pg_stat_activity 看到上百個 v-myapp-... user 同時連著。

根因：每個 application instance / pod 在啟動時 read 一次 credential、credential lease 1h、但 application 跑 30 分鐘就重啟（K8s rolling update / OOM）；舊 user 還在 PostgreSQL 端連著（connection pool 沒釋放）、新 user 又被創建、累積到 max_connections。

修法：兩層

1. Application graceful shutdown 時 vault lease revoke + connection pool drain
2. PostgreSQL connection pool 加 pool_lifetime_max 跟 application instance lifetime 對齊、避免 connection leak 到 lease 失效後仍 holding

Case 3：Vault sealed 中、existing lease 仍可用但新 lease 拿不到

徵兆：deploy 新 version 時、新 pod 起不來、vault read database/creds/... 卡住或回 Vault is sealed；但 舊 pod 持續運作正常（因為已持有 lease）。

根因：Vault sealed（master key 被 wrap、需要 unseal key 解封）時、existing lease 因為 credential 已在 DB 端創建、application 連線不需要 Vault 介入；但 新 lease 創建需要 Vault / renew 也需要 Vault。Sealed 期間 application 還能用、但無法擴容、無法 renew。

修法：

1. Vault HA cluster + auto-unseal（KMS / HSM auto-unseal）避免人工 unseal 鏈
2. Application 加 retry-with-backoff、Vault 短暫 unavailable 時不要立刻 crash
3. Lease 設長一點（default 4h、max 48h）給 unseal 流程留時間

Case 4：Application Vault token expire、lease orphan

徵兆：application 在連續跑 1-2 週後突然開始 Permission denied on vault lease renew、credential 在 max_ttl 後失效但 application 不知道。

根因：application 的 Vault token（不是 DB credential 的 lease）也有 TTL；token 過期後 application 無法 renew lease、但 application 可能還沒到 自己拿新 token 的循環。Lease 變 orphan（沒人能 renew）、TTL 到就被 revoke。

修法：

1. Application 用 vault-agent injector / sidecar pattern、由 sidecar 維護 token + lease；application 只讀 file
2. 不用 sidecar 時、application token 用 renewable token + 跟 lease 同 lifecycle 管
3. AppRole auth method 的 secret_id 跟 token TTL 都要納入 application reload 流程

Case 5：CircleCI 2023 incident 對照 — secret_id scope 過寬

徵兆：CircleCI 2023 1 月事件、攻擊者拿到開發者 endpoint session token、進而拿到 Vault AppRole 的 secret_id；secret_id 對應的 policy 含 跨環境跨資料庫 read、攻擊者用 secret_id 拿到大量動態 credential。

根因：AppRole secret_id 的 policy scope 設成 single AppRole 服務所有環境、而不是 per-environment AppRole；secret_id 外洩等於拿到全公司 dynamic credential 發放權。

修法：

1. Per-environment AppRole：dev / staging / prod 各有獨立 AppRole + secret_id、policy 只允許該環境的 database engine path
2. Secret_id TTL 短化（< 24h）、用 response wrapping 傳遞、拿到後立刻 unwrap、減少 secret_id 在 build pipeline log 留軌跡
3. Vault audit log 接 SIEM、approle/login 異常 location / IP 即刻 alert

容量規劃

Dynamic credential 的容量設計圍繞 lease churn rate — 每秒多少新 lease 創建、多少 renew、多少 revoke。

實務 sizing 範例：100 個 application pod、lease_duration 1h、renew at 50% TTL：

• 新 lease：100 / 3600 ≈ 0.03/s（pod 重啟才有）
• Renew：100 / 1800 ≈ 0.06/s
• Outstanding lease：~100 個（每 pod 一個）
• DB user 數：~100 個（peak ~150 含 grace period）
• DB connection：100 × 5（pool size）= 500、需要 PostgreSQL max_connections >= 600

超出單 Vault node 容量（~50 ops/s）時、走 Vault HA cluster + auto-unseal、或拆 namespace。

整合 / 下一步

vault-agent injector（K8s 環境推薦）

 1# pod annotation
 2metadata:
 3  annotations:
 4    vault.hashicorp.com/agent-inject: "true"
 5    vault.hashicorp.com/role: "myapp-reader"
 6    vault.hashicorp.com/agent-inject-secret-db-creds: "database/creds/myapp-reader"
 7    vault.hashicorp.com/agent-inject-template-db-creds: |
 8      {{- with secret "database/creds/myapp-reader" -}}
 9      DB_USER={{ .Data.username }}
10      DB_PASSWORD={{ .Data.password }}
11      {{- end }}

Sidecar 自動 renew lease、credential 寫進 pod shared volume、application 讀 file。Application code 不需要 Vault SDK、降低 dependency。

SDK pattern（非 K8s 環境）

Go：hashicorp/vault/api + LifetimeWatcher、Java：spring-cloud-vault、Python：hvac + Renewer。SDK 已處理 renew timing / retry / token rotation、不要自寫 ticker。

跟 cloud-native secret manager 的混搭

AWS Secrets Manager / Google Secret Manager 也有 dynamic credential rotation（每 30 天輪替）、但 cadence 是按時間、不是 按 application session。混搭 pattern：

• Cloud-native：infrastructure-level credential（RDS master / k8s service account）、long TTL（30-90 天）
• Vault dynamic：application-level credential、short TTL（1-24 小時）
• Vault root credential 存 cloud-native secret manager、Vault auto-unseal 也用 cloud KMS

下一步議題

• Database snapshot 跟 dynamic credential 衝突：PostgreSQL pg_dump 用 long-lived credential、不適用 dynamic；snapshot user 用 static + scoped policy、跟 application user 分離
• Connection pool 端的 dynamic credential 支援：PgBouncer 不支援 per-connection credential rotation、需要 connection 整個 lifecycle 跟 lease 對齊
• 多 region Vault replication：performance replication 跟 disaster recovery replication 對 lease 的處理不同、跨 region application 要 sticky 同一 region 的 Vault primary

相關連結

• 上游 vendor 頁：HashiCorp Vault
• 對照案例：Failure: Credential Rotation Without Scope
• 對照案例：CircleCI 2023 AppRole 事件 — Cross-vendor mapping
• 上游 chapter：7.6 秘密管理與機器憑證治理
• 平行 deep article：pgBouncer 配置
• Methodology：Vendor 深度技術文章的寫作方法論

本文是 Kubernetes overview 的 implementation-layer deep article。Overview 已說明 K8s 在 deployment platform 譜系的定位、本文聚焦 pod termination 這個 production 最常踩、被誤解最深的議題：序列、配置、五個 case、跟 service mesh 整合。

Graceful shutdown 沒做對、500 期間每次 deploy 都吃 502

最常見的觸發場景：deploy 新 image、prometheus alert 在 5 分鐘內收到一波 502 / 503、SRE 翻 application log 看到「正在處理 request」「connection closed」交替出現。Application 本身沒 bug、但 K8s 在 pod terminate 時跟 traffic 來源 沒對齊步調、舊 pod 還在處理請求時就被 SIGKILL、新 request 還在打到準備關閉的 pod 上。

很多團隊修法是 把 terminationGracePeriodSeconds 從 30 拉到 120、暫時掩蓋問題；但症狀會在下次 rolling update / HPA scale-down / node drain 時換個形式回來。根因在 termination 序列 — pod 不是收到 SIGTERM 就 graceful、序列裡每一步出錯都有不同 fail mode。

Termination 序列：五步、每步都能爆

K8s 收到 delete pod 請求後、發生的事 按時間 是：

關鍵誤解：

1. 「pod 從 Service 移除」跟「container 收到 SIGTERM」是 平行、不是序列。Endpoint controller 更新 Endpoints object → kube-proxy 重新寫 iptables → 各 node 的 traffic 才真正停 — 這條鏈通常需要 1-5 秒；同時間 SIGTERM 已經發給 application。

2. preStop hook 是「container 還在跑、SIGTERM 還沒發」期間執行。pre-Stop 設 sleep 10 是 production 標準作法 — 用 sleep 讓 endpoint controller 有時間把 pod 從 Service 移除、避免 SIGTERM 期間還有新 request 進來。

3. terminationGracePeriodSeconds 是 從 preStop 開始 計時、不是從 SIGTERM。preStop sleep 10s + application 30s graceful = 至少要設 40s。

4. graceful 不是 framework 自動的。Application 必須 主動處理 SIGTERM：拒絕新 request、等 in-flight 完成、close DB connection、flush log。沒處理 SIGTERM、container 會在 grace period 後被強殺。

5. readiness probe 在 Terminating 期間 仍會被執行、但結果不影響 traffic（已經從 Endpoints 移除）。但若 application 沒主動讓 readiness fail、service mesh / external LB 可能仍在送 request（依不同 mesh 行為）。

配置全圖

Deployment spec

 1apiVersion: apps/v1
 2kind: Deployment
 3spec:
 4  template:
 5    spec:
 6      terminationGracePeriodSeconds: 60          # SIGTERM 後 60s 才 SIGKILL
 7      containers:
 8        - name: app
 9          lifecycle:
10            preStop:
11              exec:
12                command: ["/bin/sh", "-c", "sleep 10"]
13          readinessProbe:
14            httpGet:
15              path: /healthz/ready
16              port: 8080
17            periodSeconds: 5
18            failureThreshold: 2

時序：t=0 preStop 開始 sleep 10s → t=10s container SIGTERM → t=70s SIGKILL（不是 t=60s、是 60s after SIGTERM）。

Application 處理 SIGTERM（Go 範例）

 1sigs := make(chan os.Signal, 1)
 2signal.Notify(sigs, syscall.SIGTERM)
 3
 4server := &http.Server{Addr: ":8080"}
 5go server.ListenAndServe()
 6
 7<-sigs                                              // 等 SIGTERM
 8log.Println("SIGTERM received, draining...")
 9
10// 1. readiness fail（讓 mesh-aware 流量停）
11ready.Store(false)
12
13// 2. wait 5s 讓 readiness probe failureThreshold 觸發
14time.Sleep(5 * time.Second)
15
16// 3. graceful shutdown server（拒新請求、等 in-flight）
17ctx, cancel := context.WithTimeout(context.Background(), 45*time.Second)
18defer cancel()
19server.Shutdown(ctx)
20
21// 4. close DB / cache / message consumer
22db.Close()
23consumer.Stop()
24
25// 5. flush log + exit
26logger.Sync()

關鍵：server.Shutdown(ctx) 是 拒新請求、等 in-flight、ctx timeout 設 grace period 減去 preStop sleep 跟 readiness fail 等待時間（60s - 10s - 5s = 45s）。

Production 故障演練

Case 1：Rolling update 期間 502 / 503

徵兆：每次 deploy 後 5 分鐘內 LB / ingress log 一波 502 / 503、application log 顯示「context canceled」「connection closed by peer」、新 pod 已 ready 但舊 pod 在 grace period 內仍收 request。

根因：沒設 preStop sleep、container 收到 SIGTERM 後立刻 server.Shutdown()、但 kube-proxy 還沒把舊 pod 從 iptables 移除、新 request 持續送到舊 pod、舊 pod 已拒收。

修法：preStop sleep 10、讓 endpoint propagation 完成再進入 SIGTERM 流程。

Case 2：Connection drain race，long-running request 被中斷

徵兆：deploy 後 application log 有大量 context canceled 對應到 long-running endpoint（例：報表生成、檔案上傳）、user 端看到 transaction 失敗、但短 request 沒事。

根因：long-running endpoint 處理時間 > terminationGracePeriodSeconds、server.Shutdown(ctx) ctx timeout 設太短、in-flight 強制中斷。

修法：

1. 把 long-running endpoint 改 async（背景 job + status endpoint）、HTTP request 立刻 return job ID
2. 短期：terminationGracePeriodSeconds 拉到 long-running 99 percentile + buffer
3. application 側 ctx timeout = grace period - preStop - readiness fail wait

Case 3：Init container 在 grace period 期間重啟、SIGTERM 沒到 main

徵兆：pod 顯示 Terminating 但 phase 一直在 Running、main container restart count + 1、application log 沒看到「SIGTERM received」。

根因：init container 用 restartPolicy: Always（K8s 1.28+ sidecar 模式）、或 main container 在 SIGTERM 前先 crash 觸發 restart、kubelet 在 restart 後 不重發 SIGTERM、main container 跑到 grace period 結束直接 SIGKILL。

修法：

1. Sidecar container（restartPolicy: Always）的 preStop 也要設 sleep、跟 main 同 lifecycle
2. main container readinessProbe 失敗時 別自動 restart（restartPolicy: OnFailure + crashLoopBackOff 觀察）
3. 觀察 kubectl describe pod 的 events、SIGTERM 沒發出來會有 Killing container event 缺失

Case 4：StatefulSet 串行終止、總時間 = pod 數 × grace period

徵兆：StatefulSet rolling update / scale-down 比 Deployment 慢 N 倍（N = replica 數）、deploy 一個 5 replica 的 statefulset 要 5 分鐘以上。

根因：StatefulSet 預設 podManagementPolicy: OrderedReady — pod 串行終止 + 串行創建、每個 pod 至少要 grace period 完成才動下一個。Deployment 用 RollingUpdate 預設 maxUnavailable=25% 平行終止。

修法：

1. StatefulSet 改 podManagementPolicy: Parallel（若 application 不要求嚴格順序）
2. 嚴格順序情境（Cassandra / Kafka / etcd）保留 OrderedReady、但 grace period 設 單 pod 必要時間、不要設 總時間能承受
3. 接受序列化代價、把 deploy 排在低流量時段

Case 5：Job / CronJob 不 graceful、SIGTERM 直接 SIGKILL

徵兆：CronJob 在 Job timeout / pod eviction 時不 graceful、寫一半的 file 留在 PVC、下次跑時 corrupt；application log 沒「SIGTERM received」、直接斷。

根因：Job 的 activeDeadlineSeconds 到期 / node eviction 觸發時、K8s 對 Job pod 仍會發 SIGTERM、但 很多 batch framework（Spring Batch / Argo Workflow worker）沒處理 SIGTERM、application 沒主動 checkpoint。

修法：

1. Batch application 處理 SIGTERM、checkpoint 進度寫 storage、下次跑時 resume
2. 不適合 checkpoint 的 batch、保證 idempotent re-run、SIGKILL 後重跑不會 corrupt
3. Job spec 加 terminationGracePeriodSeconds（預設 30、batch 通常要 60-300）

規模影響

Graceful shutdown 的成本主要在 deploy 時間 跟 capacity buffer：

實務 default：

• Web service：terminationGracePeriodSeconds: 60、preStop sleep 10、application graceful 45s
• Backend worker（消費 queue）：terminationGracePeriodSeconds: 120、preStop 不 sleep（用 readiness 控）、application 處理當前 message + commit offset
• Batch job：terminationGracePeriodSeconds: 300、checkpoint pattern
• StatefulSet（DB / queue）：grace period 對齊 vendor 建議（Kafka 90s、PostgreSQL 60s）

跟其他元件整合

Service mesh（Istio / Linkerd）

Service mesh sidecar（envoy / linkerd-proxy）也有自己的 termination — 通常比 main container 晚一點關。配置原則：

1. mesh sidecar 設 terminationGracePeriodSeconds 比 main 多 5-10s、main 處理完才換 sidecar
2. Istio 1.12+ 的 proxy.istio.io/config.holdApplicationUntilProxyStarts 控啟動順序、shutdown 也要對應
3. mTLS 環境 graceful 多一道：在 SIGTERM 後等 mesh 主動 close cert rotation、不要硬斷

Readiness probe 跟 mesh-aware traffic

純 K8s Service（kube-proxy iptables）：endpoint 移除後 已建立 connection 仍會跑完、新 connection 不來。Mesh-aware traffic（service mesh / external LB with health check）：要 readiness fail 才會停送。

修法：application graceful 第一步是 ready.Store(false) + 等 readiness probe 至少 fail 一次（5-10s）、才開始 server.Shutdown。

跟 Pod Disruption Budget（PDB）的衝突

Node drain 時 PDB 限制可同時 unavailable 的 pod 數、graceful shutdown 拖長會讓 drain 卡住。對策：

1. 緊急 drain（node 硬體故障）：kubectl drain --grace-period=30 --force、接受短時間 502
2. 正常 drain（升級 / 維運）：PDB 設 minAvailable: <replicas-1>、容許單 pod 慢慢 graceful
3. 不要設 maxUnavailable: 0、會讓 drain 卡死

下一步

• Application graceful 寫法：12-factor app disposability 章節給 framework-agnostic 模板、各語言 SDK 寫法見對應 framework
• Queue consumer 的 graceful：訊息 ack / offset commit 必須在 SIGTERM 內完成、否則 duplicate message — 對應 03 message queue 模組的 consumer-design 段
• 跨 region / 多 cluster 的 graceful：multi-cluster service mesh（Istio multicluster / Linkerd multicluster）的 traffic shift 期間 graceful 行為跟單 cluster 不同、需要對齊 mesh 配置

相關連結

• 上游 vendor 頁：Kubernetes
• 上游 chapter：5.X deployment-rollout-drain-rollback
• 對照案例：rolling update 期間 502 多見於 stage-3 mesh adoption case 庫
• 平行 deep article：pgBouncer 配置 / Vault Dynamic Credential
• Methodology：Vendor 深度技術文章的寫作方法論

本文是 Splunk overview 的 implementation-layer deep article。Overview 已說明 Splunk Enterprise Security 在 SIEM / Detection 譜系的定位、本文聚焦 Risk-Based Alerting (RBA) 的實作層 — 從「per-rule alert」轉到「score 累積 + threshold 觸發 notable」的方法論轉變、跟 tuning / scaling / 整合的具體做法。

為什麼 RBA：alert fatigue 是 detection engineering 的天花板

Detection engineering 的成熟度上限不是「能寫多少 correlation rule」、是「SOC analyst 能處理多少 alert / day 而不會麻木」。多數 SOC 在 200-500 alert/day 區間就到處理上限、再加 rule 只會推升 false positive、analyst 開始 silent ignore 中低嚴重度 alert。

RBA 的核心轉折是 把 alert 邏輯從「rule 觸發」拆成「score 累積」：每個 detection rule 不直接產 alert、而是給 user / asset / process 加 risk score；多個低嚴重訊號累積到 threshold 才產 notable（高優先 case）。SOC 看的不是「rule X 觸發了」、是「user Y 今天累積 70 分、上週 12 分」。

RBA 不是 寫 detection rule 的替代、是 aggregation 跟 prioritization 的新層。原本 100 條 rule 各自產 alert 變成 100 條 rule 共同貢獻 score、score → notable 是新的 alert 邊界。

RBA 三層 model：modifier、score、notable

Risk 流程的三個 first-class object：

關鍵設計選擇都在 modifier 層：

• 加分維度：per user / per asset / per process tree / per IP — 維度越細粒度、score 越能對應「個體」、但 query 成本越高
• 加分 weight：簡單做法 severity 直接對應（low=5 / med=15 / high=30 / critical=60）；細做要考慮 signal precision（rule 的歷史 FP rate）
• MITRE ATT&CK 對應：每個 modifier 標 tactic / technique、跟 ATT&CK 對應、用來判斷 kill chain 階段 是否完整（reconnaissance → exfiltration 全套出現 vs 單一 tactic 重複）

ES 配置 step-by-step

Risk modifier 從 correlation search 產出

| search index=auth user=* unusual_geo=true
| stats count by user, src_ip, _time
| eval risk_score=25
| eval risk_object_type="user"
| eval risk_object=user
| eval risk_message="Unusual login geography"
| eval threat_object=src_ip
| eval threat_object_type="ip_address"
| eval mitre_technique="T1078"
| collect index=risk

關鍵欄位：

• risk_object + risk_object_type：誰被加分、預設 user / system / other
• risk_score：加多少分、考量 signal precision
• threat_object：對應的 attacker artifact（IP / hash / domain）、用來跨 modifier 關聯
• mitre_technique：對應 ATT&CK ID、用於 kill chain analysis

Tuning 提醒：第一次部署別直接 collect index=risk、先 | table 看 output、估算每天會產多少 modifier；超出 indexer 容量規劃前先做 sampling（| where random()/2147483647<0.1 取 10%）。

Risk notable：threshold aggregation

| tstats summariesonly=t count, sum(All_Risk.calculated_risk_score) as total_risk
  from datamodel=Risk.All_Risk
  where earliest=-24h
  by All_Risk.risk_object, All_Risk.risk_object_type
| where total_risk > 80
| `risk_score_format`

total_risk > 80 是觸發 notable 的 threshold。Tuning 重點：

• Time window：-24h 是預設、但要看 attack pattern average duration 調整；APT 用 7-14 day window、commodity attack 用 4-12h
• Threshold value：80 是 當量 不是普世值、依 modifier weight 分佈調整；ES 7.0+ 預設建議 100、實務多在 60-150 區間
• Aggregation 維度：by user 是 default、但 lateral movement scenario 要 by asset、credential abuse 要 by service account

Tuning 提醒：第一週跑 shadow mode — 觸發 notable 但不 page、SOC 後續 review、調整 threshold 跟 weight；shadow 跑 1-2 週後再啟 production page。

Notable enrichment：人類能看的 case

| eval description="User ".risk_object." accumulated ".total_risk." risk over 24h"
| eval mitre_techniques=mvjoin(mitre_technique, ", ")
| eval contributing_rules=mvjoin(search_name, ", ")
| sendalert notable

Notable 進入 ES Incident Review、SOC analyst 看到的不只 score、還有 組成這 80 分的 N 條 rule + ATT&CK 覆蓋的 tactic；這是 RBA 比 per-rule alert 強的核心 — analyst 直接看完整 narrative、不用拼湊。

Tuning playbook：四類常見 drift

Playbook A：False positive 累積

徵兆：某 user 連續 N 天觸發 notable、SOC 每次 review 後 close 為 FP；但 modifier 仍持續加分。

根因：modifier 加分邏輯沒考慮 baseline — 例：DBA 每天用 psql 連 prod 是正常、unusual_command rule 把它當異常加 15 分、累積到 threshold。

修法：

1. Modifier 端加 whitelist_lookup：DBA / SRE / approved service account 跳過 specific modifier
2. 進階：modifier 加 signal_precision weight、historical FP rate > 30% 的 rule weight 降到 5 分以下
3. 不能輕易加 NOT user IN (...) exclusion、long whitelist 是反模式 — 用 role-based exclusion（query AD group）

Playbook B：Score inflation

徵兆：threshold 設 80、SOC 收到的 notable 每 day 從 5 個漲到 25 個、但「實際攻擊」沒對應增加。

根因：新加的 detection rule 沒對齊既有 weight 分佈、新 rule 都給 +30 / +40、global average 抬升、threshold 變相降低。

修法：

1. 每加新 rule 時跑「+1 rule 對 daily notable 數的影響」shadow simulation
2. 重新 calibrate threshold — 不是固定值、是 p95 daily total_risk 的 1.5 倍
3. 季度 review：跑 index=risk | stats sum(risk_score) by source 看 modifier 來源分佈、score 集中在少數 rule 是 inflation 訊號

Tuning 提醒：score inflation 跟 alert fatigue 是同樣症狀的不同根因；前者改 threshold + rule weight calibration、後者改 modifier 維度跟 whitelist。

Playbook C：Threshold drift

徵兆：threshold 設定半年沒動、但 attack landscape / business 行為都變了；要嘛 notable 太多（threshold 低於 baseline）、要嘛 missed detection（threshold 高於實際攻擊累積）。

根因：threshold 是 static value、但 baseline 是 dynamic；business 流程變動（雲端遷移 / 新部門 / WFH 比例變化）影響 modifier 觸發頻率。

修法：

1. Quarterly tuning cadence：每季跑 tstats sum(All_Risk.calculated_risk_score) by user | stats p50, p95, p99 看分佈
2. Adaptive threshold：用 p95 × 1.3 動態計算、寫 macro 自動 update
3. 不要把 threshold drift 當「rule 不準」、是 基準漂移、不是 rule 錯

Playbook D：Decay 設計

徵兆：user 7 天前的低分異常持續累積在 score 內、threshold 觸發 notable 但實際是 7 天分散事件、不是 當前攻擊 episode。

根因：default RBA 在 -24h window 內 sum、沒考慮 時間衰減；7 天前的低分跟今天的低分權重一樣。

修法：加 decay function、modifier weight 隨時間衰減：

| eval age_hours=(now() - _time)/3600
| eval decayed_score = calculated_risk_score * exp(-age_hours / 48)
| stats sum(decayed_score) as total_risk by risk_object

exp(-age/48) 是 48 小時半衰期、24h 前的事件權重剩 60%、48h 剩 37%、7 天前剩 < 3%。half-life 依 attack pattern 調整：commodity attack 12-24h、APT 5-14 day。

Capacity 規劃

RBA 的 capacity 三個面向：

實務 sizing：500K modifier/day、用戶 5K、tstats hourly trigger search、需要 3 indexer + 1 search head（含 RBA 之外的工作）。

注意 SC4S / Splunk Cloud ingest pricing — RBA 不增 ingest GB / day、但 datamodel acceleration 算 CPU 工作量、Splunk Cloud 是另外計費的 vCPU；on-prem 自管 indexer 沒這個 cost。

整合 / 下一步

跟 SOAR / case management

Notable 觸發後接 SOAR：

• enrichment：自動 query AD / asset DB / threat intel、把 user role / asset criticality / known IoC 補進 case
• decision tree：根據 risk score 區間決定 SOC tier（< 100 tier 1 / 100-200 tier 2 / 200+ tier 3 + page）
• playbook automation：disable user / isolate endpoint / rotate credential 走 SOAR pipeline、不要 SOC analyst 手動 click

跟 Elastic Security / Sentinel 對照

各家對 RBA 的實作命名不同：Splunk 叫 RBA、Elastic 叫 Risk Engine、Microsoft Sentinel 叫 Fusion + UEBA aggregation、Sumo Logic 叫 Insight Trainer；底層概念相同（score aggregation + threshold notable）、細節差在 modifier 寫法跟 ML 自動化程度。跨平台遷移時 modifier 邏輯多半要重寫、threshold + decay tuning 經驗可以平移。

跟 UEBA

RBA 跟 UEBA（user / entity behavior analytics）是 互補不是替代 — UEBA 用 ML 算 baseline 偏差、輸出 anomaly score 餵進 RBA 當一個 modifier 來源。實作順序通常是 先靜態 rule + RBA、再加 UEBA 補充；直接從 ML-first 開始通常 tuning 成本爆炸。

下一步議題

• Threat object correlation：跨 modifier 用 threat_object 串相同 attacker artifact、score 跨 user 跨 asset 聚合
• Kill chain coverage analysis：notable 拆成「ATT&CK tactic 覆蓋 N/14」、覆蓋越廣 priority 越高
• Risk-based response automation：score 區間自動觸發不同 SOAR playbook、人工只 review tier 3

相關連結

• 上游 vendor 頁：Splunk
• 對照案例：Okta Cross-Tenant Impersonation 2023、Microsoft Storm-0558
• 上游 chapter：7.13 偵測覆蓋率與訊號治理
• 平行 vendor：Elastic Security / Google Security Operations
• 平行 deep article：Vault Dynamic Credential
• Methodology：Vendor 深度技術文章的寫作方法論

本文是 AWS ElastiCache overview 的 implementation-layer deep article。選型層（為何用 managed、engine 選擇、跟自管取捨）見 overview；本文只處理「決定用 ElastiCache 後，哪些是 AWS 的責任、哪些仍是你的」。CLI 與計費以 AWS ElastiCache 官方文件、ElastiCache 定價 為準、最後檢查日 2026-06-16（managed 服務的引數與價格會變、以官方為準）。

managed 不等於 hands-off

把 cache 換成 ElastiCache 之後，最危險的心態是「現在 AWS 全包了」。AWS 確實接走了一大塊運維——它幫你做 failover、patching、snapshot、跨 AZ 複製，你不用再自己部署 Sentinel、不用半夜起來手動切 master。但有一類問題 ElastiCache 一個都沒幫你解，而且因為「以為 AWS 會處理」，這些問題在 managed 環境反而更容易被忽略到上線才爆。

Tinder 的配對引擎跑在 ElastiCache for Valkey 上、4700 萬月活、sub-millisecond 延遲——這證明 managed 撐得起極大規模，但 Tinder 仍要自己設計 key、處理 cache miss、控制 client 行為。ElastiCache for Redis 7.1 在 r7g.4xlarge 上單 node 可達約 100 萬 RPS、單 cluster 約 5 億 RPS（引自 AWS Database Blog）——這個吞吐是 AWS 給的，但用不用得好取決於你的 key 分布與 client 設計。

理解 ElastiCache 就是劃清這條責任邊界。本文按 shared responsibility 展開：AWS 管什麼、你管什麼、邊界上的踩坑在哪。

核心概念：shared responsibility 的兩側

ElastiCache 的責任劃分可以列成一張清楚的表，這張表是判讀所有 ElastiCache 事故的起點：

左欄是用 managed 換到的，右欄是用 managed 換不掉的。2.C9 cache stampede 的雪崩、連線風暴、eviction 選錯 在 ElastiCache 上跟自管 Redis 一模一樣會發生——因為這些是 cache 使用方式的問題，不是運維的問題。

engine 選擇與 cluster mode

ElastiCache 的兩個結構性決策：

engine：2024 起 default 是 Valkey（成本約低 20%、OSI 開源、Redis 7.2.4 fork、API 相容）；Redis OSS 仍可選但 AWS 不推；Memcached 是另一條線（純 KV、無 cluster mode 概念）。新部署或既有 Redis 遷移都走 Valkey（相容、便宜），純 cache 才考慮 Memcached。

cluster mode：disabled 是 1 primary + 最多 5 replica、單 shard、上限約 340GB；enabled 是多 shard（最多 500）、自動 sharding、橫向擴展。判讀：dataset < 300GB 且不需 sharding 用 disabled（簡單），> 300GB 或要橫向擴展用 enabled（但 client 要 cluster-aware）。

配置：建立與治理的設定路徑

 1# 建立 Valkey replication group（Multi-AZ、auto failover、cluster mode disabled）
 2aws elasticache create-replication-group \
 3  --replication-group-id prod-cache \
 4  --replication-group-description "prod cache" \
 5  --engine valkey \
 6  --cache-node-type cache.r7g.large \
 7  --num-cache-clusters 3 \           # 1 primary + 2 replica
 8  --automatic-failover-enabled \
 9  --multi-az-enabled \
10  --snapshot-retention-limit 7 \     # 自動 snapshot 保留 7 天
11  --at-rest-encryption-enabled \
12  --transit-encryption-enabled
13
14# 自訂 parameter group（maxmemory-policy 等仍是你的責任）
15aws elasticache create-cache-parameter-group \
16  --cache-parameter-group-name prod-params \
17  --cache-parameter-group-family valkey8 \
18  --description "prod cache params"
19aws elasticache modify-cache-parameter-group \
20  --cache-parameter-group-name prod-params \
21  --parameter-name-values "ParameterName=maxmemory-policy,ParameterValue=allkeys-lru"

配置判讀：

• --automatic-failover-enabled + --multi-az-enabled 是 HA 的核心，把 Sentinel 那條 failover 時序鏈託管掉
• maxmemory-policy 透過 parameter group 設定——AWS 給旋鈕、選哪個是你的責任（見 eviction 調校）
• --transit-encryption-enabled 加 TLS，但 TLS 增加 client 建連成本，連線池更重要
• IAM authentication（Redis 7+）取代 AUTH password，對應 security 模組

Production 故障演練

Case 1：failover 期間 client 持續 error

徵兆：ElastiCache 觸發 failover（看 describe-events），AWS 端 replica 晉升完成，但 application 持續 30 秒到幾分鐘大量連線 error。

根因：failover 時 primary endpoint 的 DNS 切到新 primary，但 client 的連線池還握著舊 primary 的連線、DNS 也可能有快取。AWS 完成了 failover，但 client 重連是你的責任——ElastiCache 不會幫你的 application 重連。

修法：

1. client 用支援自動重連的 library，設合理的 socket timeout 與 retry（見 連線調校）
2. 連到 primary endpoint（會跟著 failover 更新 DNS），不要連到特定 node 的 endpoint
3. 縮短 client 的 DNS 快取 TTL，讓 failover 後的 DNS 切換更快被看到
4. failover 期間的寫入中斷無法完全避免（非同步複製 + 重連時間），latency-sensitive 服務要設計降級

Case 2：跨 AZ replication lag 造成 stale read

徵兆：寫入 primary 後立刻從 replica 讀，偶爾讀到舊值；CloudWatch 的 ReplicationLag 在高寫入時段上升。

根因：ElastiCache 的跨 AZ 複製是非同步的，replica 有 lag。AWS 保證複製會發生，但不保證即時——read-from-replica 在寫後立即讀的場景會看到 stale window。這跟自管 Redis 的 replica 行為一致，managed 沒有消除它。

修法：

1. 寫後需要立即一致讀的路徑，強制 read from primary
2. 監控 CloudWatch ReplicationLag，持續高代表寫入超過複製能力，要 scale up node 或降寫入
3. 接受 cache 的最終一致性——這是 cache copy 的本質，不是 bug（見 cache copy boundary）
4. 需要強一致 + durability 走 MemoryDB（見本文 Capacity / cost 邊界段）

Case 3：Serverless 計費超出預期

徵兆：用了 ElastiCache Serverless 想省容量規劃，月底帳單遠超預期。

根因：Serverless 按 ECPU（運算）+ storage 計費，流量尖峰或低效的 access pattern（大量小命令、大 value）會推高 ECPU 消耗。Serverless 解的是「不想規劃容量」，不是「一定更便宜」——可預測的穩態流量用 node-based + Reserved Instance 通常更省。

修法：

1. 流量可預測、穩態高的 workload 用 node-based + Reserved Instance（1/3 年承諾、折扣約 30-60%）
2. 流量不可預測、有大量閒置時段的才適合 Serverless
3. 監控 ECPU 消耗，找出推高成本的 access pattern（用 pipeline 合併小命令降 ECPU）
4. 成本模型對比要算實際 workload，不要假設 Serverless 一定划算

Case 4：cluster mode enabled 但 client 不是 cluster-aware

徵兆：建了 cluster mode enabled 的 cluster，application 連線報 MOVED redirect 或連不上某些 key。

根因：cluster mode enabled 把 keyspace 分到多 shard，client 必須 cluster-aware（懂 CLUSTER SLOTS、處理 MOVED/ASK redirect）才能正確路由。普通 standalone client 連 cluster mode enabled 會失敗。

修法：

1. cluster mode enabled 一律用 cluster-aware client（連 configuration endpoint 不是單一 node）
2. 確認 application 的多 key 操作用 hash tag 把相關 key co-locate 同 slot（見 cluster re-sharding）
3. dataset < 300GB 且不需 sharding，用 cluster mode disabled 省掉這層複雜度
4. 從 disabled 升 enabled 是有成本的架構變更，初期規劃就要決定

Case 5：snapshot 期間記憶體尖峰、node 不穩

徵兆：自動 snapshot 時段 node 延遲上升、DatabaseMemoryUsagePercentage 衝高，偶爾 snapshot 失敗。

根因：Redis engine 的 snapshot 靠 fork（見 persistence / fork latency），fork 期間 copy-on-write 推高記憶體。如果 node 記憶體已吃緊，snapshot 的 fork 把它推爆。AWS 託管了 snapshot 排程，但 fork 的記憶體成本仍在 engine 層存在。

修法：

1. node 記憶體留 headroom（不要長期 > 80%），給 snapshot 的 fork copy-on-write 空間
2. snapshot window 設在低流量時段，減少 fork 期間被改的 page
3. 監控 CloudWatch DatabaseMemoryUsagePercentage，> 80% 考慮 scale up node type
4. Valkey engine 繼承 Redis 的 fork 模型，這個成本換 engine 到 Valkey 也還在（fork-less 要 DragonflyDB、但 ElastiCache 不提供）

Capacity / cost 邊界

ElastiCache 的容量判讀，混合了 AWS 的 metric 與 engine 層的行為：

撞牆後的路由判斷：

• 需要 source-of-truth 的 Redis API（不是 cache）：ElastiCache 是 cache 語意（資料可重建）。需要 durability 走 AWS MemoryDB——Redis-compatible 但有 multi-AZ transaction log、提供 source-of-truth 語意，成本約 ElastiCache 的 2-3 倍。判讀：Tubi 把 feature store 從 ScyllaDB 遷到 ElastiCache 的前提是「feature 可重新計算」——可重建選 ElastiCache，不可重建選 MemoryDB 或 database。
• 跨雲 / 不在 AWS 生態：ElastiCache 綁 AWS，跨雲走自管 Redis / Valkey 或 GCP Memorystore / Azure Cache。
• 極端單機 throughput：要榨單機多核走自管 DragonflyDB（ElastiCache 不提供 Dragonfly engine）。
• 跨 region active-passive DR：ElastiCache 的 Global Datastore（1 primary region + 多 secondary read replica、跨 region lag < 1 秒），不支援 active-active multi-master。

整合 / 下一步

ElastiCache 的 deep article 本質是「劃清 managed 邊界」，它跟 engine 層的調校知識緊密相連：

• 跟 Redis 全系列 deep article：eviction、persistence/fork、連線的調校在 ElastiCache 上仍適用（engine 是 Redis/Valkey），AWS 託管的是 failover/patching/snapshot 排程，不是這些 engine 行為。
• 跟 Valkey 相容性：ElastiCache 的 default engine 就是 Valkey，相容性與 io-threads 的判讀直接適用。
• 跟 Netflix EVCache：EVCache 是 Netflix 自管的 Memcached-based 全域 cache，對照 ElastiCache for Memcached + Global Datastore——展示了自管跨區 vs managed 跨區的取捨。
• 跟 Tinder / Tubi：兩個 ElastiCache 規模化案例，一個是 sub-ms 配對引擎、一個是 ML feature store p99<10ms，都展示了「AWS 給吞吐、你給設計」的邊界。

相關連結

• 上游 vendor 頁：AWS ElastiCache
• engine 層 deep article：Redis 記憶體與淘汰、persistence 與 fork latency、Sentinel 與 failover 時序、Valkey 相容性
• 上游能力：0.6 成本取捨、cache copy boundary
• Methodology：Vendor 深度技術文章寫作方法論

本文是 Caffeine overview 的 implementation-layer deep article。選型層（Caffeine vs Redis、process-local 的定位）見 overview；本文只處理「決定用 L1 Caffeine + L2 Redis 後，跨實例一致性怎麼處理」。API 以 Caffeine wiki 為準、最後檢查日 2026-06-16。

兩層 cache 搭起來容易，難的在後面

L1 Caffeine + L2 Redis 的兩層 cache，讀寫路徑三十行 Java 就寫完：讀的時候先查 L1（process-local、奈秒級），miss 再查 L2（Redis、毫秒級），再 miss 才回源。它擋掉了大部分 Redis 的網路往返，對「每個請求重複讀同一份小資料」的場景效果立竿見影。

真正的難度不在搭兩層，在「每個 JVM 實例有自己的 L1 副本」這個事實。假設有 10 個 application 實例，就有 10 份獨立的 Caffeine cache。實例 A 更新了某個 user 的資料、寫進 L2 Redis，但實例 B、C、D… 的 L1 還握著舊值——它們不知道資料變了。下一個打到實例 B 的請求，L1 命中，回的是舊值。Redis 是對的，但讀不到 Redis，因為 L1 先攔截了。

這就是兩層 cache 的核心問題：L1 的速度來自「不跟任何人協調」，而一致性恰恰需要協調。本文聚焦這個矛盾——兩層讀寫路徑只是背景，跨實例 invalidation 才是全部的工程量。

核心概念：L1 的 stale 從哪裡來

兩層 cache 的一致性問題，根源是 L1 的三個特性：

L1 是 per-instance 的私有副本。Caffeine 活在 JVM heap 內，每個實例一份。這是它快的原因（無網路、無序列化），也是它難一致的原因（無法被其他實例直接更新或清除）。L2 Redis 是共享的，所以 L2 一致相對容易；L1 才是 stale 的來源。

寫入只更新本地 L1 + 共享 L2。實例 A 處理一個更新：寫 L2 Redis（所有實例可見）+ 更新或清除自己的 L1。但 A 沒有辦法直接碰 B 的 L1——B 的 L1 還是舊的，直到它自己過期或被通知。

沒有通知機制，L1 只能靠 TTL 自然過期。如果不做任何跨實例協調，L1 的 stale window 就等於 L1 的 TTL。把 L1 TTL 設短（幾秒到幾十秒）是最簡單的「容忍 stale」策略——犧牲一點新鮮度換掉協調的複雜度。需要更快失效就得主動廣播。

跨實例失效的標準解法是用 L2 Redis 的 pub/sub 當廣播通道：任一實例更新資料時，往一個 channel 發一條「key X 失效了」的訊息，所有實例訂閱這個 channel、收到就清掉自己 L1 對應的 entry。這把「各自為政的 L1」連成一個能協同失效的網。

配置：兩層讀寫 + pub/sub 失效的程式碼

兩層讀取路徑（L1 → L2 → origin）：

 1public User getUser(String id) {
 2    // L1：Caffeine、奈秒級、命中就回
 3    User u = l1.getIfPresent(id);
 4    if (u != null) return u;
 5
 6    // L1 miss → L2 Redis、毫秒級
 7    String json = redis.get("user:" + id);
 8    if (json != null) {
 9        u = deserialize(json);
10        l1.put(id, u);                 // 回填 L1
11        return u;
12    }
13
14    // L2 miss → 回源 + 雙層回填
15    u = userRepository.findById(id);
16    redis.setex("user:" + id, 300, serialize(u));  // L2 TTL 5 分鐘
17    l1.put(id, u);                     // L1
18    return u;
19}

跨實例失效（寫入時往 Redis pub/sub 廣播、所有實例清 L1）：

 1// L1 設短 TTL 當保險（廣播漏掉時的上界）
 2Cache<String, User> l1 = Caffeine.newBuilder()
 3    .maximumSize(10_000)
 4    .expireAfterWrite(Duration.ofSeconds(30))  // 廣播失效之外的兜底
 5    .build();
 6
 7// 寫入：更新 L2 + 廣播失效
 8public void updateUser(User u) {
 9    userRepository.save(u);
10    redis.setex("user:" + u.id(), 300, serialize(u));  // 更新 L2（TTL 對齊讀路徑的 300s）
11    redis.publish("cache:invalidate", u.id());   // 廣播給所有實例
12    l1.invalidate(u.id());                        // 清自己的 L1
13}
14
15// 每個實例啟動時訂閱、收到就清本地 L1
16redis.subscribe("cache:invalidate", message -> l1.invalidate(message));

關鍵：L1 的短 TTL 是廣播機制的兜底——即使某個實例漏掉一條 pub/sub 訊息（pub/sub 是 fire-and-forget、訂閱者離線會錯過），L1 最多 stale 到 TTL 過期。廣播負責「快」，TTL 負責「最終」。

Production 故障演練

Case 1：更新後其他實例持續回舊值

徵兆：使用者改了資料、自己刷新看到新值（打到處理寫入的實例），但同事看到的還是舊值（打到別的實例），且持續好幾分鐘。

根因：只更新了寫入實例的 L1 與 L2，沒有跨實例廣播。其他實例的 L1 還握著舊值、攔截了讀取、根本沒查到已更新的 L2。stale window 等於 L1 TTL（如果 TTL 設很長就是好幾分鐘）。

修法：

1. 加 Redis pub/sub 廣播失效，寫入時通知所有實例清 L1
2. 廣播之外把 L1 TTL 設短當兜底（幾秒到幾十秒），縮短漏訊息時的 stale 上界
3. 強一致需求的資料根本不該進 L1——L1 的本質就是「容忍一個 stale window 換速度」
4. 對應 cache copy boundary 的新鮮度邊界判斷

Case 2：pub/sub 漏訊息、個別實例 L1 卡舊值

徵兆：多數實例更新後正常，但偶爾某個實例持續回舊值，直到重啟或 TTL 過期。

根因：Redis pub/sub 是 fire-and-forget——訂閱者在訊息發出的瞬間若斷線（網路抖動、GC pause、重連中），就永久錯過那條失效訊息。沒有兜底的話，那個實例的 L1 會一直 stale 到 TTL。

修法：

1. L1 TTL 設短是必要兜底，不要依賴 pub/sub 100% 送達（它不保證）
2. 需要可靠失效用 Redis Streams（有 consumer group + 重放）取代 pub/sub，代價是複雜度
3. 監控各實例的 L1 命中率與 stale 投訴，個別實例異常代表漏訊息
4. 接受 pub/sub 的 at-most-once 語意，用 TTL 補足最終一致

Case 3：L1 太大撐爆 heap、Full GC 風暴

徵兆：加了 L1 後 application 的 GC 時間變長、偶發 Full GC 導致請求暫停（STW），延遲尖刺。

根因：Caffeine 預設 on-heap，L1 的 maximumSize 設太大、cache 的物件佔據大量 heap，增加 GC 掃描與回收壓力。大物件 + 大容量直接推高 old gen 佔用。

修法：

1. maximumSize 對齊 heap 預算，用 recordStats() 看實際記憶體佔用
2. 用 maximumWeight + weigher 按物件實際大小限制（不只筆數），避免大物件撐爆
3. L1 只放「小、熱、重複讀」的資料，大物件留 L2 Redis（off-heap 視角）
4. 監控 GC 時間與 old gen 佔用，L1 容量是可調的 GC 旋鈕

Case 4：L1 快取了不該快取的 per-user 大物件

徵兆：L1 命中率偏低、heap 壓力大、效果不如預期。

根因：把 per-user 的大物件或低重複率的資料放 L1。L1 的價值在「少量資料被大量重複讀」（如設定檔、熱門商品、權限表），per-user 資料每個 user 一份、重複率低、塞滿 L1 又命中率低。

修法：

1. L1 只放高重複率的共享熱資料（config、feature flag、熱門 item、權限）
2. per-user 低重複資料放 L2 Redis 就好，不要進 L1
3. 用 recordStats() 的 hit rate 驗證——L1 命中率低代表放錯資料
4. 對應 2.4 cache data shape 的存取形狀判斷

Case 5：refreshAfterWrite 與 expireAfterWrite 混淆、行為不如預期

徵兆：以為設了自動刷新、結果到期還是 miss 阻塞回源；或以為會過期、結果一直回舊值。

根因：expireAfterWrite（到期 entry 失效、下次讀 miss + 阻塞載入）跟 refreshAfterWrite（到期後第一個讀觸發背景刷新、舊值立即回、不阻塞）語意不同，混用導致行為不符預期。

修法：

1. 要「到期就不可用」用 expireAfterWrite；要「到期背景刷新、舊值先頂」用 refreshAfterWrite
2. 兩者可組合：refreshAfterWrite 短 + expireAfterWrite 長，得到「背景刷新 + 最終過期」
3. refreshAfterWrite 避免 stampede（舊值先服務、單一背景刷新），適合熱 key
4. 用 LoadingCache 的 build(key -> load) 配 refresh，行為以官方 wiki 為準

Capacity / cost 邊界

兩層 cache 的容量判讀，核心在 L1 命中率、stale window 與 GC：

撞牆後的路由判斷：

• 需要強一致 / 不能容忍任何 stale：L1 process-local 本質有 stale window，不該放這類資料。強一致只用 Redis / Valkey 共享層（甚至直接回源）。
• L1 容量需求超過 heap：on-heap Caffeine 撐不住，用 off-heap 方案（Ehcache off-heap tier）或把資料留 L2 Redis。
• 可靠失效（不能漏）：pub/sub 是 at-most-once，要可靠用 Redis Streams 的 consumer group，代價是複雜度。
• 非 JVM 服務：Caffeine 綁 JVM，其他語言用對應的 process-local cache（Go ristretto、Rust moka），兩層架構的思路相同。

整合 / 下一步

兩層 cache 的工程量集中在跨實例一致性，它跟多個議題交織：

• 跟 Caffeine overview：overview 點到「跨實例 invalidation 是固有限制」、本文展開 pub/sub 廣播 + TTL 兜底的具體解法。
• 跟 Redis connection / pipeline：L1 的價值正是消除 L2 Redis 的 RTT 稅，兩層 cache 是 RTT 優化的極致（L1 命中連網路都省）。
• 跟 2.6 high concurrency：hot key 的兩層解法（local cache + Redis）就是這個架構，L1 擋掉打在單一熱 key 的洪峰。
• 跟 Tinder：每次互動查多個 cache 的服務，L1 Caffeine 可擋掉重複讀、降低 L2（ElastiCache）的壓力與 RTT——但 per-user 配對資料重複率低、要判斷哪些放得進 L1。

相關連結

• 上游 vendor 頁：Caffeine
• L2 對照：Redis 記憶體與淘汰、Redis 連線 / pipeline
• 上游概念：2.6 high concurrency、2.7 cache copy boundary
• Methodology：Vendor 深度技術文章寫作方法論

本文是 DragonflyDB overview 的 implementation-layer deep article。選型層（為何選 DragonflyDB、BSL 授權、相容度）見 overview；本文只處理「決定用 DragonflyDB 後，多核架構怎麼用、相容邊界在哪」。命令實機驗證於 dragonfly df-v1.39.0（redis_version:7.4.0）、最後檢查日 2026-06-16；效能數字以 DragonflyDB 官方 benchmark 為準。

scale-up 還是 scale-out：一個架構賭注

把一台 32 核機器交給 Redis，Redis 的主執行緒只用得到其中一核處理命令——要榨乾這台機器，你得在同一台上跑好幾個 Redis 進程、組成 Cluster、用 hash slot 把 key 分片。多核利用變成了一個分散式系統問題（cluster re-sharding、cross-slot transaction、hash tag 治理全都來了）。

DragonflyDB 賭的是相反方向：一個進程、thread-per-core、shared-nothing，讓單機在不分片的情況下用滿所有核。它的論點是——多數「需要 Redis Cluster」的場景，真正的需求是吞吐與記憶體，不是跨機器分散；如果單機就能撐到那個規模，Cluster 的複雜度就不必付。實機可以看到這個架構：

1redis-cli INFO server | grep -E "thread_count|redis_version|dragonfly_version"
2# thread_count:8               ← 自動對齊 CPU 核數
3# redis_version:7.4.0          ← 對 client 裝成 Redis 7.4
4# dragonfly_version:df-v1.39.0

thread_count:8 在一個進程內，不是 8 個 Redis 進程組 Cluster。這就是賭注的核心：把 Redis Cluster 的水平分片，收進單一進程的垂直多核。理解 DragonflyDB 就是理解這個賭注成立的條件與它撞牆的地方。

對高吞吐單機 workload，這個賭注有現成的對照。Snap 在 multi-cloud 用 KeyDB（Redis 的 multi-threaded fork、單實例吞吐提升 5-10x）撐超高吞吐 cache，正是「不想為了多核去組 Cluster」的同一類需求；DragonflyDB 是這條路線更激進的版本（從零用 C++ 重寫、不是在 Redis 上加 thread）。

核心概念：thread-per-core 與 shared-nothing

DragonflyDB 的多核不是「多個執行緒搶同一份資料」，而是把資料切給各個執行緒、彼此不共享——這是它能線性擴展到多核的關鍵。

thread-per-core + 資料分區。每個 thread 綁一個核，keyspace 被 hash 切成多個 slice，每個 slice 只由一個 thread 擁有。一個命令進來，被路由到擁有該 key 的 thread 處理。因為一個 key 只有一個 thread 碰，單 key 操作不需要鎖——這消除了 Redis 多執行緒方案最大的開銷（lock contention）。

dashtable 取代 Redis 的 dict。DragonflyDB 用自製的 dashtable（一種 hash table）取代 Redis 的 dictionary，記憶體佈局更緊湊、resize 時不需要像 Redis 那樣漸進式 rehash 全表，同樣的 dataset 通常比 Redis 省 20-40% 記憶體（依資料形狀，以官方 benchmark 為準）。

fork-less snapshot。Redis 的持久化靠 fork()，大記憶體下會凍結主執行緒並讓記憶體接近翻倍（見 Redis persistence deep article）。DragonflyDB 不用 fork——它用自己的快照演算法在不複製整個進程的前提下做一致性快照，大記憶體場景不付 fork 的延遲尖峰與記憶體翻倍代價。這是它對「fork 是 Redis 結構性瓶頸」這個痛點的直接回答。

多執行緒的代價：沒有 Redis Cluster mode。資料分區在單進程內，DragonflyDB 不提供 Redis Cluster mode（它的哲學是單機撐大、不跨機器分片）。這個取捨決定了它的相容邊界與容量天花板，是後面踩坑的根源。

配置：多核與持久化的設定路徑

1docker run -d --name dragonfly -p 6379:6379 \
2  docker.dragonflydb.io/dragonflydb/dragonfly \
3    --threads 8 \              # thread 數、預設等於 CPU 核數（一般不需手動設）
4    --maxmemory 4gb \          # 記憶體上限、行為類似 Redis maxmemory
5    --cache_mode true \        # 純 cache 模式：記憶體滿時自動 evict（類似 allkeys-lru）
6    --snapshot_cron "0 3 * * *" # fork-less snapshot 排程（cron 格式、這裡每天 3 點）

調校判讀：

• --threads 預設對齊 CPU 核數，多數情況不需手動設；設小於核數會浪費核，設大於核數沒有意義
• --cache_mode true 讓 DragonflyDB 在記憶體滿時自動淘汰（純 cache 行為）；不開則記憶體滿時拒絕寫入（類似 Redis noeviction）
• --maxmemory 留 headroom，但因為 fork-less，headroom 不需要像 Redis 留那麼多給 fork copy-on-write
• snapshot 用 --snapshot_cron 排程，fork-less 機制讓大記憶體快照不產生延遲尖峰

Production 故障演練

Case 1：client 配 Cluster mode、連不上

徵兆：從 Redis Cluster 遷來，application 的 client library 還配著 cluster mode，連 DragonflyDB 報錯或 hang，CLUSTER 相關命令行為不如預期。

根因：DragonflyDB 不提供 Redis Cluster mode（單進程多核、不跨機器分片）。cluster-aware client 會嘗試 CLUSTER SLOTS 之類的拓樸發現，跟 standalone 的 DragonflyDB 對不上。

修法：

1. client 改回 standalone 配置（不要 cluster mode）
2. 評估原本用 Cluster 的理由：若是為了多核吞吐，DragonflyDB 單進程多核已涵蓋，不需要 cluster mode
3. 若原本用 Cluster 是為了超過單機的容量 / 跨機器分散，DragonflyDB 的 scale-up 模型撐不住，該留在 Redis Cluster
4. 確認 application 沒有依賴 cluster-specific 行為（hash tag 的跨 slot 語意等）

Case 2：某些 Redis 命令 / module 不支援

徵兆：核心 SET/GET/HASH 等正常，但某個命令報 unknown command 或行為跟 Redis 不同，特別是 module 命令（RedisJSON / RedisSearch）與部分冷門命令。

根因：DragonflyDB 相容大多數 Redis 命令但不是 100%；它宣稱相容 redis_version:7.4.0，但部分 module、部分冷門命令、部分 Lua 行為有差異。

修法：

1. 遷移前盤點 application 用到的命令，對照 DragonflyDB 的 API 相容清單（官方 docs）
2. module 重度依賴（RedisJSON / RedisSearch）要特別確認——DragonflyDB 的 module 生態比 Redis 淺
3. Lua script 行為差異要實測，不要假設跟 Redis 完全一致
4. 相容性是遷移的主要風險，跟 Valkey 的相容性驗證同理但 DragonflyDB 邊界更寬（重寫而非 fork）

Case 3：thread 沒對齊核數、多核優勢沒發揮

徵兆：吞吐沒有達到預期、CPU 使用率不均（部分核閒置），thread_count 跟機器核數對不上。

根因：--threads 被手動設成小於 CPU 核數，或容器的 CPU limit 限制了實際可用核數，DragonflyDB 沒能用滿所有核。

修法：

1. redis-cli INFO server | grep thread_count 確認 thread 數對齊實體核數
2. 容器環境確認 CPU limit 沒有卡住 DragonflyDB 的核數（cgroup CPU quota）
3. 不要手動把 --threads 設小，預設對齊核數就是最佳
4. 吞吐沒到預期也可能是 workload 本身（大命令、網路 RTT），用 連線 / pipeline 的 RTT 分析交叉判斷

Case 4：跨 partition 的多 key 操作有額外成本

徵兆：大量多 key 命令（MGET 跨很多 key、跨 key 的 Lua）的延遲比預期高，單 key 操作則很快。

根因：shared-nothing 下 key 分散在不同 thread，多 key 操作要跨 thread 協調——單 key 免鎖的好處在多 key 跨 partition 時要付協調成本。這跟 Redis Cluster 的 cross-slot 是類似的本質（資料分散的代價），只是發生在單進程內。

修法：

1. 高頻的多 key 操作盡量讓 key 落在同 partition（DragonflyDB 的 key 分布規則）
2. 評估能否用單 key 結構（hash）取代多個 key 的聚合
3. 跨 partition 協調是分區架構的固有成本，不是 bug，量大時要設計繞過
4. 對照 Redis Cluster 的 cross-slot 限制，兩者都是「資料分散換吞吐」的代價

Case 5：BSL 授權踩到商業使用限制

徵兆：準備把 DragonflyDB 包成對外的 managed service 提供給客戶，法務 review 卡關。

根因：DragonflyDB 用 BSL（Business Source License），商業使用受限——具體限制是不可把 DragonflyDB 當成 managed service 對外提供（4 年後該版本轉 Apache 2.0）。內部使用無限制，但 SaaS 對外提供 DragonflyDB 即服務受限。

修法：

1. 內部使用（多數企業場景）無限制，直接用
2. 要把 DragonflyDB 當 managed service 對外賣，聯絡 DragonflyDB 取得商業 license
3. 開源合規敏感（公部門 / 企業 OSI 政策）走 OSI 認可的 Valkey（BSD）
4. 授權法律解讀諮詢法務，不要憑技術判斷

Capacity / cost 邊界

DragonflyDB 的容量判讀，核心在 scale-up 的天花板與多核效率：

撞牆後的路由判斷：

• 超過單機容量、需要跨機器分散：DragonflyDB 的 scale-up 賭注在這裡輸——它沒有 Cluster mode。要跨機器分片走 Redis / Valkey Cluster。
• 需要 OSI 認可開源授權：BSL 不是 OSI 認可，合規敏感走 Valkey（BSD）。
• 不想自管：DragonflyDB 目前沒有 fully managed offering（無 ElastiCache for Dragonfly），必須自管。要 managed 走 ElastiCache（Redis / Valkey / Memcached）。
• 跨 AZ / 跨 region HA：DragonflyDB 有 replica 模式（primary-replica）跨 AZ 可行，但跨 region 需自建——大規模跨區走 managed 的 Global Datastore。

整合 / 下一步

DragonflyDB 的定位是「Redis 相容 + 激進多核」，它在 Redis 相容服務的光譜上有明確座標：

• 跟 Valkey：兩者都打「Redis 相容 + 更好的多核」，但 Valkey 是 fork（同源、最高相容、漸進加 thread），DragonflyDB 是 C++ 重寫（相容核心但架構激進、多核更徹底）。相容度要極致選 Valkey，多核吞吐要極致選 DragonflyDB。
• 跟 KeyDB / Garnet：KeyDB 是 Redis 的 multi-threaded fork（Snap 採用、Snap 收購後相對停滯）；Garnet 是 Microsoft 的研究型高吞吐 store（生態淺）。DragonflyDB 是這個「高吞吐 Redis 替代」群裡商業化最積極、生態最活躍的。
• 跟 Redis Cluster re-sharding：如果你的 Redis Cluster re-sharding 頻繁觸發、運維負擔重，DragonflyDB 的 scale-up 模型可能用單機取代整個 Cluster——這是評估遷移的主要動機。
• 跟 Shopify write-through：write-through 在 DragonflyDB 上行為一致，但單進程多核能承接比單 Redis 進程更大的 throughput，是 read-heavy + write-through 場景的 scale-up 選項。

相關連結

• 上游 vendor 頁：DragonflyDB
• 對照 vendor：Valkey 相容性與 io-threads、Redis persistence 與 fork latency（fork-less 對照的痛點）
• 相關 migration：Redis → DragonflyDB
• Methodology：Vendor 深度技術文章寫作方法論

本文是 Google Cloud Pub/Sub overview 的 implementation-layer deep article。選型層（Pub/Sub vs Kafka / SQS）見 overview；本文只處理「決定用 Pub/Sub 後，subscription 與 ack 怎麼設」。Pub/Sub 是 managed SaaS、無法本機 docker 驗證，本文 config 依 Pub/Sub 官方文件 與下列 production case、最後檢查日 2026-06-16；引數與計費以官方為準。

push vs pull 不是實作偏好

把 Pub/Sub 的 subscription 設成 push 還是 pull，常被當成「看團隊習慣」的實作選擇。但它其實是一個關於下游容量的判讀。差別在流量控制權在誰手上：push subscription 由 Pub/Sub 主動把訊息 HTTP POST 到目標 endpoint——流量節奏由 Pub/Sub 決定，尖峰時瞬間打過來；pull subscription 由 consumer 主動拉，要拉多少、多快由 consumer 自己控制。

Mercari 的 LINE 整合把這個判讀講得很具體：Braze webhook 進來轉成 Pub/Sub event，下游要呼叫 LINE API——而 LINE API 有 RPS 限制。如果用 push，Pub/Sub 會把訊息瞬間打到 worker、worker 再打 LINE、直接超過 LINE 的 RPS 上限。所以他們用 pull subscription，worker「精確控制每秒處理訊息數」來對齊 LINE 的限制。這個案例揭露的原則是——push vs pull 不是實作偏好，是「下游能不能承受 push 的流量衝擊」的判讀：下游有速率限制、處理能力有限、或需要平滑流量，就走 pull 自我節流。

本文展開 subscription 模型、ack deadline、flow control 與 dead-letter topic——這些決定了訊息怎麼被可靠地、以下游能承受的速度消費。

核心概念：subscription、ack deadline 與 flow control

Pub/Sub 把「topic（發布）」跟「subscription（訂閱）」分開，可靠消費的旋鈕都在 subscription 上。

一個 topic、多個 subscription、各自獨立。發布者發到 topic，每個 subscription 收到一份完整的訊息流、各自維護消費進度。這天然支援 fanout（多個服務各建一個 subscription）。Mercari 的另一個案例還揭露 topic 的雙重角色——它同時是「dispatch」跟「load-leveling buffer」，突發流量先進 topic 緩衝、consumer 按自己節奏消化。

ack deadline 是 Pub/Sub 版的可見性逾時。consumer 收到訊息後，有一段 ack deadline 來處理並 ack。在 deadline 內沒 ack，Pub/Sub 重新投遞（at-least-once）。跟 SQS visibility timeout 同樣是雙邊風險：太短→處理中就重投、太長→失敗後恢復慢。處理中可用 modifyAckDeadline（client library 通常自動 lease extension）延長。

flow control 限制 client 端同時持有的未 ack 量。pull subscription 的 client library 可設 max_outstanding_messages / max_outstanding_bytes——consumer 最多同時持有多少未 ack 訊息。這是 consumer 端自我節流的旋鈕，避免一次拉太多撐爆自己或下游。Mercari 對齊 LINE RPS 靠的就是這層控制。

dead-letter topic（DLT）給毒訊息出口。subscription 設 dead-letter policy（maxDeliveryAttempts + dead-letter topic）後，重投超過上限的訊息被轉到 DLT，不再阻塞後續。Mercari item feed 正是「重試多次仍失敗送 DLT、後續訊息優先處理」——避免 poison message 卡住 pipeline。

配置：subscription + ack deadline + DLT（依官方文件）

Pub/Sub 是 managed、以下 gcloud 依官方文件（未本機 docker 驗證、引數以官方為準）：

 1# 1. 建 topic + dead-letter topic
 2gcloud pubsub topics create orders
 3gcloud pubsub topics create orders-dlt
 4
 5# 2. pull subscription：ack deadline + dead-letter policy
 6gcloud pubsub subscriptions create orders-worker \
 7  --topic=orders \
 8  --ack-deadline=60 \
 9  --dead-letter-topic=orders-dlt \
10  --max-delivery-attempts=5
11
12# 3. consumer 端 flow control（client library、以 Python 為例、概念跨語言一致）
13#    flow_control = FlowControl(max_messages=100, max_bytes=10*1024*1024)
14#    subscriber.subscribe(sub_path, callback=handle, flow_control=flow_control)
15#    handle 內：處理成功 message.ack()、失敗 message.nack()
16
17# push subscription（僅當下游能承受 Pub/Sub 主動推的流量時）：
18# gcloud pubsub subscriptions create orders-push \
19#   --topic=orders --push-endpoint=https://my-svc/handler --ack-deadline=60

判讀：

• 下游有 RPS 限制 / 處理能力有限 → pull + flow control（self-throttle，Mercari 模式）
• 下游能吸收推送尖峰、要 serverless 簡單 → push
• ack-deadline 略高於處理時間；長任務靠 client library 的 lease extension
• max-delivery-attempts + DLT 給毒訊息出口

Production 故障演練

Case 1：用 push、下游被瞬間流量打爆

徵兆：流量尖峰時下游 endpoint 5xx 暴增、或下游的第三方 API 回 429（rate limited），訊息大量重投惡化。

根因：用 push subscription，Pub/Sub 把訊息瞬間 POST 到 endpoint，超過下游（或下游依賴的外部 API）的處理 / 速率上限。正是 Mercari LINE 要避開的情形。

修法：

1. 下游有速率限制改用 pull subscription + flow control，由 consumer 自我節流
2. flow control 的 max_outstanding_messages 對齊下游能承受的並發
3. push 只用在下游能吸收推送尖峰的場景
4. push 場景下游要自己擋（rate limit / 佇列），不能假設 Pub/Sub 會幫你平滑

Case 2：ack deadline 太短、訊息處理中就被重投

徵兆：同一則訊息被處理多次，尤其處理較慢時；訂閱的 redelivery 指標偏高。

根因：ack deadline 設得比處理時間短，訊息在處理途中 deadline 到期、Pub/Sub 重投。跟 SQS visibility timeout 太短同類。

修法：

1. ack deadline 設成略高於處理時間 p99
2. 用 client library 的自動 lease extension（modifyAckDeadline）處理長尾任務
3. 消費端冪等——at-least-once 本來就可能重投（見 6.12 idempotency）
4. 監控 redelivery 率，偏高代表 deadline 偏短或處理變慢

Case 3：沒設 DLT、毒訊息一直重投阻塞

徵兆：某則訊息一直失敗、一直被重投，後續訊息處理被拖慢。

根因：subscription 沒設 dead-letter policy。處理失敗（nack 或沒 ack）的訊息一再重投、沒有上限與出口，毒訊息反覆消耗 consumer。

修法：

1. 設 dead-letter policy（max-delivery-attempts + DLT），重投達上限轉 DLT
2. DLT 是另一個 topic，要有處理 / 告警流程（Mercari「送 DLT、後續訊息優先處理」）
3. max-delivery-attempts 平衡暫時性失敗重試與毒訊息隔離
4. 對照 SQS redrive：兩者都是 managed 原生 DLQ/DLT、比自建省事

Case 4：flow control 沒設、consumer 一次拉太多撐爆

徵兆：consumer 記憶體暴增 / OOM，或一次拉太多把下游打爆。

根因：pull subscription 沒設 flow control，client library 預設可能持有大量未 ack 訊息，consumer 端記憶體與下游壓力失控。

修法：

1. 設 max_outstanding_messages / max_outstanding_bytes 限制同時持有量
2. 對齊 consumer 處理能力與下游容量（Mercari 對齊 LINE RPS）
3. 監控 consumer 記憶體與未 ack 數，調 flow control 參數
4. flow control 是 pull 自我節流的核心，不設等於放棄背壓

Case 5：誤用 ordering key、吞吐受限

徵兆：開了 message ordering 後吞吐明顯下降、特定 ordering key 的訊息處理變慢。

根因：Pub/Sub 的順序保證是 per-ordering-key 的——同一個 ordering key 的訊息嚴格按序、必須序列處理（前一則 ack 才處理下一則）。把所有訊息塞同一個 ordering key 等於序列化整條流、吞吐崩。

修法：

1. ordering key 用細粒度（per-entity，如 per-user），讓不同 key 可並行
2. 不需要嚴格順序的就別開 ordering（預設無序、吞吐高）
3. 評估順序需求的真實範圍——多數場景只需 per-entity 順序，不是全域
4. 嚴格全域順序 + 高吞吐有本質衝突，重新審視需求或走 Kafka 的 partition 模型

Capacity / cost 邊界

Pub/Sub 的容量判讀（managed、無 broker 運維）：

撞牆後的路由判斷：

• 需要長期保留 + 任意 replay：Pub/Sub 有 retention（可設、seek 到時間點）但事件流長期 replay + 生態走 Kafka。
• 嚴格全域順序 + 高吞吐：Pub/Sub ordering 是 per-key 序列化，全域順序高吞吐走 Kafka partition 設計。
• 不在 GCP 生態：Pub/Sub 綁 GCP，跨雲走 Kafka / NATS 或對應雲的 managed（SQS）。
• 複雜 routing（topic exchange 式）：Pub/Sub 是 topic→subscription 扇出，複雜 routing 規則走 RabbitMQ exchange。

整合 / 下一步

push/pull 判讀與 ack 是 Pub/Sub 可靠消費的核心，它跟其他議題交織：

• 跟 3.4 consumer design：push/pull、ack deadline、flow control 是 consumer 設計的具體選項。
• 跟 6.12 idempotency / replay：at-least-once + 重投要求消費冪等。
• 跟 SQS visibility timeout：ack deadline 對應 visibility timeout、DLT 對應 redrive，兩個 managed queue 的可靠消費模型高度對位、可對照閱讀。
• 跟 webhook buffer 模式：Pub/Sub topic 當 load-leveling buffer（Mercari）對應 SQS Twilio webhook buffer——把不可控的外部 webhook 流量先緩衝再按自己節奏消化。

相關連結

• 上游 vendor 頁：Google Cloud Pub/Sub
• 對照 vendor：AWS SQS visibility timeout、RabbitMQ DLQ
• 對應案例：3.C65 Mercari LINE flow control、3.C64 Mercari item feed DLT
• 上游概念：3.4 consumer design

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

本文是 KeyDB overview 的 implementation-layer deep article。選型層（KeyDB vs Redis / DragonflyDB / Valkey、為何選 fork）見 overview；本文只處理「決定用 KeyDB active-active 後，衝突與一致性怎麼判」。命令實機驗證於 eqalpha/keydb image、最後檢查日 2026-06-16；複製機制以 KeyDB active-replication 文件 為準。

兩邊都能寫，聽起來太美好

Redis 的複製是單向的：一個 master 寫、replica 唯讀。要跨區讓兩邊都能就近寫入，Redis 本身做不到（得靠應用層分區或外部工具）。KeyDB 的 active-active 把這個限制拿掉——兩個（含以上）KeyDB 節點都是 master、都能接受寫入、互相把寫入同步給對方。對「兩個 region 都要低延遲寫入同一份 cache」的場景，這聽起來解決了所有問題。

問題藏在「兩邊同時寫同一個 key」的那一刻。active-active 沒有全域協調者來仲裁誰對誰錯，它用 last-write-wins（LWW）：比較兩筆寫入的時間戳，留下較晚的、默默丟掉較早的。多數時候沒事，但當兩個 region 在幾毫秒內各自更新同一個 key，其中一筆寫入會無聲消失——沒有錯誤、沒有日誌、application 以為自己寫成功了。

理解 KeyDB active-active 就是理解這個取捨：它用 LWW 換到了「兩邊都能寫」的可用性，代價是放棄了強一致與「不丟寫入」的保證。本文展開複製機制、衝突語意，以及哪些資料放得進這個模型、哪些放進去就是 bug。

核心概念：active-active 的複製與衝突語意

active-active 不是「分散式交易」，它是「雙向非同步複製 + LWW 衝突解決」。理解它要抓三個點：

每個節點都是 active-replica。一般 Redis replica 是唯讀的；KeyDB 的 active-replica 既接受本地寫入、又接收對方的複製流。兩個節點互相設定對方為 master，形成雙向複製環。實機看到的 role 就是 active-replica（不是 master / slave）。

複製是非同步的。本地寫入立即回 OK 給 client，之後才非同步傳給對方節點。這意味著兩個節點之間永遠有一個複製延遲窗口——在這個窗口內，兩邊看到的資料可能不同。這是 active-active 是 AP（可用性 + 分區容忍）而非 CP 的根本原因。

衝突用 last-write-wins 解決。同一個 key 在兩個節點被並發修改時，KeyDB 比較版本，保留較晚的寫入、丟棄較早的。沒有 merge、沒有 vector clock、沒有 application callback——就是比誰較晚。KeyDB 用 hybrid logical clock（HLC）排序、不是純 wall-clock，但 HLC 仍綁節點實體時鐘——時鐘不同步（clock skew）會直接影響哪一筆被判定為「較晚」。同步的是 key 的「值」不是「操作」，這也是為什麼並發 INCR 會互相覆蓋而非累加（見故障演練 Case 1）。

每筆寫入帶來源標記避免無限迴圈。A 的寫入同步給 B 後，B 不會再把它當成新寫入傳回 A（否則會無限循環）。KeyDB 用來源標記處理這個，但複製拓樸設計錯（例如環狀多節點）仍可能放大流量。

配置：兩節點 active-active 的設定路徑

實機驗證的最小雙主設定（兩個節點互相複製）：

1# 節點 A 與 B 都開 active-replica + multi-master
2docker run -d --name kdb-a --network kdbnet -p 6401:6379 \
3  eqalpha/keydb keydb-server --active-replica yes --multi-master yes
4docker run -d --name kdb-b --network kdbnet -p 6402:6379 \
5  eqalpha/keydb keydb-server --active-replica yes --multi-master yes
6
7# 互相指向對方（形成雙向複製）
8keydb-cli -p 6401 replicaof kdb-b 6379
9keydb-cli -p 6402 replicaof kdb-a 6379

實機驗證雙向同步（最後檢查日 2026-06-16）：

 1# 寫 A、讀 B
 2keydb-cli -p 6401 SET fromA hello   # → OK
 3keydb-cli -p 6402 GET fromA         # → hello   （A 的寫入同步到 B）
 4
 5# 寫 B、讀 A（雙向）
 6keydb-cli -p 6402 SET fromB world   # → OK
 7keydb-cli -p 6401 GET fromB         # → world   （B 的寫入同步到 A）
 8
 9# 確認 role 與複製鏈路
10keydb-cli -p 6401 INFO replication | grep -E "role|master_link_status|connected_slaves"
11# role:active-replica
12# master_link_status:up
13# connected_slaves:1

兩個節點都回報 role:active-replica（不是傳統的 master / slave），master_link_status:up 確認複製鏈路健康。寫入任一節點、另一節點都讀得到，這就是 active-active 的核心行為。

Production 故障演練

Case 1：並發寫同一 key、一筆寫入無聲消失

徵兆：兩個 region 的 application 各自更新同一個 user 的 cache（例如 profile），事後發現其中一個 region 的更新「沒生效」——但寫入時 application 收到的是 OK，沒有任何錯誤。

根因：active-active 的 LWW。兩筆寫入在複製延遲窗口內並發發生，KeyDB 比較時間戳保留較晚的、默默丟棄較早的。application 兩邊都以為自己寫成功了（本地確實 OK），但同步後只有一筆存活。

修法：

1. 不要讓同一個 key 被多個 region 並發寫——按 key 分區（user X 的寫入永遠路由到 region A），把多主退化成「就近讀 + 單點寫」
2. 真的需要多點寫的計數器類資料，用 CRDT 語意的結構（KeyDB 的 LWW 不適合 counter，並發 INCR 會互相覆蓋而非累加）
3. 接受 LWW 是 cache 的取捨——可重建的 cache 副本丟一筆寫入可回源重算，不可重建的資料不該放 active-active
4. 衝突無聲是最危險的——加應用層的寫入審計（不靠 KeyDB 告警）

Case 2：clock skew 讓「較晚」的判定錯亂

徵兆：明明 region B 後寫的值，最後存活的卻是 region A 先寫的值——LWW 的「後寫者勝」失效。

根因：LWW 比較時間戳，但兩個節點的系統時鐘若沒同步（clock skew），「較晚」的判定就錯了。B 的時鐘慢了 200ms，B 後寫的值帶的時間戳反而比 A 早，被判定為「較舊」丟棄。

修法：

1. 所有 KeyDB 節點強制 NTP 時鐘同步，把 skew 壓到毫秒級
2. 監控節點間的時鐘偏差，skew 超過複製延遲就有 LWW 判定錯亂風險
3. 對時間敏感的衝突，LWW 本質不可靠——時鐘永遠無法完美同步，這是 LWW 模型的固有弱點
4. 需要正確衝突解決的場景，不要用 LWW 的 active-active，改強一致儲存

Case 3：複製延遲下的 stale read

徵兆：region A 寫入後，立刻有請求打到 region B 讀同一 key，讀到舊值；幾百毫秒後再讀才是新值。

根因：active-active 是非同步複製，A 的寫入要經過網路傳到 B 才可見。在這個複製延遲窗口內，B 讀到的是 stale 值。跨 region 的延遲窗口比同 AZ 大得多。

修法：

1. 寫後需要立即一致讀的路徑，讀同一個寫入的節點（read-your-writes 綁定到寫入 region）
2. 監控節點間複製延遲，跨 region 的延遲是 stale window 的下界
3. 接受最終一致——這是 active-active 的本質，cache 場景多數可容忍短暫 stale
4. 不可容忍 stale 的資料不適合 active-active，走單寫入點 + 跨區唯讀 replica

Case 4：複製拓樸設計錯、流量放大或迴圈

徵兆：加了第三個 active 節點組成環狀後，節點間流量異常放大、CPU 升高，甚至同一筆寫入被反覆傳遞。

根因：active-active 多節點（> 2）的拓樸需要小心設計。全互連（full mesh）下每筆寫入要傳給所有其他節點、流量隨節點數平方成長；環狀拓樸若來源標記處理不當可能放大傳遞。

修法：

1. 多節點 active-active 優先用 full mesh 但控制節點數（active-active 不適合大量節點）
2. 監控節點間複製流量，異常放大代表拓樸或來源標記問題
3. 大規模多區優先考慮「每區單寫入點 + 跨區唯讀」而非全 active-active
4. active-active 的甜蜜點是 2-3 個區的雙向就近寫，不是大規模 mesh

Case 5：節點重連後的全量重同步衝擊

徵兆：一個節點短暫斷線後重連，重連瞬間 CPU / 網路尖峰，期間延遲升高。

根因：節點斷線時間過長、超過複製 backlog 能覆蓋的範圍，重連時要做全量重同步（full resync）——對方節點要產生快照（fork、見 Redis persistence 的 fork 成本，KeyDB 繼承 Redis 的 fork 機制）並傳輸整個 dataset。

修法：

1. 設足夠大的 repl-backlog-size，讓短暫斷線走部分同步（partial resync）而非全量
2. 重同步的 fork 成本跟記憶體 headroom 相關，節點要留 fork 空間
3. 監控 master_link_status，頻繁 down / up 代表網路不穩、要先修網路
4. 跨 region 的 active-active 對網路穩定性敏感，不穩的鏈路會頻繁觸發重同步

Capacity / cost 邊界

active-active 的容量判讀，核心在衝突率與複製健康：

撞牆後的路由判斷：

• 需要正確的衝突解決 / 不能丟寫入：LWW 不保證，走強一致儲存（database 模組 的 multi-region 一致性方案）或單寫入點架構。
• 需要 counter / 累加語意的多點寫：LWW 會讓並發 INCR 互相覆蓋，KeyDB active-active 不適合，改 CRDT 或單點 counter。
• 跨 region 但可接受單寫入點：用 Redis / Valkey 的單向複製（一區寫、其他區唯讀），比 active-active 簡單且無衝突。
• 大規模多區：active-active 的甜蜜點是 2-3 區，更大規模走 managed 的跨區方案（ElastiCache Global Datastore 的 active-passive）。

整合 / 下一步

active-active 是 KeyDB 區別於 Redis 的核心能力之一，但它的取捨跨多個子系統：

• 跟 KeyDB overview：overview 點到 active-active 是 last-write-wins、本文展開它什麼時候默默丟資料。
• 跟 Redis persistence / fork latency：KeyDB 繼承 Redis 的 fork 機制，節點重連的全量重同步付 fork 成本。
• 跟 cache copy boundary：active-active 的 stale window 與 LWW 丟寫入，本質是「cache 副本的新鮮度與一致性邊界」議題的多主版本。
• 跟 Snap KeyDB cross-cloud case：Snap 用 KeyDB 的主因是 cross-cloud latency 治理（cache 與 application 共置），active-active 的雙向就近寫是這類 multi-cloud 場景的工具，但要按 key 分區避開 LWW 衝突。

相關連結

• 上游 vendor 頁：KeyDB
• 對照 vendor：DragonflyDB 多核架構、Redis Sentinel failover（單向複製的 HA）
• 上游概念：2.7 cache copy boundary
• Methodology：Vendor 深度技術文章寫作方法論

本文是 Memcached overview 的 implementation-layer deep article。選型層（純 KV vs Redis data types、何時選 Memcached）見 overview；本文只處理「決定用 Memcached 後，slab 記憶體怎麼配才不會莫名淘汰」。命令實機驗證於 memcached:1.6（VERSION 1.6.42）、最後檢查日 2026-06-16；機制以 Memcached 官方 wiki 為準。

明明有記憶體、卻在 evict

Memcached 最違反直覺的故障是這樣：監控顯示 evictions 持續上升、hit rate 在掉，但 stats 算下來實際用掉的記憶體遠低於 -m 設的上限——機器明明還有空間，Memcached 卻在淘汰資料。換成 Redis 思維的人會卡住，因為 Redis 是一個共用的記憶體池，不會出現「有空間卻淘汰」。

這個現象叫 slab calcification，根因在 Memcached 的記憶體模型：它把記憶體預先切成許多固定大小的格子（slab class），每個 class 各自管自己那塊，跟 Redis 共用一個記憶體池的模型相反。記憶體一旦分配給某個 class，預設不會還回去給別的 class 用。如果你的 value 大小分布隨時間改變（早期都是小 value、後來都是大 value），早期被小 value 佔走的記憶體還鎖在小 class 裡，大 value 的 class 沒有足夠空間、開始淘汰——即使整體還有大量「屬於別人」的空閒記憶體。

理解 Memcached 就是理解這套 slab 經濟學。它用「放棄記憶體的靈活性」換到了「永不碎片化、O(1) 分配、可預測的多執行緒擴展」。這個取捨在純 cache 場景非常划算，但它的失敗模式跟 Redis 完全不同，要用 slab 的語言來判讀。

核心概念：slab allocator 的會計模型

Memcached 啟動時不會把 -m 指定的記憶體一次配掉，而是按需求以 page（預設 1MB）為單位分配給 slab class，每個 class 存放某個大小區間的 item。

slab class 與 chunk size。每個 slab class 對應一個固定的 chunk size，item 被放進「裝得下它的最小 class」。class 的 chunk size 按 growth_factor 等比成長——實機看預設值：

1printf 'stats settings\r\nquit\r\n' | nc localhost 11211 | grep growth_factor
2# STAT growth_factor 1.25
3
4printf 'set k1 0 0 5\r\nhello\r\nstats slabs\r\nquit\r\n' | nc localhost 11211 | grep -E "chunk_size|active_slabs"
5# STAT 1:chunk_size 96      ← 最小的 slab class、chunk 96 bytes
6# STAT active_slabs 1

growth_factor 1.25 表示每個 class 的 chunk size 是前一個的 1.25 倍：class 1 是 96 bytes、class 2 約 120、class 3 約 152……一路到 item 大小上限。一個 100 bytes 的 value 放不進 96 bytes 的 class 1，被放進 120 bytes 的 class 2——浪費 20 bytes。這個「向上取整到 chunk size」的浪費是 slab 模型的固有成本。

page 分配是單向的。當某個 class 需要空間，Memcached 給它一個 1MB 的 page，切成該 class 的 chunk。這個 page 預設永久屬於這個 class——這就是 calcification 的來源。-o slab_automove 與手動 slabs reassign 可以把 page 在 class 間搬移，但預設行為偏保守。

LRU 是 per-slab-class 的。淘汰不是全域的，是每個 slab class 維護自己的 LRU。所以「class 2 滿了開始淘汰、但 class 5 有空閒 page」是正常現象——淘汰看的是該 class 自己的空間，不是全域記憶體。

這三點合起來解釋了開頭的悖論：evict 發生在某個 class 內，跟全域剩餘記憶體無關。

配置：slab 與多執行緒的設定路徑

1# 啟動參數（Memcached 的調校多在啟動參數、不像 Redis 有大量 runtime CONFIG SET）
2docker run -d --name memcached -p 11211:11211 memcached:1.6 \
3  memcached \
4    -m 1024 \          # 記憶體上限 1024 MB
5    -t 4 \             # worker thread 數（多執行緒、對齊 CPU 核數）
6    -f 1.25 \          # slab growth factor（預設 1.25、調小→class 更密集→浪費更少但 class 更多）
7    -I 2m \            # 單一 item 大小上限（預設 1MB、超過要調大或拆 value）
8    -o slab_automove=1 # 自動把空閒 page 從一個 class 搬到吃緊的 class（緩解 calcification）

調校判讀：

• -m 是給 item 資料的上限，Memcached 自身的 hash table、連線 buffer 等 overhead 在 -m 之外，機器要留 headroom
• -t 對齊 CPU 核數——Memcached 從早期就是 multi-threaded，這是它跟早期單執行緒 Redis 的核心差異
• -f 調小（例如 1.08）讓 slab class 更密集、向上取整浪費更少，代價是 class 數變多、管理開銷略增
• -I 是單 item 上限，超過會 store 失敗（見故障演練 Case 3）
• slab_automove=1 是緩解 calcification 的關鍵，預設視版本而定，明確開啟較穩

Production 故障演練

Case 1：slab calcification——value 大小漂移造成假性記憶體不足

徵兆：evictions 上升、hit rate 下降，但 stats 顯示 bytes 遠低於 limit_maxbytes。stats slabs 看到某個 class 的 page 用滿在淘汰，另一個 class 有大量空閒 chunk。

根因：value 大小分布隨時間漂移。早期 value 小、記憶體被分配給小 slab class；後來 value 變大、需要大 class，但 page 已被小 class 鎖住不還，大 class 空間不足開始淘汰。整體記憶體沒滿，但「對的 class」沒空間。

修法：

1. 開 -o slab_automove=1，讓 Memcached 自動把空閒 page 從冷 class 搬到吃緊的 class
2. 手動觸發搬移：slabs reassign <src_class> <dst_class>（緊急救火用）
3. 監控 stats slabs 各 class 的 used_chunks vs total_chunks 與 stats items 的 per-class evicted，找出失衡的 class
4. 從源頭穩定 value 大小分布——序列化格式統一、避免同類資料時大時小

Case 2：chunk 向上取整浪費大量記憶體

徵兆：存的 value 總大小算起來只有 600MB，但 Memcached 報用掉接近 1GB，記憶體效率異常低。

根因：value 大小剛好落在 slab class chunk size 的「上緣之外」，被向上取整到下一個更大的 class，每個 item 浪費接近一個 growth step 的空間。例如大量 130 bytes 的 value 被放進 152 bytes 的 class，每個浪費 22 bytes，量大就顯著。

修法：

1. -f 調小（1.25 → 1.08）讓 class 粒度更細，向上取整的浪費變小
2. stats slabs 看主要 class 的 chunk_size 跟你的 value 實際大小差多少，量化浪費
3. value 設計上靠近 chunk 邊界（例如壓縮或裁剪 metadata 讓 value 剛好塞進較小的 class）
4. 浪費是 slab 模型的固有成本，純 KV 的 trade-off——換到的是永不碎片化與 O(1) 分配

Case 3：value 超過 item 大小上限、store 直接失敗

徵兆：某些大 value 的寫入回 SERVER_ERROR object too large for cache，application 端 cache 寫入靜默失敗、之後一直 miss。

根因：單一 item 超過 -I 設的上限（預設 1MB）。Memcached 設計上不適合存大 object，預設 1MB 是刻意的純 cache 邊界。

修法：

1. 確認 value 大小分布，大 value 是否真該進 Memcached（純 KV cache 不適合大 blob）
2. 必要時調大 -I（例如 -I 2m），但這會改變 slab class 結構、增加大 chunk 的記憶體佔用
3. 大 object 考慮壓縮、或拆成多個小 key、或改放適合的儲存（物件儲存 / Redis 的 hash）
4. application 端要處理 store 失敗，不要假設 set 一定成功——失敗就走 origin

Case 4：thread 數設太高、lock contention 反而拖慢

徵兆：把 -t 從 4 調到 32 想榨多核效能，throughput 沒升反降，CPU 在 system time 飆高。

根因：Memcached 的多執行緒有 per-item lock（hash bucket lock），thread 數遠超核數時，執行緒互搶 lock 與 CPU、context switch 開銷超過平行收益。

修法：

1. -t 對齊實體核數，不要超配（多數場景 4-8 已足夠，極高核機器再往上調並壓測）
2. 用實際 workload 壓測對比不同 -t 的 throughput，找拐點
3. hot key 集中時 lock contention 更明顯（同 bucket），這是資料分布問題不是 thread 數問題
4. 跨機器水平擴展（client-side consistent hashing）比單機堆 thread 更能解規模，見本文整合段

Case 5：連線數打到上限、新連線被拒

徵兆：高並發下新連線報錯或 hang，stats 的 curr_connections 接近 max_connections，listen_disabled_num 在增加。

根因：每個 client 連線佔一個 connection slot，Memcached 預設 -c 1024。大量 client（尤其沒用連線池、每請求建連）會打滿 connection 上限。

修法：

1. client 端用連線池重用連線，不要每請求建連
2. 調高 -c（例如 -c 4096），但連線本身有記憶體 overhead（在 -m 之外），要算進機器容量
3. 監控 curr_connections 與 listen_disabled_num，後者非零代表曾達上限拒絕連線
4. 連線數爆炸常是 client fan-out 問題，跨多 Memcached node 分散（consistent hashing）能攤平單 node 連線壓力

Capacity / cost 邊界

Memcached 的容量判讀，核心在 slab 效率與多執行緒擴展：

撞牆後的路由判斷：

• 需要 data types / 持久化 / distributed lock：Memcached 是純 KV、刻意不做這些。需要這些走 Redis / Valkey，這是 capability 差異不是調校能補。
• 單機容量 / throughput 不夠：Memcached 沒有 server-side cluster，靠 client-side consistent hashing（ketama）水平擴展到多 node，見整合。
• 想要 Memcached 的多執行緒 + Redis 的 data types：DragonflyDB 兼具多核與 Redis 相容，是兩者的中間點。

整合 / 下一步

Memcached 的單機很簡單，它的工程深度在「如何把多個 Memcached node 組成一個 cache 層」——而這發生在 client 端與代理層，不在 server：

• client-side consistent hashing（ketama）：Memcached server 之間互不知道彼此，sharding 由 client library 用 consistent hashing 決定 key 去哪個 node，加減 node 時最小化 key 重新分布。這是 Memcached 水平擴展的基礎。
• 跟 Meta mcrouter：Meta 的 mcrouter 是 Memcached 專屬的 protocol-aware routing proxy，把跨叢集 / 跨區的流量收斂、失效隔離、pool 管理從 client 端移到代理層——這是 Memcached 大規模治理的標準答案。
• 跟 Netflix EVCache：EVCache 基於 Memcached，Netflix 在上面加跨 AZ replication 與 client-side smart routing，補足 Memcached 沒有的跨區 HA。
• 跟 Meta TAO：TAO 底層用 Memcached 作為 social graph 的 cache 層，上層加一致性與關聯查詢——展示了純 KV 之上如何疊加語意。
• 跟 Meta CacheLib + Kangaroo：當 DRAM 的記憶體經濟撞到極限，Meta 用 CacheLib 把 cache 分層到 flash——這是 slab 記憶體經濟學的下一個邊界。

相關連結

• 上游 vendor 頁：Memcached
• 對照 vendor：Redis 記憶體與淘汰調校（jemalloc 池 vs slab class 的差異）、DragonflyDB
• 相關 migration：Redis → Memcached
• Methodology：Vendor 深度技術文章寫作方法論

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

本文是 Google Cloud Pub/Sub overview 的 implementation-layer deep article。Overview 回答「Pub/Sub 該不該選、跟 Kafka / SQS 差在哪」；本文回答「ordering key 怎麼設、DLT 怎麼擋 poison message、schema 怎麼守契約，各自踩哪些坑」。閱讀前可先讀 overview 的 ordering / DLT / schema 各段建立 context。

文中 gcloud 指令的語法以 Pub/Sub emulator 實機驗證（topic / subscription / schema / ordering key / DLT / push 各操作均跑通），標準版的雲端配額、IAM 與計費行為依官方文件。

三道治理共用同一個交付骨架

Pub/Sub 的 ordering key、dead-letter topic、schema enforcement 看似三個獨立功能，實際都掛在同一個交付骨架上：subscription 是消費進度的 first-class 抽象、訊息經 ackDeadline 控制重投、失敗訊息經投遞次數計數決定去留。理解這個骨架之後，三道治理只是骨架上的三個切面 — ordering 切的是「投遞順序」、DLT 切的是「投遞次數上限」、schema 切的是「投遞前的內容守門」。

這條骨架跟 Kafka 思路不同。Kafka 的消費進度綁在 consumer group + partition offset；Pub/Sub 的 topic 是 first-class，subscription 才是 consumer 抽象，一個 topic 可以掛 N 個 subscription、各自有獨立進度與獨立的 ackDeadline / DLT / ordering 設定。同一份 event 流，A subscription 可以開 ordering 嚴格有序、B subscription 可以不開 ordering 換吞吐，互不影響。

把這三道治理寫進一篇的理由是：它們在 production 會互相牽制。Ordering key 開了之後 DLT 的隔離行為會變（有序流裡一則 poison message 會卡住整把 key 的後續訊息）；schema enforcement 擋下的不相容 publish 不會進 DLT（根本沒進 topic）。分開讀三個官方頁面看不到這層耦合。

subscription 是 first-class：ackDeadline 與 extension

subscription 承擔「這個消費者讀到哪、還有多少沒 ack」的責任。每則訊息投遞給 subscriber 後，Pub/Sub 啟動一個 ackDeadline 倒數；倒數內收到 ack 就移除訊息、倒數結束沒收到 ack 就重投。預設 ackDeadline 是 10 秒、上限 600 秒。

 1# subscription 的 ackDeadline 預設 10 秒、retention 預設 7 天
 2gcloud pubsub subscriptions describe demo-sub
 3# ackDeadlineSeconds: 10
 4# messageRetentionDuration: 604800s   # 7 天
 5
 6# 建 subscription 時可顯式設更長的 ackDeadline 與更短的 retention
 7gcloud pubsub subscriptions create cfg-sub \
 8  --topic=demo-topic \
 9  --ack-deadline=120 \
10  --message-retention-duration=3d
11# ackDeadlineSeconds: 120
12# messageRetentionDuration: 259200s   # 3 天

ackDeadline 是一道「處理時間預算」。設太短，處理還沒完訊息就被重投，consumer 會收到重複；設太長，consumer crash 後訊息要等滿 deadline 才重投，延遲拉高。長任務不靠把 ackDeadline 一次設到 600 秒解決，而是靠 ack deadline extension：consumer 在處理中週期性發 modifyAckDeadline 把單則訊息的 deadline 往後延，處理完才 ack。

1# pull 一則但不 auto-ack，拿到 ackId
2ACKID=$(gcloud pubsub subscriptions pull demo-sub --limit=1 --format='value(ackId)')
3
4# 處理中動態延長這則訊息的 ackDeadline 到 300 秒
5gcloud pubsub subscriptions modify-message-ack-deadline demo-sub \
6  --ack-ids="$ACKID" \
7  --ack-deadline=300

實務上不手動發 modifyAckDeadline，而是用 client library 的自動 lease 管理：client 在背景對 outstanding 訊息週期性續約，直到 application code 回 ack / nack。這跟 SQS 的 visibility timeout 語意類似 — 都是「訊息正在被處理、暫時別重投」的租約 — 但 Pub/Sub 是 per-message lease + client 自動續約，SQS 是 per-receive visibility window + 手動 ChangeMessageVisibility。

ackDeadline 的陷阱在 batch 邊界。client library 常以 batch 為單位 pull，但 ackDeadline lease 是 per-message。若 application 把整個 batch 當一個工作單元處理、處理時間超過單則 ackDeadline 且 client 未對每則續約，未 ack 的訊息會被重投。Mercari 的 actionable history pipeline 揭露的正是這個 client library 行為：ack deadline 以整批 batch 為粒度運作，同批只要有一則過期或被 nack，已 ack 的訊息會跟著一起重投（3.C63）。

Push、Pull、Streaming Pull 與 flow control

subscription 有兩種交付方向，pull 之下又分 unary pull 與 streaming pull。三者對應不同的下游承壓能力。

Push 把投遞節奏交給 Pub/Sub：endpoint 回 2xx 視為 ack、回非 2xx 或逾時視為 nack 並 backoff 重投。Pull 把節奏交給 consumer：consumer 想拉才拉、拉多少自己定。Streaming pull 是 production 高吞吐場景的主力 — client library 預設用它，因為它能在單一長連線上做精細的 flow control。

flow control 是 pull 的核心優勢：consumer 用 max_outstanding_messages 與 max_outstanding_bytes 設定「同時最多持有多少未 ack 訊息」，超過上限 client 就暫停從連線拉取，等 application ack 釋放額度才繼續。這讓 consumer 能把消費速率對齊到下游能吃的速率，而不是被 broker 灌爆。

Push vs pull 不是實作偏好，是「下游能否接受 push 衝擊」的判讀。Mercari 把外部行銷 webhook（Braze）轉成 Pub/Sub event 後，下游 worker 刻意用 pull subscription 精確控制每秒處理訊息數，因為下游要呼叫的外部 LINE API 有 RPS 限制 — push 會把瞬間流量直接打到受限的外部 API（3.C65）。下游有硬性 RPS 上限時，pull + flow control 是讓消費速率可控的手段。

Ordering Key：有序的代價是吞吐

Ordering key 讓「帶同一個 ordering key 的訊息，在 subscription 端按 publish 順序投遞」。它把全域無序的 Pub/Sub 變成 per-key 有序 — 不同 key 之間仍可並行、亂序，只有同 key 內部保證順序。要生效需要兩端配合：subscription 建立時開 --enable-message-ordering，publish 時帶 --ordering-key。

1# subscription 端開啟 ordering
2gcloud pubsub subscriptions create ord-sub \
3  --topic=ord-topic \
4  --enable-message-ordering
5# describe 可見 enableMessageOrdering: true
6
7# publish 端帶 ordering key（同一 key 的訊息會保序）
8gcloud pubsub topics publish ord-topic --message=m1 --ordering-key=user-123
9gcloud pubsub topics publish ord-topic --message=m2 --ordering-key=user-123

Ordering key 的設計責任在於選對 key 的粒度。粒度太粗（例如所有訊息共用一個 key）會把整條 topic 退化成單線序列、吞吐崩塌；粒度太細（例如每則訊息一個 key）等於沒開 ordering。正確做法是按「需要保序的業務實體」選 key — 同一個 user-123 的事件要保序、不同 user 之間不需要 — 這樣並行度等於活躍 key 數，既保序又不犧牲整體吞吐。

跟 Kafka 對照能看清取捨。Kafka 用 partition + 同 key hash 到同 partition 達成保序，partition 數是固定預先規劃的並行上限；Pub/Sub 沒有顯式 partition，ordering key 的並行度是動態的、由活躍 key 數決定。代價是 Pub/Sub 的有序投遞要求同 key 訊息送到同一個內部處理單元，這個約束讓單一 ordering key 的吞吐有上限（官方標稱單 ordering key 約 1 MB/s）。

Ordering 跟 DLT 在 production 會耦合：有序流裡若一則訊息反覆失敗、Pub/Sub 為維持順序不會跳過它去投後面的訊息，整把 key 的後續訊息全卡住，直到該訊息 ack 或送進 DLT。沒開 ordering 時 poison message 只卡自己；開了 ordering 後它卡住整條 key 序列。這是下一節 DLT 要解的問題在 ordering 場景下被放大的原因。

Dead-Letter Topic：投遞次數上限決定隔離時機

Dead-letter topic 是 poison-message quarantine 在 Pub/Sub 的實作：subscription 對每則訊息計數投遞次數，超過 max-delivery-attempts 就把訊息轉發到另一個 topic（DLT），主 subscription 不再重投它，後續正常訊息得以前進。

 1gcloud pubsub topics create main-topic
 2gcloud pubsub topics create dl-topic
 3
 4gcloud pubsub subscriptions create main-sub \
 5  --topic=main-topic \
 6  --dead-letter-topic=dl-topic \
 7  --max-delivery-attempts=5
 8# deadLetterPolicy:
 9#   deadLetterTopic: projects/<proj>/topics/dl-topic
10#   maxDeliveryAttempts: 5

DLT 是 topic 不是 queue，這是 Pub/Sub 跟 SQS DLQ 的關鍵差異。SQS 的 DLQ 是另一個 queue、消費者直接 receive；Pub/Sub 的 DLT 是 topic，要再掛一個 subscription 才能讀。好處是 DLT 上可以同時掛多個 subscription — 一個給人工檢視、一個給自動 replay、一個給長期歸檔 — fan-out 內建。代價是多一層 subscription 配置，且 DLT 也有自己的 retention（同樣預設 7 天，poison message 要在這之內處理掉）。

max-delivery-attempts 設定的是「容忍多少次暫時性失敗」與「多快放棄」之間的平衡。設太低（例如 1-2 次），下游短暫抖動就把訊息丟進 DLT、誤殺可恢復的訊息；設太高（例如 50 次），一則真正壞掉的訊息會反覆重試半天、占用 consumer 資源、在有序流裡還會長時間卡住整條 key。官方允許範圍 5-100，常見起點是 5。

搭配 retry policy 的 backoff 能讓重投不至於太密集：

1gcloud pubsub subscriptions create retry-sub \
2  --topic=main-topic \
3  --min-retry-delay=10s \
4  --max-retry-delay=600s
5# retryPolicy:
6#   minimumBackoff: 10s
7#   maximumBackoff: 600s

啟用 DLT 需要把 Pub/Sub service account 授權對主 subscription 有 subscriber、對 DLT 有 publisher（emulator 不校驗 IAM，正式環境若漏授權，訊息超過 max attempts 後不會進 DLT、而是繼續留在主 subscription 重投，看起來像 DLT 沒生效）。授權細節依 GCP 官方 IAM 文件。

Mercari 的商品 feed 同步示範了 DLT 的標準用法：pull subscription + 自家 batch requester、成功 ack 整批、失敗 nack 讓 Pub/Sub 重送、重試多次仍失敗送 DLT、後續訊息優先處理；同一個 topic 還兼當突發流量的 load-leveling buffer（3.C64）。

Schema Enforcement：投遞前的契約守門

Schema enforcement 把 event schema compatibility 從「應用層約定」提升到「broker 強制」。topic 綁定一個 Avro 或 Protobuf schema 後，不符 schema 的 publish 在進 topic 前就被拒絕 — 訊息根本不會被儲存、不會投遞、不會進 DLT。

1# 1. 建 schema（Avro，一個必填 string 欄位 id）
2gcloud pubsub schemas create order-schema \
3  --type=avro \
4  --definition='{"type":"record","name":"Order","fields":[{"name":"id","type":"string"}]}'
5
6# 2. topic 綁 schema + 指定 message encoding
7gcloud pubsub topics create sch-topic \
8  --schema=order-schema \
9  --message-encoding=json

綁定後的 publish 行為（emulator 實機驗證 enforce）：

 1# 符合 schema：通過
 2gcloud pubsub topics publish sch-topic --message='{"id":"abc"}'
 3# messageIds: ['4']
 4
 5# 欄位不符 schema：被拒
 6gcloud pubsub topics publish sch-topic --message='{"wrong":123}'
 7# ERROR: INVALID_ARGUMENT: Could not parse message
 8
 9# 非 JSON 垃圾：被拒
10gcloud pubsub topics publish sch-topic --message='not-json'
11# ERROR: INVALID_ARGUMENT: Could not parse message

schema 守門的價值在於把契約破壞擋在 producer 端、而不是 consumer 端。沒有 schema enforcement 時，producer 改了 payload 結構、不相容的訊息照樣進 topic、要到 consumer 解析失敗才爆 — 此時訊息已經在系統裡流動、可能已 fan-out 到多個 subscription、修復成本高。有 schema enforcement 時，不相容的 publish 在源頭就失敗，問題暴露在「誰送了壞訊息」而不是「誰收到壞訊息」。

schema evolution 要在「擋住破壞性改版」與「不阻塞合理演進」之間取捨。新增可選欄位或帶預設值的欄位維持相容、可以平滑演進；新增必填欄位、刪欄位、改型別是破壞性改版，會讓既有 producer 或 consumer 失效。設計上先定相容性等級（backward / forward / full）再演進，刪欄位分兩步（先停用再移除），避免一次破壞性改版打掛下游。

跟 Kafka Schema Registry 對照：Kafka 的 schema 校驗在 client 端（producer / consumer 各自向 Registry 查 schema、序列化時校驗），broker 本身不認識 schema；Pub/Sub 的 schema 綁在 topic、校驗在 broker 端 publish 路徑上。前者校驗點分散、靈活但要求所有 client 守規矩；後者校驗點集中在 broker、強制但耦合到 topic 配置。

五個 Production 故障演練

deep article 的差異化價值在故障演練。以下五個徵兆對應前述三道治理在 production 的典型失效。

演練一：Ordering key 把吞吐限到單線

徵兆：開了 ordering 後整條 topic 的吞吐從數萬 msg/s 掉到數百 msg/s，subscription backlog（num_undelivered_messages）持續攀升、oldest_unacked_message_age 越拉越長，但 consumer CPU 並不滿載 — consumer 在等訊息、不是在忙。

根因：ordering key 粒度太粗。最常見是「所有訊息共用同一個 ordering key」（例如固定字串、或單一租戶 ID），整條 topic 退化成單一有序序列，並行度等於 1。單一 ordering key 的吞吐有上限（官方標稱約 1 MB/s），所有訊息擠進一個 key 就被這個上限封頂。

判讀與修法：

1. 確認 ordering key 的基數（cardinality）。gcloud pubsub topics publish 帶的 --ordering-key 在 production 是業務欄位映射來的 — 檢查映射邏輯是否塌縮成低基數。
2. 把 key 粒度對齊到「真正需要保序的業務實體」：同一筆訂單 / 同一個 user / 同一個 device 內要保序，跨實體不需要。粒度從「全域一個 key」改成「per-user 一個 key」，並行度從 1 拉到活躍 user 數。
3. 評估是否真的需要 ordering。多數 pipeline 靠 consumer 端 idempotency + 版本號就能容忍亂序，不需要 broker 層保序 — 把保序成本從吞吐換成 consumer 設計（見 3.7 event contract 的 idempotency key 段）。

演練二：Ack deadline 太短導致重複投遞

徵兆：consumer 處理邏輯正確、下游也成功，但同一則訊息被處理多次；DELIVERY_ATTEMPT 計數異常偏高、下游出現重複副作用（重複扣款 / 重複發信）。Backlog 不一定高，但「處理量」遠大於「publish 量」。

根因：ackDeadline 比實際處理時間短。預設 10 秒對「呼叫一個慢的外部 API」「處理大 payload」這類任務不夠，訊息在 application 還沒 ack 前就過了 deadline、被 Pub/Sub 重投，於是同一則訊息有多個 consumer 副本在跑。若 client library 的自動 lease extension 沒生效（例如 application 阻塞在同步呼叫、background lease thread 餓死），重投更嚴重。

判讀與修法：

1. 量測 p99 處理時間，把 ackDeadline 設到 p99 之上留 buffer，但不要不加判斷地設到 600 秒上限 — deadline 越長，consumer crash 後訊息重投的延遲越長。
2. 長任務靠 lease extension 而非長 ackDeadline：確認 client library 的自動續約有在跑，application code 不要在處理迴圈裡阻塞到讓 background 續約 thread 餓死。
3. consumer 端做 idempotency：用 message 的 dedup key（3.7）讓重複投遞變成無害 — at-least-once 交付下重複是常態，不靠調 ackDeadline 消除、靠 consumer 設計吸收。

演練三：DLT max delivery attempts 設定誤判

徵兆：兩種反向徵兆。其一，DLT 堆滿了「其實能恢復」的訊息 — 下游一抖動就被丟進 DLT，DLT backlog 暴增、人工 replay 不完。其二，主 subscription 卡著一則壞訊息反覆重投半天都不進 DLT、後面訊息（尤其在 ordering 流裡）全堵住。

根因：第一種是 max-delivery-attempts 設太低（1-2 次），暫時性失敗就被當成 poison。第二種是設太高（數十次）或根本沒設 DLT，真正的 poison message 反覆重試、占資源、卡序列。

判讀與修法：

1. 區分「暫時性失敗」與「結構性失敗」。暫時性（下游超時、限流）需要重試容忍度，結構性（payload 解析不了、業務規則永久拒絕）越早隔離越好。
2. max-delivery-attempts 起點設 5，搭配 retry policy backoff（--min-retry-delay / --max-retry-delay）讓重試之間有間隔、給下游恢復時間，而不是密集重打。
3. 確認 DLT 真的接得到訊息：檢查 Pub/Sub service account 對 DLT 的 publisher 授權（漏授權會讓訊息超過 attempts 後繼續留在主 subscription、看起來像沒進 DLT）。
4. DLT 要掛 subscription 才讀得到 — DLT 是 topic 不是 queue，建完 DLT 還要建 DLT 的 subscription 並設好 retention，否則 poison message 在 DLT 裡放滿 7 天後一樣丟失。

演練四：Push endpoint 500 觸發 retry storm

徵兆：push subscription 的下游 HTTP endpoint 開始大量回 500，Pub/Sub backoff 重投、但 endpoint 仍 500，重投量隨 backlog 累積越滾越大；endpoint 一旦短暫恢復就被積壓的重投流量瞬間打回 500，形成「恢復即再掛」的震盪。

根因：push 的 flow control 由 Pub/Sub 掌握、按 ack 動態調速 — endpoint 回 2xx 視為 ack、非 2xx 視為 nack 並重投。當 endpoint 因下游依賴（DB / 外部 API）掛掉而持續 500，Pub/Sub 的 backoff 重投跟累積的 backlog 疊加，恢復瞬間的流量遠超 endpoint 平時負載。這正是「下游能否接受 push 衝擊」的反面 — push 沒有 consumer 端的 flow control 閥門。

判讀與修法：

1. 先判訊息毒性 vs endpoint 健康。若是 endpoint 整體掛（所有訊息都 500），是容量 / 依賴問題；若是特定訊息 500（多數成功、少數失敗），是 poison message，該走 DLT。
2. endpoint 整體掛的場景，push 不是好選擇 — 改 pull + flow control，讓 consumer 用 max_outstanding_messages 把消費速率對齊到下游能吃的速率，避免恢復瞬間被積壓流量打垮（對照 3.C65 的下游 RPS 限制場景）。
3. 對 push 配 DLT，把反覆 500 的特定訊息隔離出去，避免單一 poison message 混在正常流量裡放大 retry。
4. endpoint 側對「Pub/Sub 重投」做 idempotency，因為 push 也是 at-least-once、500 後的重投會帶來重複。

演練五：Schema enforcement 擋下不相容 publish

徵兆：某次 producer 部署後，該 service 的 publish 開始大量回 INVALID_ARGUMENT: Could not parse message，訊息發不出去；但 consumer 端風平浪靜、沒有任何解析錯誤、backlog 也沒異常。

根因：這通常不是故障、是 schema enforcement 正常運作。producer 改了 payload 結構（加必填欄位 / 改型別 / 漏欄位），新 payload 不符 topic 綁定的 schema，broker 在 publish 路徑上擋下、訊息根本沒進 topic。徵兆出現在 producer 端（publish 失敗）而非 consumer 端（解析失敗），正是 schema 守門把問題前移到源頭的設計意圖。

判讀與修法：

1. 先確認是「該擋」還是「誤擋」。對照 producer 的新 payload 與 topic schema：若是破壞性改版（加必填欄位 / 改型別），enforcement 擋對了 — 該回滾 producer 或先演進 schema。
2. 用 gcloud pubsub schemas validate-message 在部署前 dry-run 校驗 payload 對 schema，把「不相容」暴露在 CI 而不是 production publish。
3. schema 演進走相容路徑：新增欄位帶預設或設可選、刪欄位分兩步、避免一次破壞性改版。先升 schema 再升 producer，順序反了就會出現這個徵兆。
4. 區分 schema enforcement 失敗與 DLT：schema 擋下的訊息不進 topic、不進 DLT（DLT 隔離的是「進了 topic 但消費反覆失敗」的訊息）。兩者是交付管線的不同關卡，徵兆與修法都不同。

容量與選型邊界：標準版 vs Pub/Sub Lite

前述配置適用標準版 Pub/Sub。標準版的計費與容量模型偏向「全域路由內建、按用量計費、不需預先規劃容量」；當吞吐極高且 region 確定時，Pub/Sub Lite 的 partition-based / zonal 模型成本更低。

Pub/Sub Lite 是獨立的 CLI surface（gcloud pubsub lite-topics / gcloud pubsub lite-subscriptions），不是標準版的一個 flag。選 Lite 的代價是要自己 provision partition 數與 throughput capacity（回到接近 Kafka 的容量規劃），換來的是高吞吐穩定流量下顯著更低的成本。判準是吞吐「夠高且夠穩定到值得自己管容量」— 流量彈性大、或不想管 partition 的場景仍該留在標準版。

Spotify 的 autoscaling 案例揭露 backlog 不等於 consumer healthy：下游 export 失敗時 consumer 不 ack 仍持續耗 CPU，autoscaling 把 CPU 越拉越高、反而擴出更多空轉 consumer；解法是 exponential backoff 抑制 CPU 消耗（3.C61）。容量規劃的 autoscale signal 要看「處理成功率」而非「CPU + backlog」，否則擴縮方向會反。

整合與下一步

BigQuery / Cloud Storage subscription：免 consumer 的落地路徑

標準版提供兩種「不需要自寫 consumer」的 subscription，直接把訊息落地到分析 / 儲存層：

• BigQuery subscription（--bigquery-table）：訊息直接寫進 BQ table，免 Dataflow 中介，適合 streaming analytics。可搭配 --use-topic-schema 讓 BQ table schema 對齊 topic schema — schema enforcement 在這裡延伸成「落地結構也受契約約束」。
• Cloud Storage subscription（--cloud-storage-bucket）：訊息批次寫成 GCS object，適合 data lake / 歸檔。

這兩種 subscription 把「event 流 → 分析 / 儲存」的常見管線收進 Pub/Sub 配置，省掉一層自管 consumer。它們仍受同一套 ackDeadline / DLT 骨架管轄。

Cross-link

• 上游 vendor 頁：Google Cloud Pub/Sub overview — 選型層、跟 Kafka / SQS 取捨
• 契約與重播邊界：3.7 Event Contract 與 Replay Boundary — schema / idempotency key / replay window 先於 broker 選型
• 知識卡：Event Schema Compatibility（schema enforcement 守的契約等級）、Poison-Message Quarantine（DLT 的隔離機制）
• 對應 case：3.C64 Mercari Item Feed DLT、3.C65 Mercari LINE flow control、3.C61 Spotify autoscaling、3.C63 Mercari actionable history
• 方法論：Vendor 深度技術文章的寫作方法論

何時 revisit

• ordering key 吞吐撞上單 key 上限、且無法再細分 key：評估改用 Kafka partition 模型，或把保序成本移到 consumer 端 idempotency
• 高吞吐穩定流量 + 成本壓力浮現：評估標準版 → Pub/Sub Lite，接受自管 partition 容量換成本
• schema 需要跨多 vendor 共用契約（同一份 event 同時進 Pub/Sub 與 Kafka）：評估把 schema source of truth 抽到 broker 外的 registry

本文是 RabbitMQ overview 的 implementation-layer deep article。選型層（RabbitMQ vs Kafka / SQS、何時選 RabbitMQ）見 overview；本文只處理「決定用 RabbitMQ 後，失敗訊息怎麼 retry 才不會卡死隊列」。DLX 拓樸實機驗證於 rabbitmq:3-management、最後檢查日 2026-06-16；機制以 RabbitMQ DLX 官方文件 為準。

失敗訊息 requeue 回隊首，會卡住整條隊列

消費一則訊息失敗了——下游 API 超時、資料還沒就緒、暫時性錯誤。最直覺的處理是 nack 加 requeue=true，讓它重新排隊再試一次。問題是 RabbitMQ 的 requeue 把訊息放回原隊列的隊首，於是它立刻又被同一個 consumer 取出、再次失敗、再 requeue……在「下游還沒恢復」的那段時間裡，這則訊息反覆佔據隊首，後面所有正常訊息全被卡住。這就是 head-of-line blocking：一則毒訊息（poison message）拖垮整條隊列。

Indeed 每天處理 35M+ 職缺訊息，原本的架構正是把失敗訊息 requeue 回隊首，造成阻塞。他們的解法是設計 Requeue → Delay queue → Dead Letter Queue 三層 escalation：retry 幾次後讓訊息進延遲隊列（隔一段時間再試）、再失敗幾次才進 DLQ（停止重試、留待人工或專門處理）。這個案例揭露的核心原則是——retry 策略要跟隊列拓樸一起設計，不是純 client 端的 backoff。

本文展開 RabbitMQ 實現這套分層 retry 的機制（dead-letter exchange + TTL）、實機驗證的拓樸、以及把它寫成事故的踩坑。

核心概念：dead-letter exchange 的求值模型

RabbitMQ 的失敗訊息處理建立在 dead-letter exchange（DLX）上。理解它要抓住「訊息在什麼條件下被 dead-letter、去哪裡」。

訊息在三種情況被 dead-letter。一則訊息會從它所在的隊列被轉送到該隊列設定的 DLX：(1) 被 consumer nack / reject 且 requeue=false；(2) 訊息 TTL 到期（x-message-ttl 或 per-message expiration）；(3) 隊列達到長度上限（x-max-length）被擠掉。這三種 reason 會記在訊息的 x-death header 裡。

DLX 是隊列的屬性、不是訊息的。在宣告隊列時用 x-dead-letter-exchange 指定這個隊列的「死信要送去哪個 exchange」，搭配 x-dead-letter-routing-key 指定送過去時用什麼 routing key。死信被當成一則新訊息發布到那個 exchange，再依綁定路由到 DLQ。

TTL + DLX 組出「延遲隊列」。RabbitMQ 沒有原生的延遲投遞，但可以用「一個沒有 consumer、只設 TTL + DLX 的隊列」模擬：訊息進這個隊列、躺到 TTL 到期、被 dead-letter 回工作 exchange——等於延遲了 TTL 那麼久才重新可被消費。這是分層 retry 的關鍵積木。

x-death header 累積重試歷史。每次 dead-letter，RabbitMQ 在 x-death header 追加一筆記錄（哪個隊列、什麼 reason、次數 count）。消費端讀這個 count 就能判斷「這則訊息重試幾次了」，決定要再延遲還是進 DLQ。這是實現「retry n 次後升級」的依據。

配置：work → delay → DLQ 三層拓樸

實機驗證的最小 DLX 拓樸（工作隊列的訊息 TTL 到期後 dead-letter 到 DLQ）：

 1# 宣告 DLX exchange 與 DLQ
 2rabbitmqadmin declare exchange name=dlx type=direct
 3rabbitmqadmin declare queue name=dlq
 4rabbitmqadmin declare binding source=dlx destination=dlq routing_key=app.work
 5
 6# 工作隊列：設 TTL + 指向 DLX（TTL 到期或 nack(requeue=false) 都會 dead-letter）
 7rabbitmqadmin declare queue name=app.work \
 8  arguments='{"x-message-ttl":2000,"x-dead-letter-exchange":"dlx","x-dead-letter-routing-key":"app.work"}'
 9
10# 驗證：發一則、等 2s TTL 到期、它從 app.work 搬到 dlq
11rabbitmqadmin publish routing_key=app.work payload="poison-msg"
12# 等 TTL（2s）過期後（實測等 4s 確保）：
13rabbitmqctl list_queues name messages
14# app.work   0     ← TTL 到期被搬走
15# dlq        1     ← 落到 DLQ（訊息帶 x-death header、reason=expired）

實機驗證於 rabbitmq:3-management（最後檢查日 2026-06-16）：publish 後等 TTL 過期，app.work 歸零、dlq 出現該訊息。

三層 escalation 的完整拓樸（對應 Indeed 模式）：

1app.work（主工作隊列）
2  └─ consumer nack(requeue=false) 或處理失敗
3       ↓ dead-letter 到
4app.retry（延遲隊列：x-message-ttl=30s、無 consumer、DLX 指回 app.work）
5  └─ TTL 到期
6       ↓ dead-letter 回
7app.work（再次嘗試；消費端讀 x-death count）
8  └─ 重試達上限（例如 count >= 3）→ 消費端主動 nack 到
9app.dlq（死信終點：無自動重試、人工 / 專門 consumer 處理）

判讀：

• 延遲時間靠 app.retry 的 TTL 控制；要指數退避就設多個不同 TTL 的 delay 隊列（30s / 5m / 1h）逐層升級
• 「重試幾次」由消費端讀 x-death 的 count 判斷、達上限才送終點 DLQ
• DLQ 不該有自動重試的 consumer（否則又是迴圈）；它是給人看的、或給冪等的專門修復流程

Production 故障演練

Case 1：requeue 回隊首、毒訊息卡死整條隊列

徵兆：下游短暫故障期間，整條隊列的消費停滯、consumer CPU 衝高但吞吐歸零，恢復後發現大量正常訊息延遲。

根因：失敗時用 nack(requeue=true)，訊息回到隊首被立刻重取、反覆失敗，head-of-line blocking。下游故障越久，毒訊息霸佔隊首越久。

修法：

1. 失敗一律 nack(requeue=false) 走 DLX，不要 requeue 回原隊列
2. 用 delay 隊列（TTL + DLX）讓重試隔一段時間，給下游恢復時間
3. 重試有上限，達上限進終點 DLQ，停止自動重試
4. 這正是 Indeed 案例 的核心教訓：retry 拓樸化，不要 requeue-to-head

Case 2：delay 隊列綁錯、retry 變無限迴圈

徵兆：某些訊息永遠在重試、x-death count 累積到幾百次，DLQ 卻一直是空的。

根因：delay 隊列的 DLX 指回工作隊列，但消費端沒有檢查 x-death count、或上限判斷寫錯，訊息在 work ↔ retry 之間無限往返、永遠到不了終點 DLQ。

修法：

1. 消費端每次處理前讀 x-death 的 count，超過上限就主動投遞到終點 DLQ（不再走 retry）
2. 上限判斷要涵蓋所有 retry 路徑，不要漏掉某條
3. 監控 x-death count 分布，出現高 count 訊息代表升級邏輯漏了
4. 終點 DLQ 絕對不要接會 nack-to-DLX 的 consumer，否則迴圈

Case 3：per-queue TTL 的隊首阻塞陷阱

徵兆：用 x-message-ttl 設隊列級 TTL 做延遲，但發現訊息沒有按預期時間 dead-letter，延遲時間忽長忽短。

根因：隊列級 TTL（x-message-ttl）只在訊息到達隊首時才檢查是否過期。如果用 per-message TTL 且不同訊息 TTL 不同，前面一則長 TTL 的訊息會擋住後面短 TTL 的——後者明明過期了卻因為不在隊首而沒被 dead-letter。

修法：

1. delay 隊列用統一的隊列級 TTL（同一個 delay 隊列裡所有訊息延遲時間相同），不要在同隊列混用 per-message TTL
2. 要多種延遲時間就開多個 delay 隊列（每個固定 TTL），不要靠 per-message TTL
3. 理解 TTL 是「到隊首才檢查」的惰性求值，不是精準定時器
4. 需要精準排程的延遲用專門的 delay 機制（rabbitmq-delayed-message-exchange plugin），不靠 TTL 模擬

Case 4：DLX 沒綁好、死信靜默消失

徵兆：訊息明明該 dead-letter，但 DLQ 一直收不到，訊息憑空消失。

根因：DLX exchange 存在、隊列也設了 x-dead-letter-exchange，但 DLX 到 DLQ 的 binding 不存在或 routing key 對不上。死信被發布到 DLX 後沒有任何隊列接收（unroutable），直接被丟棄。

修法：

1. 確認 DLX → DLQ 的 binding 存在且 routing key 匹配（x-dead-letter-routing-key 對上 binding key）
2. 沒設 x-dead-letter-routing-key 時死信沿用原 routing key，binding 要對應原 key
3. 給 DLX 設 alternate exchange 或在 DLX 上掛一個 catch-all 隊列，避免 unroutable 死信靜默消失
4. 監控 DLX 的 unroutable / drop 指標，死信消失是嚴重的資料遺失

Case 5：DLQ 無上限成長、變成第二個問題

徵兆：DLQ 累積到幾十萬則訊息、記憶體吃緊，沒人處理。

根因：DLQ 是終點但沒有處理流程——訊息一直進、沒人消費，DLQ 變成一個越長越大的垃圾堆，最終吃光 broker 記憶體（classic queue 訊息在記憶體）。

修法：

1. DLQ 要有處理流程：告警 + 人工 / 自動修復 consumer（冪等地重新投遞或記錄）
2. DLQ 設 x-max-length 或自己的 TTL，避免無限成長（但要先確認丟棄可接受）
3. 監控 DLQ 深度與成長速率，持續成長代表上游有系統性失敗、要根治而非堆 DLQ
4. quorum queue 對 DLQ 是合理選擇（持久、不純靠記憶體），見 quorum vs mirrored queue deep article

Capacity / cost 邊界

分層 retry 拓樸的容量判讀：

撞牆後的路由判斷：

• 重試量大、delay 隊列堆積：重試治標、下游系統性故障要根治；考慮 circuit breaker 在上游擋住而非無限重試。
• 需要精準延遲排程：TTL 模擬的延遲不精準（惰性求值），用 rabbitmq-delayed-message-exchange plugin。
• DLQ / 隊列要持久可靠：classic queue 靠記憶體 + 鏡像，大量積壓有風險；用 quorum queue（Raft 持久）。
• 吞吐 / 保留需求超過 RabbitMQ：retry / replay 是 log-based broker 的強項，大規模 replay 走 Kafka（consumer 各自 offset、可重讀）。

整合 / 下一步

分層 retry 是 RabbitMQ 可靠消費的核心，它跟其他議題交織：

• 跟 3.2 durable queue：DLQ 要持久才不會在 broker 重啟時丟失死信。
• 跟 3.4 consumer design：prefetch / ack 策略決定毒訊息影響範圍，跟 retry 拓樸一起設計。
• 跟 6.12 idempotency / replay：retry 與 DLQ 重新投遞都要求消費冪等，否則重試造成重複副作用。
• 跟 quorum vs mirrored queue：DLQ 與重試隊列的持久性選 quorum queue，避開 mirrored queue 的網路成本。

相關連結

• 上游 vendor 頁：RabbitMQ
• 同 vendor deep article：quorum vs mirrored queue
• 對應案例：3.C25 Indeed delay queue + DLQ 三層 escalation
• 上游概念：3.2 durable queue、3.4 consumer design

本文是 Valkey overview 的 implementation-layer deep article。選型層（為何 fork、授權治理、何時選 Valkey）見 overview；本文只處理「決定用 Valkey 後，相容性怎麼驗、執行緒怎麼調」。命令實機驗證於 valkey/valkey:8 image（valkey_version 8.1.8）、最後檢查日 2026-06-16；效能數字以 valkey.io 官方 benchmark 為準。

「100% 相容」要能驗證才敢切

Valkey 從 Redis 7.2.4 fork、宣稱 100% API 相容、drop-in 替換——這對選型是好消息，對上線前的工程師卻是一個需要證據的斷言。把 production 的 Redis 換成 Valkey，最怕的不是「大部分指令能跑」，而是某個邊角行為、某個 client library 的版本協商、某個 module 沒有對應 fork，在切換後才浮現。相容性不能靠信任，要靠驗證。

驗證的起點是一個容易被忽略的細節：Valkey 的 INFO server 同時回報兩個版本號。

1docker exec valkey valkey-cli INFO server | grep -E "redis_version|valkey_version|server_name"
2# redis_version:7.2.4    ← client library 以此協商相容行為
3# server_name:valkey
4# valkey_version:8.1.8   ← Valkey 自身的演進線

這個雙版本回報就是相容性的機制本身：client library 看到 redis_version:7.2.4，就以 Redis 7.2.4 的協定與行為運作，完全不知道背後是 Valkey；valkey_version 才是 Valkey 自己的版本，記錄它在 fork 之後加了什麼（例如 8.x 的多執行緒）。理解這條雙線——「對外裝成 Redis 7.2.4、對內持續演進」——是判斷相容性邊界的鑰匙。

對大規模生產驗證，Tinder 的配對引擎是現成的證據：4700 萬月活、每次滑動讀多個 cache、sub-millisecond 延遲，跑在 Amazon ElastiCache for Valkey 上——這個規模的服務跑在 Valkey 上，本身就是相容性的背書。另一個訊號是 AWS 在 2024 把 ElastiCache 的 default engine 從 Redis 改成 Valkey（AWS 宣稱成本較 Redis OSS 低約 20%、以 ElastiCache 定價 為準、最後檢查日 2026-06-16）。這些都是外部背書，但各服務有自己的 client library、module 與邊角用法，仍需自行驗證。

核心概念：相容性的三層邊界

「100% 相容」在不同層次有不同的精確度，驗證要分三層做。

協定與核心指令層：完全相容。string / hash / list / set / sorted set / stream / hyperloglog / geo 的所有指令、TTL / eviction / persistence / pub-sub / transaction、RESP 協定——這層是 fork 自 Redis 7.2.4 的部分，行為一致。所有標準 Redis client library 透過 redis_version 協商，直接連、不改 code。

檔案格式層：相容。RDB 與 AOF 的檔案格式跟 Redis 7.2.4 一致，可以直接把 Redis 的資料目錄拷給 Valkey 載入——這是 drop-in 遷移的基礎，不需要 dump / reload。

生態與新功能層：要逐項確認。Redis 7.4+ 在 fork 之後新增的功能（Valkey 不一定跟進）、Redis Stack 的商業 module（RedisJSON / RedisSearch，Valkey 有自己的 valkey-search / valkey-bloom 但不是同一套）、偏 Redis Inc 的監控工具（RedisInsight 部分 vendor-specific 命令）——這層是相容性的真實風險所在，驗證要集中在這裡。

驗證的操作順序：先確認 client library 連得上且核心指令正常（第一層），再確認資料能載入（第二層），最後盤點你實際用到的 module 與 7.4+ 功能（第三層）。前兩層幾乎必過，工夫花在第三層。

配置：io-threads 多執行緒調校

Valkey 跟 Redis 7.2.4 拉開的第一個實質技術差異是執行緒模型。Redis 的命令處理是單執行緒（I/O threads 只分擔 socket 讀寫，命令仍在主執行緒），Valkey 8.x 把更多 I/O 路徑非同步化，在多核機器上能讓單實例吞吐明顯高於 Redis——具體倍數依 workload 與核數而定，以 valkey.io 官方 benchmark 為準，這裡不複述未經自己壓測的數字。

執行緒由 io-threads 控制，預設 1（單執行緒，跟 Redis 行為一致）：

1# 確認目前執行緒數（預設 1）
2valkey-cli CONFIG GET io-threads
3# 1) "io-threads"
4# 2) "1"
5
6# 調高 I/O 執行緒數（建議不超過機器實體核數、留核給其他進程）
7# redis.conf / valkey.conf:
8#   io-threads 4

調校判讀：

• io-threads 是啟動參數，多數版本需要重啟生效（不是所有 CONFIG SET 都能熱套），改 conf 後 rolling restart
• 設定值對齊機器核數但留 headroom，例如 8 核機器設 4-6，不要設滿
• 單核或低核機器設 1（預設）即可，多執行緒在核數不足時沒有收益反而增加切換開銷
• I/O 密集（大量小命令、高連線數）的 workload 收益最明顯；CPU 密集的重命令（大 Lua、大 collection 操作）收益有限

調完用實際 workload 壓測驗證，不要假設「開了就快」——執行緒配置的收益高度依賴 workload 形狀。

Production 故障演練

Case 1：切換後 module 指令報 unknown command

徵兆：drop-in 換成 Valkey 後核心功能正常，但某些路徑報 ERR unknown command 'JSON.SET' 或 FT.SEARCH，application 部分功能失效。

根因：用到了 Redis Stack 的商業 module（RedisJSON / RedisSearch）。這些 module 不在 fork 範圍內，Valkey 有自己的 valkey-search / valkey-bloom，但不是同一套指令、需要另外安裝。

修法：

1. 切換前用 MODULE LIST 在原 Redis 上盤點所有載入的 module
2. 逐個確認 Valkey 是否有對應替代（valkey-search 對 RedisSearch 等），確認指令相容度
3. 沒有對應的 module，評估改用 module-free 設計（例如把 JSON 操作拉回 application 層）
4. 重度依賴 Redis Stack 商業 module 的場景，相容性邊界在這裡，可能該留在 Redis Inc 商業版

Case 2：client library 太舊、協商失敗

徵兆：絕大多數 client 正常，但某個老服務的 client library 連 Valkey 報協定錯誤或行為異常。

根因：Valkey 回報 redis_version:7.2.4，client library 若太舊（不支援 Redis 7.2 對應的協定特性，例如 RESP3）會協商失敗。這不是 Valkey 的問題，是 client 本來就跟不上 Redis 7.2。

修法：

1. valkey-cli INFO server 確認回報的 redis_version，對照 client library 支援到哪個 Redis 版本
2. 升級過舊的 client library 到支援 Redis 7.2 的版本
3. 必要時 client 端強制用 RESP2（多數 library 可配置），避開 RESP3 協商
4. 這類問題在升級 Redis 7.2 時也會遇到，不是 Valkey 特有

Case 3：監控工具部分指標消失

徵兆：切換後 RedisInsight 或某監控 dashboard 部分面板空白、某些 vendor-specific 命令回錯。

根因：RedisInsight 等 Redis Inc 工具有部分偏 Redis 商業版的命令，Valkey 不一定實作。核心指標（memory / hit rate / connections）通用，但 vendor-specific 的進階面板可能缺。

修法：

1. 監控改用通用工具：valkey-cli INFO、Prometheus + redis_exporter（相容 Valkey）、Grafana
2. 核心指標（used_memory / keyspace_hits / connected_clients）在 Valkey 完全相容，監控覆蓋不受影響
3. 把監控的相容性納入切換前驗證清單，不要切換後才發現面板空白
4. 對應 記憶體 與 連線 調校用到的 INFO 指標，這些在 Valkey 都通用

Case 4：io-threads 開太多、效能反而下降

徵兆：把 io-threads 從 1 調到 16 想榨效能，結果延遲不降反升、CPU 使用率異常。

根因：io-threads 設成超過機器實體核數，執行緒互搶 CPU、context switch 開銷超過平行收益。或 workload 是 CPU 密集（重命令），I/O 多執行緒對它沒幫助。

修法：

1. io-threads 不超過實體核數，留 headroom 給 OS 與其他進程（8 核設 4-6）
2. 用實際 workload 壓測對比不同 io-threads 值的延遲與吞吐，不要憑感覺調滿
3. CPU 密集 workload 收益有限，問題可能在命令本身太重（大 collection / 大 Lua），先優化命令
4. 多執行緒解的是 I/O 平行度，不是單命令執行速度，分清楚瓶頸在哪

Case 5：以為換 Valkey 就解決了 Redis 的記憶體 / fork 問題

徵兆：因為 Redis 的 fork 延遲尖峰或記憶體 OOM 而切到 Valkey，切完發現同樣的尖峰與 OOM 還在。

根因：Valkey fork 自 Redis 7.2.4，繼承了 Redis 的記憶體模型、eviction 演算法、AOF/RDB fork 機制。這些行為在 Valkey 上完全一致——Valkey 的差異在執行緒與授權，不在記憶體與持久化架構。

修法：

1. 記憶體 / 淘汰 / fork 的調校在 Valkey 上跟 Redis 完全一樣，直接套用 Redis 記憶體調校 與 persistence / fork latency
2. fork 尖峰是 Redis 系列的共同架構限制，要根治走 DragonflyDB 的 fork-less 機制，不是換 Valkey
3. 切換 Valkey 的理由應該是授權合規、多執行緒吞吐或 managed 成本，不是記憶體問題
4. 切換前釐清痛點：是授權 / 成本（Valkey 解）還是記憶體 / fork 架構（Valkey 不解）

Capacity / cost 邊界

Valkey 的容量判讀，多數沿用 Redis（同源），差異集中在執行緒與授權成本：

撞牆後的路由判斷：

• 記憶體 / fork 是瓶頸：Valkey 同源、不解這層，走 DragonflyDB（fork-less + 更省記憶體）或 Redis 系列的 Cluster 分片。
• 需要 Redis Stack 商業 module：Valkey 的 valkey-search / valkey-bloom 覆蓋不到全部，重度依賴走 Redis Inc 商業版。
• 不想自管：ElastiCache for Valkey 是 AWS 的 default engine，managed failover / snapshot / patching 全託管，成本比 ElastiCache for Redis 低約 20%。

整合 / 下一步

Valkey 的 deep article 大量複用 Redis 的調校知識（同源），它自己的獨特性在相容性驗證、執行緒與授權：

• 跟 Redis 全系列 deep article：記憶體、持久化、Sentinel、連線的調校在 Valkey 上完全一致，Valkey 不重寫這些，直接套用。
• 跟 ElastiCache for Valkey：managed Valkey 把執行緒與 failover 託管，省掉自管的調校與演練。
• 跟 Tinder 的 ElastiCache for Valkey 案例：4700 萬月活的 sub-millisecond 配對引擎是相容性與規模化的生產證據，但 module / client 的相容性仍需逐案驗證。
• 跟 DragonflyDB：兩者都打「Redis 相容 + 更好的執行緒」，但 Valkey 是 fork（同源、最高相容），DragonflyDB 是 C++ 重寫（相容核心但架構不同），選型差異在相容度 vs 架構激進度。

相關連結

• 上游 vendor 頁：Valkey
• 同源 deep article：Redis 記憶體與淘汰調校、persistence 與 fork latency
• 平行 vendor：AWS ElastiCache（default engine 即 Valkey）、DragonflyDB
• Methodology：Vendor 深度技術文章寫作方法論

本文是 PostgreSQL overview 的 implementation-layer deep article。Overview 已說明 PostgreSQL 在 OLTP 譜系的定位、本文聚焦 Patroni-based HA 的 lifecycle 設計 — 從正常運作到 failover 完成的 5 段、每段配置 + failure mode + recovery。

Failover lifecycle：5 段不是一條曲線

PostgreSQL 原生沒有 auto-failover；primary 掛了、application 卡死、SRE 手動 promote standby — 整個過程通常 5-30 分鐘。Patroni 把這條鏈拆成 自動化的 5 段 lifecycle、每段有自己的 trigger、配置、失敗模式：

每段都有獨立配置、不是「設一個 timeout 就好」。後面分段展開。

Stage 1：Detection — DCS heartbeat 跟 TTL

 1# patroni.yml 核心配置
 2scope: myapp-pg-cluster
 3namespace: /db/
 4name: pg-node-1                                # 跟 hostname 一致
 5
 6etcd:
 7  hosts: etcd1:2379,etcd2:2379,etcd3:2379       # DCS quorum
 8  protocol: https
 9
10bootstrap:
11  dcs:
12    ttl: 30                                     # leader lock TTL
13    loop_wait: 10                               # patroni 主循環間隔
14    retry_timeout: 10                           # DCS retry 上限
15    maximum_lag_on_failover: 1048576            # standby 落後 1MB 內才能 promote
16    synchronous_mode: false                     # async / sync 取捨

關鍵直覺：

• TTL (30s) = leader 失聯多久才被視為 dead。設太短（< 15s）會把 transient network jitter 當 dead；設太長（> 60s）unavailability 拖長
• loop_wait + retry_timeout < TTL：Patroni 必須在 TTL 內成功跟 DCS 互動 N 次、loop_wait=10 + retry_timeout=10 給每個循環 20s buffer
• maximum_lag_on_failover：standby WAL 落後超過這個閾值就 不參與 election；防止「promote 一個落後 5 分鐘的 standby」資料丟失

Stage 2：Election — DCS quorum + watchdog 防 split-brain

1watchdog:
2  mode: required                                # required / automatic / off
3  device: /dev/watchdog
4  safety_margin: 5

Election 期間最大風險是 split-brain — network partition 下、舊 leader 還活著但跟 DCS 斷線；新 leader 從 standby 升上來、application 同時連兩個 PostgreSQL 寫。資料 divergence 後 無法自動 reconcile。

防護機制兩層：

1. DCS quorum：etcd / Consul 至少 3 node、過半 quorum 才能寫 leader key — 少數派 partition 無法 elect 新 leader
2. Watchdog (Linux kernel)：required mode 強制 — Patroni 必須定期 poke /dev/watchdog、若 Patroni 自己掛或被 OS 凍結、kernel 自動 reboot 整台機器、避免舊 leader 在 DCS 失聯後繼續接寫

Watchdog required 是 production-grade 的硬要求 — automatic / off 在 split-brain 場景下無法防護。

Stage 3：Promotion — pg_ctl + replication slot 切換

新 leader 寫 DCS key 成功後、Patroni 自動執行：

1# Patroni 內部、不要手動跑
2pg_ctl promote -D /var/lib/postgresql/data
3# postgresql.auto.conf 移除 primary_conninfo
4# postgresql.auto.conf 重新計算 timeline ID
5# 啟動接寫

Promotion 期間關鍵議題：

• timeline divergence：新 leader 開新 timeline ID（從 leader 失聯時的 LSN 開始）；其他 standby 需要 pg_rewind 把自己的 WAL fork 點對齊新 timeline
• replication slot 處理：舊 leader 上的 replication slot 在 DCS 中已 stale、新 leader 重建 slot；如果 logical replication consumer 沒 idempotent、會 replay 部分訊息
• promotion latency：通常 3-10 秒（pg_ctl 本身 < 5s、加 DCS 寫確認）

Stage 4：Reconfiguration — client routing 切換

PostgreSQL 自己升 leader 還不夠、application 不知道；要靠前端 routing 層轉發。三種典型 pattern：

1[client] → [HAProxy / pgBouncer] → [pg-node-1 (leader)]
2                                 → [pg-node-2 (standby, read)]
3                                 → [pg-node-3 (standby, read)]

Patroni REST API 暴露 /leader / /replica / /health endpoint、HAProxy 用 health check 跑這些 endpoint：

1# haproxy.cfg
2backend pg-write
3  option httpchk OPTIONS /leader
4  http-check expect status 200
5  server pg-node-1 pg-node-1:5432 check port 8008
6  server pg-node-2 pg-node-2:5432 check port 8008 backup
7  server pg-node-3 pg-node-3:5432 check port 8008 backup

Reconfiguration 期間關鍵延遲：

• HAProxy health check 間隔（預設 2s）+ failure threshold（預設 3 次）= ~6s 切換感應
• PgBouncer 不主動 health check、要靠 application 端 retry 跟 connection drop 觸發重連
• 整個 reconfiguration 端到端通常 10-20s（含 PostgreSQL promotion 時間）

Stage 5：Recovery — pg_rewind 跟 base backup 取捨

舊 leader 恢復後變 standby，但 WAL 已 divergence — 必須選一條 recovery path：

• pg_rewind：rewind 舊 leader WAL 到分歧點、重新接 streaming replication；條件 = 分歧 WAL 量小（< 幾 GB）且 timeline 可對齊
• 重 base backup：用 pg_basebackup 從新 leader 拉完整 base + WAL；條件 = 任何時候都可、但時間長（TB 級 1-4 小時）

Patroni 預設嘗試 pg_rewind、失敗才退 base backup。production 配置：

1postgresql:
2  use_pg_rewind: true
3  remove_data_directory_on_rewind_failure: true   # rewind 失敗自動清 data dir、再 base backup
4  remove_data_directory_on_diverged_timelines: true

Production 故障演練

Case 1：Split-brain due to DCS partition

徵兆：兩個 PostgreSQL node 都在接寫、application 大量寫入 conflict / unique constraint violation。

根因：DCS（etcd）partition — 兩個 etcd node 在 partition 兩側、都自認 quorum；其實是 split-vote、兩邊都不應該。Patroni 在兩邊各 elect 一個 leader。

修法：

1. DCS 必須奇數 node（3 / 5 / 7）、過半 quorum 嚴格 enforce
2. DCS 部署跨 AZ / region 時、quorum size 要考慮 partition 機率（3 AZ 各 1 node 是 production 最低標）
3. Watchdog required mode 是最後一道閘門 — DCS partition 加 quorum 失靈時、watchdog 強制 reboot 失聯 node

Case 2：Standby 落後太多、無法 failover

徵兆：primary 失聯後、Patroni log 顯示 Following members have lag greater than maximum_lag_on_failover、所有 standby 都被拒 promote、cluster unavailable。

根因：maximum_lag_on_failover 設 1MB、但 standby replication lag 累積到 50MB（write-heavy workload + slow disk on standby）。安全機制觸發、但代價是 無 standby 可升、需要人工降低門檻或等 standby catch up。

修法：

1. 預防：standby 容量 / IO 對齊 primary、避免 lag 累積；prometheus alert pg_replication_lag_bytes > 10MB 觸發前 catch
2. 臨時：手動 patronictl edit-config 把 maximum_lag_on_failover 暫時拉到 50MB、接受可能丟 50MB worth of writes、換 availability
3. 長期：sync replication（一個 standby 強制同步）、保證至少一個 standby zero-lag

Case 3：Promotion 後 application connection storm

徵兆：failover 完成後 30-120 秒內、application log 大量 connection refused / password authentication failed、application 自己 retry storm。

根因：新 leader 剛 promote、PostgreSQL max_connections 容量還在 warm up（shared memory / cache 未 prime）、application 同時湧入大量 connection request；應用 retry 不夠 jitter、queue 堆積。

修法：

1. Application 用 exponential backoff with jitter、不要 immediate retry
2. PgBouncer / connection pool 限制每 application instance 對 PG 的 connection 上限、不直連 PG
3. 預先在 standby 跑 pg_prewarm 把熱表 cache 預熱、promotion 後 cache miss 不爆

Case 4：pg_rewind 失敗、退到 base backup 沒做

徵兆：舊 leader 恢復後、Patroni log 顯示 pg_rewind failed、舊 leader 一直 STARTING、無法重接 cluster；SRE 手動跑 pg_basebackup 才恢復。

根因：remove_data_directory_on_rewind_failure: false（預設）— rewind 失敗時 Patroni 不主動清 data dir、需要 SRE 手動處理；運維沒 runbook、卡在這步幾小時。

修法：

1. Production 設 remove_data_directory_on_rewind_failure: true + remove_data_directory_on_diverged_timelines: true、讓 Patroni 自動 fallback
2. data dir 跑在獨立 PV / disk、清掉風險可控（不要跑 root disk）
3. 容量規劃：base backup 時間預估納入 RTO（TB 級 base backup 1-4 小時、不是 RTO 30 分鐘所能承受）

Case 5：Watchdog 觸發整機 reboot、誤殺

徵兆：production server 在無故障時 unexpected reboot、dmesg 顯示 watchdog: BUG: soft lockup。

根因：Patroni 主循環因 etcd 短暫慢回應卡住 60+ 秒、kernel watchdog 觸發 reboot；但實際 PostgreSQL 沒 hang、是 Patroni-watchdog 鏈過敏。

修法：

1. safety_margin 設大一點（10-15）、給 Patroni loop_wait 抖動空間
2. etcd 跟 Patroni 部署在低延遲 network 內（同 AZ < 5ms）、跨 region etcd 不建議
3. watchdog device 用 softdog（軟體模擬）vs 硬體 watchdog、debug 時 softdog 容易觀察

容量規劃

整合 / 下一步

跟 PgBouncer 整合

PgBouncer 不主動感知 Patroni failover、要靠：

1. HAProxy 在 PgBouncer 上層：HAProxy 跑 Patroni health check、PgBouncer connection 重新路由
2. PgBouncer reload：failover 後 SRE / automation 跑 pgbouncer -R、強制重連 backend
3. Connection pool drain：application 端 connection pool 設 pool_lifetime_max=5min、舊 connection 自然汰換

跟 cert-manager（TLS rotation）

Patroni REST API 跟 PostgreSQL streaming replication 都用 TLS、cert rotation 不能停服務：

1. cert-manager 自動換證後、Patroni 跟 PostgreSQL 都需要 reload（不是 restart）
2. patronictl reload <cluster> 不會觸發 failover、只 reload config
3. PostgreSQL pg_ctl reload 是 SIGHUP、平滑載入新 cert

跟 backup / PITR

Patroni 不管 backup — 但 standby promotion 後、WAL archive 必須跟新 leader 的 timeline 對齊：

1. WAL archive 命令模板含 %t（timeline）：archive_command = 'wal-g wal-push %p'
2. Backup tool（pgBackRest / WAL-G）支援 timeline 切換、archive 不會中斷
3. 詳見 PITR + WAL archiving deep article

下一步議題

• Multi-region Patroni：跨 region 部署的 DCS quorum 設計、跟單 region 的取捨完全不同
• PostgreSQL 16+ streaming replication slot 持久化：簡化 standby promotion 後 logical consumer 重連
• 跟 Kubernetes operator 整合：Patroni 跑在 K8s 時、StatefulSet + pod identity + DCS 部署模式

相關連結

• 上游 vendor 頁：PostgreSQL
• 上游 chapter：High Concurrency Access — connection / replication / HA 全鏈
• 平行 deep article：pgBouncer 配置 / Vault Dynamic Credential
• Methodology：Vendor 深度技術文章的寫作方法論

本文是 AWS SQS overview 的 implementation-layer deep article。本文的 CLI 指令語法經 LocalStack round-trip 驗證、真實 AWS 的 scaling 行為、Lambda event source mapping 細節與計費數字依 AWS 官方文件。

SQS 沒有 broker ACK，delivery 控制全靠 visibility timeout

SQS 跟自管 broker（RabbitMQ / Kafka）最大的操作差異是：consumer 不會跟 broker 維持一條長連線、也沒有 channel-level 的 ack / nack 協議。SQS 的整個 delivery 保證建立在一個計時器上 — visibility timeout。訊息被 ReceiveMessage 拉走後進入 in-flight 狀態、在 timeout 視窗內對其他 consumer 不可見；consumer 處理成功就呼叫 DeleteMessage 把它移除、處理失敗或當機則什麼都不做、等 timeout 到期訊息自動回到 queue 重新可見。

這個設計把「確認處理完成」的責任從 broker 連線狀態轉移到 consumer 的主動刪除。好處是 consumer 可以隨時死掉、重啟、水平擴縮、不需要維持任何 session 狀態 — 訊息不會因為連線斷掉而遺失。代價是 visibility timeout 這個數字變成最容易設錯、後果最隱蔽的參數：設太短訊息會在 consumer 還在處理時就重新可見、被另一個 consumer 重複領走；設太長則 consumer 當機後訊息要等很久才回到 queue、retry 延遲拉長。

實機建立一個 queue 並查 default、可以確認這個視窗的起點。新建 queue 的 VisibilityTimeout 預設 30 秒：

1# 不帶任何 attribute 建 queue
2aws sqs create-queue --queue-name demo-default
3
4# 查 default visibility timeout
5aws sqs get-queue-attributes \
6  --queue-url <url> \
7  --attribute-names VisibilityTimeout
8# => "VisibilityTimeout": "30"

30 秒對「處理時間穩定在數百毫秒」的 task 綽綽有餘、對「呼叫第三方 API、跑批次轉檔、寫多個下游」的 task 則經常不夠。下一節先把這個參數設對，後面的故障演練再展開它設錯時的具體徵兆。

對齊 visibility timeout 與 consumer 處理時間

設定 visibility timeout 的判準是「略高於 consumer 處理單則訊息的最大時間」、不是平均時間。Capital One 的官方 tech blog 在講 SQS + Lambda 時明示這條原則：visibility timeout 應比最大處理時間略高 — 因為決定 redelivery 的是尾端那幾則最慢的訊息、不是中位數。處理時間 p50 是 2 秒、p99 是 25 秒時、visibility timeout 要對齊 p99 加緩衝、設到 30-40 秒、而不是看 p50 設 10 秒。

建 queue 時直接帶 VisibilityTimeout attribute，或對既有 queue 用 set-queue-attributes 調整：

1# 建立時指定（單位：秒；上限 12 小時 = 43200）
2aws sqs create-queue \
3  --queue-name demo \
4  --attributes VisibilityTimeout=60
5
6# 對既有 queue 調整
7aws sqs set-queue-attributes \
8  --queue-url <url> \
9  --attributes VisibilityTimeout=120

處理時間本身不可預測的場景（例如轉檔大小差異大、下游 API 偶發慢）、用一個固定的 queue-level visibility timeout 會兩頭不討好：對齊最壞情況會讓正常訊息當機後 retry 太慢、對齊正常情況會讓慢訊息 redelivery。SQS 給的工具是 ChangeMessageVisibility — consumer 在處理過程中發現這則會花更久時，主動延長這一則訊息的 visibility timeout，而不影響 queue default：

1# consumer 拿到 ReceiptHandle 後，動態把這則延長到 120 秒
2aws sqs change-message-visibility \
3  --queue-url <url> \
4  --receipt-handle <receipt-handle> \
5  --visibility-timeout 120

實務上長任務 consumer 的常見寫法是「heartbeat extension」：每處理一段就呼叫一次 ChangeMessageVisibility 往後推、形成一個續命迴圈、直到處理完成才 DeleteMessage。這把「我還活著、還在處理這則」的訊號明確化、避免用一個保守的 queue-level 大數字一刀切。ReceiptHandle 是每次 ReceiveMessage 回傳的一次性 token、不是 message id — 同一則訊息被重新領取後 ReceiptHandle 會變、延長操作必須用當次領取拿到的那一個。

Long polling 決定空輪詢成本，short polling 是預設陷阱

Polling 模式直接決定 SQS 的 request 帳單，因為 SQS 按 request 數計費、而 ReceiveMessage 即使沒拿到訊息也算一次 request。Short polling（預設、WaitTimeSeconds=0）的行為是「立即回應」：consumer 發 ReceiveMessage、SQS 抽樣一部分 server 立刻回、queue 空的時候回一個空 response。Consumer 為了即時拿到訊息會緊接著再發一次、形成高頻空輪詢 — 在低流量 queue 上、絕大多數 request 都是空回、帳單全花在「問有沒有訊息」上。

Long polling（WaitTimeSeconds 設 1-20 秒）改變這個行為：SQS 收到 ReceiveMessage 後、若 queue 當下沒訊息、會 hold 住這條連線最多 WaitTimeSeconds 秒、期間一有訊息到達就立刻回傳、整段時間都沒訊息才回空。對 consumer 端來說一個 20 秒的 long poll 取代了 20 秒內可能發出的數十次 short poll、空 request 數量大幅下降。

1# long polling：等到有訊息或最多 20 秒才回
2aws sqs receive-message \
3  --queue-url <url> \
4  --wait-time-seconds 20

設定 long polling 有兩個位置：per-request 帶 --wait-time-seconds、或 queue-level 設 ReceiveMessageWaitTimeSeconds attribute 讓所有 receive 預設走 long polling。後者更穩、不依賴每個 consumer 都記得帶參數。20 秒幾乎總是對的選擇：它把空輪詢壓到最低、而 latency 代價只在「queue 剛好空、訊息在 poll 結束後才到」這個邊界出現 — 大多數有持續流量的 queue 根本碰不到 20 秒上限。唯一要留意的是 consumer 的 socket timeout 必須大於 WaitTimeSeconds、否則 client 會在 SQS 還在 hold 連線時自己先 timeout 斷線。

SQS + Lambda：event source mapping 把 polling 交給 AWS

把 SQS 接上 Lambda 時、polling 這件事整個從應用程式碼消失、改由 Lambda 的 event source mapping 接管。Event source mapping 是 Lambda service 內部一組 managed poller、持續對 queue 做 long polling、把拉到的訊息打包成 batch 同步 invoke 函式、函式正常返回就由 service 代為 DeleteMessage。Consumer 端不再寫 receive / delete 迴圈、只寫處理單一 batch 的 handler。

這套 managed poller 的 scaling 不是線性的、有 ramp-up 上限。Capital One 觀察到的行為是：Lambda 初始開 5 個並行的 long polling 連線、隨 queue 累積每分鐘最多增加 60 個 instance、standard queue 的並行 batch 上限到 1000。這意味著 queue 突然湧入大量訊息時、Lambda 不會瞬間炸開到滿並行、而是分鐘級爬升 — 容量規劃時要把這段 ramp-up 期算進 backlog 消化時間、不能假設「訊息一到就有足夠 consumer」。

兩個核心參數決定每次 invoke 的形狀：

Batch size 拉大表面上省錢 — invoke 次數少、每則訊息分攤的 request 成本低。但它跟下一節的部分失敗處理直接耦合：batch 越大、一則毒訊息拖累整批重投的範圍越大。Batch window 則是流量稀疏時讓 batch 攢滿的手段、流量本來就密集時設不設都差不多、反而會引入不必要的 latency。

DLQ 與 redrive policy：用 maxReceiveCount 隔離毒訊息

毒訊息（永遠處理失敗的訊息 — 格式損壞、引用了已刪除的資源、觸發 consumer 確定性 bug）會在 visibility timeout 機制下無限重投：處理失敗、timeout 到期、重新可見、再次被領取、再次失敗。沒有上限的話這則訊息會永遠佔用 consumer 資源、且其他正常訊息的處理被它反覆插隊。Dead-letter queue（DLQ）加 maxReceiveCount 是 SQS 對這個問題的標準解 — 訊息被接收超過 N 次後、SQS 自動把它移到另一個指定的 queue（DLQ）、主 queue 不再被它卡住。

設定分兩步：先建一個普通 queue 當 DLQ、取它的 ARN、再對主 queue 設 redrive policy 指向這個 ARN 並設 maxReceiveCount：

 1# 1. 建 DLQ 並取得 ARN
 2aws sqs create-queue --queue-name demo-dlq
 3aws sqs get-queue-attributes \
 4  --queue-url <dlq-url> \
 5  --attribute-names QueueArn
 6# => "QueueArn": "arn:aws:sqs:us-east-1:000000000000:demo-dlq"
 7
 8# 2. 對主 queue 設 redrive policy（被接收 5 次後送 DLQ）
 9aws sqs set-queue-attributes \
10  --queue-url <main-url> \
11  --attributes '{"RedrivePolicy":"{\"deadLetterTargetArn\":\"arn:aws:sqs:us-east-1:000000000000:demo-dlq\",\"maxReceiveCount\":\"5\"}"}'

DLQ 不是訊息的墳場、是待診斷的暫存區。對應 poison message quarantine 的思路、DLQ 累積要分兩種根因處理：訊息格式錯（永遠失敗、需要修 producer 或人工丟棄）vs 下游服務暫時 down（訊息本身沒問題、修好下游後可以重放）。後者用 redrive 把訊息從 DLQ 批次放回主 queue 重新處理、對應 dlq drain 的排空流程。判斷之前先看 DLQ 裡訊息的內容、不要不加判斷地 redrive — 把毒訊息 redrive 回去只會再走一輪 maxReceiveCount 又回到 DLQ。

maxReceiveCount 設多少是取捨：太小（例如 1-2）會讓「下游短暫抖動」這種暫時性失敗被誤判成毒訊息、過早送進 DLQ；太大（例如 100）會讓真正的毒訊息浪費大量 consumer 重試。多數 task queue 設 3-5 是合理起點 — 足以吸收幾次暫時性失敗、又不至於讓確定性失敗的訊息空轉太久。

Message size 限制與 extended client

SQS 單則訊息上限是 256 KB（含 message body 與 attributes）。這對純事件通知、id 引用、小型 payload 足夠、但對「訊息本身要攜帶大檔案內容」的場景不夠 — 例如要傳一份報表、一張圖、一段長文字。直接的反模式是把大內容塞進 message body、撞上 256 KB 限制後 SendMessage 直接報錯。

標準解是 claim-check 模式：大 payload 寫到 S3、訊息只攜帶 S3 的物件引用（bucket + key）、consumer 收到訊息後再去 S3 取內容。AWS 提供的 Extended Client Library（Java / Python 等 SDK）把這個模式封裝起來 — SendMessage 時若 payload 超過門檻、library 自動把內容寫 S3、訊息只帶 pointer；consumer 端 ReceiveMessage 時 library 自動從 S3 取回、對應用程式碼透明。

選擇門檻時要把 S3 的 request 成本與 latency 算進來：每則大訊息變成「一次 S3 PUT + 一次 SQS Send」、consumer 端「一次 SQS Receive + 一次 S3 GET」。對大多數 payload 都超過 256 KB 的 queue、這是必要成本；對 payload 多數很小、偶爾爆量的 queue、extended client 只在超門檻時走 S3、混合成本可接受。Payload 普遍很大且高頻的場景、要重新評估 SQS 是否適合 — 可能該改用 streaming（Kinesis / Kafka）或乾脆讓 producer / consumer 直接交換 S3 引用、SQS 只傳通知。

Cost：按 request 計費，每一次操作都是一個 request

SQS 的計費模型是 per-request、不是 per-message-stored、也沒有固定月費。每一次 API call — SendMessage、ReceiveMessage（含空回）、DeleteMessage、ChangeMessageVisibility — 都算一個 request。這個模型對成本估算的影響是：帳單由「操作次數」驅動、而非「訊息量」或「儲存時長」。一則訊息從 producer 到 consumer 的最小生命週期是 send（1）+ receive（1）+ delete（1）= 3 個 request；空輪詢、retry、visibility 延長都會額外加 request。

兩個降低 request 數的主要手段：

第一是 batch 操作。SendMessageBatch 與 DeleteMessageBatch 一次最多打包 10 則、而 SQS 把一個 batch call 算作一個 request（實際計費以 64 KB 為一個 request 單位、一個 batch 在此範圍內仍是少數 request）。把 10 則訊息的 send 從 10 個 request 壓成 1 個 batch request、在高頻 queue 上是數量級的成本差異：

1aws sqs send-message-batch \
2  --queue-url <url> \
3  --entries 'Id=m1,MessageBody=a' 'Id=m2,MessageBody=b'

第二是 long polling 消滅空 request — 前面 polling 段已經展開。低流量 queue 的帳單若異常高、第一個要查的就是有沒有開 long polling、consumer 是不是在 short polling 下高頻空轉。

Data transfer cost 只在跨 region 時出現 — 同 region 內 producer / consumer 與 SQS 之間的傳輸不計流量費。把 producer、consumer、queue 放在同一個 region 是預設、跨 region 設計要把 egress 成本明確算進來。FIFO queue 的 per-request 單價比 standard 高、是用成本換 ordering 與去重保證 — 不需要嚴格順序的場景用 standard、把這筆溢價省下來。

Rapid7 的規模參考點說明這個計費模型在極端規模下的份量：Rapid7 公開引述 SQS 撐住「每天數十億則訊息」。在這個量級、per-request 計費乘以訊息數是一筆需要認真建模的成本 — batch、long polling、避免不必要的 visibility 延長、控制 retry 次數、每一項節省都被訊息量放大。SQS 在數十億級可用、但成本結構必須被當作架構參數對待、不是事後才看帳單。

Production 故障演練

故障一：visibility timeout 短於處理時間，訊息被重複處理

徵兆：consumer log 顯示同一個 message id 在短時間內被處理多次、下游出現重複的副作用（重複扣款、重複寄信、重複寫入）；CloudWatch 的 ApproximateNumberOfMessagesNotVisible（in-flight 數）異常高、NumberOfMessagesReceived 遠大於 NumberOfMessagesDeleted。

根因：visibility timeout 設定值低於 consumer 實際處理單則訊息的時間。訊息在 consumer 還沒處理完、還沒呼叫 DeleteMessage 之前、timeout 就到期、訊息重新可見、被另一個 consumer（或同一個 consumer 的下一輪 poll）領走。新建 queue 的 default 是 30 秒 — 處理時間長於此就會踩到：

1aws sqs get-queue-attributes \
2  --queue-url <url> \
3  --attribute-names VisibilityTimeout
4# 看到 30 而 consumer 處理時間 > 30s，就是這個問題

修法：把 visibility timeout 對齊 consumer 處理時間的 p99 加緩衝、用 set-queue-attributes 調高；處理時間變異大的長任務改用 ChangeMessageVisibility heartbeat 在處理中動態延長。同時、因為 SQS standard 是 at-least-once、重複投遞在故障與 retry 下本來就會發生、consumer 的處理邏輯必須冪等 — 對齊 visibility timeout 降低重複頻率、冪等性才是真正消除重複副作用的防線。

故障二：short polling 預設導致低流量 queue 帳單異常

徵兆：一個訊息量很低的 queue、月度 SQS 帳單卻很高；CloudWatch 顯示 NumberOfEmptyReceives 佔 ReceiveMessage 總數的絕大比例 — 大量 request 是空回。

根因：consumer 走 short polling（WaitTimeSeconds=0、預設值）、在 queue 空的時候緊密地反覆發 ReceiveMessage、每次都立即空回、每次都計一個 request。流量越低、空回比例越高、帳單越是花在「問有沒有訊息」上。

修法：在 queue-level 設 ReceiveMessageWaitTimeSeconds=20 讓所有 receive 預設走 long polling、或在每個 ReceiveMessage 帶 --wait-time-seconds 20。Queue-level 設定更穩、不依賴每個 consumer 記得帶參數。設定後 consumer 在 queue 空時會 hold 住連線最多 20 秒、空 request 數量級下降、帳單同步下降。同時確認 consumer 的 socket timeout 大於 20 秒、避免 client 先於 SQS 斷線。

故障三：Lambda batch 部分失敗，整批訊息被重投

徵兆：一個 batch 裡只有少數訊息處理失敗、但整批訊息（含已成功的）全部回到 queue 重新處理；下游對已成功的訊息出現重複副作用；DLQ 累積速度遠超實際毒訊息數量。

根因：Lambda event source mapping 的 default 行為是「整批成敗一體」— 函式只要拋出錯誤、整個 batch 被視為失敗、所有訊息（包含已經處理成功的）都不會被刪除、全部重新可見重投。Batch size 越大、一則失敗拖累的成功訊息越多。

修法：啟用 partial batch response — event source mapping 設 ReportBatchItemFailures、handler 返回時只回報失敗的 message id 清單、SQS 只把這些重投、已成功的正常刪除。這把失敗的爆炸半徑從「整批」縮到「真正失敗的那幾則」。配合縮小 batch size 進一步降低單批風險、並確保 handler 冪等以承受不可避免的重投。Handler 必須正確實作 partial response 的返回格式 — 漏回報某則失敗會讓它被當成成功刪除、訊息靜默遺失。

故障四：maxReceiveCount 設定不當，毒訊息空轉或誤判

徵兆：兩種相反的故障形狀。一是 DLQ 幾乎為空但主 queue 有訊息反覆重試數十次、consumer log 同一 message id 重複出現、佔用處理容量 — maxReceiveCount 設太大。二是 DLQ 快速累積大量其實沒問題的訊息、redrive 回去又能正常處理 — maxReceiveCount 設太小、把下游短暫抖動誤判成毒訊息。

根因：redrive policy 沒設、或 maxReceiveCount 與「暫時性失敗的正常重試次數」不匹配。沒設 redrive policy 時毒訊息無限重投；設太大時毒訊息空轉太久才進 DLQ；設太小時正常訊息在下游抖動期間被過早判死。

修法：對主 queue 設 redrive policy、maxReceiveCount 取 3-5 作為起點 — 足以吸收幾次暫時性失敗、又不讓確定性失敗的訊息空轉太久。觀察 DLQ 的累積模式再微調：DLQ 累積的多是「下游修好後 redrive 能成功」的訊息就調高、累積的多是「redrive 回去又進 DLQ」的真毒訊息就維持或調低。對 DLQ 設 CloudWatch alarm 監控 ApproximateNumberOfMessagesVisible、累積超過閾值就告警人工介入、區分 redrive vs 丟棄。

故障五：FIFO queue 撞上吞吐上限

徵兆：把 standard queue 換成 FIFO 取得 ordering 後、高峰流量下 producer 端開始收到 throttling、訊息積壓、SendMessage 報限流錯誤；吞吐怎麼加 consumer 都上不去。

根因：FIFO queue 為了維持順序與去重、吞吐遠低於 standard。FIFO 的基礎吞吐是每秒 300 則訊息（API call）、開啟 batching 後到每秒 3000 則。更關鍵的是順序保證的粒度在 MessageGroupId — 同一個 group 內的訊息嚴格串行處理、跨 group 才能並行。若所有訊息共用一個 group id、實際並行度退化成 1、無論加多少 consumer 都無法並行消化。

1# FIFO send 必須帶 MessageGroupId（決定順序與並行粒度）
2aws sqs send-message \
3  --queue-url <fifo-url> \
4  --message-body "ordered-1" \
5  --message-group-id "group-a"

修法：先確認是否真的需要全域順序 — 多數場景只需要「同一個實體（同一用戶、同一訂單）內部有序」、不需要跨實體有序。把 MessageGroupId 設成業務實體 id（用戶 id、訂單 id）、讓不同實體的訊息能跨 group 並行、吞吐隨 group 數量擴展。確定需要嚴格全域順序且吞吐撞頂的場景、FIFO 的設計上限就是天花板 — 此時要重新評估是否該換成 streaming（Kafka 的 partition 模型在 per-key 有序下提供更高並行）、或拆分 queue。不需要任何順序保證的場景、退回 standard queue、把 FIFO 的吞吐限制與成本溢價一起省掉。

整合與下一步

跟 consumer 設計能力對接

本文的 visibility timeout heartbeat、partial batch response、冪等處理都是 3.4 consumer 設計 的具體落地 — consumer-design 講語言無關的 consumer 模式、本文是 SQS 上的實作形狀。retry 與 replay 的交接路徑見 queue consumer retry replay handoff。

跟知識卡對位

DLQ 段對應 poison message quarantine（毒訊息隔離）與 dlq drain（DLQ 排空）兩張卡 — SQS 的 redrive policy + maxReceiveCount 是這兩個概念在 managed queue 上的具體機制。visibility timeout 的 in-flight 概念見 in-flight。

跟 case 對位

visibility timeout 與 Lambda event source 的 ramp-up 行為來自 3.C50 Capital One；at-least-once + DLQ 在工作排程的取捨來自 3.C48 Airbnb Dynein；per-request cost 在極端規模的份量來自 3.C59 Rapid7。

何時 revisit

FIFO 吞吐撞頂、需要 replay / streaming、或 cost 在 streaming 模型下更划算時、回 SQS overview 的「何時改走其他服務」 重新選型。跨雲 managed queue 的對照見 Google Pub/Sub。

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

本文是 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 的細部配置

本文是 Redis Streams overview 的 implementation-layer deep article。Overview 給選型與最短路徑、本文聚焦「consumer crash 之後、卡在 PEL 的訊息怎麼回到處理流程」這條 implementation flow。實機輸出來自 redis:7（7.4.9）單節點。

consumer crash 後、訊息卡在哪裡

Redis Streams 的 consumer group 設計是「先投遞、後 ack」：XREADGROUP 把 entry 投給某個 consumer 的同時、entry 進入該 group 的 PEL（Pending Entries List）、標記為「已投遞、未確認」。consumer 處理完才呼叫 XACK 把 entry 移出 PEL。這一段「已投遞未 ack」的視窗、是 Redis Streams 提供 at-least-once 的全部依據。

問題在於 consumer crash 時機落在這個視窗內。consumer 已經拿到訊息、PEL 已經記了它的名字、但它在 ack 之前就死了。Redis 沒有 broker 級的「重新投遞」背景程序——不像 RabbitMQ consumer 斷線後 unacked 訊息自動 requeue。Redis 把這筆訊息留在 PEL、owner 仍是那個死掉的 consumer、然後什麼都不做。要讓這筆訊息回到處理流程、只有 application 主動呼叫 XCLAIM 或 XAUTOCLAIM 改寫 owner。

這就是 Bitso 自建 Reliable Streams 抽象 揭露的核心事實：Redis Streams 是「資料結構」、不是「broker 系統」、可靠性責任在 application 層。本文展開的就是這個責任的具體形狀——PEL 怎麼累積、怎麼判讀、接管機制怎麼運作、以及哪些操作會讓接管失效。

PEL 機制：XREADGROUP 進、XACK 出

PEL 是 per-group 的結構、記錄每個 entry 的四個欄位：entry ID、目前 owner consumer、idle time（距上次投遞的毫秒數）、delivery count（被投遞過幾次）。先用實機輸出建立基礎。寫入 5 筆、建 group、兩個 consumer 各讀一部分：

 1$ redis-cli XADD mystream '*' event order_1 amount 100
 21781584105202-0
 3# ... order_2 ~ order_5、各得遞增 entry ID
 4
 5$ redis-cli XGROUP CREATE mystream g1 0
 6OK
 7
 8$ redis-cli XREADGROUP GROUP g1 c1 COUNT 3 STREAMS mystream '>'
 9# c1 拿到 order_1 / order_2 / order_3
10$ redis-cli XREADGROUP GROUP g1 c2 COUNT 10 STREAMS mystream '>'
11# c2 拿到 order_4 / order_5

'>' 代表「只取從未投遞給本 group 的新訊息」。投遞後這 5 筆全進 PEL。XPENDING 的 summary 形式給總覽：

1$ redis-cli XPENDING mystream g1
25                  # PEL 總數
31781584105202-0    # 最小 pending ID
41781584105578-0    # 最大 pending ID
5c1                 # 各 consumer 的 pending 數
63
7c2
82

5 筆全在 PEL、c1 扛 3 筆、c2 扛 2 筆。展開形式 XPENDING <key> <group> - + <count> 給每筆細節：

1$ redis-cli XPENDING mystream g1 - + 10
21781584105202-0  c1  6318  1    # entry ID / owner / idle ms / delivery count
31781584105278-0  c1  6318  1
41781584105373-0  c1  6318  1
51781584105466-0  c2  6224  1
61781584105578-0  c2  6224  1

idle 是 6318ms（距投遞已過 6.3 秒）、delivery count 都是 1（只投過一次）。這兩個數字是後面接管決策的核心輸入：idle 判斷「owner 是不是死了」、delivery count 判斷「這筆是不是 poison message」。

XACK 把處理完的 entry 移出 PEL：

 1$ redis-cli XACK mystream g1 1781584105202-0
 21                  # 成功移除 1 筆
 3
 4$ redis-cli XPENDING mystream g1
 54                  # PEL 剩 4 筆
 61781584105278-0
 71781584105578-0
 8c1
 92
10c2
112

PEL 從 5 降到 4。判讀原則固定：PEL 持續成長就是 consumer 健康訊號異常——不是 crash 沒 ack、就是處理速度跟不上、再不然是 ACK 程式碼漏寫。三者用 idle time 區分：crash 的 entry idle 會單調成長、處理慢的 idle 在 timeout 附近震盪、漏 ACK 的 entry delivery count 停在 1 但 idle 無上限成長。

XCLAIM 與 XAUTOCLAIM：改寫 owner 的兩條路

接管的本質是把 PEL entry 的 owner 從死掉的 consumer 改成活著的 consumer。XCLAIM 是手動指定 entry ID 接管、XAUTOCLAIM 是自動掃 idle 超過門檻的 entry 批次接管。兩者都接受 min-idle-time 參數當安全閥。

XCLAIM <key> <group> <new-consumer> <min-idle-time> <id...>：把指定 entry 改判給新 consumer、條件是該 entry 的 idle 已達 min-idle-time。下面用 min-idle-time 0（無條件接管）把 c1 的一筆轉給 c3：

 1$ redis-cli XCLAIM mystream g1 c3 0 1781584105278-0
 21781584105278-0
 3event
 4order_2
 5amount
 6200               # 回傳被接管 entry 的完整內容
 7
 8$ redis-cli XPENDING mystream g1 - + 10
 91781584105278-0  c3  66     2    # owner 變 c3、idle 歸零(66ms)、delivery count 升到 2
101781584105373-0  c1  14590  1
111781584105466-0  c2  14496  1
121781584105578-0  c2  14496  1

接管後三件事同時發生：owner 改成 c3、idle 重置（剛 claim、66ms）、delivery count 從 1 升到 2。delivery count 自增是接管機制留下的審計軌跡——一筆訊息 delivery count 累積到 5、10、代表它反覆被接管又反覆沒處理完、這就是 poison message 的訊號、該路由到隔離區（見 recovery semantics 與 poison message quarantine）。

XAUTOCLAIM <key> <group> <new-consumer> <min-idle-time> <start-id>（Redis 6.2+）省掉「先 XPENDING 找 ID、再逐筆 XCLAIM」兩步、一次掃描接管：

 1$ redis-cli XAUTOCLAIM mystream g1 c3 0 0
 20-0                          # 下次掃描的 cursor（0-0 代表掃完一輪）
 31781584105278-0 ...          # 接管的 entry 內容（order_2）
 41781584105373-0 ...          # order_3
 51781584105466-0 ...          # order_4
 61781584105578-0 ...          # order_5
 7(empty array)                # 第三個回傳值：已從 stream 刪除的 entry ID 清單
 8
 9$ redis-cli XPENDING mystream g1
104
111781584105278-0
121781584105578-0
13c3                           # 全部 4 筆 owner 變 c3
144