Kafka 3.X升级架构咨询及PLAINTEXT端点解析异常排查

我现有一套基于Docker Compose部署的3节点Kafka集群，使用Kafka 2.2.0镜像与Zookeeper 3.5镜像，Zookeeper集群已正常运行。计划升级至Kafka 3.X，原以为该版本无需显式部署Zookeeper（以为内置会自动启动），实际发现需单独打包Zookeeper镜像与Kafka镜像分别部署：Zookeeper镜像通过Dockerfile的CMD调用zoo-start.sh并配置相关参数，Kafka镜像通过CMD调用start.sh并配置Kafka参数。但升级后出现异常：

KafkaException: Unable to parse PLAINTEXT://127.0.0.1: to a broker endpoint -

现咨询当前架构方案是否正确，以及该异常的解决方法。以下为单节点Zookeeper与Kafka的Docker Compose配置：

zookeeper:
  hostname: ${HOST_IP}
  image: ${ZOOKEEPER_IMAGE}
  container_name: zookeeper
  command: /bin/bash -c "/start.sh"
  volumes:
    - ${VOLUMES_FOLDER}/zk/data:/data
    - ${VOLUMES_FOLDER}/zk/conf:/conf
  network_mode: "host"
  ports:
    - 0.0.0.0:${ZOOKEEPER_EXPOSED_PORT}:${ZOOKEEPER_EXPOSED_PORT}

kafka1:
  hostname: ${HOST_IP}
  image: ${KAFKA_IMAGE}
  depends_on:
  - zookeeper
  container_name: kafka1
  command: /bin/bash -c "/start.sh"
  volumes:
    - ${VOLUMES_FOLDER}/kf/1/logs:/logs
    - ${VOLUMES_FOLDER}/kf/1/data:/data
  environment:
    - KAFKA_ADVERTISED_HOST_NAME=${HOST_IP}
    - KAFKA_DELETE_TOPIC_ENABLE=true
    - KAFKA_BROKER_ID=10
    - port = ${KAFKA1_EXPOSED_PORT}
    - ZOOKEEPER_IP=${HOST_IP}
    - JMX_PORT=7208
  network_mode: "host"
  ports:
    - 0.0.0.0:${KAFKA1_EXPOSED_PORT}:${KAFKA1_EXPOSED_PORT}

一、架构方案正确性分析 #

Kafka 3.X支持两种运行模式，你当前的架构是合法的：

• 传统ZooKeeper依赖模式：你现在采用的单独部署ZooKeeper+Kafka的方式完全符合该模式要求，是稳定且成熟的部署方案，适合熟悉传统集群架构的场景。
• KRaft无ZooKeeper模式：这是Kafka 2.8+引入的新特性，不需要单独部署ZooKeeper，由Kafka自身控制器节点管理元数据。你之前误以为内置自动启动ZooKeeper，是混淆了该模式与传统模式的区别。如果想切换到KRaft模式，需要重新配置Kafka启动参数（如指定process.roles、controller.quorum.voters等），但当前架构本身没有问题。

二、异常解决方法 #

报错的核心原因是Kafka监听地址配置不完整，端口部分缺失或未正确加载，结合你的配置，可从以下几点修复：

1. 修正环境变量格式
   你的Kafka环境变量中port = ${KAFKA1_EXPOSED_PORT}存在多余空格，Docker环境变量不允许这种格式，需改为：

   - port=${KAFKA1_EXPOSED_PORT}
   

2. 替换废弃的配置项
   KAFKA_ADVERTISED_HOST_NAME在Kafka 2.3之后已被废弃，Kafka 3.X推荐使用KAFKA_ADVERTISED_LISTENERS和KAFKA_LISTENERS完整定义监听地址，替换原有的KAFKA_ADVERTISED_HOST_NAME：

   - KAFKA_LISTENERS=PLAINTEXT://0.0.0.0:${KAFKA1_EXPOSED_PORT}
   - KAFKA_ADVERTISED_LISTENERS=PLAINTEXT://${HOST_IP}:${KAFKA1_EXPOSED_PORT}
   

3. 检查start.sh脚本的配置逻辑
   确认start.sh是否正确将环境变量注入Kafka的server.properties，需确保包含以下配置：

   echo "listeners=PLAINTEXT://0.0.0.0:${port}" >> /path/to/server.properties
   echo "advertised.listeners=PLAINTEXT://${HOST_IP}:${port}" >> /path/to/server.properties
   

   若脚本未正确处理这些变量，会导致端口缺失，生成127.0.0.1:这种不完整的地址。

4. 验证环境变量传递有效性
   进入Kafka容器执行echo $port和echo $HOST_IP，确认变量是否正确加载。如果变量为空，检查.env文件是否正确定义了KAFKA1_EXPOSED_PORT和HOST_IP，或Docker Compose是否正确读取了这些变量。

三、额外优化建议 #

• 长期来看，建议迁移到KRaft模式，减少ZooKeeper的运维成本。
• 避免使用network_mode: host，除非有特殊需求，使用Docker自定义网络可更好地隔离服务、避免端口冲突。
• 确保版本兼容性：Kafka 3.X建议搭配Zookeeper 3.6+版本，避免潜在的兼容性问题。

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