3. Kafka 集群环境搭建：单机与集群模式部署、ZooKeeper/KRaft 配置、常用命令行工具

Kafka 的运行模式经历了从“强依赖 ZooKeeper”到“内置 KRaft 共识”的演进。本章将覆盖两种模式下的单机与集群搭建步骤，并介绍日常运维中最常用的命令行工具。无论你选择哪种模式，理解其架构差异是第一步。

3.1 架构模式对比：ZooKeeper 模式 vs. KRaft 模式

在 Kafka 2.8 之前，元数据（Broker 注册、Topic 分区分配、Controller 选举）全部由 ZooKeeper 管理。Kafka 2.8 开始引入 KRaft（Kafka Raft），将元数据存储在 Kafka 内部 Topic __cluster_metadata 中，不再依赖外部 ZooKeeper。KRaft 模式在 Kafka 3.x 中达到生产就绪状态。

3.2 单机模式部署（KRaft 模式）

单机模式用于开发测试。以下步骤基于 Kafka 3.6+ 的 KRaft 模式，无需安装 ZooKeeper。

1. 下载解压

   wget https://downloads.apache.org/kafka/3.6.0/kafka_2.13-3.6.0.tgz
   tar -xzf kafka_2.13-3.6.0.tgz
   cd kafka_2.13-3.6.0

2. 生成集群 ID 并格式化存储目录

   KAFKA_CLUSTER_ID="$(bin/kafka-storage.sh random-uuid)"
   bin/kafka-storage.sh format -t $KAFKA_CLUSTER_ID -c config/kraft/server.properties

3. 启动 Kafka 服务

   bin/kafka-server-start.sh config/kraft/server.properties

4. 验证启动

   bin/kafka-topics.sh --bootstrap-server localhost:9092 --list

   返回空列表即表示服务正常。

3.3 集群模式部署（KRaft 模式，3 节点）

生产环境至少需要 3 个 Controller 节点（或组合角色节点）以保证 Raft 多数派。以下以 3 台机器（node1、node2、node3）为例。

3.3.1 配置节点属性

每个节点的 config/kraft/server.properties 核心配置如下：

3.3.2 格式化与启动

在所有节点上执行：

# 生成相同的集群 ID（只需在 node1 生成，复制到其他节点）
KAFKA_CLUSTER_ID="$(bin/kafka-storage.sh random-uuid)"
echo $KAFKA_CLUSTER_ID   # 记录此 ID

# 每个节点用相同 ID 格式化
bin/kafka-storage.sh format -t <相同集群ID> -c config/kraft/server.properties

# 启动服务
bin/kafka-server-start.sh config/kraft/server.properties

3.3.3 验证集群

# 在任意节点查看集群 Broker 列表
bin/kafka-broker-api-versions.sh --bootstrap-server node1:9092

# 创建测试 Topic
bin/kafka-topics.sh --bootstrap-server node1:9092 --create --topic test-cluster --partitions 3 --replication-factor 2

# 查看 Topic 详情
bin/kafka-topics.sh --bootstrap-server node1:9092 --describe --topic test-cluster

3.4 集群模式部署（ZooKeeper 模式）

如果你维护的是旧版 Kafka 集群，以下为 ZooKeeper 模式的标准部署步骤。

3.4.1 部署 ZooKeeper 集群（3 节点）

# 每个 ZK 节点的 zoo.cfg 核心配置
tickTime=2000
initLimit=10
syncLimit=5
dataDir=/data/zookeeper
clientPort=2181
server.1=node1:2888:3888
server.2=node2:2888:3888
server.3=node3:2888:3888

在 dataDir 下创建 myid 文件，内容分别为 1、2、3。

3.4.2 配置 Kafka Broker

每个 Broker 的 config/server.properties 核心配置：

broker.id=1   # 每个节点唯一
listeners=PLAINTEXT://node1:9092
advertised.listeners=PLAINTEXT://node1:9092
log.dirs=/data/kafka/logs
zookeeper.connect=node1:2181,node2:2181,node3:2181/kafka
offsets.topic.replication.factor=3

3.4.3 启动顺序

1. 先启动所有 ZooKeeper 节点：bin/zkServer.sh start
2. 再启动所有 Kafka Broker：bin/kafka-server-start.sh config/server.properties

3.5 常用命令行工具

以下为日常巡检和问题排查中最常用的 Kafka 命令行工具，所有命令均位于 bin/ 目录下。

3.5.1 快速验证集群健康

# 1. 查看所有 Topic
bin/kafka-topics.sh --bootstrap-server node1:9092 --list

# 2. 查看特定 Topic 的分区分布
bin/kafka-topics.sh --bootstrap-server node1:9092 --describe --topic factor-alert

# 3. 发送一条测试消息
echo '{"factor":"volatility","value":0.85,"drift":true}' | bin/kafka-console-producer.sh --topic factor-alert --bootstrap-server node1:9092

# 4. 消费测试消息（从最新开始）
bin/kafka-console-consumer.sh --topic factor-alert --bootstrap-server node1:9092

# 5. 查看消费者组偏移
bin/kafka-consumer-groups.sh --bootstrap-server node1:9092 --describe --group factor-drift-group

3.6 部署架构总览

下图展示了 KRaft 模式下 3 节点集群的组件关系与内部通信路径。每个节点同时承担 Broker 和 Controller 角色，通过 Raft 协议在 Controller 层达成共识，Broker 层负责处理客户端请求。

3.7 部署检查清单

无论选择哪种模式，部署完成后建议逐项核对以下清单：

• 网络连通性： 各节点间 9092（数据）、9093（Raft/Controller）、2181（ZooKeeper）端口互通。
• 磁盘容量： log.dirs 所在分区至少预留 20% 空闲空间，建议使用独立数据盘。
• JVM 堆内存： 生产环境 Broker 堆内存建议 4G~8G，Controller 节点可适当降低。
• Topic 副本因子： 至少设置为 2，关键 Topic 设置为 3。
• 最小 ISR： min.insync.replicas 建议设置为副本因子减 1，保证写入一致性。
• 日志保留策略： 根据数据量设置 log.retention.hours 或 log.retention.bytes，避免磁盘写满。