10.2.5 ZooKeeper或KRaft模式配置

本节说明 Kafka 在 ZooKeeper 与 KRaft 两种模式下的配置要点、参数含义与部署注意事项，便于根据版本与规模选择合适的集群形态，并给出可执行示例、排错与练习。

一、原理草图（模式对比）

二、模式选择与适用场景
- ZooKeeper 模式：生态成熟、运维复杂度较高，适合已有 ZK 集群或混合版本环境。
- KRaft 模式：Kafka 自带元数据管理，无需 ZK，适合新建集群与简化运维（Kafka 3.3+ 推荐）。

三、ZooKeeper 模式配置与示例

1) 安装与目录准备（示例路径）

# 以 /opt/kafka 为安装目录
tar -xf kafka_2.13-3.6.1.tgz -C /opt/
ln -s /opt/kafka_2.13-3.6.1 /opt/kafka

# 数据目录
mkdir -p /data/kafka-logs /data/zookeeper
chown -R kafka:kafka /data/kafka-logs /data/zookeeper

2) ZooKeeper 配置（/opt/kafka/config/zookeeper.properties）

dataDir=/data/zookeeper
clientPort=2181
server.1=zk1:2888:3888
server.2=zk2:2888:3888
server.3=zk3:2888:3888

3) myid 文件（每台 ZK 节点）

# zk1
echo 1 > /data/zookeeper/myid
# zk2
echo 2 > /data/zookeeper/myid
# zk3
echo 3 > /data/zookeeper/myid

4) Kafka broker 配置（/opt/kafka/config/server.properties）

broker.id=1
listeners=PLAINTEXT://0.0.0.0:9092
advertised.listeners=PLAINTEXT://broker1:9092
log.dirs=/data/kafka-logs
zookeeper.connect=zk1:2181,zk2:2181,zk3:2181
num.network.threads=3
num.io.threads=8

5) 启动与验证

# 启动 ZK
/opt/kafka/bin/zookeeper-server-start.sh -daemon /opt/kafka/config/zookeeper.properties

# 启动 Kafka
/opt/kafka/bin/kafka-server-start.sh -daemon /opt/kafka/config/server.properties

# 验证 ZK 端口
echo ruok | nc zk1 2181   # 预期返回 "imok"

# 验证 broker
/opt/kafka/bin/kafka-broker-api-versions.sh --bootstrap-server broker1:9092

四、KRaft 模式配置与示例

1) 角色规划
- 单角色：controller+broker 同机（中小规模）。
- 分离角色：专用 controller 与 broker（中大规模）。

2) 配置示例（单角色，/opt/kafka/config/kraft/server.properties）

process.roles=broker,controller
node.id=1
controller.quorum.voters=1@c1:9093,2@c2:9093,3@c3:9093
controller.listener.names=CONTROLLER
listeners=PLAINTEXT://0.0.0.0:9092,CONTROLLER://0.0.0.0:9093
advertised.listeners=PLAINTEXT://broker1:9092
log.dirs=/data/kafka-logs

3) 初始化元数据并启动

# 生成 cluster.id
CLUSTER_ID=$(/opt/kafka/bin/kafka-storage.sh random-uuid)
echo $CLUSTER_ID

# 格式化存储（首次）
/opt/kafka/bin/kafka-storage.sh format \
  -t $CLUSTER_ID \
  -c /opt/kafka/config/kraft/server.properties

# 启动 KRaft broker
/opt/kafka/bin/kafka-server-start.sh -daemon /opt/kafka/config/kraft/server.properties

4) 验证与主题创建

/opt/kafka/bin/kafka-topics.sh \
  --bootstrap-server broker1:9092 \
  --create --topic demo --partitions 3 --replication-factor 1

/opt/kafka/bin/kafka-topics.sh \
  --bootstrap-server broker1:9092 --describe --topic demo

五、关键参数解释（简明对照）
- broker.id / node.id：节点唯一编号，重复会导致元数据冲突。
- listeners：服务监听地址（0.0.0.0 表示绑定所有网卡）。
- advertised.listeners：对客户端广播的地址，必须可被客户端解析。
- controller.quorum.voters：控制器选举成员列表，格式 id@host:port。
- log.dirs：消息数据目录，建议独立磁盘。

六、排错要点（常见问题与命令）
1) 客户端连接失败
- 检查 advertised.listeners 是否可解析：

getent hosts broker1
nc -zv broker1 9092

2) ZK 选举异常
- 端口未放行（2888/3888）：

nc -zv zk1 2888
nc -zv zk1 3888

3) KRaft 启动失败提示 No directory in log.dirs
- 检查权限与目录存在：

ls -ld /data/kafka-logs

4) 多节点 node.id 冲突
- 检查配置：

grep -E 'node.id|broker.id' /opt/kafka/config/*/server.properties

七、练习
1) 在 3 台服务器上分别部署 ZK 模式，创建 test-topic 并验证分区。
2) 在 3 台服务器上部署 KRaft 单角色集群，完成 cluster.id 初始化并创建主题。
3) 故意将 advertised.listeners 配置为不可解析域名，观察客户端报错并修复。