Apache Kafka 教學手冊
Apache Kafka 教學手冊 項目 內容 文件版本 2.0 最後更新 2026 年 9 月 29 日 適用版本 Apache Kafka 4.3.x（KRaft 模式；ZooKeeper 模式已於 4.0 移除） 適用對象 後端工程師、系統架構師、SRE、DevOps、資安與稽核人員 文件定位 企業標準技術白皮書／內部標準教材 使用情境 大型企業、金融業（銀行、證券、保險）內部系統 文件維護 內部技術團隊 Created by Eric Cheng ⚠️ v2.0 重大改版說明：本版以 Apache Kafka 4.3（最新修補版 4.3.1）為基準全面改寫。v1.0 以 Kafka 3.x／ZooKeeper 並存時代為基準，其中 inter.broker.protocol.version 升級流程、zookeeper.connect ACL 指令、config/kraft/ 設定路徑等內容在 4.x 已不適用。完整更正清單請見附錄 E：版本更新紀錄，查證來源請見附錄 F：查證紀錄。 目錄 執行摘要 1. Apache Kafka 簡介 1.1 Kafka 是什麼？解決什麼問題？ 1.2 與傳統 Message Queue 的差異 1.3 適合與不適合的使用情境 1.4 核心概念與五大 API 1.4.1 事件（Event）結構 1.4.2 核心術語 1.4.3 五大 API 1.5 版本演進與 4.x 重點 1.5.1 近期版本時間軸 1.5.2 4.x 對企業的關鍵影響 1.6 💡 本章實務建議 2. Kafka 系統架構總覽 2.1 Kafka 核心元件說明 2.1.1 Broker 2.1.2 Topic 與 Partition 2.1.3 Producer 2.1.4 Consumer 與 Consumer Group 2.1.5 Controller 與 KRaft Metadata Quorum 2.1.6 Share Group（Queues for Kafka） 2.2 高可用（HA）與水平擴充設計原則 2.2.1 副本機制（Replication） 2.2.2 高可用設計原則 2.2.3 機架感知（Rack Awareness） 2.2.4 水平擴充原則 2.3 儲存層架構 2.3.1 Log Segment 結構 2.3.2 高效能設計 2.4 Tiered Storage（分層儲存） 2.5 💡 本章實務建議 3. Kafka 安裝與部署 3.1 環境需求 3.1.1 硬體需求 3.1.2 軟體需求 3.1.3 網路需求 3.2 單機環境安裝（KRaft 模式） 3.3 多節點叢集安裝（正式環境） 3.3.1 叢集規劃 3.3.2 Controller 節點設定 3.3.3 Broker 節點設定 3.3.4 叢集初始化與啟動 3.3.5 Controller 動態擴縮 3.4 ZooKeeper 移除與遷移路徑 3.5 常見安裝錯誤與排除方式 3.6 Docker 容器部署 3.6.1 快速啟動 3.6.2 以環境變數設定 3.6.3 Docker Compose 範例（單節點開發環境） 3.7 Kubernetes 部署 3.8 系統服務與作業系統調校 3.8.1 Systemd Service 3.8.2 JVM 調校 3.8.3 作業系統調校 3.9 💡 本章實務建議 4. Kafka 基本設定說明 4.1 Broker 重要設定參數 4.1.1 核心設定 4.1.2 效能相關設定 4.1.3 日誌與可靠性設定 4.1.4 Kafka 4.0 預設值變更 4.2 Topic 設計原則 4.2.1 Partition 數量設計 4.2.2 Replication Factor 設計 4.2.3 Topic 層級設定 4.3 Producer 重要設定 4.4 Consumer 重要設定 4.5 資料保留策略（Retention Policy） 4.6 Share Group 設定 4.7 動態設定管理 4.8 💡 本章實務建議 5. Kafka 系統使用教學 5.1 Topic 管理 5.1.1 建立 Topic 5.1.2 查詢 Topic 5.1.3 修改 Topic 5.1.4 刪除 Topic 5.2 Producer 發送訊息 5.2.1 使用 Console Producer 5.2.2 Java Producer 範例 5.3 Consumer 消費訊息 5.3.1 使用 Console Consumer 5.3.2 Java Consumer 範例 5.4 Offset 管理 5.4.1 查看 Consumer Group Offset 5.4.2 重置 Offset 5.4.3 群組管理工具（KIP-1043） 5.5 訊息順序性與重複消費 5.5.1 訊息順序保證 5.5.2 避免重複消費 5.6 Share Group 操作 5.6.1 Console Share Consumer 5.6.2 管理 Share Group 5.6.3 Java Share Consumer 範例 5.7 交易與 Exactly-Once 語意 5.7.1 傳遞語意比較 5.7.2 交易 Producer（Consume-Transform-Produce） 5.8 💡 本章實務建議 6. Kafka 與應用系統串接方式 6.1 與 Spring Boot 整合 6.1.1 Maven 依賴 6.1.2 設定檔（application.yml） 6.1.3 Producer 實作 6.1.4 Consumer 實作 6.1.5 Kafka 設定類別與錯誤處理 6.1.6 非阻塞重試（@RetryableTopic） 6.1.7 Share Consumer 整合 6.2 系統解耦架構設計 6.3 同步系統 vs 事件驅動架構 6.4 常見整合架構模式 6.4.1 Event Sourcing 6.4.2 CDC（Change Data Capture） 6.4.3 Saga 模式 6.4.4 Transactional Outbox 模式 6.5 Schema Registry 與 Schema 演進 6.6 Kafka Connect 與 CDC 6.7 Kafka Streams 串流處理 6.8 💡 本章實務建議 7. Kafka 系統維運與監控 7.1 常見監控指標 7.1.1 Broker 層級指標 7.1.2 Controller 與 KRaft 指標 7.1.3 Topic／Partition 層級指標 7.1.4 Client 層級指標 7.2 Consumer Lag 監控與處理 7.2.1 查看 Consumer Lag 7.2.2 Lag 過高的原因與解決方案 7.3 系統監控設定 7.3.1 JMX 監控設定 7.3.2 Prometheus 整合 7.3.3 Grafana Dashboard 7.4 常見營運問題與排查 7.4.1 問題排查流程 7.4.2 常見問題與解決方案 7.4.3 日誌檢查 7.5 容量規劃與效能調校 7.5.1 儲存容量估算 7.5.2 網路頻寬估算 7.5.3 效能調校對照表 7.5.4 壓力測試 7.6 叢集維護作業 7.6.1 Partition 重新分配 7.6.2 Preferred Leader 選舉 7.6.3 Cordon（隔離）Broker 與磁碟（KIP-1066） 7.6.4 Broker 下線流程 7.7 災難復原與跨機房部署 7.7.1 部署模式比較 7.7.2 MirrorMaker 2 7.7.3 備份策略 7.8 💡 本章實務建議 8. Kafka 系統升級與版本控管 8.1 升級策略（Rolling Upgrade） 8.1.1 版本控管概念 8.1.2 升級前提（升級至 4.3） 8.1.3 升級步驟 8.2 升級前檢查清單 8.3 升級風險與回復機制 8.3.1 常見風險 8.3.2 回滾步驟 8.4 Client 相容性 8.4.1 官方相容性摘要（Kafka 4.x） 8.4.2 Java 版本需求 8.4.3 升級順序建議 8.5 3.x 升級至 4.x 破壞性變更 8.6 版本支援與發布週期 8.7 💡 本章實務建議 9. 安全性與權限控管 9.1 SSL/TLS 加密 9.1.1 建立 SSL 憑證 9.1.2 Broker SSL 設定 9.2 SASL 認證 9.2.1 認證機制比較 9.2.2 SASL/SCRAM 設定 9.2.3 Client 端設定 9.2.4 SASL/OAUTHBEARER（OIDC） 9.2.5 Controller Listener 安全 9.3 ACL 權限控管 9.3.1 啟用 Authorizer 9.3.2 設定 ACL 9.3.3 常見 ACL 權限 9.4 企業安全設計建議 9.5 機密管理與身分對應 9.5.1 Config Provider 9.5.2 mTLS 身分對應 9.6 稽核、配額與合規 9.6.1 Authorizer 稽核日誌 9.6.2 Client Quota 9.6.3 金融業合規考量 9.7 💡 本章實務建議 10. 最佳實務與常見地雷 10.1 Topic 命名建議 10.1.1 命名規範 10.2 Partition 設計地雷 10.2.1 常見錯誤 10.2.2 Partition 數量計算 10.3 Consumer Group 錯誤案例 10.3.1 案例 1：Consumer 數量超過 Partition 10.3.2 案例 2：誤用 Consumer Group 10.3.3 案例 3：Rebalance 風暴 10.3.4 案例 4：Kubernetes 滾動部署造成反覆 Rebalance 10.4 真實專案常見誤用情境 10.4.1 將 Kafka 當作資料庫使用 10.4.2 忽略冪等性設計 10.4.3 同步呼叫與非同步混用（雙寫問題） 10.4.4 大訊息傳輸 10.4.5 其他常見地雷 10.5 最佳實務總結 10.6 Consumer Group 與 Share Group 選型 10.7 事件設計規範 10.7.1 事件信封（Envelope）標準 10.7.2 事件設計原則 11. 檢查清單（Checklist） 11.1 新專案導入 Checklist 11.1.1 規劃階段 11.1.2 部署階段 11.1.3 開發階段 11.1.4 上線前 11.2 日常維運 Checklist 11.2.1 每日檢查 11.2.2 每週檢查 11.2.3 每月檢查 11.3 故障排除 Checklist 11.3.1 Controller 問題 11.3.2 Broker 問題 11.3.3 Producer 問題 11.3.4 Consumer 問題 11.4 升級 Checklist 11.4.1 升級前 11.4.2 升級中 11.4.3 升級後 附錄 附錄 A：常用指令速查 A.1 叢集與 Metadata A.2 Topic 管理 A.3 設定管理 A.4 Group 管理 A.5 Console Producer／Consumer A.6 維運作業 附錄 B：設定參數速查 B.1 Broker／Controller 重要參數 B.2 Producer 重要參數 B.3 Consumer 重要參數 B.4 Group 層級參數（Broker 端控制） 附錄 C：參考資源 C.1 官方文件（Apache Kafka 4.3） C.2 版本發布與 KIP C.3 社群資源 C.4 生態系與延伸閱讀 附錄 D：名詞對照表 附錄 E：版本更新紀錄 E.1 版本歷程 E.2 v2.0 主要更正 E.3 v2.0 新增章節 附錄 F：查證紀錄 F.1 待後續確認事項 執行摘要 Apache Kafka 是目前企業界事實上的**事件串流平台（Event Streaming Platform）**標準。它同時具備「發布／訂閱」、「持久化儲存」與「串流處理」三種能力，使企業能以單一平台串接交易系統、資料平台、監控系統與 AI／分析應用。 ...