运行Kafka KRaft模式时为何控制器必须设为localhost？

问题现象 #

在KRaft模式下，当配置CONTROLLER监听器为非localhost的IP（比如局域网IP10.0.0.48、192.168.56.1）时，Kafka Broker无法正常启动，持续输出连接localhost:9093失败的日志，最终抛出CancellationException并退出。仅当CONTROLLER监听器配置为localhost时，Broker才能成功启动。

核心原因 #

导致该问题的关键在于KRaft模式的控制器地址逻辑：

1. Quorum选民配置优先级更高
   KRaft模式依赖controller.quorum.voters配置定义控制器集群的节点地址，格式为brokerId@host:port。如果此项配置写的是1@localhost:9093（单节点场景常见配置），Broker会直接使用这个地址连接控制器，完全忽略listeners中CONTROLLER字段的配置。这就导致即使你把CONTROLLER监听器绑定到其他IP，Broker依然尝试连接localhost:9093，而控制器实际监听的是其他IP，自然连接失败。

2. 旧元数据缓存残留
   如果曾经用localhost作为控制器地址启动过Kafka，KRaft会将控制器节点信息写入本地的元数据快照（存储在kraft-combined-logs目录）和meta.properties文件中。后续即使修改listeners配置，Kafka启动时会优先读取缓存的元数据，依然使用旧的localhost地址连接控制器，导致启动失败。

解决方法 #

针对上述原因，可按以下步骤处理：

• 同步配置项
  若要用非localhost的IP作为控制器地址，确保controller.quorum.voters的地址与listeners中的CONTROLLER地址完全一致。示例配置：

  listeners=PLAINTEXT://10.0.0.48:9092,CONTROLLER://10.0.0.48:9093
  controller.quorum.voters=1@10.0.0.48:9093
  

• 清除旧元数据
  如果之前用localhost启动过，需删除Kafka数据目录下的kraft-combined-logs文件夹和meta.properties文件，重新启动Kafka以写入新的控制器地址元数据。

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