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(改编自 官方单节点示例):
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启动容器:
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 的文件,内容如下:
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 中可以直接运行
- 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 节点总数
bashkafka-topics.sh --create --topic user-logs \ --bootstrap-server kafka1:9092 \ --partitions 3 --replication-factor 3查看 Topic 列表
bashkafka-topics.sh --list --bootstrap-server kafka1:9092查看 Topic 详细信息 (查看分区分布、ISR 同步列表等关键信息)
bashkafka-topics.sh --describe --topic user-logs --bootstrap-server kafka1:9092修改 Topic 配置 (例如:修改数据保留时间为 1 天)
bashkafka-configs.sh --bootstrap-server kafka1:9092 \ --entity-type topics --entity-name user-logs \ --alter --add-config retention.ms=86400000增加分区数量 (注意:分区只能增加不能减少)
bashkafka-topics.sh --bootstrap-server kafka1:9092 \ --alter --topic user-logs --partitions 5删除 Topic
bashkafka-topics.sh --delete --topic user-logs --bootstrap-server kafka1:9092
消费者组 (Consumer Group) 管理
这是排查消息堆积(Lag)问题的核心命令。
列出所有消费者组
bashkafka-consumer-groups.sh --list --bootstrap-server kafka1:9092查看消费进度与堆积 (LAG) (最常用)
- LAG 列显示了积压的消息数量。
bashkafka-consumer-groups.sh --describe --bootstrap-server kafka1:9092 --group my-group-id重置消费偏移量 (Reset Offset)
- 场景: 系统故障修复后,需要重新消费之前的数据。
- 步骤: 必须先停止消费者应用,然后执行命令。
- 示例: 将
my-group-id组对user-logs主题的消费位置回退到 最早 处。
bashkafka-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)
用于在服务器上快速验证集群是否可用。
控制台生产者 (手动发消息)
bashkafka-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 与集群)
查看集群版本
bashkafka-broker-api-versions.sh --bootstrap-server kafka1:9092 | grep "(id:"删除特定消费者组
bashkafka-consumer-groups.sh --bootstrap-server kafka1:9092 --delete --group my-group-id
Kafka 可视化管理工具(UI)
- UI for Apache Kafka 它集成了管理和数据查看,部署最简单(需加入 compose 网络并用容器名直连):
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)
总结
- 架构选择:推荐使用 KRaft 模式(Kafka 4.0 起已彻底移除 ZooKeeper),开发测试用单节点,生产用 3/5 节点集群。
- 网络配置:在 Docker Compose 中,
KAFKA_ADVERTISED_LISTENERS是最容易出错的地方——宿主机访问用localhost:9092,容器间访问用服务名(如kafka1、kafka:19092),必须与客户端所在网络匹配。 - 核心参数:所有命令都依赖
--bootstrap-server(KRaft 模式无需--zookeeper),请务必指定任意一个 Broker 的地址。