零停机升级指南：Apache Kafka 3.1集群滚动升级全流程与兼容性保障

零停机升级指南：Apache Kafka 3.1集群滚动升级全流程与兼容性保障

【免费下载链接】kafka Mirror of Apache Kafka 项目地址: https://gitcode.com/gh_mirrors/kafka31/kafka

你是否曾因担心服务中断而推迟Kafka集群升级？本文将通过滚动升级方案，实现从Apache Kafka 3.1版本到最新版本的无缝迁移，全程保障业务连续性。读完本文你将掌握：

• 无需停机的分步升级操作指南
• 版本间兼容性配置的关键参数
• 升级前后的风险排查与回滚预案
• 新旧架构（ZooKeeper/KRaft）的差异化升级路径

升级前准备与环境检查

兼容性矩阵确认

Kafka集群升级前需验证版本间兼容性，重点关注：

• 协议兼容性：通过inter.broker.protocol.version控制（配置文件路径：config/server.properties）
• 消息格式兼容性：通过log.message.format.version控制
• 元数据版本：KRaft架构需关注metadata.version参数

版本对应关系：3.1.x集群升级时，初始协议版本应设置为3.1，消息格式版本保持与当前集群一致。

关键文件备份

执行升级前必须备份以下文件：

# 备份配置文件
cp config/server.properties config/server.properties.bak
cp config/zookeeper.properties config/zookeeper.properties.bak

# 备份数据目录（根据实际配置调整路径）
tar -czf /backup/kafka-logs-$(date +%F).tar.gz /var/lib/kafka-logs

预检查清单

使用官方提供的系统测试工具执行自动化检查：

./tests/docker/run_tests.sh --suites=upgrade:precheck

滚动升级实施步骤

ZooKeeper架构集群升级

1. 修改配置文件

在所有broker节点的config/server.properties中添加：

inter.broker.protocol.version=3.1
log.message.format.version=3.1  # 若从未修改过可省略此行

2. 逐个节点升级

# 1. 停止当前broker
bin/kafka-server-stop.sh

# 2. 升级软件包（以tar包安装为例）
tar -xzf kafka_2.13-3.7.1.tgz -C /opt
ln -sf /opt/kafka_2.13-3.7.1 /opt/kafka

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

监控要点：通过JMX监控kafka.server:type=BrokerTopicMetrics,name=MessagesInPerSec指标，确保流量恢复正常后再升级下一个节点。

3. 升级协议版本

待所有节点完成软件升级后，修改config/server.properties：

inter.broker.protocol.version=3.7

再次逐个重启broker使新协议生效。

图1：多数据中心Kafka集群升级拓扑（文件路径：docs/images/kafka_multidc.png）

KRaft架构集群升级

KRaft架构升级流程更简洁，无需额外协议配置：

# 1. 逐个升级broker节点（同ZooKeeper架构步骤2）

# 2. 升级元数据版本
bin/kafka-features.sh upgrade --metadata 3.7

注意：3.3.0之后的元数据版本不支持降级，执行升级前需通过metadata.version文档确认兼容性。

兼容性保障机制

跨版本通信保障

Kafka通过双向兼容设计确保升级过程中服务可用：

• 高版本broker可处理低版本客户端请求
• 低版本broker可解析高版本消息格式（需正确配置log.message.format.version）

客户端滚动升级

生产者/消费者客户端应在broker升级完成后进行：

1. 升级依赖包（以Maven为例）：

<dependency>
  <groupId>org.apache.kafka</groupId>
  <artifactId>kafka-clients</artifactId>
  <version>3.7.1</version>
</dependency>

2. 添加客户端版本控制参数：

Properties props = new Properties();
props.put("client.dns.lookup", "use_all_dns_ips");  // 3.0+新特性

升级后验证与优化

健康检查

执行官方提供的验证脚本：

./bin/kafka-run-class.sh kafka.examples.UpgradeVerification \
  --bootstrap-server broker1:9092,broker2:9092 \
  --topic test-validation

性能优化

升级完成后建议执行：

1. 消息格式转换：将log.message.format.version升级至3.7并重启broker
2. 分区再平衡：使用kafka-reassign-partitions.sh工具优化副本分布

监控指标重点关注

• 控制器选举成功率：kafka.controller:type=ControllerStats,name=ControllerElectionRateAndTimeMs
• 副本同步延迟：kafka.cluster:type=ReplicaManager,name=UnderReplicatedPartitions
• 消费者滞后量：kafka.consumer:type=ConsumerFetcherManager,name=MaxLag,clientId=*

常见问题与解决方案

元数据版本不兼容

症状：broker启动失败并提示Unsupported metadata version
解决：通过kafka-features.sh工具查询当前元数据版本：

bin/kafka-features.sh describe --bootstrap-server localhost:9092

消息格式转换失败

解决方案：参考升级文档中的性能优化建议，分阶段完成消息格式转换。

控制器切换异常

应急处理：手动触发控制器选举：

bin/kafka-topics.sh --bootstrap-server broker1:9092 --describe --topic __controller

总结与后续建议

滚动升级方案通过逐个节点替换和双向兼容性设计，实现了Kafka集群的零停机升级。关键成功因素包括：

1. 严格遵循"先升级软件，后升级协议"的两步法
2. 升级过程中持续监控核心指标
3. 保持客户端与broker版本差不超过2个大版本

建议后续关注：

• Kafka 4.0路线图中Java 11支持的移除计划
• 逐步迁移至KRaft架构以消除ZooKeeper依赖
• 定期执行集群健康检查脚本

行动清单：

•  备份关键配置与数据
•  执行预检查测试套件
•  按节点顺序实施升级
•  验证协议版本与消息格式
•  监控系统运行24小时后完成验收

【免费下载链接】kafka Mirror of Apache Kafka 项目地址: https://gitcode.com/gh_mirrors/kafka31/kafka