Debian 上 Kafka 升级指南

一 升级前准备

• 明确当前部署形态：是 Zookeeper 模式 还是 KRaft 模式，以及 Scala 版本（如 2.13）。
• 完整备份：配置文件（如 /etc/kafka/server.properties）、数据目录（如 /var/lib/kafka）、Topic 元数据与 ACL 策略。
• 检查兼容性：
  • 新版本对 Java 的要求（例如 Kafka 4.0+ 不再支持 Java 8）。
  • 客户端与服务端的协议与特性兼容（如 KRaft 为 2.8 引入，旧客户端可能不支持）。
• 先在测试环境演练，再在生产环境执行滚动或离线升级。
• 规划维护窗口与回滚方案（保留旧目录与配置，便于快速回退）。

二 两种常见升级路径

• 方式 A 二进制包升级（通用、可控性强，适合自管或 Zookeeper 场景）

  1. 确认版本与运行状态：
     kafka-topics.sh --version
     sudo systemctl status kafka
  2. 停止服务：
     sudo systemctl stop kafka

     若仍使用 Zookeeper：sudo systemctl stop zookeeper

  3. 备份：
     sudo cp -r /etc/kafka /etc/kafka.bak
     sudo cp -r /var/lib/kafka /var/lib/kafka.bak
  4. 下载并解压新版本（示例为 4.0.0）：
     wget https://downloads.apache.org/kafka/4.0.0/kafka_4.0.0-bin.tar.gz
     sudo tar -xzf kafka_4.0.0-bin.tar.gz -C /opt/
  5. 迁移配置与目录：

     仅复制需要的配置，避免覆盖新版本默认优化项

     sudo cp /etc/kafka.bak/server.properties /opt/kafka_4.0.0/config/

     如沿用旧数据目录，确保配置指向 /var/lib/kafka

  6. 调整 systemd 单元（如使用 systemd 管理）：

     编辑 /etc/systemd/system/kafka.service，将 ExecStart 指向新二进制

     示例：/opt/kafka_4.0.0/bin/kafka-server-start.sh /opt/kafka_4.0.0/config/server.properties

     sudo systemctl daemon-reload
  7. 启动并验证：
     sudo systemctl start kafka
     kafka-topics.sh --version
     tail -f /var/log/kafka/server.log
  8. 观察无误后再清理旧版本目录。

• 方式 B 包管理器升级（如使用 Confluent 提供的 APT 仓库）

  1. 备份配置与数据（同上）。
  2. 更新 APT 索引并安装新版本：
     sudo apt update
     sudo apt install kafka
  3. 对比并合并新旧配置（/etc/kafka/server.properties），保留自定义项。
  4. 启动服务并验证：
     sudo systemctl start kafka
     sudo systemctl status kafka

三 版本差异与关键配置

• 运行模式变更：Kafka 4.0 移除 Zookeeper，默认使用 KRaft。若从 Zookeeper 迁移至 KRaft，需按官方步骤完成元数据迁移与 quorum 配置，再切换启动方式。
• Java 运行时：Kafka 4.0+ 要求 Java 11+，请提前完成 JDK 升级与验证。
• 兼容性控制（跨小版本升级且需兼容旧客户端时）：
  • 在 server.properties 中临时设置：
    inter.broker.protocol.version=旧版本（如 2.8）
    log.message.format.version=旧版本（如 2.8）
  • 完成滚动升级并验证后，再移除上述参数以启用新特性。
• 配置项差异：不同版本可能新增或废弃参数，升级后对照发行说明逐项校验。

四 验证与回滚

• 快速验证：
  • 版本：kafka-topics.sh --version
  • 连通与元数据：kafka-topics.sh --list --bootstrap-server localhost:9092
  • 日志：tail -f /var/log/kafka/server.log（无 ERROR/异常堆栈）
• 监控与观察：持续关注 生产/消费延迟、请求耗时、错误率 等关键指标。
• 回滚要点：
  • 立即停止新版本，恢复旧版二进制与配置；
  • 若已迁移至 KRaft，需切回 Zookeeper 模式后再启动旧版；
  • 恢复数据目录与 ACL 后重启，核对位点与数据一致性。

五 生产环境建议

• 采用滚动升级减少停机时间，逐台重启并在每批次后进行功能与性能验证。
• 升级前协调客户端升级窗口，避免新旧协议/特性冲突。
• 对关键业务 Topic 进行位点与数据校验，确保无消息丢失或重复。
• 完整保留 配置、数据与安装包，并详细记录变更单与回滚预案。