零停机升级！Apache Kafka 3.1跨版本数据迁移全攻略
【免费下载链接】kafka Mirror of Apache Kafka 
项目地址: https://gitcode.com/gh_mirrors/kafka31/kafka
你是否曾因Kafka集群升级导致业务中断？是否在版本迁移中遭遇数据丢失或性能骤降？本文将通过3大核心方案、8个实操步骤和4个避坑指南，帮助你实现从任意旧版本到3.1的无缝迁移，同时保障数据一致性与服务可用性。读完本文你将掌握：ZooKeeper到KRaft架构平滑过渡、跨版本协议兼容配置、MirrorMaker 2数据镜像实战，以及降级回滚应急方案。
迁移前必知：3.1版本核心变更与影响范围
Apache Kafka 3.1作为重要版本更新，引入了多项影响迁移策略的关键特性。其中最显著的变更包括KRaft（Kafka Raft元数据管理）模式的生产就绪支持，替代了传统的ZooKeeper依赖，这要求管理员在迁移时评估架构转型的可能性。根据官方升级文档，3.1版本对消息格式和协议版本进行了优化，inter.broker.protocol.version默认值更新为3.1，而log.message.format.version则保持与之前版本的兼容性。
图1：Kafka从ZooKeeper到KRaft的架构演进示意图
兼容性矩阵（基于配置文件分析）： | 组件 | 向前兼容版本 | 需特别注意 | |------|------------|-----------| | 生产者API | 0.10.0.0+ | 旧版Scala客户端需升级 | | 消费者API | 0.11.0.0+ | 自动偏移量提交逻辑优化 | | 协议版本 | 2.8.0+ | 低于2.8需分阶段升级 |
方案一：滚动升级（适用于ZooKeeper集群）
滚动升级是保障服务连续性的首选方案，通过逐个升级Broker节点实现零停机迁移。该流程需严格遵循协议版本控制与配置更新顺序，具体步骤如下：
1. 预升级配置调整
编辑所有Broker的server.properties，添加协议版本控制参数：
# 临时锁定当前版本（假设从3.0升级）
inter.broker.protocol.version=3.0
log.message.format.version=3.0
此配置确保在所有节点升级完成前，集群维持旧版协议兼容性。
2. 节点逐个升级
按以下顺序操作每个Broker：
# 1. 停止目标Broker
bin/kafka-server-stop.sh
# 2. 升级安装包（从GitCode仓库获取3.1版本）
git clone https://gitcode.com/gh_mirrors/kafka31/kafka
cd kafka && git checkout 3.1.0
# 3. 启动新版本Broker
bin/kafka-server-start.sh -daemon config/server.properties
需等待每个节点完全加入集群（通过JMX监控kafka.server:type=ReplicaManager,name=UnderReplicatedPartitions指标确认）后，再进行下一个节点升级。
3. 协议版本最终升级
待所有节点完成二进制升级后，修改server.properties：
# 解锁至3.1版本协议
inter.broker.protocol.version=3.1
log.message.format.version=3.1
再次逐个重启Broker使配置生效。此时集群已完全切换到3.1协议栈，无法再降级到3.0及以下版本。
方案二：KRaft架构迁移（适用于全新部署）
对于计划从ZooKeeper迁移到KRaft模式的用户，3.1提供了完善的元数据迁移工具。该方案适合新建集群或有较长维护窗口的场景，核心流程包括元数据迁移与数据镜像两个阶段。
1. 初始化KRaft控制器
# 生成集群ID
bin/kafka-storage.sh random-uuid
# 格式化存储目录（控制器节点）
bin/kafka-storage.sh format -t <uuid> -c config/kraft/controller.properties
KRaft模式使用单独的controller.properties配置文件，需注意与Broker配置的端口冲突。
2. 元数据迁移
使用官方迁移工具导出ZooKeeper元数据：
bin/zookeeper-metadata-migration.sh --zookeeper.connect localhost:2181 \
--kafka.metadata.log.dir /tmp/kraft-combined-logs
迁移完成后启动KRaft控制器和Broker节点，通过kafka-metadata-shell.sh验证元数据完整性。
3. 数据同步验证
部署MirrorMaker 2工具同步旧集群数据：
bin/connect-mirror-maker.sh config/connect-mirror-maker.properties
关键配置项包括：
# 源集群与目标集群配置
clusters = source, target
source.bootstrap.servers = old-cluster:9092
target.bootstrap.servers = new-kraft-cluster:9092
# 主题同步规则
topics = .*
groups = .*
通过监控connect-mirror-maker.properties中配置的检查点主题，确认数据偏移量同步状态。
图2：MirrorMaker 2跨集群数据同步架构
方案三：双集群镜像（适用于版本差异过大场景）
当源版本低于2.8时，直接滚动升级存在协议兼容性风险，建议采用双集群并行架构，通过数据镜像实现平滑过渡。该方案涉及四个关键步骤：
1. 新建3.1目标集群
按照标准部署流程搭建全新3.1集群，推荐启用KRaft模式以简化架构。确保目标集群与源集群网络互通，且配置足够的存储空间容纳镜像数据。
2. 部署数据镜像通道
配置MirrorMaker 2实现双向同步：
# 启用偏移量追踪
offset-syncs.enabled = true
# 同步间隔（秒）
sync.interval.seconds = 60
启动后通过kafka-consumer-groups.sh验证消费者组偏移量同步状态。
3. 应用切换策略
采用"先消费后生产"的渐进式切换顺序：
- 将所有消费者应用升级至3.1客户端并指向新集群
- 监控消费延迟指标（
kafka.consumer:type=ConsumerFetcherManager,name=MaxLag） - 逐步将生产者切换到新集群，建议先切换非核心业务流量
4. 旧集群退役
确认新集群数据完整性（通过kafka-verifiable-producer.sh和kafka-verifiable-consumer.sh工具验证）后，关停旧集群。
避坑指南：四大迁移风险与应对策略
1. 消息格式兼容性问题
现象：升级后消费者出现UnknownMagicByteException异常。 解决：在server.properties中临时保留旧版消息格式：
log.message.format.version=3.0
待所有消费者升级完成后再更新为3.1。
2. 控制器选举风暴
风险：滚动升级过程中频繁触发Leader重选举。 缓解：调整zookeeper.properties：
# 延长选举超时时间
zookeeper.session.timeout.ms=30000
3. 磁盘空间耗尽
预防：迁移前清理旧日志，监控server.properties中配置的日志保留策略：
log.retention.hours=72
log.segment.bytes=1073741824
4. 跨版本工具不兼容
问题：使用旧版工具操作新版集群可能导致数据损坏。 规范：严格使用3.1版本配套工具，如kafka-topics.sh和kafka-configs.sh。
迁移后验证清单
- 集群健康度：通过
kafka-topics.sh --describe确认所有分区ISR完整 - 性能基准：对比升级前后的生产/消费吞吐量（参考jmh-benchmarks中的性能测试结果）
- 功能验证：测试新特性如增量fetch和事务支持
- 监控告警：确认所有关键指标告警正常触发
总结与展望
Apache Kafka 3.1的迁移工作需根据现有架构和业务连续性要求选择合适方案：ZooKeeper集群优先采用滚动升级，新部署推荐直接使用KRaft模式，版本差异过大时则需双集群镜像。无论采用何种方案，严格的预升级测试和分阶段验证都是成功的关键。随着Kafka逐步淘汰ZooKeeper依赖，建议在迁移过程中规划KRaft架构转型，为未来版本升级奠定基础。
关注本系列下一篇《Kafka 3.1性能优化实战》，将深入探讨分区重新平衡策略与JVM调优技巧。
【免费下载链接】kafka Mirror of Apache Kafka 项目地址: https://gitcode.com/gh_mirrors/kafka31/kafka
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
