4. 环境搭建与快速入门
Kafka 的学习必须从“能跑起来”开始。本章围绕环境搭建与快速入门，覆盖单机部署、集群部署、Docker 安装、命令行工具使用，以及第一个生产与消费示例。目标不是把 Kafka 调优到生产级，而是建立一条可重复的最小闭环：启动 Broker、创建 Topic、写入消息、读取消息，并能观察分区与偏移量。
一、单机部署：最快建立可运行环境
单机部署适合本地开发与教学验证。Kafka 依赖 Java 运行环境，通常还需要 ZooKeeper（旧版本）或 KRaft（新版本）。以 KRaft 模式为例，单机启动只需配置节点角色、日志目录和监听地址。关键参数包括 process.roles、node.id、controller.quorum.voters、listeners 和 log.dirs。
# 1. 生成集群ID（KRaft模式）
bin/kafka-storage.sh random-uuid
# 2. 格式化日志目录
bin/kafka-storage.sh format -t <uuid> -c config/kraft/server.properties
# 3. 启动 Broker
bin/kafka-server-start.sh config/kraft/server.properties
启动后，Broker 会监听 9092 端口。此时可以创建 Topic 并测试生产消费。单机模式的优势是启动快、依赖少；缺点是副本因子只能为 1，无法验证高可用与故障转移。
二、集群部署：理解分区与副本的物理分布
集群部署的核心是让多个 Broker 共同承载 Topic 的分区与副本。假设有 3 个 Broker，创建 Topic 时设置 --partitions 3 --replication-factor 3，则每个分区会有一个 Leader 和两个 Follower。Leader 负责读写，Follower 负责同步。当某个 Broker 宕机，Controller 会触发 Leader 选举，保证分区继续可用。
集群部署的关键配置包括：每个 Broker 唯一的 broker.id、listeners 与 advertised.listeners、log.dirs、zookeeper.connect 或 KRaft 的 controller.quorum.voters。生产环境还应关注 num.partitions、default.replication.factor 和 min.insync.replicas。
advertised.listeners 必须配置为客户端可访问的地址，否则客户端会拿到错误的 Broker 地址而连接失败。
三、Docker 安装：可重复、可迁移的快速方式
Docker 方式适合快速搭建和销毁环境。使用 Docker Compose 可以一次启动 ZooKeeper/KRaft、Kafka Broker 和可选的管理界面。以下是一个最小 KRaft 单节点示例：
services:
kafka:
image: bitnami/kafka:3.7
ports:
- "9092:9092"
environment:
- KAFKA_CFG_NODE_ID=1
- KAFKA_CFG_PROCESS_ROLES=broker,controller
- KAFKA_CFG_CONTROLLER_QUORUM_VOTERS=1@kafka:9093
- KAFKA_CFG_LISTENERS=PLAINTEXT://:9092,CONTROLLER://:9093
- KAFKA_CFG_ADVERTISED_LISTENERS=PLAINTEXT://localhost:9092
- KAFKA_CFG_CONTROLLER_LISTENER_NAMES=CONTROLLER
- KAFKA_CFG_LOG_DIRS=/bitnami/kafka/data
启动命令为 docker compose up -d。进入容器后即可使用 Kafka 命令行工具。Docker 方式的优势是环境隔离、版本可控；注意容器内外的网络地址差异，尤其是 advertised.listeners 的配置。
四、命令行工具：创建、生产、消费与查看
Kafka 自带命令行工具，位于 bin/ 目录。常用工具包括 kafka-topics.sh、kafka-console-producer.sh、kafka-console-consumer.sh 和 kafka-consumer-groups.sh。下表列出核心命令与用途：
| 命令 | 用途 | 关键参数 |
|---|---|---|
| kafka-topics.sh --create | 创建 Topic | --partitions、--replication-factor |
| kafka-topics.sh --describe | 查看分区与副本分布 | --topic |
| kafka-console-producer.sh | 向 Topic 写入消息 | --broker-list、--topic |
| kafka-console-consumer.sh | 从 Topic 读取消息 | --from-beginning、--group |
| kafka-consumer-groups.sh | 查看消费组偏移量 | --describe、--group |
五、第一个生产与消费示例
下面完成一个最小闭环：创建 Topic、启动生产者、启动消费者并验证消息。假设 Broker 地址为 localhost:9092。
# 1. 创建 Topic
bin/kafka-topics.sh --create \
--topic sensor-data \
--partitions 3 \
--replication-factor 1 \
--bootstrap-server localhost:9092
# 2. 启动生产者（另开终端）
bin/kafka-console-producer.sh \
--topic sensor-data \
--bootstrap-server localhost:9092
# 输入消息
{"deviceId":"D001","temp":23.5}
{"deviceId":"D002","temp":24.1}
# 3. 启动消费者（再开终端）
bin/kafka-console-consumer.sh \
--topic sensor-data \
--from-beginning \
--bootstrap-server localhost:9092
消费者应输出刚才写入的两条 JSON 消息。若使用消费组，可加上 --group sensor-group，再用 kafka-consumer-groups.sh --describe 查看每个分区的 CURRENT-OFFSET 与 LAG。LAG 为 0 表示消息已全部消费。
六、常见误区与复盘
- 只启动 Broker 就以为成功：必须验证 Topic 创建、生产、消费全链路，否则可能只是端口通了。
- 忽略 advertised.listeners：Docker 或远程环境中，客户端拿到的地址不可达会导致连接超时。
- 副本因子大于 Broker 数：创建 Topic 会失败，需保证
replication-factor ≤ Broker 数量。 - 消费者看不到历史消息：默认从最新位置开始，需加
--from-beginning或指定 offset。 - 把单机配置直接用于生产：单机副本因子为 1，无高可用，生产环境应使用多 Broker 集群。