4. 版本兼容性与升级路径规划
在把现有 Kafka 集群迁移到 Confluent Platform 之前，最容易被低估的风险不是“装不上”，而是“版本对不上”。Apache Kafka 与 Confluent Platform 并不是两条完全独立的版本线：Confluent Platform 以某个 Apache Kafka 版本为内核，再叠加 Confluent 自研组件（Schema Registry、Connect、ksqlDB、Control Center、Tiered Storage、RBAC 等）和补丁。因此，规划升级路径的第一步，是先把“Kafka 内核版本”和“平台组件版本”分开看，再判断它们之间的兼容边界。
一、先厘清两条版本线的对应关系
Apache Kafka 的版本号形如 2.8.0、3.4.0、3.6.1，其中前两位表示特性版本，第三位是补丁版本。Confluent Platform 的版本号形如 6.2.0、7.4.0、7.6.0，它内部绑定的 Kafka 版本并不与自身版本号一致。例如 Confluent Platform 7.4.x 对应 Apache Kafka 3.4.x，7.6.x 对应 Apache Kafka 3.6.x。规划时必须先查清目标 CP 版本所绑定的 Kafka 内核版本，再判断源集群的 Kafka 版本能否直接升级到该内核版本。
除了内核，还要关注三类组件版本：一是协议版本，包括消息格式版本（message format version）和 inter-broker 协议版本；二是客户端版本，生产者和消费者的 API 版本；三是生态组件版本，如 Schema Registry、Connect 插件、ksqlDB 查询引擎。它们各自的兼容策略不同，不能用一个“大版本”笼统覆盖。
二、兼容性判断的三个维度
第一是协议兼容。Kafka 的 wire protocol 在 0.8 到 3.x 之间经历过多次演进，尤其是消息格式从 V0/V1 升级到 V2（Record Batch）后，旧客户端无法直接读写新格式。若源集群仍在使用 V0/V1 消息格式，升级到 3.x 前必须先把 log.message.format.version 和 message.format.version 提升到目标版本，并等待旧数据被滚动覆盖或完成迁移。
第二是客户端兼容。老版本客户端（如 0.10.x、0.11.x）连接新 broker 时，可能因 API 版本协商失败而报 UnsupportedVersionException。规划时要盘点所有生产者和消费者的客户端版本，优先升级到与目标 broker 同主版本或至少 2.x 以上的客户端。
第三是组件兼容。Schema Registry 对 Kafka 内核版本有明确要求，Connect 插件的 API 版本必须与 Connect 运行时匹配，ksqlDB 对 Kafka 流处理 API 的依赖更强。若源集群使用了自研 Connect 插件或自定义 SerDe，需要逐个验证其在目标 CP 版本下能否加载。
三、制定升级路径的实操方法
升级路径不是“一步到位”，而是分阶段收敛风险。推荐按以下顺序推进。
第一步，盘点现状。用 kafka-broker-api-versions.sh 查看 broker 支持的 API 版本，用 kafka-topics.sh --describe 检查各 topic 的 message.format.version，用客户端依赖清单确认生产者/消费者的 Kafka 客户端版本。把结果整理成一张“版本—组件—风险”对照表。
第二步，先升消息格式，再升 broker。如果源集群消息格式仍是 V0/V1，直接升级 broker 会导致新旧格式混用。正确做法是先把 log.message.format.version 设为当前 broker 支持的最高版本，滚动重启，等待旧格式数据被清理或迁移，再执行 broker 升级。
第三步，滚动升级 broker。每次只停一台 broker，升级后确认 ISR 恢复、副本同步正常，再处理下一台。对于使用 ZooKeeper 的旧集群，若目标 CP 版本已默认 KRaft，需要额外规划元数据迁移，不能简单替换二进制包。
第四步，分批升级客户端。先升级非核心业务的生产者，观察 record-error-rate 和 request-latency-avg；再升级消费者，重点看 records-lag-max 和 rebalance 次数。客户端升级通常比 broker 升级更容易回滚，适合作为验证窗口。
第五步，启用 Confluent 组件。broker 稳定后，再部署 Schema Registry、Connect、Control Center。Schema Registry 需要与 broker 同版本或兼容版本，Connect 插件要逐个验证加载。建议先在测试环境用一份生产 topic 的 schema 做兼容性测试。
四、一个可参考的升级检查清单
| 检查项 | 判断依据 | 不通过时的处理 |
|---|---|---|
| 源 Kafka 版本 | 是否跨 2 个以上主版本 | 分多跳升级，不跳版 |
| 消息格式版本 | 是否为 V2 | 先升格式再升 broker |
| 客户端版本 | 是否 ≥ 2.0 | 先升级客户端或使用兼容层 |
| 自研 Connect 插件 | 能否在目标 CP 加载 | 重编译或替换插件 |
| Schema Registry 兼容性 | schema 是否可注册 | 调整兼容级别或迁移 schema |
| 元数据模式 | ZooKeeper 还是 KRaft | 规划 ZK → KRaft 迁移 |
最后，升级路径规划的输出不应只是一张时间表，而应包含“版本映射、兼容性判断、分阶段操作、回滚方案、验证指标”五个部分。只有把每一步的输入、判断依据和观察指标写清楚，才能在真正执行时快速定位问题，而不是等到 broker 起不来才回头查版本。