Docker 部署 Kafka (KRaft 模式)

发布时间: 更新时间: 总字数:2451 阅读时间:5m 作者:IP:上海 网址

KRaft(Kafka Raft Metadata mode)自 Kafka 2.8 引入、3.3 起生产就绪,4.0 起彻底移除 ZooKeeper,成为唯一部署形态。本文介绍基于 Apache 官方镜像 apache/kafka 部署单节点 Kafka(开发/测试环境)与基于 Docker Compose 部署 3 节点 KRaft 集群(生产环境)的方案,以及生产环境中高频使用的维护命令。

单节点部署(开发/测试环境)

Kafka 从 3.7.0 起提供官方 Docker 镜像 apache/kafka,默认即为 KRaft 单节点(combined 模式:同一进程既是 broker 也是 controller),适合本地开发与功能验证。

创建 docker-compose.yml(改编自 官方单节点示例):

yaml
services:
  kafka:
    image: apache/kafka:4.0.0
    container_name: kafka
    ports:
      - "9092:9092"
    environment:
      KAFKA_NODE_ID: 1
      KAFKA_PROCESS_ROLES: "broker,controller"
      KAFKA_CONTROLLER_QUORUM_VOTERS: "1@kafka:29093"
      KAFKA_LISTENERS: "CONTROLLER://:29093,PLAINTEXT_HOST://:9092,PLAINTEXT://:19092"
      KAFKA_ADVERTISED_LISTENERS: "PLAINTEXT_HOST://localhost:9092,PLAINTEXT://kafka:19092"
      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: "CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT,PLAINTEXT_HOST:PLAINTEXT"
      KAFKA_INTER_BROKER_LISTENER_NAME: "PLAINTEXT"
      KAFKA_CONTROLLER_LISTENER_NAMES: "CONTROLLER"
      CLUSTER_ID: "4L6g3nShT-eMCtK--X86sw"
      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
      KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: 1
      KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: 1

启动容器:

bash
docker compose up -d

关键配置项说明:

  • 官方镜像的环境变量直接映射 server.properties 参数名(如 KAFKA_PROCESS_ROLES),没有 Bitnami 镜像的 KAFKA_CFG_ 前缀,迁移时容易踩坑;
  • KAFKA_PROCESS_ROLES=broker,controller:该节点既存储数据(broker),也管理集群元数据(controller,即替代 ZooKeeper 的角色);
  • KAFKA_CONTROLLER_QUORUM_VOTERS=1@kafka:29093:定义 KRaft 投票节点,格式为 id@host:port,单机指向自己即可;
  • 三个监听器各司其职:PLAINTEXT_HOST(localhost:9092)供宿主机访问,PLAINTEXT(kafka:19092)供 Docker 网络内的其他容器访问,CONTROLLER(29093)用于 KRaft 元数据仲裁。KAFKA_ADVERTISED_LISTENERS 必须与访问方所处网络匹配,这是最常见的连接失败原因;
  • CLUSTER_ID:显式固定集群 ID,保证重建容器后节点仍归属同一集群;
  • 单节点下副本因子上限为 1:KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR、KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR 等内部 topic 参数必须为 1,手动建 Topic 时 --replication-factor 也只能为 1。

集群部署(3 节点)

注意(2025-08 镜像政策变更):Broadcom 已将 Bitnami 公共镜像目录收紧为商业化的 Bitnami Secure Images,bitnami/kafka 的公开 tag 已下架(历史版本迁移至 bitnamilegacy/kafka,冻结且不再有安全更新)。下文的 bitnami/kafka 配置现仅可作为 KAFKA_CFG_* 参数写法的参考;新部署建议改用 Apache 官方镜像 apache/kafka(环境变量去掉 KAFKA_CFG_ 前缀即可迁移),或 Confluent 官方镜像。

Kafka 3.3+ 版本不再需要部署 ZooKeeper,这大大简化了架构。本节使用 bitnami/kafka 镜像(历史方案)。

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

编写 docker-compose.yml

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

yaml
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:

启动集群

在目录下执行:

bash
docker compose up -d

查看状态:

bash
docker compose ps

常见维护命令合集

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

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

bash
docker exec -it kafka1 bash

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

  • KRaft 模式下不需要也不允许指定 --zookeeper 参数(Kafka 4.0 起该参数已彻底移除),所有命令必须使用 --bootstrap-server;
  • 若使用上文单节点部署,请将命令中的 --bootstrap-server kafka1:9092 换成 --bootstrap-server localhost:9092,且 --replication-factor 上限为 1(不能超过集群中的 Broker 节点总数)。

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 它集成了管理和数据查看,部署最简单(需加入 compose 网络并用容器名直连):
bash
docker run -d -p 8080:8080 \
  --network <项目名>_default \
  -e KAFKA_CLUSTERS_0_NAME=local \
  -e KAFKA_CLUSTERS_0_BOOTSTRAPSERVERS=kafka1:9092 \
  provectuslabs/kafka-ui:latest
  • AKHQ (原 KafkaHQ)
  • Redpanda Console (原 Kowl)
  • Offset Explorer (原 Kafka Tool)

总结

  1. 架构选择:推荐使用 KRaft 模式(Kafka 4.0 起已彻底移除 ZooKeeper),开发测试用单节点,生产用 3/5 节点集群。
  2. 网络配置:在 Docker Compose 中,KAFKA_ADVERTISED_LISTENERS 是最容易出错的地方——宿主机访问用 localhost:9092,容器间访问用服务名(如 kafka1、kafka:19092),必须与客户端所在网络匹配。
  3. 核心参数:所有命令都依赖 --bootstrap-server(KRaft 模式无需 --zookeeper),请务必指定任意一个 Broker 的地址。

参考

  1. https://kafka.apache.org/documentation/
  2. https://kafka.apache.org/documentation/#docker