消息队列 / 系统课时

搭建单节点开发环境

搭建单节点开发环境

本课用一个 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 可以避免和其他练习实例混用数据。

bash
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"

预期结果

text
openjdk version "<VERSION>" ...
Kafka scripts ready
config/dev-single.properties created

listeners 是进程实际绑定的地址,advertised.listeners 是 Broker 返回给客户端的访问地址,不能写成客户端无法解析或无法到达的主机名。Controller 使用独立的 9093 端口,只参与 KRaft 元数据通信。

格式化存储并启动服务

KRaft 不会替空目录自动生成集群身份。必须先生成一次集群 ID,再用同一个 ID 格式化配置中的日志目录;重复格式化已有数据目录可能破坏原有实例,因此重做实验时应先停止服务并删除明确属于本实验的目录。:contentReference[oaicite:1]{index=1}

bash
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"

预期结果

text
<CLUSTER_ID>
Formatting dynamic metadata voter directory <PATH> ...
broker reachable

实际格式化日志会包含版本和目录信息,文本可能随 Kafka 小版本不同而变化;判断成功的关键是命令退出码为 0,并且 /tmp/kafka-dev-single/meta.properties 已生成。

创建主题并验证消息收发

连通性检查只能证明端口可访问,完整验收还要覆盖元数据写入、分区创建、消息追加和读取。下面创建单分区主题,写入一条消息,再从头消费一条。

bash
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

预期输出

text
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 法定人数,并为后续停机与选举实验准备环境。

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

目录与阅读设置

阅读设置

17

记录一个想法

搭建单节点开发环境

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

登录哪都通