3. Kafka 安装与配置：单机部署、ZooKeeper 依赖、关键配置文件详解

本章聚焦 Kafka 单机环境的搭建全流程。作为消息队列契约体系的基础设施层，Kafka 的安装配置直接决定了后续生产消费行为的稳定性。本节将依次讲解 ZooKeeper 依赖关系、单机部署步骤、核心配置项含义，并通过结构图与表格帮助你建立清晰的配置认知。

3.1 ZooKeeper 依赖与角色

Kafka 从诞生之初就依赖 ZooKeeper 完成集群元数据管理、Broker 注册、Leader 选举和消费者组协调。在单机部署中，ZooKeeper 同样必须先行启动。

依赖角色 说明 单机是否必需
Broker 注册 每个 Kafka Broker 启动时在 ZooKeeper 创建临时节点 是
Topic 元数据 Topic 分区信息、副本分配存储在 ZooKeeper 是
Controller 选举 集群中首个 Broker 成为 Controller，负责分区 Leader 选举 是（单机自动当选）
消费者组偏移量 旧版消费者偏移量存储在 ZooKeeper；新版已移至 Kafka 内部 Topic 部分依赖
版本提示：Kafka 2.8+ 开始提供基于 KRaft 的 ZooKeeper-free 模式，但生产环境主流仍使用 ZooKeeper 架构。本课程以 ZooKeeper 模式为准。

3.2 单机部署步骤

以下步骤基于 Kafka 3.5.x 版本，操作系统为 Linux（CentOS 7 / Ubuntu 22.04 均适用）。

  1. 下载与解压 
    wget https://downloads.apache.org/kafka/3.5.1/kafka_2.13-3.5.1.tgz
tar -xzf kafka_2.13-3.5.1.tgz
cd kafka_2.13-3.5.1
  2. 启动 ZooKeeper 
    bin/zookeeper-server-start.sh config/zookeeper.properties &

    默认监听 2181 端口。可通过 netstat -tlnp | grep 2181 验证。

  3. 修改 Kafka 关键配置（见 3.3 节）
  4. 启动 Kafka Broker 
    bin/kafka-server-start.sh config/server.properties &

    查看日志 logs/server.log 确认启动成功，出现 started (kafka.server.KafkaServer) 即完成。

  5. 验证部署 
    # 创建测试 Topic
bin/kafka-topics.sh --create --topic test-topic --bootstrap-server localhost:9092 --partitions 1 --replication-factor 1

# 列出 Topic
bin/kafka-topics.sh --list --bootstrap-server localhost:9092
常见错误：如果 Broker 启动时报 Connection to node -1 could not be established，请检查 advertised.listeners 是否配置正确，以及 ZooKeeper 是否已启动。

3.3 关键配置文件详解

Kafka 的核心配置集中在 config/server.properties。以下按功能模块拆解最关键的参数。

3.3.1 基础 Broker 配置

参数名 默认值 说明 单机推荐值
broker.id 0 集群内唯一标识，单机保持 0 0
listeners PLAINTEXT://:9092 Broker 监听地址和协议 PLAINTEXT://0.0.0.0:9092
advertised.listeners null 对外发布的地址，客户端连接使用 PLAINTEXT://localhost:9092
log.dirs /tmp/kafka-logs 消息日志存储路径 /data/kafka/logs
num.partitions 1 Topic 默认分区数 3（开发环境）

3.3.2 ZooKeeper 连接配置

参数名 默认值 说明 单机推荐值
zookeeper.connect localhost:2181 ZooKeeper 连接地址，多个用逗号分隔 localhost:2181
zookeeper.connection.timeout.ms 18000 连接 ZooKeeper 超时时间 18000
zookeeper.session.timeout.ms 18000 Session 超时，Broker 心跳间隔 18000

3.3.3 日志与保留策略

参数名 默认值 说明 单机推荐值
log.retention.hours 168 消息保留时间（小时） 72
log.retention.bytes -1 分区日志最大字节数，-1 表示不限 1073741824（1GB）
log.segment.bytes 1073741824 单个日志段文件大小 536870912（512MB）
log.cleanup.policy delete 日志清理策略：delete 或 compact delete

3.4 单机部署架构图

下图展示了单机环境下 Kafka Broker 与 ZooKeeper 的进程关系，以及客户端（Producer / Consumer）的连接路径。

Kafka 单机部署架构图 ZooKeeper 端口 2181 Kafka Broker 端口 9092 注册 / 选举 Producer Consumer 发送消息 拉取消息 说明：单机部署中 ZooKeeper 和 Kafka Broker 运行在同一台机器，Producer 和 Consumer 通过 localhost:9092 连接 Broker。

3.5 配置验证与常用命令

完成配置后，建议执行以下命令验证关键参数是否生效。

验证目标 命令 预期输出
ZooKeeper 状态 echo ruok | nc localhost 2181 imok
Broker 列表 bin/zookeeper-shell.sh localhost:2181 ls /brokers/ids [0]
Topic 列表 bin/kafka-topics.sh --list --bootstrap-server localhost:9092 已创建的 Topic 名称
日志目录 ls /data/kafka/logs 包含 __consumer_offsets-0 等目录
生产建议：单机部署仅用于开发测试。生产环境至少 3 台 Broker + 3 台 ZooKeeper 组成集群，并配置副本因子 ≥ 2。

3.6 单机配置与集群配置对比

下表列出单机与集群在关键配置上的差异，帮助你理解后续章节的集群扩展。

配置项 单机值 集群典型值 差异原因
broker.id 0 0, 1, 2 … 集群需要唯一标识
zookeeper.connect localhost:2181 zk1:2181,zk2:2181,zk3:2181 集群 ZooKeeper 多节点
offsets.topic.replication.factor 1 3 保证偏移量 Topic 高可用
transaction.state.log.replication.factor 1 3 事务状态 Topic 高可用

3.7 配置文件片段示例

以下是一个完整的单机 server.properties 核心配置示例，可直接用于开发环境。

# Broker 标识
broker.id=0

# 监听地址
listeners=PLAINTEXT://0.0.0.0:9092
advertised.listeners=PLAINTEXT://localhost:9092

# 日志存储
log.dirs=/data/kafka/logs

# ZooKeeper 连接
zookeeper.connect=localhost:2181
zookeeper.connection.timeout.ms=18000

# Topic 默认分区
num.partitions=3

# 日志保留策略
log.retention.hours=72
log.retention.bytes=1073741824
log.segment.bytes=536870912
log.cleanup.policy=delete

# 网络线程
num.network.threads=3
num.io.threads=8

# 副本配置（单机无实际副本）
offsets.topic.replication.factor=1
transaction.state.log.replication.factor=1
transaction.state.log.min.isr=1
路径建议：生产环境不要使用 /tmp/kafka-logs，应挂载独立数据盘，并配置合理的日志保留策略，避免磁盘写满。

3.8 本章小结

单机部署是理解 Kafka 架构的起点。通过本节学习，你应掌握：

  • ZooKeeper 在 Kafka 中的核心依赖角色
  • 从下载到验证的完整部署流程
  • Broker、ZooKeeper、日志保留三大类关键配置
  • 单机与集群配置的核心差异
← 上一章 📖 返回目录 下一章 →