消息队列 / 系统课时
搭建单节点开发环境
搭建单节点开发环境
本课用一个 Kafka 进程同时承担 Broker 与 Controller 角色,完成 KRaft 配置、存储格式化、后台启动以及消息收发验证。结束后,你将得到一个可反复重建、适合本地编码和命令练习的最小开发环境。
学习目标
- 写出单节点 KRaft 的最小可用配置
- 理解集群 ID、存储格式化与服务启动的先后顺序
- 通过创建主题、生产消息和消费消息验证连通性
准备环境与配置
以下命令以 Linux、macOS 或 WSL 中解压后的 Apache Kafka 4.3.1 为例,并要求本机已经安装 Java 17 或更高版本。单节点采用 broker,controller 组合角色,运维简单,适合开发环境,但不应用来模拟生产级容错。:contentReference[oaicite:0]{index=0}
先进入 Kafka 安装目录并确认 Java 与脚本可用,然后创建独立配置。使用独立的 log.dirs 可以避免和其他练习实例混用数据。
cd <PATH>/kafka_2.13-4.3.1
java -version
test -x bin/kafka-storage.sh && echo "Kafka scripts ready"
cat > config/dev-single.properties <<'EOF'
process.roles=broker,controller
node.id=1
controller.quorum.bootstrap.servers=127.0.0.1:9093
controller.listener.names=CONTROLLER
listeners=PLAINTEXT://127.0.0.1:9092,CONTROLLER://127.0.0.1:9093
advertised.listeners=PLAINTEXT://127.0.0.1:9092
inter.broker.listener.name=PLAINTEXT
listener.security.protocol.map=PLAINTEXT:PLAINTEXT,CONTROLLER:PLAINTEXT
log.dirs=/tmp/kafka-dev-single
num.partitions=1
offsets.topic.replication.factor=1
transaction.state.log.replication.factor=1
transaction.state.log.min.isr=1
EOF
echo "config/dev-single.properties created"预期结果
openjdk version "<VERSION>" ...
Kafka scripts ready
config/dev-single.properties createdlisteners 是进程实际绑定的地址,advertised.listeners 是 Broker 返回给客户端的访问地址,不能写成客户端无法解析或无法到达的主机名。Controller 使用独立的 9093 端口,只参与 KRaft 元数据通信。
格式化存储并启动服务
KRaft 不会替空目录自动生成集群身份。必须先生成一次集群 ID,再用同一个 ID 格式化配置中的日志目录;重复格式化已有数据目录可能破坏原有实例,因此重做实验时应先停止服务并删除明确属于本实验的目录。:contentReference[oaicite:1]{index=1}
KAFKA_CLUSTER_ID="$(bin/kafka-storage.sh random-uuid)"
echo "$KAFKA_CLUSTER_ID"
bin/kafka-storage.sh format \
--standalone \
-t "$KAFKA_CLUSTER_ID" \
-c config/dev-single.properties
bin/kafka-server-start.sh -daemon config/dev-single.properties
sleep 3
bin/kafka-broker-api-versions.sh \
--bootstrap-server 127.0.0.1:9092 >/dev/null \
&& echo "broker reachable"预期结果
<CLUSTER_ID>
Formatting dynamic metadata voter directory <PATH> ...
broker reachable实际格式化日志会包含版本和目录信息,文本可能随 Kafka 小版本不同而变化;判断成功的关键是命令退出码为 0,并且 /tmp/kafka-dev-single/meta.properties 已生成。
创建主题并验证消息收发
连通性检查只能证明端口可访问,完整验收还要覆盖元数据写入、分区创建、消息追加和读取。下面创建单分区主题,写入一条消息,再从头消费一条。
bin/kafka-topics.sh \
--create \
--topic dev-check \
--partitions 1 \
--replication-factor 1 \
--bootstrap-server 127.0.0.1:9092
printf 'hello-kraft\n' | bin/kafka-console-producer.sh \
--topic dev-check \
--bootstrap-server 127.0.0.1:9092
bin/kafka-console-consumer.sh \
--topic dev-check \
--from-beginning \
--max-messages 1 \
--timeout-ms 5000 \
--bootstrap-server 127.0.0.1:9092预期输出
Created topic dev-check.
hello-kraft
Processed a total of 1 messages主题创建成功说明 Controller 已提交元数据,能够读回 hello-kraft 则说明 Broker 的写入与读取链路正常。停止服务可执行 bin/kafka-server-stop.sh,确认进程退出后再清理 /tmp/kafka-dev-single。
典型失败处理
出现 Address already in use 时,先检查 9092 和 9093 是否被其他 Kafka 实例占用;修改端口时必须同步修改监听地址和 controller.quorum.bootstrap.servers。出现无法连接时,优先核对 advertised.listeners,因为客户端首次连接后会按照 Broker 返回的地址重新建立连接。
若格式化提示目录已存在,不要直接加跳过参数掩盖问题。开发环境中应先确认服务已停止,再删除本课专用目录并重新生成集群 ID;已有重要数据时则禁止重新格式化,应保留原 meta.properties 并排查配置路径是否写错。
本课总结
- 单节点开发环境可以让一个进程同时承担 Broker 与 Controller 角色
- KRaft 的正确顺序是准备配置、生成集群 ID、格式化存储、启动服务
- 只有主题创建和消息收发都成功,才能确认开发环境完整可用
下一课预告
下一课将把单节点扩展为三个独立节点,配置不同的节点身份、客户端端口和 Controller 法定人数,并为后续停机与选举实验准备环境。