Kafka 3.2.0 KRaft模式下Broker离线引发NotControllerException问题求助

错误原因分析 #

离线的kafka-2节点本地元数据仍保留着自己作为控制器的记录，但在它离线期间，集群剩余2个节点维持了Raft quorum并重新选举了新控制器。当该节点尝试恢复时，它以“控制器身份”发送心跳请求，被集群当前控制器拒绝，因此抛出NotControllerException。由于3节点集群只要有2个节点在线就能维持quorum，客户端可以正常工作。

修复步骤 #

• 先确认当前集群状态

  1. 用KRaft元数据工具查看当前控制器：

     kafka-metadata-shell.sh --bootstrap-server <在线Broker地址:端口>
     

     进入shell后输入get /controller即可看到当前控制器的node.id。
  2. 检查分区副本状态，确认是否有未同步分区：

     kafka-topics.sh --bootstrap-server <在线Broker地址:端口> --describe --under-replicated-partitions
     

• 尝试常规重启恢复

  1. 停止kafka-2节点的进程，然后正常启动服务。
  2. 启动后观察kafka-2的日志：如果日志中出现“joined quorum”相关信息，且NotControllerException不再出现，说明节点已成功重新加入集群，元数据同步完成。

• 元数据损坏时的强制修复
  如果重启后报错仍存在，说明节点本地元数据损坏：

  1. 彻底停止kafka-2节点进程。
  2. 备份节点的data目录（重要），然后删除data目录下的meta.properties文件和raft-log目录。
  3. 确保kafka-2的server.properties配置正确：
     • process.roles和其他节点一致（应为broker,controller，因为是KRaft模式下的控制器节点）
     • node.id设置为2（对应kafka-2）
     • controller.quorum.voters和其他节点完全相同（格式为1@node1:port,2@node2:port,3@node3:port）
  4. 重新启动kafka-2节点，此时节点会从集群当前控制器同步最新元数据，不再以旧的控制器身份运行。

自动恢复说明 #

如果是临时网络波动、进程意外退出等简单故障，重启节点后通常能自动完成元数据同步，错误会自行消失。但如果是本地元数据文件损坏、磁盘故障导致数据丢失，则需要手动清理元数据后重新加入集群。

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