Kafka KRaft集群控制器替换失败求助：无停机操作致集群不可恢复

问题背景 #

使用Kafka 3.4.0 KRaft模式，尝试以下操作后集群无法恢复：

• 修改所有broker和控制器的quorum数量从3改为2，重启1台broker后集群宕机
• 尝试安装新控制器并修改quorum替换节点，同样导致集群崩溃
• 执行/opt/kafka# ./bin/kafka-metadata-quorum.sh -h仅支持describe命令，无--add-voter等成员变更选项

核心原因 #

Kafka 3.4.0版本的kafka-metadata-quorum.sh工具仅支持元数据状态查询，不支持通过命令行直接添加/移除投票者；且KRaft集群的quorum成员变更必须遵循滚动更新逻辑，直接批量修改配置并重启会破坏集群法定人数一致性，导致集群分裂或无法选举leader。

恢复与操作步骤 #

1. 恢复崩溃的集群 #

如果集群已宕机，按以下步骤恢复：

• 将所有节点（控制器、broker）的controller.quorum.voters配置改回原3节点的配置
• 先重启所有控制器节点，等待它们形成法定人数（用kafka-metadata-quorum.sh describe查看Current Leader是否正常）
• 再逐个重启broker节点，确保每个broker都能连接到控制器集群

2. 正确的控制器替换流程（3.4.0版本） #

假设要替换旧控制器节点（ID:1）为新控制器节点（ID:4，地址:new-controller:9093）：

• 部署新控制器节点，配置process.roles=controller，controller.quorum.voters保持原3个旧节点，启动新节点（此时它为备用节点，非投票者）
• 逐个修改所有节点（旧控制器、新控制器、broker）的controller.quorum.voters配置，将其中一个旧节点条目替换为4@new-controller:9093
• 先重启被替换的旧控制器节点，等待它重新加入集群并同步元数据
• 再重启新控制器节点，使其成为投票者成员
• 最后逐个重启broker节点，确保它们更新quorum配置
• 用kafka-metadata-quorum.sh describe确认投票者列表已更新，集群状态正常后，停止旧控制器节点

3. 正确调整Quorum数量从3到2（3.4.0版本） #

• 确保当前3个控制器节点均在线且集群健康
• 逐个修改所有节点的controller.quorum.voters配置，移除其中一个节点的条目，保留2个
• 先重启被移除的控制器节点，让它退出集群
• 依次重启剩下的2个控制器节点，等待它们重新形成法定人数
• 最后逐个重启broker节点
• 用kafka-metadata-quorum.sh describe验证投票者数量为2，leader正常选举

关键注意事项 #

• 禁止批量修改配置后批量重启：必须逐个修改、逐个重启，每一步都要确保集群有足够的在线投票者形成法定人数（3节点集群至少2个在线，2节点集群至少1个在线）
• 操作前备份所有控制器节点的metadata.dir目录：一旦操作失败，可通过备份目录恢复节点
• 每一步操作后，用kafka-metadata-quorum.sh describe检查以下状态：
  • Current Leader是否存在且正常
  • Voters列表是否符合预期
  • Is Controller状态是否正常

内容的提问来源于stack exchange，提问作者Andrei Le