消息队列 / 系统课时

搭建三节点测试集群

搭建三节点测试集群

这一节在单机上启动三个 KRaft 节点,每个进程同时承担 Broker 与 Controller 角色,并使用独立端口、节点 ID 和数据目录。完成后你将得到一个可创建三副本主题、可停掉单节点做故障实验的最小测试集群。

学习目标

  • 为三个节点配置唯一 node.id、Broker/Controller 监听端口和一致的控制器投票集合。
  • 使用同一个集群 ID 格式化三个存储目录并启动集群。
  • 通过元数据法定人数、主题副本和单节点故障验证集群是否可用。

规划单机三节点拓扑

假设 Kafka 已解压到 <PATH>/kafka,Java 运行环境可用,并且下面六个端口没有被占用。为了让故障关系容易观察,三个进程都配置为 broker,controller;这适合实验,不代表生产部署建议。

节点 node.id Broker 端口 Controller 端口 数据目录
node1 1 19092 19093 <PATH>/kafka-data/node-1
node2 2 29092 29093 <PATH>/kafka-data/node-2
node3 3 39092 39093 <PATH>/kafka-data/node-3

三节点 KRaft 测试集群拓扑

写入三个节点配置

先把 <PATH> 替换为本机可写的绝对路径,再创建三个配置文件。三份配置中的 controller.quorum.voters 必须完全一致,而 node.id、监听端口和 log.dirs 必须各自独立。

bash
export KAFKA_HOME="<PATH>/kafka"
mkdir -p "$KAFKA_HOME/config/kraft-test"

cat > "$KAFKA_HOME/config/kraft-test/node1.properties" <<'EOF'
process.roles=broker,controller
node.id=1
controller.quorum.voters=1@localhost:19093,2@localhost:29093,3@localhost:39093
listeners=PLAINTEXT://:19092,CONTROLLER://:19093
advertised.listeners=PLAINTEXT://localhost:19092
listener.security.protocol.map=PLAINTEXT:PLAINTEXT,CONTROLLER:PLAINTEXT
inter.broker.listener.name=PLAINTEXT
controller.listener.names=CONTROLLER
log.dirs=<PATH>/kafka-data/node-1
num.partitions=3
default.replication.factor=3
min.insync.replicas=2
offsets.topic.replication.factor=3
transaction.state.log.replication.factor=3
transaction.state.log.min.isr=2
EOF

cat > "$KAFKA_HOME/config/kraft-test/node2.properties" <<'EOF'
process.roles=broker,controller
node.id=2
controller.quorum.voters=1@localhost:19093,2@localhost:29093,3@localhost:39093
listeners=PLAINTEXT://:29092,CONTROLLER://:29093
advertised.listeners=PLAINTEXT://localhost:29092
listener.security.protocol.map=PLAINTEXT:PLAINTEXT,CONTROLLER:PLAINTEXT
inter.broker.listener.name=PLAINTEXT
controller.listener.names=CONTROLLER
log.dirs=<PATH>/kafka-data/node-2
num.partitions=3
default.replication.factor=3
min.insync.replicas=2
offsets.topic.replication.factor=3
transaction.state.log.replication.factor=3
transaction.state.log.min.isr=2
EOF

cat > "$KAFKA_HOME/config/kraft-test/node3.properties" <<'EOF'
process.roles=broker,controller
node.id=3
controller.quorum.voters=1@localhost:19093,2@localhost:29093,3@localhost:39093
listeners=PLAINTEXT://:39092,CONTROLLER://:39093
advertised.listeners=PLAINTEXT://localhost:39092
listener.security.protocol.map=PLAINTEXT:PLAINTEXT,CONTROLLER:PLAINTEXT
inter.broker.listener.name=PLAINTEXT
controller.listener.names=CONTROLLER
log.dirs=<PATH>/kafka-data/node-3
num.partitions=3
default.replication.factor=3
min.insync.replicas=2
offsets.topic.replication.factor=3
transaction.state.log.replication.factor=3
transaction.state.log.min.isr=2
EOF

printf 'created 3 configs\n'

预期输出

text
created 3 configs

CONTROLLER 监听器只服务控制器通信,不应放进 advertised.listeners 给普通客户端使用。单机实验使用 localhost 即可;跨主机部署时必须改成节点之间真实可解析、可连通的地址。

使用同一个集群 ID 格式化存储

三个节点必须属于同一个集群,所以只生成一次集群 ID,再用它格式化全部节点。下面的命令在每次格式化成功后输出固定确认文字,便于判断是哪一步失败。

bash
export KAFKA_HOME="<PATH>/kafka"
CLUSTER_ID="$("$KAFKA_HOME/bin/kafka-storage.sh" random-uuid)"
printf 'CLUSTER_ID=%s\n' "$CLUSTER_ID"

"$KAFKA_HOME/bin/kafka-storage.sh" format -t "$CLUSTER_ID" -c "$KAFKA_HOME/config/kraft-test/node1.properties" >/dev/null &&
printf 'node1 formatted\n'
"$KAFKA_HOME/bin/kafka-storage.sh" format -t "$CLUSTER_ID" -c "$KAFKA_HOME/config/kraft-test/node2.properties" >/dev/null &&
printf 'node2 formatted\n'
"$KAFKA_HOME/bin/kafka-storage.sh" format -t "$CLUSTER_ID" -c "$KAFKA_HOME/config/kraft-test/node3.properties" >/dev/null &&
printf 'node3 formatted\n'

预期输出

text
CLUSTER_ID=<ID>
node1 formatted
node2 formatted
node3 formatted

<ID> 每次新建实验集群都可能不同。若某个目录已经格式化为另一个集群 ID,不要用强制手段覆盖;先确认是否是旧实验数据,再清理对应测试目录并重新开始。

启动节点并验证法定人数

准备独立日志目录后启动三个进程。这里使用后台方式并记录 PID,便于后续模拟单节点故障。

bash
export KAFKA_HOME="<PATH>/kafka"
mkdir -p "<PATH>/kafka-logs"

nohup "$KAFKA_HOME/bin/kafka-server-start.sh" "$KAFKA_HOME/config/kraft-test/node1.properties" > "<PATH>/kafka-logs/node1.log" 2>&1 &
echo $! > "<PATH>/kafka-logs/node1.pid"
nohup "$KAFKA_HOME/bin/kafka-server-start.sh" "$KAFKA_HOME/config/kraft-test/node2.properties" > "<PATH>/kafka-logs/node2.log" 2>&1 &
echo $! > "<PATH>/kafka-logs/node2.pid"
nohup "$KAFKA_HOME/bin/kafka-server-start.sh" "$KAFKA_HOME/config/kraft-test/node3.properties" > "<PATH>/kafka-logs/node3.log" 2>&1 &
echo $! > "<PATH>/kafka-logs/node3.pid"

printf 'start requested for 3 nodes\n'

预期输出

text
start requested for 3 nodes

启动请求发出后,再读取 KRaft 法定人数状态;真正健康的集群应能选出 Leader Controller,并显示当前投票者集合。

bash
export KAFKA_HOME="<PATH>/kafka"
"$KAFKA_HOME/bin/kafka-metadata-quorum.sh"   --bootstrap-server localhost:19092   describe --status

预期输出

text
ClusterId: <ID>
LeaderId: <ID>
LeaderEpoch: <VALUE>
HighWatermark: <VALUE>
MaxFollowerLag: <VALUE>
MaxFollowerLagTimeMs: <VALUE>
CurrentVoters: <VALUE>
CurrentObservers: <VALUE>

实际数值与列表格式会随运行状态和 Kafka 版本变化,但 LeaderId 应能解析到当前控制器领导者,CurrentVoters 应包含本实验配置的三个控制器节点。

创建三副本主题并做故障实验

先创建一个三分区、三副本主题,再写入并读回一条消息。这同时验证 Broker 监听器、元数据控制面和普通消息数据面。

bash
export KAFKA_HOME="<PATH>/kafka"
"$KAFKA_HOME/bin/kafka-topics.sh"   --bootstrap-server localhost:19092   --create   --topic kraft-demo   --partitions 3   --replication-factor 3

printf 'kraft-ok\n' | "$KAFKA_HOME/bin/kafka-console-producer.sh"   --bootstrap-server localhost:19092   --topic kraft-demo

"$KAFKA_HOME/bin/kafka-console-consumer.sh"   --bootstrap-server localhost:19092   --topic kraft-demo   --from-beginning   --max-messages 1

预期输出

text
Created topic kraft-demo.
kraft-ok

接着停掉 node3。三 Controller 配置仍剩两个投票者,可以维持多数派;三副本主题也应暂时保留两个在线副本。等待故障被检测后,再检查法定人数状态。

bash
kill "$(cat "<PATH>/kafka-logs/node3.pid")"
sleep 5
export KAFKA_HOME="<PATH>/kafka"
"$KAFKA_HOME/bin/kafka-metadata-quorum.sh"   --bootstrap-server localhost:19092   describe --status

预期输出

text
ClusterId: <ID>
LeaderId: <ID>
LeaderEpoch: <VALUE>
HighWatermark: <VALUE>
MaxFollowerLag: <VALUE>
MaxFollowerLagTimeMs: <VALUE>
CurrentVoters: <VALUE>
CurrentObservers: <VALUE>

此时仍能查询到有效的 LeaderId,说明控制器多数派尚在。不要仅凭“还能生产消息”判断 KRaft Quorum 是否健康,因为主题 ISR 与 Controller Quorum 是两套机制。

如果节点无法启动,优先检查三类错误:端口冲突、重复 node.id、三份 controller.quorum.voters 不一致;如果格式化阶段失败,则再核对数据目录是否残留了其他集群 ID。按这个顺序排查,通常能在日志中迅速找到首个真实错误。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

搭建三节点测试集群

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通