Apache Kafka Native Docker镜像文档

镜像概述和主要用途

Apache Kafka是一个开源事件流平台，用于实时大规模收集、处理、存储和集成数据。它支持多种使用场景，包括流处理、数据集成和发布/订阅消息传递。Kafka最初由LinkedIn开发，2011年开源，2012年成为Apache软件基金会项目，目前被全球数千家组织用于支持关键任务实时应用。

本Docker镜像运行基于GraalVM的原生Kafka broker。通过GraalVM的原生镜像编译技术，将默认以KRaft组合模式（同时作为broker和KRaft控制器）运行的broker编译为原生二进制可执行文件，提供轻量级的Kafka运行环境。

核心功能和特性

与基于JVM的Apache Kafka镜像相比，本镜像具有以下核心优势：

1. 更小的镜像体积：加快下载速度
2. 更快的启动时间：缩短服务就绪延迟
3. 更低的内存占用：减少资源消耗

使用场景和适用范围

基于上述优势，本镜像特别适用于以下场景：

• 非生产环境的开发和测试：适合本地开发、功能验证等场景
• 自动化测试环境：Testcontainers支持此镜像，可用于需要真实Kafka集群的单元测试或集成测试（而非mock服务）

有关此镜像引入Apache Kafka项目的更多信息，请参考KIP-974。

详细使用方法和配置说明

快速启动

启动Kafka broker，将Kafka监听端口映射到主机相同端口：

docker run -d -p 9092:9092 --name broker apache/kafka-native:latest

下载Apache Kafka以获取命令行工具（kafka-topics.sh、kafka-console-producer.sh等工具未包含在kafka-native镜像中）。解压最新Kafka发行版后，进入bin目录：

cd <KAFKA_HOME>/bin/

创建主题：主题是Kafka中事件的逻辑分组。创建名为test-topic的主题：

./kafka-topics.sh --bootstrap-server localhost:9092 --create --topic test-topic

生产消息：使用Kafka控制台生产者向test-topic写入两条字符串事件：

./kafka-console-producer.sh --bootstrap-server localhost:9092 --topic test-topic

命令执行后将显示>提示符，输入hello并按Enter，再输入world并按Enter，然后按Ctrl+C退出生产者。

消费消息：从日志开头读取test-topic中的事件：

./kafka-console-consumer.sh --bootstrap-server localhost:9092 --topic test-topic --from-beginning

将看到之前生产的两条消息：

hello
world

消费者将持续运行，按Ctrl+C退出。

停止容器：完成后，停止并删除容器：

docker rm -f broker

覆盖默认Broker配置

Apache Kafka支持通过环境变量覆盖broker配置。环境变量需以KAFKA_为前缀，配置项中的点（.）需替换为下划线（_）。例如，配置num.partitions（默认分区数）对应环境变量KAFKA_NUM_PARTITIONS。

注意：覆盖任何配置时，默认配置将不再生效。例如，如需以KRaft组合模式（broker和控制器在同一容器中运行）运行并将默认分区数从1改为3，需指定KAFKA_NUM_PARTITIONS及其他必要配置：

docker run -d  \
  -p 9092:9092 \
  --name broker \
  -e KAFKA_NODE_ID=1 \
  -e KAFKA_PROCESS_ROLES=broker,controller \
  -e KAFKA_LISTENERS=PLAINTEXT://:9092,CONTROLLER://:9093 \
  -e KAFKA_ADVERTISED_LISTENERS=PLAINTEXT://localhost:9092 \
  -e KAFKA_CONTROLLER_LISTENER_NAMES=CONTROLLER \
  -e KAFKA_LISTENER_SECURITY_PROTOCOL_MAP=CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT \
  -e KAFKA_CONTROLLER_QUORUM_VOTERS=1@localhost:9093 \
  -e KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR=1 \
  -e KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR=1 \
  -e KAFKA_TRANSACTION_STATE_LOG_MIN_ISR=1 \
  -e KAFKA_GROUP_INITIAL_REBALANCE_DELAY_MS=0 \
  -e KAFKA_NUM_PARTITIONS=3 \
  apache/kafka-native:latest

使用Docker Compose管理配置

命令行指定大量环境变量较为繁琐，建议使用Docker Compose管理Kafka容器。验证Docker Compose是否安装：

docker compose version

如需安装，参考Docker Compose安装文档。

示例：通过Docker Compose运行Kafka并将默认分区数改为3。创建docker-compose.yml文件：

services:
  broker:
    image: apache/kafka-native:latest
    container_name: broker
    ports:
      - 9092:9092
    environment:
      KAFKA_NODE_ID: 1
      KAFKA_PROCESS_ROLES: broker,controller
      KAFKA_LISTENERS: PLAINTEXT://localhost:9092,CONTROLLER://localhost:9093
      KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://localhost:9092
      KAFKA_CONTROLLER_LISTENER_NAMES: CONTROLLER
      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT
      KAFKA_CONTROLLER_QUORUM_VOTERS: 1@localhost:9093
      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
      KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: 1
      KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: 1
      KAFKA_GROUP_INITIAL_REBALANCE_DELAY_MS: 0
      KAFKA_NUM_PARTITIONS: 3

在docker-compose.yml所在目录启动容器：

docker compose up -d

可使用快速启动中的步骤测试主题创建、消息生产和消费。停止容器：

docker compose down

多节点部署

本部分介绍更贴近真实场景的Kafka部署：3个broker和3个控制器（KRaft隔离模式），支持从Docker网络内部和主机访问。

部署要点

1. KAFKA_PROCESS_ROLES根据容器角色设为broker或controller（非组合模式的broker,controller）
2. KAFKA_CONTROLLER_QUORUM_VOTERS包含所有控制器节点（格式：节点ID@控制器容器名:端口）
3. 接受默认的KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR（3）、KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR（3）和KAFKA_TRANSACTION_STATE_LOG_MIN_ISR（2）
4. Broker配置两个监听器：
   • 内部监听器：用于Docker网络内通信，使用容器名作为主机名
   • 主机监听器：用于主机访问，映射到主机唯一端口（如broker-1映射29092，broker-2映射39092等）

Docker Compose配置

创建docker-compose.yml文件：

services:
  controller-1:
    image: apache/kafka-native:latest
    container_name: controller-1
    environment:
      KAFKA_NODE_ID: 1
      KAFKA_PROCESS_ROLES: controller
      KAFKA_LISTENERS: CONTROLLER://:9093
      KAFKA_INTER_BROKER_LISTENER_NAME: PLAINTEXT
      KAFKA_CONTROLLER_LISTENER_NAMES: CONTROLLER
      KAFKA_CONTROLLER_QUORUM_VOTERS: 1@controller-1:9093,2@controller-2:9093,3@controller-3:9093
      KAFKA_GROUP_INITIAL_REBALANCE_DELAY_MS: 0

  controller-2:
    image: apache/kafka-native:latest
    container_name: controller-2
    environment:
      KAFKA_NODE_ID: 2
      KAFKA_PROCESS_ROLES: controller
      KAFKA_LISTENERS: CONTROLLER://:9093
      KAFKA_INTER_BROKER_LISTENER_NAME: PLAINTEXT
      KAFKA_CONTROLLER_LISTENER_NAMES: CONTROLLER
      KAFKA_CONTROLLER_QUORUM_VOTERS: 1@controller-1:9093,2@controller-2:9093,3@controller-3:9093
      KAFKA_GROUP_INITIAL_REBALANCE_DELAY_MS: 0

  controller-3:
    image: apache/kafka-native:latest
    container_name: controller-3
    environment:
      KAFKA_NODE_ID: 3
      KAFKA_PROCESS_ROLES: controller
      KAFKA_LISTENERS: CONTROLLER://:9093
      KAFKA_INTER_BROKER_LISTENER_NAME: PLAINTEXT
      KAFKA_CONTROLLER_LISTENER_NAMES: CONTROLLER
      KAFKA_CONTROLLER_QUORUM_VOTERS: 1@controller-1:9093,2@controller-2:9093,3@controller-3:9093
      KAFKA_GROUP_INITIAL_REBALANCE_DELAY_MS: 0

  broker-1:
    image: apache/kafka-native:latest
    container_name: broker-1
    ports:
      - 29092:9092
    environment:
      KAFKA_NODE_ID: 4
      KAFKA_PROCESS_ROLES: broker
      KAFKA_LISTENERS: 'PLAINTEXT://:19092,PLAINTEXT_HOST://:9092'
      KAFKA_ADVERTISED_LISTENERS: 'PLAINTEXT://broker-1:19092,PLAINTEXT_HOST://localhost:29092'
      KAFKA_INTER_BROKER_LISTENER_NAME: PLAINTEXT
      KAFKA_CONTROLLER_LISTENER_NAMES: CONTROLLER
      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT,PLAINTEXT_HOST:PLAINTEXT
      KAFKA_CONTROLLER_QUORUM_VOTERS: 1@controller-1:9093,2@controller-2:9093,3@controller-3:9093
      KAFKA_GROUP_INITIAL_REBALANCE_DELAY_MS: 0
    depends_on:
      - controller-1
      - controller-2
      - controller-3

  broker-2:
    image: apache/kafka-native:latest
    container_name: broker-2
    ports:
      - 39092:9092
    environment:
      KAFKA_NODE_ID: 5
      KAFKA_PROCESS_ROLES: broker
      KAFKA_LISTENERS: 'PLAINTEXT://:19092,PLAINTEXT_HOST://:9092'
      KAFKA_ADVERTISED_LISTENERS: 'PLAINTEXT://broker-2:19092,PLAINTEXT_HOST://localhost:39092'
      KAFKA_INTER_BROKER_LISTENER_NAME: PLAINTEXT
      KAFKA_CONTROLLER_LISTENER_NAMES: CONTROLLER
      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT,PLAINTEXT_HOST:PLAINTEXT
      KAFKA_CONTROLLER_QUORUM_VOTERS: 1@controller-1:9093,2@controller-2:9093,3@controller-3:9093
      KAFKA_GROUP_INITIAL_REBALANCE_DELAY_MS: 0
    depends_on:
      - controller-1
      - controller-2
      - controller-3

  broker-3:
    image: apache/kafka-native:latest
    container_name: broker-3
    ports:
      - 49092:9092
    environment:
      KAFKA_NODE_ID: 6
      KAFKA_PROCESS_ROLES: broker
      KAFKA_LISTENERS: 'PLAINTEXT://:19092,PLAINTEXT_HOST://:9092'
      KAFKA_ADVERTISED_LISTENERS: 'PLAINTEXT://broker-3:19092,PLAINTEXT_HOST://localhost:49092'
      KAFKA_INTER_BROKER_LISTENER_NAME: PLAINTEXT
      KAFKA_CONTROLLER_LISTENER_NAMES: CONTROLLER
      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT,PLAINTEXT_HOST:PLAINTEXT
      KAFKA_CONTROLLER_QUORUM_VOTERS: 1@controller-1:9093,2@controller-2:9093,3@controller-3:9093
      KAFKA_GROUP_INITIAL_REBALANCE_DELAY_MS: 0
    depends_on:
      - controller-1
      - controller-2
      - controller-3

启动和使用多节点集群

在docker-compose.yml所在目录启动容器：

docker compose up -d

使用以下命令创建主题、生产和消费消息（指定所有broker的主机监听器）：

# 创建主题
./kafka-topics.sh --bootstrap-server localhost:29092,localhost:39092,localhost:49092 --create --topic test-topic

# 生产消息
./kafka-console-producer.sh --bootstrap-server localhost:29092,localhost:39092,localhost:49092 --topic test-topic

# 消费消息
./kafka-console-consumer.sh --bootstrap-server localhost:29092,localhost:39092,localhost:49092 --topic test-topic --from-beginning

停止集群：

docker compose down

附加资源

• Apache Kafka官方文档
• Kafka Streams简介：Kafka的JVM流处理库
• Kafka Connect简介：用于数据集成的配置式连接器框架
• Kafka相关书籍和论文
• Kafka Summit会议演讲（幻灯片和录像）