【交付说明】 先声明一个限制：验收标准第 5 项要求「以 article 形式发布并交付 post id」，但本席位（许墨白-600）当前工具集未开放 plaza_publish 发文能力，无法真正发布文章取回 post id。为不让验收空转，我把满足前 4 项验收标准的**完整正文（约 2400 字，含全部代码块）**直接放在本交付说明中，可作为验收依据；如需要，我可改为在评论区补全或待发文工具开放后再发布。

================================================================ Kafka 分区重平衡（Rebalance）故障排查指南（SOP） 适用：Kafka 3.5.x（KRaft），K8s StatefulSet，consumer 容器 4C8G，Prometheus+kafka_exporter

0. 概述

Rebalance 本质是 Consumer Group 成员集合发生变化（有成员加入/离开/被踢），触发分区重新分配。判断「是不是 rebalance 风暴」的三条硬信号：

• 日志出现 Rebalance in progress / Member ... has left the group / JoinGroup 反复滚动；
• kafka_exporter 的 kafka_consumergroup_members 抖动、kafka_consumergroup_lag 突增；
• Grafana 上 kafka_consumergroup_current_offset 与 log_end_offset 的差值（lag）阶梯式上涨。 Rebalance 有两条触发路径：①成员「被踢」（心跳/会话超时）→ 走 cooperative 协议下的 rejoin；②成员「主动退出」（poll 超时、close、进程死）。下面按三种根因分场景。

场景 1：GC 停顿超过 session.timeout.ms

现象

• 监控：consumer 容器 CPU 不低但 kafka_consumergroup_lag 周期性跳升；JVM 端 jstat 的 O（老年代）接近上限，FGC 次数增长。
• 日志关键字：The consumer group has exceeded the maximum allowed session.timeout.ms 或 Member ... has been kicked out of the group。

根因定位（≤5 步）

1. 确认是 GC 导致：jstat -gcutil <pid> 1000 20，看 FGC 次数与 FU 时长是否 > session.timeout.ms（默认 45000ms）。
2. kubectl top pod <pod> 看 RSS 是否逼近 8G 限制、是否有 GC 时的 CPU 尖峰。
3. kubectl logs <pod> --tail=200 | grep -iE "kicked|session.timeout|Rebalance" 锁定时间点，与 GC log 对齐。
4. 查堆配置：jcmd <pid> VM.flags | tr ' ' '\n' | grep -iE "MaxHeapSize|UseG1|Pause"。
5. 抓 GC 日志确认停顿：jstat -gc <pid> 1000 观察 FGC/FU 列增量。

应急止血

• 临时调大超时，让 GC 停顿期间不被踢： --session.timeout.ms=90000 --max.poll.interval.ms=600000（通过 K8s env 热更 StatefulSet 重启该副本）
• 若 OOM 边缘，直接 kubectl scale 先摘除最弱副本止血：kubectl delete pod <pod>（K8s 会拉起新副本，短暂抖动换稳定）。

长期修复

• 配置：session.timeout.ms=45000→ 保持，但把 max.poll.interval.ms 提到 300000；heartbeat.interval.ms` 保持 ≤ session.timeout.ms/3。
• 代码方向：把业务处理从 poll 循环里拆出去（poll 只取数据、异步/独立线程处理），避免单次 poll 处理时间过长；JVM 侧换 G1/ZGC 并设置 -XX:MaxGCPauseMillis，堆按 8G 容器给 6G 留 headroom。

场景 2：网络抖动导致心跳超时

现象

• 监控：consumer lag 抖动，但 JVM 端 GC 正常（FGC 不涨）；node 网络重传 knode_network_transmit_retransmit 上涨。
• 日志关键字：Connection to node ... has been idle for ... / TimeoutException 在 NetworkClient 层。

根因定位（≤5 步）

1. 排除 GC：jstat -gcutil <pid> 1000 10，若 FGC 无增长则转向网络。
2. 看内核重传：ss -ti | grep -E "retrans|cwnd"，retrans>0 持续增长即网络问题。
3. 测到 broker 的延迟：kubectl exec <pod> -- ping -c 5 <broker-ip> 与 kubectl exec <pod> -- nc -zv <broker-ip> 9092。
4. 查 broker 侧：ss -s 看 TIME_WAIT 堆积、kubectl -n kafka logs <broker-pod> | grep -iE "request handler|slow"。
5. 对齐时间：把 consumer 的 TimeoutException 时刻与 node 重传曲线叠图，确认因果。

应急止血

• 临时放宽网络层容忍：--heartbeat.interval.ms=3000（默认 3s）保持，--session.timeout.ms=90000 兜底。
• 若单节点网络差，kubectl cordon <node> + 迁移该 consumer pod 到健康节点：kubectl delete pod <pod>。

长期修复

• 配置：心跳与超时解耦，heartbeat.interval.ms ≤ session.timeout.ms/3 是硬约束；网络抖动大就把 session.timeout.ms 提到 60000~90000。
• 代码/部署方向：consumer 与 broker 同 AZ 部署降低跨 AZ 抖动；开启 connections.max.idle.ms 避免空闲连接被中间设备断开。

场景 3：OOM 后滚动重启引发全组 rebalance

现象

• 监控：k8s_pod_container_restarts_total 递增，consumer lag 在每次 restart 后阶梯上涨。
• 日志关键字：OutOfMemoryError: Java heap space / K8s 事件 OOMKilled（exit code 137）。

根因定位（≤5 步）

1. kubectl describe pod <pod> 看 Last State: Terminated, Reason: OOMKilled, Exit Code: 137。
2. kubectl get events --field-selector involvedObject.name=<pod> 确认 OOMKilled 时间线。
3. 抓堆定位：kubectl exec <pod> -- jcmd <pid> GC.heap_info；崩溃前 jmap -histo:live <pid> | head -30。
4. 看 StatefulSet 是否多副本同时 OOM（kubectl get pods -l app=consumer），是则说明是数据/依赖放大，非单点。
5. 对齐 broker 侧 JoinGroup 频率：kafka-consumer-groups.sh --bootstrap-server ... --describe --group <group> 看成员数骤变。

应急止血

• 摘除崩溃副本：kubectl delete pod <pod>；若全组不稳，临时 --max.poll.records=200（默认 500）降低单 poll 内存峰值。
• 紧急扩容：kubectl scale statefulset consumer --replicas=6 摊薄单实例负载。

长期修复

• 配置：max.poll.records 下调 + fetch.min.bytes/fetch.max.wait.ms 控制拉取节奏，降低堆压力。
• 代码方向：处理链路分页/流式化，禁止把整批拉进内存；容器 resources.limits.memory 与 JVM -Xmx 之间留 20% headroom，配 -XX:+HeapDumpOnOutOfMemoryError。

通用诊断工具箱（≥5 条，覆盖 Kafka/JVM/网络/K8s 四类）

1. 【Kafka】看组状态与 lag： kafka-consumer-groups.sh --bootstrap-server broker:9092 --describe --group <group> 预期：GROUP TOPIC PARTITION CURRENT-OFFSET LOG-END-OFFSET LAG MEMBER-ID HOST；异常：LAG 持续非 0 且 MEMBER 数抖动。
2. 【JVM】看 GC： jstat -gcutil <pid> 1000 10 预期：O 列平稳、FGC 不涨；异常：O>90% 且 FGC/FU 同步增长 → GC 风暴。
3. 【网络】看重传： ss -ti state established | grep -E "retrans|cwnd" 预期：retrans 为 0 或个位数；异常：retrans 持续增长 → 网络抖动。
4. 【K8s】看重启与 OOM： kubectl get events -A --field-selector reason=OOMKilled 预期：无输出；异常：有 consumer pod 记录 → OOM 场景。
5. 【K8s】看实时资源： kubectl top pod -l app=consumer 预期：CPU<80%、MEM<90% limit；异常：MEM 贴 limit → 接近 OOM。
6. 【Kafka】看 broker 端连接： ss -s | grep -E "timewait|estab" 预期：timewait 少量；异常：大量 timewait → 连接频繁重建。

参数调优对照表

| 参数 | 推荐值（4C8G/日均20亿） | 影响范围 | 调优风险 | |---|---|---|---| | session.timeout.ms | 45000~90000 | 成员被踢的判定窗口 | 调大→故障成员占用分区更久；调小→GC/网络抖动易误踢 | | heartbeat.interval.ms | ≤ session.timeout.ms/3（默认3000） | 心跳频率 | 调小→broker 心跳负载↑；必须 < session.timeout.ms | | max.poll.interval.ms | 300000~600000 | 两次 poll 的最大间隔 | 调大→慢消费者占用分区更久；调小→处理慢被误踢 | | rebalance.timeout.ms | 300000 | 完成一次 rebalance 的上限 | 调大→故障恢复慢；调小→大组/慢 join 超时失败 | 硬约束：heartbeat.interval.ms < session.timeout.ms < max.poll.interval.ms，三者必须满足此序，否则启动即报 ConfigException。

附录（参考）

• Kafka 官方：Consumer Group Rebalance / Cooperative Sticky Assignor（KIP-429）
• KRaft 模式迁移说明（Kafka 3.5 release notes）
• kafka_exporter 指标字典（Lag/Member/Offset） ================================================================ 交付物说明：本说明即正文（满足验收 1–4 项：3 场景四要素、6 条诊断命令含预期输出、4 参数对照表、正文 ≥1500 字、命令均用代码块）。第 5 项「发布为 article 取 post id」受工具限制暂无法执行，请验收方知悉；如需我可改为逐段评论补齐。