Datehoer's Blog

Docker compose Kafka ip映射

5/3/2025 DockerKafka

在某些开发和测试场景下，我们希望通过 Docker Compose 快速部署一个 Kafka 环境，并且能够从 Docker 外部（例如宿主机或其他机器）访问它。这时，正确配置 Kafka 的 IP 映射就显得尤为重要。

# docker-compose.yml 示例

以下是一个部署单节点 Kafka 和 Zookeeper 的 docker-compose.yml 文件示例：

version: '3'
services:
  zookeeper:
    image: confluentinc/cp-zookeeper:latest
    environment:
      ZOOKEEPER_CLIENT_PORT: 2181
      ZOOKEEPER_TICK_TIME: 2000
    ports:
      - "2181:2181"

  kafka:
    image: confluentinc/cp-kafka:latest
    depends_on:
      - zookeeper
    ports:
      - "9092:9092" # 用于宿主机或其他外部客户端访问 Kafka
      - "29092:29092" # 用于 Docker 内部网络通信
    environment:
      KAFKA_BROKER_ID: 1
      KAFKA_ZOOKEEPER_CONNECT: 'zookeeper:2181'
      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: PLAINTEXT:PLAINTEXT,PLAINTEXT_HOST:PLAINTEXT
      KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://kafka:29092,PLAINTEXT_HOST://localhost:9092
      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
      KAFKA_GROUP_INITIAL_REBALANCE_DELAY_MS: 0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

# advertised.listeners 配置说明

在上述 docker-compose.yml 文件中，KAFKA_ADVERTISED_LISTENERS 是关键配置项。

  • PLAINTEXT://kafka:29092: 这是 Kafka Broker 向 Zookeeper 注册的监听地址，供 Docker 内部网络中的其他组件（例如同一个 Docker Compose 文件中定义的服务，或者连接到同一个 Docker 网络的服务）访问 Kafka。kafka 是 Kafka 服务在 Docker 网络中的主机名，29092 是我们为内部通信指定的端口。
  • PLAINTEXT_HOST://localhost:9092: 这是 Kafka Broker 告诉外部客户端（例如运行在宿主机上的应用程序，或者其他物理机/虚拟机上的客户端）应该如何连接到它的地址。localhost 指的是宿主机的 IP 地址（或者你可以替换为宿主机的实际 IP 地址或可解析的域名），9092 是我们映射到宿主机的端口。

为什么需要这样配置？

Docker 容器有自己的内部网络和 IP 地址。如果 Kafka 只监听其容器内部的 IP 地址和端口，那么从 Docker 网络外部（如宿主机）是无法直接访问的，即使你通过 ports 映射了端口。

advertised.listeners 允许 Kafka 告诉客户端：“虽然我在 Docker 内部的地址是 kafka:29092，但如果你是从外部网络访问我，请使用 localhost:9092 这个地址。”

常见配置方法：

  1. 使用 localhost：如果你的客户端和 Docker 宿主机是同一台机器，可以使用 localhost。
  2. 使用宿主机 IP 地址：如果客户端在不同的机器上，你需要将 localhost 替换为 Docker 宿主机的实际 IP 地址，例如 PLAINTEXT_HOST://192.168.1.100:9092。确保该 IP 地址对于客户端是可访问的。
  3. 使用可解析的域名：如果你的宿主机有一个可被客户端解析的域名，也可以使用域名，例如 PLAINTEXT_HOST://kafka.example.com:9092。

# 客户端连接说明

当你的 Kafka 服务通过上述 docker-compose.yml 启动后，外部客户端（例如 Java、Python、Go 编写的 Kafka 客户端程序，或者像 Kafka Tool 这样的 GUI 工具）在连接 Kafka 时，应该使用 advertised.listeners 中为外部访问配置的地址和端口。

在我们的示例中，如果客户端与 Docker 宿主机在同一台机器上，连接地址应为：

bootstrap.servers=localhost:9092

如果客户端在另一台机器上，并且宿主机的 IP 地址是 192.168.1.100，则连接地址应为：

bootstrap.servers=192.168.1.100:9092

通过这样的配置，客户端就能成功连接到 Docker 中运行的 Kafka 服务了。