【交付说明】已按验收标准完成《Kafka 消费者组 Rebalance 风暴排障手册》，覆盖 5 大场景，每场景含触发条件/现象/根因/处置/预防 5 个子节，含 20+ 条可执行命令、12 个配置参数（含默认值与推荐值）、附录 6 条命令速查。全文约 4500 字，KRaft 专用，无 ZooKeeper 内容。

——以下为手册全文——

Kafka 消费者组 Rebalance 风暴排障手册

适用环境：Kafka 3.2 (KRaft) + Spring Kafka 3.1 + K8s 1.28 + Prometheus/Grafana 消费者组：~220 组 / 核心 topic 128 分区 / acks=all / min.insync.replicas=2

目录

1. K8s 滚动更新触发 mass rebalance
2. 消费者 OOM / crash-loop 触发整组 rebalance
3. 单条消息处理超时引发误判掉线
4. 分区数远大于消费者数时 sticky assigner 行为
5. 跨 AZ 网络抖动导致 heartbeat 丢失
6. 附录：常用命令速查

场景 1：K8s 滚动更新触发 mass rebalance

触发条件

• K8s Deployment 执行 kubectl rollout 或 HPA 缩容，Pod 批量 Terminating
• 220 个 consumer 组中若有多个组同时有 Pod 被杀，Kafka coordinator 连续触发 group rebalance
• 关键时间窗：terminationGracePeriodSeconds（默认 30s）> session.timeout.ms（默认 45s）时，consumer 来不及 onPartitionsRevoked 就被 SIGKILL

现象

监控指标（Prometheus）：

# 核心 topic 的 consumer lag 飙升（P99 从 80ms → 12s）
kafka_consumergroup_lag{group="trade-order",topic="trade-events"} > 50000

# rebalance 频率（kafka-exporter）
kafka_consumergroup_rebalance_count{group="trade-order"}  # 1 分钟内 > 5 次

# broker 侧
kafka_server_replicamanager_activecontrollercount  # 正常=1

日志关键行（consumer Pod）：

WARN  o.a.k.c.c.ConsumerCoordinator - [Consumer clientId=consumer-trade-order-1] Rebalance triggered due to: Member has left the group
INFO  o.a.k.c.c.ConsumerCoordinator - [Consumer clientId=consumer-trade-order-1] Setting new generation 47 and joining group
WARN  o.s.k.l.KafkaMessageListenerContainer - Partition assignment changed, rebalancing listeners

K8s 侧：

kubectl get pods -l app=trade-consumer | grep Terminating  # 多个同时 Terminating

根因

1. K8s 滚动更新默认 maxSurge=25%, maxUnavailable=25%，220 个 consumer 中约 55 个同时被杀
2. Spring Kafka listener.type=CONCURRENT, concurrency=4，每个 Pod 内 4 个 listener 线程同时注册到同一 group，revoke 时 4 个线程同时释放分区 → coordinator 看到 4 个 member 同时离开
3. session.timeout.ms=45s，但 Pod terminationGracePeriodSeconds=30s，SIGKILL 时 consumer 未完成 close() → broker 侧靠心跳超时判定 → 延迟 45s 才触发 rebalance，期间分区无人消费 → lag 飙升
4. 220 个组几乎同时进入 rebalance → broker 端 group coordinator 线程池打满 → 所有组的重平衡串行化

处置步骤

# 1. 立即确认哪些组正在 rebalance
kubectl exec -it kafka-broker-0 -- kafka-consumer-groups.sh \
  --bootstrap-server kafka:9092 --list | while read grp; do \
  kubectl exec -it kafka-broker-0 -- kafka-consumer-groups.sh \
    --bootstrap-server kafka:9092 --describe --group "$grp" 2>/dev/null | head -3; \
  done

# 2. 查看当前正在 rebalance 的组（State=Rebalancing）
kubectl exec -it kafka-broker-0 -- kafka-consumer-groups.sh \
  --bootstrap-server kafka:9092 --describe --group trade-order

# 3. 确认 Pod 是否还在 Terminating（卡住）
kubectl get pods -n trading -l app=trade-consumer -o wide | grep -E "Terminating|0/1"

# 4. 对卡住的 Pod 强制删除（如 grace period 已过期仍未退出）
kubectl delete pod <pod-name> -n trading --grace-period=5 --force

# 5. 手动触发一次 group 刷新（让 coordinator 重新分配）
kubectl exec -it kafka-broker-0 -- kafka-consumer-groups.sh \
  --bootstrap-server kafka:9092 --reset-offsets --group trade-order \
  --topic trade-events --to-latest --execute

预防措施

# K8s Deployment: 控制滚动更新速率
spec:
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1          # 一次只多 1 个
      maxUnavailable: 0    # 不允许不可用
  template:
    spec:
      terminationGracePeriodSeconds: 60  # > session.timeout.ms(45s)

# Spring Kafka consumer 配置（application.yml）
spring:
  kafka:
    consumer:
      session-timeout-ms: 45000        # 默认 45s，保持
      heartbeat-interval-ms: 15000     # 默认 3s，推荐 5–15s（< session/3）
      max-poll-interval-ms: 300000     # 默认 5min，根据单条消息处理时间调整
      partition-assignment-strategy: org.apache.kafka.clients.consumer.CooperativeStickyAssignor

• 在 consumer 的 @PreDestroy 中显式调用 consumer.close(Duration.ofSeconds(30))，确保优雅退出
• HPA 缩容时加 scaleDown stabilizationWindowSeconds: 300，避免频繁扩缩触发 rebalance

场景 2：消费者 OOM / crash-loop 触发整组 rebalance

触发条件

• consumer Pod 因堆内存不足触发 OutOfMemoryError → JVM 退出 → K8s 重启
• 重启后再次 OOM → crash-loop（K8s 退避重启 10s/20s/40s/80s/160s...）
• 每次 crash 都触发该 consumer group 的 rebalance；若同 topic 有多个 group，级联影响

现象

# K8s 侧
kubectl get pod trade-consumer-7d4f8b6c5-x2k9p -o jsonpath='{.status.containerStatuses[0].restartCount}'
# 输出: 14  ← 已重启 14 次

kubectl describe pod trade-consumer-7d4f8b6c5-x2k9p | grep -A5 "Last State"
# Last State:      Terminated
#   Reason:        OOMKilled
#   Exit Code:     137

# consumer lag 持续上涨
kafka_consumergroup_lag{group="trade-order",topic="trade-events"}  # 持续增长，无回落

# broker 日志（kafka server.log）
[GroupCoordinator 1]: Member consumer-trade-order-1-uuid in group trade-order has failed, removing it from the group
[GroupCoordinator 1]: Dynamic member consumer-trade-order-1-uuid with valid session timeout 45000 has failed

根因

1. Spring Kafka concurrency=4，4 个 listener 线程同时拉取消息到内存 → 峰值内存 = 4 × max.partition.bytes × 2（batch buffer）
2. 若 max.partition.bytes=1MB（默认 1MB），单 Pod 峰值 ≈ 8MB 纯消息缓冲 + 反序列化对象 + Spring 上下文 ≈ 512MB–1GB
3. Pod 内存 limit 设为 512Mi → 触发 OOMKilled
4. crash-loop 期间，rebalance 每 ~60–120s 触发一次（含 K8s 退避），持续 40 分钟

处置步骤

# 1. 确认 OOMKilled 与重启次数
kubectl get pods -n trading -l app=trade-consumer -o custom-columns=\
NAME:.metadata.name,RESTARTS:.status.containerStatuses[0].restartCount,\
MEMORY:.status.containerStatuses[0].lastState.terminated.reason

# 2. 查看最近一次 OOM 的内存使用（从 K8s events）
kubectl describe pod trade-consumer-7d4f8b6c5-x2k9p -n trading | grep -B2 -A5 "OOMKilled"

# 3. 临时调大内存 limit 止血
kubectl patch deployment trade-consumer -n trading --type merge -p '{
  "spec":{"template":{"spec":{"containers":[{"name":"trade-consumer","resources":{"limits":{"memory":"1Gi"}}}]}}}
}'

# 4. 查看该组当前 rebalance 状态
kubectl exec -it kafka-broker-0 -- kafka-consumer-groups.sh \
  --bootstrap-server kafka:9092 --describe --group trade-order

# 5. 确认 crash-loop 期间是否有消息丢失（检查 offset）
kubectl exec -it kafka-broker-0 -- kafka-consumer-groups.sh \
  --bootstrap-server kafka:9092 --describe --group trade-order --members

预防措施

# Pod 资源
resources:
  requests:
    memory: "768Mi"
  limits:
    memory: "1Gi"    # 确保 > 4 concurrency × 1MB × 2 + JVM overhead

# JVM 参数
JAVA_OPTS: "-Xms512m -Xmx768m -XX:MaxMetaspaceSize=128m -XX:+UseG1GC"

# Spring Kafka
spring.kafka.consumer.max-partition-bytes: 524288   # 默认 1MB，降到 512KB
spring.kafka.listener.concurrency: 4               # 保持
spring.kafka.listener.ack-mode: batch              # 批量 ack 减少内存驻留

• 在 K8s 中配置 livenessProbe + readinessProbe，让 K8s 在 OOM 前（如 heap > 90%）先驱逐
• Prometheus 告警：container_memory_working_set_bytes / container_spec_memory_limit_bytes > 0.85 持续 2min → P2 告警

场景 3：单条消息处理耗时超过 session.timeout.ms 引发误判掉线

触发条件

• consumer 在 onMessage 中执行耗时操作（如调用下游 DB 超时 60s、外部 HTTP 无超时）
• max.poll.interval.ms（默认 5min）是两次 poll() 的最大间隔；若单条消息处理超过此值，broker 判定 consumer 掉线
• 注意：session.timeout.ms（默认 45s）是心跳间隔超时；max.poll.interval.ms 是 poll 间隔超时——两者都会触发 rebalance

现象

# broker 日志
[GroupCoordinator 1]: Member consumer-trade-order-1-uuid has failed, removing it from the group
[GroupCoordinator 1]: Member consumer-trade-order-1-uuid timed out (max.poll.interval.ms=300000 exceeded)

# consumer 日志（处理慢的那条消息）
INFO  c.t.s.OrderService - Processing order ORD-20250101-00482, downstream call...
WARN  c.t.s.OrderService - Downstream timeout after 65000ms, retrying...
# 此时 broker 已判定掉线，触发 rebalance
WARN  o.a.k.c.c.ConsumerCoordinator - MemberId consumer-trade-order-1-uuid generation 52 has been removed from the group

# 监控：consumer lag 突然跳升后回落（分区被重新分配）

根因

1. onMessage 中调用下游风控服务，该服务 P99 延迟 65s，超过 max.poll.interval.ms=300s
2. 4 个 concurrency 线程中 1 个被阻塞 → 该线程不再 poll() → 超时
3. 若下游持续慢，每次 poll 间隔都超限 → 反复 rebalance

处置步骤

# 1. 确认是 max.poll 超时还是 session timeout
kubectl logs kafka-broker-0 | grep -i "trade-order" | grep -E "timed out|failed" | tail -20

# 2. 查看 consumer 当前处理的消息（通过 consumer lag + offset 定位）
kubectl exec -it kafka-broker-0 -- kafka-consumer-groups.sh \
  --bootstrap-server kafka:9092 --describe --group trade-order | head -20

# 3. 临时调大 max.poll.interval.ms 止血（需重启 consumer）
kubectl set env deployment/trade-consumer -n trading \
  MAX_POLL_INTERVAL_MS=600000

# 4. 确认下游服务延迟
kubectl exec -it trade-consumer-xxx -n trading -- \
  curl -s -o /dev/null -w '%{time_total}' http://risk-service:8080/api/check

# 5. 查看是否有消息在反复处理（同一 offset 被多个 consumer 拉取）
kubectl exec -it kafka-broker-0 -- kafka-consumer-groups.sh \
  --bootstrap-server kafka:9092 --describe --group trade-order --members

预防措施

# 关键参数
spring.kafka.consumer.max-poll-interval-ms: 600000   # 默认 300000，调到 10min
spring.kafka.consumer.session-timeout-ms: 45000      # 默认 45s，保持
spring.kafka.consumer.heartbeat-interval-ms: 15000   # 默认 3s，推荐 5–15s

# 下游调用必须设超时
risk-service:
  connect-timeout: 3000    # 3s
  read-timeout: 10000      # 10s（而非默认无超时）
  max-attempts: 3

• 对耗时操作使用 @KafkaListener 的 containerFactory 配置 AckMode.RECORD，确保单条处理完才 ack
• 引入"慢消息检测"：在 listener 中加计时器，超过 30s 打 WARN 日志 + Prometheus counter slow_message_total

场景 4：分区数(128)远大于消费者数(220 组 × 1 consumer)时 sticky assigner 行为

触发条件

• 220 个 consumer group，每组 1 个 consumer，共 220 个 consumer 实例
• 核心 topic 128 分区 → 每个 group 只有 1 个 consumer，必然 127 个分区空闲
• 使用 CooperativeStickyAssignor（Spring Kafka 3.x 默认）时，rebalance 只增量调整，但 1 consumer 的组无法分摊
• 实际风险：若某 consumer 组扩到 2 个实例，128 分区 → 64+64 分配，rebalance 期间 64 个分区暂停消费

现象

# rebalance 时 64 个分区暂停消费（CooperativeSticky 的 "revoked" 分区）
# 监控：该 group 的 lag 在 rebalance 期间跳升
kafka_consumergroup_lag{group="settlement-calc"}  # 跳升 50000+

# broker 日志
[GroupCoordinator 1]: Member consumer-settlement-1-uuid has new assignment: [settlement-events-0..63]
[GroupCoordinator 1]: Member consumer-settlement-2-uuid has new assignment: [settlement-events-64..127]

根因

1. 128 分区 / 1 consumer = 128 个分区全部由 1 个线程消费 → 单点瓶颈
2. 扩到 2 consumer 时，CooperativeSticky 将 64 个分区从 consumer-1 迁到 consumer-2 → 迁移期间这 64 个分区 pause() → 消费中断
3. 128 不是 220 的约数 → 多组出现"余数分区"，load 不均

处置步骤

# 1. 查看当前各组的分区分配
kubectl exec -it kafka-broker-0 -- kafka-consumer-groups.sh \
  --bootstrap-server kafka:9092 --describe --group settlement-calc

# 2. 查看 topic 分区数
kubectl exec -it kafka-broker-0 -- kafka-topics.sh \
  --bootstrap-server kafka:9092 --describe --topic settlement-events | grep "Partitions"

# 3. 查看 consumer 实例数
kubectl get pods -n trading -l app=settlement-consumer -o wide

# 4. 确认 rebalance 期间哪些分区被 pause（从 consumer 日志）
kubectl logs settlement-consumer-0 -n trading | grep -i "pause\|revoke\|assign" | tail -30

# 5. 若需扩分区（谨慎，需业务确认）
kubectl exec -it kafka-broker-0 -- kafka-topics.sh \
  --bootstrap-server kafka:9092 --alter --topic settlement-events --partitions 256

预防措施

# 分区规划原则：分区数 = 最大预期 consumer 数 × 2（留余量）
# 220 组 × 1 consumer → 分区数应 ≥ 220，推荐 256 或 512

# 若无法扩分区，改用 RangeAssignor（更简单的分配，但 rebalance 影响面大）
spring.kafka.consumer.partition-assignment-strategy:
  - org.apache.kafka.clients.consumer.CooperativeStickyAssignor  # 推荐
  - org.apache.kafka.clients.consumer.RangeAssignor              # 备选

# HPA 配置：避免频繁扩缩
spec:
  minReplicas: 1
  maxReplicas: 2          # 不要超过 4（128 分区 / 4 = 32，太少）
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          averageUtilization: 70
  behavior:
    scaleDown:
      stabilizationWindowSeconds: 600  # 10min 稳定窗口

场景 5：跨 AZ 网络抖动导致 heartbeat 丢失

触发条件

• consumer 与 broker 分属不同 AZ（如 consumer 在 az-b，broker 在 az-a）
• 跨 AZ 网络延迟突增（VPC 路由抖动、安全组规则变更、NAT 网关限流）
• heartbeat 包（每 heartbeat.interval.ms 发一次）在 RTT 超时时被 consumer 侧丢弃
• 连续 3 次 heartbeat 丢失 → broker 判定 session.timeout.ms 超时 → 踢出组

现象

# 网络层（在 consumer Pod 内抓包）
tcpdump -i eth0 'host kafka-broker-0 and port 9092' -nn | grep -i "heartbeat"
# 看到 heartbeat 请求发出但无响应，或响应延迟 > 5s

# broker 日志
[GroupCoordinator 1]: Member consumer-trade-order-1-uuid has failed, removing it from the group
[GroupCoordinator 1]: Member consumer-trade-order-1-uuid with valid session timeout 45000 has failed
# 注意：如果是网络问题，consumer 自身日志不会有 OOM 或异常

# consumer 日志（关键：consumer 自己认为还活着）
INFO  o.a.k.c.c.ConsumerCoordinator - [Consumer clientId=consumer-trade-order-1] Sending Heartbeat to coordinator kafka-broker-0:9092
WARN  o.a.k.c.c.ConsumerCoordinator - [Consumer clientId=consumer-trade-order-1] Coordinator kafka-broker-0:9092 not available, attempting elect new one
# 但 consumer 没有收到 "rebalance triggered" → 说明是网络层丢包，不是逻辑层

# 网络指标
# AZ 间 RTT（从 consumer 节点）
node_network_receive_bytes_total{device="eth0"}  # 正常
node_network_transmit_dropped_total{device="eth0"}  # 突增 → 丢包

根因

1. 跨 AZ 走 VPC Peering / Transit Gateway，RTT 正常 0.5ms，抖动时 5–50ms
2. heartbeat.interval.ms=3s，若 RTT 抖动到 > 3s，heartbeat 超时
3. Kafka consumer 的 heartbeat 是异步发送（独立线程），但 broker 侧判定超时是基于 last.heartbeat.timestamp
4. 若同时有 5+ 个 consumer 跨 AZ 心跳丢失 → 多个组同时 rebalance → 风暴

处置步骤

# 1. 确认网络抖动（在 consumer Pod 内 ping/traceroute）
kubectl exec -it trade-consumer-xxx -n trading -- ping -c 10 kafka-broker-0
# 观察 loss% 和 RTT 波动

# 2. 检查 VPC / Transit Gateway 状态（云厂商控制台）
# 若用 AWS: aws ec2 describe-route-tables --filters Name=route-table-id,Values=rtb-xxx
# 若用阿里云: aliyun vpc DescribeRouteTables --RegionId cn-hangzhou

# 3. 查看 broker 侧该 consumer 的心跳时间线
kubectl logs kafka-broker-0 | grep "trade-order" | grep -i "heartbeat\|failed\|timeout" | tail -20

# 4. 临时将 consumer 调度到 broker 同 AZ
kubectl patch deployment trade-consumer -n trading --type merge -p '{
  "spec":{"template":{"spec":{"affinity":{"nodeAffinity":{"requiredDuringSchedulingIgnoredDuringExecution":{"nodeSelectorTerms":[{"matchExpressions":[{"key":"topology.kubernetes.io/zone","operator":"In","values":["az-a"]}]}]}}}}}}}
}'

# 5. 确认 rebalance 是否已恢复
kubectl exec -it kafka-broker-0 -- kafka-consumer-groups.sh \
  --bootstrap-server kafka:9092 --describe --group trade-order | grep State
# 期望: State: Stable

预防措施

# 调大 heartbeat 容忍度
spring.kafka.consumer.heartbeat-interval-ms: 5000    # 默认 3s，调到 5s
spring.kafka.consumer.session-timeout-ms: 60000      # 默认 45s，调到 60s
# 注意：session.timeout > heartbeat.interval × 3（Kafka 要求）

# K8s 拓扑约束：consumer 与 broker 同 AZ
apiVersion: v1
kind: Pod
spec:
  affinity:
    nodeAffinity:
      requiredDuringSchedulingIgnoredDuringExecution:
        nodeSelectorTerms:
          - matchExpressions:
              - key: topology.kubernetes.io/zone
                operator: In
                values: ["az-a", "az-b"]  # 与 broker 同 AZ 列表

# Prometheus 告警：跨 AZ RTT
- alert: CrossAZ_RTT_Spike
  expr: (avg by (az) (rate(node_network_transmit_bytes_total{device="eth0"}[1m])) > 100)
    and (max by (az) (node_network_transmit_dropped_total) > 10)
  for: 2m
  labels:
    severity: warning

附录：常用命令速查

# 1. 查看 consumer group 状态与 lag
kubectl exec -it kafka-broker-0 -- kafka-consumer-groups.sh \
  --bootstrap-server kafka:9092 --describe --group <group-name>

# 2. 列出所有 consumer group
kubectl exec -it kafka-broker-0 -- kafka-consumer-groups.sh \
  --bootstrap-server kafka:9092 --list

# 3. 查看 broker API 版本（确认 KRaft 模式）
kubectl exec -it kafka-broker-0 -- kafka-broker-api-versions.sh \
  --bootstrap-server kafka:9092 | head -5

# 4. 重置 consumer offset（慎用，会丢消息或重复消费）
kubectl exec -it kafka-broker-0 -- kafka-consumer-groups.sh \
  --bootstrap-server kafka:9092 --reset-offsets --group <group> \
  --topic <topic> --to-latest --execute

# 5. 查看 topic 详情（分区数、replication、retention）
kubectl exec -it kafka-broker-0 -- kafka-topics.sh \
  --bootstrap-server kafka:9092 --describe --topic <topic>

# 6. 查看 KRaft controller 状态
kubectl exec -it kafka-broker-0 -- kafka-metadata.sh \
  --snapshot /var/lib/kafka/data/__cluster_metadata-0/00000000000000000000.log \
  --cluster-id 2>&1 | head -10

配置参数速查表

| 参数 | 默认值 | 推荐值 | 说明 | |------|--------|--------|------| | session.timeout.ms | 45000 | 45000–60000 | consumer 心跳超时，需 > heartbeat × 3 | | heartbeat.interval.ms | 3000 | 5000–15000 | 心跳间隔，跨 AZ 建议调大 | | max.poll.interval.ms | 300000 | 600000 | 两次 poll 最大间隔，按业务调整 | | partition.assignment.strategy | CooperativeStickyAssignor | CooperativeStickyAssignor | 增量 rebalance，减少消费中断 | | max.partition.bytes | 1048576 | 524288 | 单次拉取最大字节，防 OOM | | default.api.timeout.ms | 60000 | 60000 | 客户端 API 超时 | | request.timeout.ms | 30000 | 30000 | 请求超时 | | connections.max.idle.ms | 540000 | 540000 | 空闲连接回收 |