CentOS 上 Kafka 版本升级实操指南
一 升级前准备
- 明确升级路径：区分是 Zookeeper 模式 还是 KRaft 模式，以及目标版本（如从 2.x/3.x → 3.5.x/4.0.x）。跨大版本（如到 4.0）通常要求 Java 17。
- 检查兼容性：确认新版本与现有 Zookeeper/客户端库/连接器 的兼容性，先在测试环境验证。
- 备份与变更记录：完整备份 config/server.properties、主题与 ACL 配置、监控告警、证书/密钥等。
- 规划窗口与回退：尽量使用 滚动升级 降低停机风险，准备回退包与步骤。
- 资源与权限：确保磁盘空间充足、目录权限正确，且具备 sudo 权限。
- 环境校验：在 CentOS 上安装并验证 Java（示例：OpenJDK 8 或 Java 17）。
二 升级路径与差异
| 升级场景 |
前置条件 |
关键动作 |
备注 |
| Zookeeper 模式跨小版本（如 3.3.x → 3.4.x/3.5.x） |
业务允许短暂停机或采用滚动升级 |
逐台替换二进制、保留 log.dirs、按阶段设置协议/消息格式版本、滚动重启 |
建议先在测试环境演练 |
| KRaft 模式跨小版本（如 3.5.x → 4.0.x） |
目标版本为 4.0+ 时准备 Java 17 |
使用 kafka-storage.sh format 初始化/迁移元数据、逐台替换 |
4.0 起官方默认 KRaft，注意目录与端口 |
| 跨大版本到 4.0 |
明确变更点、全面回归测试 |
升级客户端、重跑兼容性/性能测试、灰度切换 |
关注命令与 API 变化 |
说明：Kafka 4.0 起默认 KRaft（移除 Zookeeper 依赖），并倾向 Java 17；跨大版本升级务必做功能与负载测试。
三 标准操作步骤
- 下载并解压新版本（示例目录 /opt/kafka_new）：
- 示例：wget https://downloads.apache.org/kafka/4.0.0/kafka_2.13-4.0.0.tgz && tar xzf kafka_2.13-4.0.0.tgz -C /opt/ && mv /opt/kafka_2.13-4.0.0 /opt/kafka_new
- 准备配置与数据目录：
- 复制旧配置：cp /opt/kafka_old/config/server.properties /opt/kafka_new/config/
- 保持 log.dirs 不变（指向原数据目录），避免数据迁移风险。
- 模式差异处理：
- KRaft：生成 Cluster ID 并格式化存储（仅首次或元数据迁移时执行一次）
- 示例：export KAFKA_CLUSTER_ID=“$(uuidgen)”
/opt/kafka_new/bin/kafka-storage.sh format -t $KAFKA_CLUSTER_ID -c /opt/kafka_new/config/server.properties
- Zookeeper：保持 zookeeper.connect 不变。
- 滚动升级（推荐）：
- 逐台操作：停止旧实例 → 启动新实例 → 观察日志与副本同步 → 验证后再处理下一台。
- 小版本 Zookeeper 模式可在升级阶段按需设置：
- inter.broker.protocol.version=新版本号
- log.message.format.version=新版本号
- 全部升级完成后，再统一移除或升级这些版本参数（按官方升级说明执行）。
- 验证：
- 查看集群与主题：/opt/kafka_new/bin/kafka-topics.sh --bootstrap-server broker:9092 --list
- 收发测试消息、检查消费者组与监控指标是否正常。
四 回退与常见问题
- 回退方案：
- 保留旧版本目录（如 /opt/kafka_old）与 log.dirs 不变；出现问题立即停止新版本，直接用旧版本二进制启动，以缩短回退时间。
- 常见问题与排查：
- 无法启动/元数据不一致：检查 broker.id 唯一、listeners/advertised.listeners 配置、目录权限与磁盘空间；查看 server.log 报错。
- 版本不兼容：确认 Java 版本 满足目标 Kafka 要求（4.0 建议 Java 17）；客户端库与服务端版本匹配。
- 连接异常：如启用远程访问，开放 9092/9093 端口，必要时调整 SELinux/防火墙 策略。
- 升级后命令不可用：注意 KRaft 与 Zookeeper 模式下命令参数差异（如元数据/存储相关工具与脚本）。
五 systemd 服务示例与切换
- 创建服务文件（示例 /etc/systemd/system/kafka.service）：
- [Unit] Description=Apache Kafka Server; Requires=zookeeper.service（Zookeeper 模式）
- [Service] Type=simple; ExecStart=/opt/kafka_new/bin/kafka-server-start.sh /opt/kafka_new/config/server.properties; ExecStop=/opt/kafka_new/bin/kafka-server-stop.sh; Restart=on-abnormal
- [Install] WantedBy=multi-user.target
- 切换版本：更新 ExecStart/ExecStop 中的 Kafka 安装路径 后执行：systemctl daemon-reload && systemctl restart kafka
- 建议通过软链接管理版本目录（如 /opt/kafka -> /opt/kafka_3.5.2），升级时仅切换软链接指向，减少配置改动与风险。