消息队列 / 系统课时
滚动重启与版本升级
滚动重启与版本升级
滚动维护的目标不是“把所有节点都重启一遍”,而是在每次只改变一个节点的前提下持续验证副本、控制面和客户端可用性。本课给出升级前检查、节点顺序、健康门禁与回滚方法,尽量把维护风险限制在单个 Broker。
学习目标
- 在维护前确认版本、客户端和副本状态是否满足滚动条件
- 按单节点变更、健康验证、再进入下一节点的顺序执行维护
- 为升级失败准备可操作的停止条件与回滚路径
先建立升级门禁
开始前先锁定源版本、目标版本、元数据模式、配置差异和客户端兼容范围。跨大版本升级尤其要核对目标版本的发布说明,确认是否存在不支持直接跨越的版本、已删除配置或消息格式变化。
运行下面的检查,至少要保证没有未同步副本,并记录消费组基线。命令中的 <HOST>、<PORT> 与实际环境值可能不同。
kafka-topics.sh --bootstrap-server <HOST>:<PORT> --describe --under-replicated-partitions
kafka-consumer-groups.sh --bootstrap-server <HOST>:<PORT> --all-groups --describe预期输出
# 第一条命令在健康状态下无未同步分区,因此可能没有正文输出。
GROUP TOPIC PARTITION CURRENT-OFFSET LOG-END-OFFSET LAG
<GROUP> <TOPIC> <ID> <VALUE> <VALUE> <VALUE>如果第一条命令返回任何分区,先处理 ISR 收缩问题,不要在副本已经降级时继续滚动。消费组数据用于升级前后对比,而不是要求所有组的 LAG 都为 0。
按单节点顺序滚动
一次只处理一个 Broker:停止流量影响可控的节点,完成重启或二进制切换,等待它重新加入集群,再检查副本恢复。只有健康门禁重新满足,才进入下一个节点。

如果 Kafka 由 systemd 管理,可以用下面的单节点操作模板。<KAFKA_SERVICE> 是实际服务名;升级二进制或配置的动作应在 stop 与 start 之间完成。
sudo systemctl stop <KAFKA_SERVICE>
# 在这里切换已验证的新版本二进制或配置。
sudo systemctl start <KAFKA_SERVICE>
sudo systemctl is-active <KAFKA_SERVICE>预期输出
active不要并行重启多个 Broker 来“节省时间”。副本因子为 3 的主题也可能因为机架分布、ISR 已收缩或磁盘恢复速度不足而失去冗余。
每个节点都做健康验证
单个 Broker 返回后,先确认进程存活,再确认它能被集群发现,最后验证副本与业务指标。对于 KRaft 集群,还应额外观察元数据仲裁是否稳定;ZooKeeper 模式则检查对应控制器与会话状态。
最关键的停止条件包括:未同步副本持续增加、离线分区出现、生产或消费错误率显著上升、控制器反复切换、Broker 迟迟不能加入集群。任一条件出现,都应暂停后续节点维护。
版本升级要把兼容性变化拆开
如果目标版本支持分阶段升级,优先先替换 Broker 二进制并保持兼容配置,再在所有节点都稳定后启用新的协议或特性。这样出现问题时,回滚面通常小于“二进制、协议、配置一次全部切换”。
在升级窗口内还要冻结与主题副本、分区迁移、批量扩缩容无关的变更,避免同时发生再分配、Leader 迁移和节点升级,导致故障信号难以归因。
回滚以恢复兼容状态为目标
回滚不只是把服务重新启动,而是恢复到升级前已验证的二进制、配置和协议组合。每处理一个 Broker,都应保留原版本安装包、原配置和变更记录,并明确哪些数据格式或特性一旦启用后不能安全降级。
如果新版本节点启动失败或加入集群后健康门禁长期不恢复,应停止继续滚动,回退当前节点并重新验证集群。只有恢复到升级前基线,才决定修复后重试还是结束维护窗口。