集群升级与滚动重启实践

集群元数据（topic、分区、ISR、ACL）存储在 ZooKeeper
broker 与 ZK 交互，Controller 由 ZK 选举产生

元数据作为「元数据日志」存在 Kafka 自身（__cluster_metadata topic）
Controller 由 Raft 协议选举，无需 ZK
优点：启动快、元数据扩展性好、运维组件少

① 目标版本与当前版本的「升级路径」是否直达（避免跨太多大版本）
② 客户端协议版本兼容（老客户端能否连新 broker）
③ 消息格式版本（log.message.format.version）是否需要升级
④ 使用的功能是否被废弃（如 ZK 相关 API、旧版工具）
⑤ 依赖的插件（Connector、Schema Registry）版本兼容

# 1. 确认所有分区有完整 ISR
kafka-topics.sh --bootstrap-server kafka:9092 --describe --under-replicated-partitions

# 2. 确认无 offline 分区
kafka-topics.sh --bootstrap-server kafka:9092 --describe --unavailable-partitions

# 3. 确认 controller 健康
zookeeper-shell.sh zk:2181 get /controller   # ZK 模式

① 升级窗口选在低峰期（消费 Lag 低、生产流量低）
② 确认磁盘空间充足（升级可能触发日志滚动/重建）
③ 确认无正在执行的大规模重平衡或分区迁移

① 备份关键配置（server.properties、topic 配置）
② 确认「回滚到旧版本」的步骤可行（消息格式未升级则可回滚）
③ 准备好监控大盘与告警

每次只重启一个 broker
重启后等待：该 broker 的分区 ISR 恢复完整
确认健康后再重启下一个

# ① 重启前：确认该节点分区 ISR 完整
kafka-topics.sh --bootstrap-server kafka:9092 \
  --describe --under-replicated-partitions | grep <broker-id>

# ② 优雅停止 broker（发 SIGTERM，让它先卸任 controller / 完成副本同步）
kill -SIGTERM <kafka-pid>
# 等待进程退出，日志出现 "shutdown completed"

# ③ 启动新版本 broker
./bin/kafka-server-start.sh -daemon config/server.properties

# ④ 等待 ISR 恢复：观察该节点的分区重新同步
#    用监控或循环检查 until under-replicated 为空

SIGTERM：broker 优雅关闭——卸任 controller、刷盘、通知其他 broker
SIGKILL：强杀——可能触发更长的恢复、controller 重选

若重启的是 controller 节点：
  → 触发 controller 选举 → 元数据重新加载 → 短暂元数据操作阻塞
建议：先确认哪些是 controller，必要时先「转移 controller」再重启

# 查看当前 controller
zookeeper-shell.sh zk:2181 get /controller

#!/usr/bin/env bash
set -euo pipefail
BROKERS="1 2 3 4 5"

for id in $BROKERS; do
  echo ">>> restarting broker $id"
  ssh broker-$id "sudo systemctl stop kafka"
  # 等待该节点分区 ISR 恢复
  until is_isr_healthy "$id"; do sleep 10; done
  ssh broker-$id "sudo systemctl start kafka"
  # 等待节点上线且 ISR 完整
  until is_broker_up "$id" && is_isr_healthy "$id"; do sleep 10; done
  echo ">>> broker $id healthy, sleep 60s before next"
  sleep 60
done

inter.broker.protocol.version=3.5    # broker 间通信协议版本
log.message.format.version=3.5       # 消息落盘格式版本

阶段一：升级二进制
  ① 保持 inter.broker.protocol.version = 旧版本
  ② 逐个滚动重启所有 broker（新二进制 + 旧协议）
  ③ 此时集群可随时回滚（回滚 = 换回旧二进制重启）

阶段二：升级协议与格式
  ④ 全部 broker 就绪后，改 inter.broker.protocol.version = 新版本
  ⑤ 再滚动重启一次（协议生效）
  ⑥ 改 log.message.format.version = 新版本
  ⑦ 再滚动重启（格式生效，此步后不可回滚）

Kafka 的协议向后兼容：新 broker 能服务旧客户端
但反向不成立：旧 broker 无法服务「使用新特性」的新客户端

① 新版客户端可能默认启用幂等生产者、新分区器 → 行为变化
② 序列化格式（Schema）需向后兼容，别在升级时顺带改 Schema
③ 消费组协议（如 cooperative-sticky）变化可能触发一次全量再平衡

# 若升级 log.message.format.version
log.message.format.version=3.5

影响：新写入的消息用新格式
代价：旧 broker 无法读取 → 不可回滚
前提：所有消费者客户端都支持新格式

broker 重启 → 消费者感知到分区变化 → 可能触发消费组再平衡
频繁再平衡 → 消费停顿
对策：升级窗口选低峰、确认消费组稳定、避免升级时同时改消费端

broker：under-replicated 分区数、offline 分区数、ActiveControllerCount
消费：消费 Lag、消费组再平衡次数
系统：磁盘 IO、网络、GC 暂停

# 关键：升级全程盯着未同步分区
watch -n 5 'kafka-topics.sh --bootstrap-server kafka:9092 \
  --describe --under-replicated-partitions | wc -l'

可以继续下一步的标志：
  - under-replicated-partitions == 0
  - unavailable-partitions == 0
  - 消费 Lag 回落到基线
  - ActiveControllerCount == 1

□ 目标版本与升级路径确认
□ 集群健康：under-replicated=0、offline=0
□ 低峰窗口、磁盘充足、无进行中的迁移
□ 备份配置、明确回滚步骤与窗口
□ 两阶段参数策略（协议/格式最后升）
□ 客户端版本兼容确认
□ 监控大盘就绪、告警开启
□ 逐个滚动、每次等 ISR 恢复
□ 升级后验证：收发、消费 Lag、Controller 唯一

# 端到端收发验证
kafka-console-producer.sh --bootstrap-server kafka:9092 --topic smoke-test <<< "hello"
kafka-console-consumer.sh --bootstrap-server kafka:9092 --topic smoke-test \
  --from-beginning --max-messages 1