Docker 部署 Kafka (KRaft 模式)

随着 Kafka 3.3+ 版本的发布，KRaft 模式（去 ZooKeeper 模式） 已经成为生产就绪的标准。本文介绍基于 Docker Compose 部署 3 节点 Kafka KRaft 集群 的方案，以及生产环境中高频使用的维护命令。

部署

Kafka 3.3+ 版本不再需要部署 ZooKeeper，这大大简化了架构。本文使用目前最流行的 bitnami/kafka 镜像。

编写 docker-compose.yml

创建一个名为 docker-compose.yml 的文件，内容如下：

services:
  kafka1:
    image: bitnami/kafka:latest
    container_name: kafka1
    hostname: kafka1
    ports:
      - '9092:9092'
    environment:
      # KRaft 设置
      - KAFKA_ENABLE_KRAFT=yes
      - KAFKA_CFG_PROCESS_ROLES=broker,controller
      - KAFKA_CFG_CONTROLLER_LISTENER_NAMES=CONTROLLER
      - KAFKA_CFG_NODE_ID=1
      - KAFKA_CFG_CONTROLLER_QUORUM_VOTERS=1@kafka1:9093,2@kafka2:9093,3@kafka3:9093
      # 这是一个固定的集群ID，用于保证节点属于同一个集群
      - KAFKA_KRAFT_CLUSTER_ID=MkU3OEVBNTcwNTJENDM2Qk
      # 监听器设置
      - KAFKA_CFG_LISTENERS=PLAINTEXT://:9092,CONTROLLER://:9093
      - KAFKA_CFG_ADVERTISED_LISTENERS=PLAINTEXT://kafka1:9092
      - KAFKA_CFG_LISTENER_SECURITY_PROTOCOL_MAP=CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT
      # 允许任意人连接（生产环境请关闭）
      - ALLOW_PLAINTEXT_LISTENER=yes
    volumes:
      - kafka1_data:/bitnami/kafka

  kafka2:
    image: bitnami/kafka:latest
    container_name: kafka2
    hostname: kafka2
    environment:
      - KAFKA_ENABLE_KRAFT=yes
      - KAFKA_CFG_PROCESS_ROLES=broker,controller
      - KAFKA_CFG_CONTROLLER_LISTENER_NAMES=CONTROLLER
      - KAFKA_CFG_NODE_ID=2
      - KAFKA_CFG_CONTROLLER_QUORUM_VOTERS=1@kafka1:9093,2@kafka2:9093,3@kafka3:9093
      - KAFKA_KRAFT_CLUSTER_ID=MkU3OEVBNTcwNTJENDM2Qk
      - KAFKA_CFG_LISTENERS=PLAINTEXT://:9092,CONTROLLER://:9093
      - KAFKA_CFG_ADVERTISED_LISTENERS=PLAINTEXT://kafka2:9092
      - KAFKA_CFG_LISTENER_SECURITY_PROTOCOL_MAP=CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT
      - ALLOW_PLAINTEXT_LISTENER=yes
    volumes:
      - kafka2_data:/bitnami/kafka

  kafka3:
    image: bitnami/kafka:latest
    container_name: kafka3
    hostname: kafka3
    environment:
      - KAFKA_ENABLE_KRAFT=yes
      - KAFKA_CFG_PROCESS_ROLES=broker,controller
      - KAFKA_CFG_CONTROLLER_LISTENER_NAMES=CONTROLLER
      - KAFKA_CFG_NODE_ID=3
      - KAFKA_CFG_CONTROLLER_QUORUM_VOTERS=1@kafka1:9093,2@kafka2:9093,3@kafka3:9093
      - KAFKA_KRAFT_CLUSTER_ID=MkU3OEVBNTcwNTJENDM2Qk
      - KAFKA_CFG_LISTENERS=PLAINTEXT://:9092,CONTROLLER://:9093
      - KAFKA_CFG_ADVERTISED_LISTENERS=PLAINTEXT://kafka3:9092
      - KAFKA_CFG_LISTENER_SECURITY_PROTOCOL_MAP=CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT
      - ALLOW_PLAINTEXT_LISTENER=yes
    volumes:
      - kafka3_data:/bitnami/kafka

volumes:
  kafka1_data:
  kafka2_data:
  kafka3_data:

启动集群

在目录下执行：

docker-compose up -d

查看状态：

docker-compose ps

常见维护命令合集

为了执行命令，我们通常进入其中一个容器（例如 kafka1）来操作，或者在命令前加上 docker exec -it kafka1。

以下命令假设你已经进入了容器：

docker exec -it kafka1 bash

注：Bitnami 镜像的脚本通常在 /opt/bitnami/kafka/bin/ 下，或者已添加到 PATH 中可以直接运行

Topic 管理

这是最基础的运维操作。

• 创建 Topic (3 分区，3 副本)

  • --replication-factor <Integer>
  • 作用：指定每个分区的副本（Replica）数量
  • 说明：决定了数据的可靠性和容灾能力
    • 1：无备份，Broker 宕机数据可能丢失
    • 2：容忍 1 台 Broker 宕机
    • 3：生产环境常用值，容忍 2 台 Broker 宕机
  • 限制：副本因子不能大于集群中可用的 Broker 节点总数
  bash

  kafka-topics.sh --create --topic user-logs \
    --bootstrap-server kafka1:9092 \
    --partitions 3 --replication-factor 3

• 查看 Topic 列表

  bash

  kafka-topics.sh --list --bootstrap-server kafka1:9092

• 查看 Topic 详细信息 (查看分区分布、ISR 同步列表等关键信息)

  bash

  kafka-topics.sh --describe --topic user-logs --bootstrap-server kafka1:9092

• 修改 Topic 配置 (例如：修改数据保留时间为 1 天)

  bash

  kafka-configs.sh --bootstrap-server kafka1:9092 \
    --entity-type topics --entity-name user-logs \
    --alter --add-config retention.ms=86400000

• 增加分区数量 (注意：分区只能增加不能减少)

  bash

  kafka-topics.sh --bootstrap-server kafka1:9092 \
    --alter --topic user-logs --partitions 5

• 删除 Topic

  bash

  kafka-topics.sh --delete --topic user-logs --bootstrap-server kafka1:9092

消费者组 (Consumer Group) 管理

这是排查消息堆积（Lag）问题的核心命令。

• 列出所有消费者组

  bash

  kafka-consumer-groups.sh --list --bootstrap-server kafka1:9092

• 查看消费进度与堆积 (LAG) (最常用)

  • LAG 列显示了积压的消息数量。
  bash

  kafka-consumer-groups.sh --describe --bootstrap-server kafka1:9092 --group my-group-id

• 重置消费偏移量 (Reset Offset)

  • 场景： 系统故障修复后，需要重新消费之前的数据。
  • 步骤： 必须先停止消费者应用，然后执行命令。
  • 示例： 将 my-group-id 组对 user-logs 主题的消费位置回退到 最早 处。
  bash

  kafka-consumer-groups.sh --bootstrap-server kafka1:9092 \
    --group my-group-id \
    --topic user-logs \
    --reset-offsets --to-earliest --execute

  选项包括 --to-earliest, --to-latest, --to-datetime, --shift-by 等

生产与消费测试 (Console)

用于在服务器上快速验证集群是否可用。

• 控制台生产者 (手动发消息)

  bash

  kafka-console-producer.sh --topic user-logs --bootstrap-server kafka1:9092
  > hello kafka
  > this is a test

• 控制台消费者 (查看消息)

  bash

  # --from-beginning 表示把历史数据也读出来
  kafka-console-consumer.sh --topic user-logs --from-beginning --bootstrap-server kafka1:9092

高级维护 (Broker 与集群)

• 查看集群版本

  bash

  kafka-broker-api-versions.sh --bootstrap-server kafka1:9092 | grep "^id"

• 删除特定消费者组

  bash

  kafka-consumer-groups.sh --bootstrap-server kafka1:9092 --delete --group my-group-id

Kafka 可视化管理工具（UI）

• UI for Apache Kafka 它集成了管理和数据查看，部署最简单

docker run -it -p 8080:8080 \
  -e KAFKA_CLUSTERS_0_NAME=local \
  -e KAFKA_CLUSTERS_0_BOOTSTRAPSERVERS=host.docker.internal:9092 \
  provectuslabs/kafka-ui:latest

• AKHQ (原 KafkaHQ)
• Redpanda Console (原 Kowl)
• Offset Explorer (原 Kafka Tool)

总结

1. 架构选择：推荐使用 KRaft 模式（KAFKA_ENABLE_KRAFT=yes），抛弃 ZooKeeper。
2. 网络配置：在 Docker Compose 中，KAFKA_CFG_ADVERTISED_LISTENERS 是最容易出错的地方，确保它指向容器间可访问的主机名（如 kafka1）。
3. 核心参数：所有命令都依赖 --bootstrap-server，请务必指定任意一个 Broker 的地址。