消息队列 / 系统课时
搭建三节点测试集群
搭建三节点测试集群
这一节在单机上启动三个 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 |

写入三个节点配置
先把 <PATH> 替换为本机可写的绝对路径,再创建三个配置文件。三份配置中的 controller.quorum.voters 必须完全一致,而 node.id、监听端口和 log.dirs 必须各自独立。
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'预期输出
created 3 configsCONTROLLER 监听器只服务控制器通信,不应放进 advertised.listeners 给普通客户端使用。单机实验使用 localhost 即可;跨主机部署时必须改成节点之间真实可解析、可连通的地址。
使用同一个集群 ID 格式化存储
三个节点必须属于同一个集群,所以只生成一次集群 ID,再用它格式化全部节点。下面的命令在每次格式化成功后输出固定确认文字,便于判断是哪一步失败。
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'预期输出
CLUSTER_ID=<ID>
node1 formatted
node2 formatted
node3 formatted<ID> 每次新建实验集群都可能不同。若某个目录已经格式化为另一个集群 ID,不要用强制手段覆盖;先确认是否是旧实验数据,再清理对应测试目录并重新开始。
启动节点并验证法定人数
准备独立日志目录后启动三个进程。这里使用后台方式并记录 PID,便于后续模拟单节点故障。
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'预期输出
start requested for 3 nodes启动请求发出后,再读取 KRaft 法定人数状态;真正健康的集群应能选出 Leader Controller,并显示当前投票者集合。
export KAFKA_HOME="<PATH>/kafka"
"$KAFKA_HOME/bin/kafka-metadata-quorum.sh" --bootstrap-server localhost:19092 describe --status预期输出
ClusterId: <ID>
LeaderId: <ID>
LeaderEpoch: <VALUE>
HighWatermark: <VALUE>
MaxFollowerLag: <VALUE>
MaxFollowerLagTimeMs: <VALUE>
CurrentVoters: <VALUE>
CurrentObservers: <VALUE>实际数值与列表格式会随运行状态和 Kafka 版本变化,但 LeaderId 应能解析到当前控制器领导者,CurrentVoters 应包含本实验配置的三个控制器节点。
创建三副本主题并做故障实验
先创建一个三分区、三副本主题,再写入并读回一条消息。这同时验证 Broker 监听器、元数据控制面和普通消息数据面。
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预期输出
Created topic kraft-demo.
kraft-ok接着停掉 node3。三 Controller 配置仍剩两个投票者,可以维持多数派;三副本主题也应暂时保留两个在线副本。等待故障被检测后,再检查法定人数状态。
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预期输出
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。按这个顺序排查,通常能在日志中迅速找到首个真实错误。