Kafka版本升级Ubuntu上注意啥
小樊
50
2026-01-09 17:37:45
Ubuntu 上 Kafka 版本升级注意事项
一 升级前检查清单
明确升级路径：区分 ZooKeeper 模式 与 KRaft 模式 ，以及跨大版本的边界（如 2.8 → 3.x 、3.x → 4.0 ）。从 Kafka 4.0 开始 KRaft 已成熟，若从 2.x 升到 4.0 属于跨大版本，需按官方升级路径分阶段进行，不能直接替换二进制后启动。
兼容性核对：确认 Java 版本 与新版本匹配（Kafka 3.0 起已标注 Java 8 废弃 ，4.0 不再支持 Java 8 ；启用 TLS 时 Java 11+ 性能更佳）；核对 ZooKeeper 版本（稳定版建议 3.5.x ），并预留足够堆内存（常见 3–5GB ）。
安全补丁：如仍在 2.3.0–3.3.2 区间，存在 CVE-2023-25194（JNDI 注入） 风险，建议至少升级到 3.4.0+ ；Kafka 3.4.0 起默认禁用有问题的登录模块，并可通过系统属性 org.apache.kafka.disallowed.login.modules 进一步限制。
回滚预案：准备完整回滚方案（旧包、配置、数据目录、Topic/ACL/Quota 元数据快照），先在 测试环境 验证业务链路与性能。
备份与变更窗口：全量备份 配置 、密钥/证书 、ZooKeeper 数据 （若使用 ZK）、关键 Topic 数据/ACL/配额 ；选择低峰时段滚动升级，逐台验证。
二 升级路径与关键配置
滚动升级通用步骤（ZooKeeper 模式，适用于 2.x → 3.x 等）：
在待升级节点的 server.properties 增加：inter.broker.protocol.version=当前运行版本 （如 3.4 ）；若此前显式设置了 log.message.format.version ，保持原值不变。
逐个节点停机、替换二进制、迁移/比对配置、启动并验证复制与业务指标；此阶段仍可按旧协议运行，便于回滚。
集群验证通过后，将 inter.broker.protocol.version 改为 目标版本 （如 3.4 ），再次逐个滚动重启使新协议生效；此后通常不再支持降级。
如曾显式设置 log.message.format.version ，在所有客户端升级完成后，再将其提升到目标版本并滚动重启。
跨大版本到 KRaft（如 2.x → 4.0）：不建议直接切换，推荐先按官方步骤升级到 3.4/3.5 的稳定 KRaft 形态 ，再升级到 4.0 ；KRaft 需配置 process.roles 、controller.quorum.voters 、生成 cluster.id 并执行 kafka-storage.sh format 。
配置项重点核对：broker.id （唯一）、listeners / advertised.listeners （内外网可达性）、zookeeper.connect （ZK 模式）、KRaft 相关参数（KRaft 模式）；确保与现有网络、ACL、认证方式一致。
三 Ubuntu 与系统层面的注意点
使用 systemd 管理时，先停用旧服务，更新 ExecStart 指向新版本二进制，执行 systemctl daemon-reload 后再启动；升级完成且验证无误再清理旧包与旧日志，避免误删运行中数据。
目录与权限：将 log.dirs 指向持久化磁盘（避免 /tmp ），确认 kafka 用户对数据/日志目录有 读写权限 ；若启用 TLS ，同步更新 server.properties 中的 listeners/ssl 配置与证书路径。
防火墙与端口：开放 9092/9093 （内外网分离时区分），如使用 KRaft 控制器端口通常为 9093 ；验证端口连通性与回环访问策略。
资源与监控：升级窗口内关注 CPU/IO/网络 与 ISR/UnderReplicatedPartitions ，并实时查看 server.log 与 controller.log 的错误与告警。
四 客户端与生态组件
升级顺序：先完成 Broker 全部升级与协议切换，再升级 Producer/Consumer/Admin 客户端与 Kafka Connect/Streams ；避免新旧协议混用导致 NotLeaderOrFollowerException 等不兼容错误。
兼容性：确认客户端库版本与目标 Broker 兼容；若使用 SASL/SSL ，保持 JAAS/证书 配置一致；在 3.4+ 可结合 org.apache.kafka.disallowed.login.modules 禁用高风险登录模块。
验证：回归核心业务链路（生产/消费/回溯）、ACL/配额 生效、监控与告警 正常，必要时做 性能压测 与 故障演练 。
五 常见坑与快速排错
协议不一致导致节点反复报错（如 Connection … disconnected before the response was read / NotLeaderOrFollowerException ）：多为 inter.broker.protocol.version 与 log.message.format.version 未正确设置或未按滚动流程重启，按“先固定协议→升级验证→再提升协议→再次滚动重启”的顺序修复。
安全漏洞风险：低于 3.4.0 的 Kafka Connect 存在 JNDI 注入 ，尽快升级到 3.4.0+ 并限制登录模块。
回滚失败：一旦将 inter.broker.protocol.version 提升到目标大版本并滚动重启，通常不再支持降级；务必在提升前完成全量验证与备份。
KRaft 启动异常：检查 controller.quorum.voters 、process.roles 、cluster.id 与 log.dirs 是否匹配，必要时重新执行 kafka-storage.sh format ；确保 9093 端口与防火墙策略正确。
