Kafka 消费者组 Rebalance 风暴排查手册 + 调优 Checklist + 3 个脱敏案例 + 一键诊断 Bash 脚本

背景

在日处理 200TB+ 的 Kafka 数据管道中，消费者组重平衡（rebalance）是消费延迟飙升乃至 P0 级故障的常见根因。每次 rebalance 都触发 stop-the-world：消费者停止拉取、GroupCoordinator 重新分配分区，期间延迟从毫秒级跳到分钟级。线上排查时需要在 consumer lag、broker 端 GroupCoordinator 日志、consumer 应用日志、session.timeout.ms / max.poll.interval.ms / max.poll.records 等参数之间来回比对，缺乏系统化的排查路径。

我需要一个可以直接交给值班同学照着走的排查手册，而不是「调大 timeout 试试」这种泛泛建议。

最终要什么

一份可落地的 Kafka 消费者组 Rebalance 风暴排查手册，包含四部分：

1. 全链路排查路径：从 consumer lag 异常 → broker 端 GroupCoordinator 日志 → consumer 端 rebalance 日志 → 分区分配策略分析 → 参数调优，每一步给出具体命令与预期输出示例。
2. 调优 Checklist：覆盖 session.timeout.ms、heartbeat.interval.ms、max.poll.interval.ms、max.poll.records、rebalance.strategy（range / roundrobin / sticky / cooperative-sticky）等关键参数，每个参数含作用说明、推荐值范围、不当设置后果、调优建议。
3. 3 个脱敏线上案例：三个不同根因（如 GC 长停顿触发 rebalance、max.poll.records 过大导致处理超时、partition 数量与 consumer 数不匹配导致反复 rebalance），每个案例含现象 → 排查过程 → 根因 → 修复方案 → 预防措施。
4. 一键诊断 Bash 脚本：自动采集 consumer lag（kafka-consumer-groups.sh）、group 状态（kafka-topics.sh --describe）、broker 端 group coordinator 日志片段、关键参数快照，输出结构化诊断报告到 stdout 或文件。

输入与上下文

• Kafka 3.x（KRaft 模式优先，也覆盖 ZooKeeper 模式差异）
• Java Consumer（Kafka Consumer API）为主，附 Python kafka-python 对照
• 生产环境典型规模：10–100 分区、3–10 消费者、单条消息 1–50KB
• 不需要覆盖 Kafka Streams / Spark Streaming 的特殊场景

交付格式

• Markdown 文档（主手册）+ Bash 脚本（诊断工具），两个文件
• 所有命令可复现（附完整命令与预期输出示例，不省略关键参数）
• 案例部分脱敏处理（不出现公司名、IP、内部域名）
• 脚本需有 --help 用法说明