Kafka容器启动时创建主题失败：无法连接到节点

问题核心是Kafka容器启动后服务尚未完全就绪，就执行了主题创建命令，导致连接失败，甚至干扰Kafka正常初始化，进而影响后续手动操作。以下是针对性的解决方法：

1. 给Kafka和ZooKeeper添加健康检查 #

Kafka依赖ZooKeeper，且自身启动需要初始化时间，通过健康检查可确保服务就绪后再执行后续操作。在Docker Compose中添加如下配置：

services:
  zookeeper:
    image: confluentinc/cp-zookeeper:latest
    environment:
      ZOOKEEPER_CLIENT_PORT: 2181
      ZOOKEEPER_TICK_TIME: 2000
    healthcheck:
      test: ["CMD", "zkServer.sh", "status"]
      interval: 5s
      timeout: 10s
      retries: 5

  kafka:
    image: confluentinc/cp-kafka:latest
    environment:
      KAFKA_BROKER_ID: 1
      KAFKA_ZOOKEEPER_CONNECT: zookeeper:2181
      KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://kafka:9092,PLAINTEXT_HOST://localhost:9093
      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: PLAINTEXT:PLAINTEXT,PLAINTEXT_HOST:PLAINTEXT
      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
    depends_on:
      zookeeper:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "kafka-topics.sh", "--list", "--bootstrap-server", "localhost:9092"]
      interval: 5s
      timeout: 10s
      retries: 5

2. 延迟执行主题创建命令 #

方式一：使用临时容器执行创建任务 #

利用Compose的依赖关系和健康检查，创建一个一次性容器，等待Kafka就绪后执行主题创建命令：

services:
  # ...上述zookeeper和kafka配置...
  kafka-topic-creator:
    image: confluentinc/cp-kafka:latest
    depends_on:
      kafka:
        condition: service_healthy
    command: >
      bash -c "kafka-topics.sh --create --topic my-topic --bootstrap-server kafka:9092 --partitions 1 --replication-factor 1 && echo 'Topic created successfully'"
    restart: "no" # 任务完成后自动退出

方式二：自定义Entrypoint脚本延迟执行 #

创建entrypoint.sh脚本，先启动Kafka，等待服务就绪后再创建主题：

#!/bin/bash
# 后台启动Kafka
/etc/confluent/docker/run &

# 轮询等待Kafka服务就绪
until kafka-topics.sh --list --bootstrap-server localhost:9092; do
  echo "Waiting for Kafka to be ready..."
  sleep 5
done

# 创建目标主题
kafka-topics.sh --create --topic my-topic --bootstrap-server localhost:9092 --partitions 1 --replication-factor 1

# 保持进程运行
wait

在Compose中挂载脚本并设置为Entrypoint：

kafka:
  # ...其他配置...
  volumes:
    - ./entrypoint.sh:/entrypoint.sh
  entrypoint: ["/bin/bash", "/entrypoint.sh"]

3. 验证Listeners配置正确性 #

确保KAFKA_ADVERTISED_LISTENERS配置覆盖容器内部和主机访问场景：

• 容器内部通信使用PLAINTEXT://kafka:9092（kafka为Compose服务名）
• 主机本地访问使用PLAINTEXT_HOST://localhost:9093
  此配置可保证容器内的kafka-topics.sh脚本无论是用localhost:9092还是kafka:9092都能正常连接服务。

问题原因说明 #

手动docker exec能成功创建主题，是因为此时Kafka已完全启动、端口正常监听；而直接在Compose中添加创建命令时，命令会在Kafka初始化阶段立即执行，此时服务尚未就绪，连接失败。若该命令持续重试占用资源，还会导致Kafka无法完成初始化，进而连后续手动执行命令也失败。

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