修改KAFKA_ADVERTISED_LISTENERS监听器名称引发inter.broker.listener.name错误

问题背景 #

使用以下Docker Compose配置可正常启动Kafka：

kafka:
  image: confluentinc/cp-kafka:7.6.0
  depends_on:
    - zookeeper
  networks:
    - dev-net
  ports:
    - 9093:9093
  environment:
    KAFKA_BROKER_ID: 1
    KAFKA_ZOOKEEPER_CONNECT: zookeeper:2181
    KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: PLAINTEXT:PLAINTEXT,PLAINTEXT_INTERNAL:PLAINTEXT
    KAFKA_ADVERTISED_LISTENERS: PLAINTEXT_INTERNAL://kafka:9092,PLAINTEXT://localhost:9093
    KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
    KAFKA_AUTO_CREATE_TOPICS_ENABLE: "true"

zookeeper:
  image: confluentinc/cp-zookeeper:7.6.0
  environment:
    ZOOKEEPER_CLIENT_PORT: 2181
    ZOOKEEPER_TICK_TIME: 2000
  networks:
    - dev-net
  ports:
    - "2181:2181"

但将监听器名称修改为以下配置后，启动失败并报错：

KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: L1:PLAINTEXT,L2:PLAINTEXT
KAFKA_ADVERTISED_LISTENERS: L1://kafka:9092,L2://localhost:9093

错误日志：

2025-07-21T12:30:52+02:00 [2025-07-21 10:30:52,029] ERROR Exiting Kafka due to fatal exception (kafka.Kafka$)
2025-07-21T12:30:52+02:00 java.lang.IllegalArgumentException: requirement failed: inter.broker.listener.name must be a listener name defined in advertised.listeners. The valid options based on currently configured listeners are L1,L2
2025-07-21T12:30:52+02:00   at scala.Predef$.require(Predef.scala:337)
2025-07-21T12:30:52+02:00   at kafka.server.KafkaConfig.validateValues(KafkaConfig.scala:2390)
2025-07-21T12:30:52+02:00   at kafka.server.KafkaConfig.<init>(KafkaConfig.scala:2233)
2025-07-21T12:30:52+02:00   at kafka.server.KafkaConfig.<init>(KafkaConfig.scala:1604)
2025-07-21T12:30:52+02:00   at kafka.Kafka$.buildServer(Kafka.scala:72)
2025-07-21T12:30:52+02:00   at kafka.Kafka$.main(Kafka.scala:91)
2025-07-21T12:30:52+02:00   at kafka.Kafka.main(Kafka.scala)

错误原因 #

Confluent官方的cp-kafka镜像默认将PLAINTEXT_INTERNAL设置为broker间通信的监听器（inter.broker.listener.name）。

在最初的配置中，advertised.listeners包含了PLAINTEXT_INTERNAL这个名称，与镜像默认的inter.broker.listener.name匹配，因此启动正常。

当你把监听器名称改成自定义的L1和L2后，镜像默认的inter.broker.listener.name依然是PLAINTEXT_INTERNAL，但这个名称已经不在新配置的advertised.listeners列表里了。而Kafka的配置规则要求inter.broker.listener.name必须是advertised.listeners中已定义的监听器名称，因此触发了非法参数异常，导致启动失败。

修复方案 #

在Kafka的环境变量中显式指定KAFKA_INTER_BROKER_LISTENER_NAME为自定义监听器中适合broker间通信的那个（比如L1，因为它指向容器内部地址）：

environment:
  # 保留其他原有配置
  KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: L1:PLAINTEXT,L2:PLAINTEXT
  KAFKA_ADVERTISED_LISTENERS: L1://kafka:9092,L2://localhost:9093
  KAFKA_INTER_BROKER_LISTENER_NAME: L1

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