GitHub Workflow中Kafka生产者构建失败问题求助

核心排查方向 #

1. 检查Kafka的监听与通告地址配置 #

Docker Compose中Kafka的listeners和advertised.listeners是连接成功的关键，直接影响客户端能否获取正确的连接地址：

• 本地环境里localhost指向主机，但自托管Runner如果是容器化运行，localhost仅代表Runner容器本身，而非Kafka容器所在的主机
• 适配外部客户端访问的配置示例：

  services:
    kafka:
      image: wurstmeister/kafka:latest
      environment:
        KAFKA_LISTENERS: PLAINTEXT://0.0.0.0:9092,PLAINTEXT_HOST://0.0.0.0:9093
        KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://kafka:9092,PLAINTEXT_HOST://${HOST_IP}:9093
        KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: PLAINTEXT:PLAINTEXT,PLAINTEXT_HOST:PLAINTEXT
        KAFKA_ZOOKEEPER_CONNECT: zookeeper:2181
      ports:
        - "9093:9093"
  

  其中${HOST_IP}可替换为自托管Runner所在主机的实际IP，或在Workflow中通过$(hostname -I | awk '{print $1}')动态获取

2. 确认自托管Runner的网络上下文 #

• 如果Runner是容器化运行：
  • 需将Kafka容器加入Runner所在的Docker网络，或使用network_mode: host让Kafka直接复用主机网络（注意避免端口冲突）
  • 此时客户端应使用主机IP而非localhost连接Kafka
• 如果Runner是直接在主机上运行：
  • 确保Docker Compose的端口映射正确（如9093:9093），且Kafka的advertised.listeners指向localhost:9093

3. 验证网络连通性 #

在GitHub Workflow中添加测试步骤，先确认Runner能访问Kafka服务：

- name: Test Kafka connectivity
  run: |
    # 检查端口是否开放
    nc -zv localhost 9093
    # 尝试列出主题（需提前安装kafka-cli）
    kafka-topics.sh --list --bootstrap-server localhost:9093

如果这一步失败，说明问题出在网络/端口层面，而非代码本身

4. 检查Python客户端配置 #

• 确保bootstrap_servers与Kafka的advertised.listeners地址完全匹配
• 若Kafka版本较新，添加api_version参数规避版本兼容问题：

  from kafka import KafkaProducer
  import json
  
  producer = KafkaProducer(
      bootstrap_servers=['localhost:9093'],
      api_version=(2, 8, 0),  # 替换为你的Kafka实际版本
      value_serializer=lambda x: json.dumps(x).encode('utf-8')
  )
  

• 不要额外配置SSL参数（除非Kafka明确开启了SSL），否则会直接导致生产者构造失败

5. 排查防火墙与端口限制 #

• 检查自托管Runner所在主机的防火墙规则（ufw status或iptables -L），确保9093端口对外开放
• 确认Docker daemon未限制端口转发功能

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