Kafka 配置参数详解：ZooKeeper 模式与 KRaft 模式对比
Kafka 配置参数根据底层元数据管理方式的不同，主要分为 ZooKeeper 模式和 KRaft 模式。本文将先分别介绍两种模式的核心架构，再详细对比各模块的配置参数，帮助你快速掌握 Kafka 配置要点。
一、ZooKeeper 模式配置详解
1. 核心架构概述
ZooKeeper 模式是 Kafka 传统架构，依赖 ZooKeeper 集群管理元数据（如 Topic 信息、分区副本分配、broker 存活状态等）。Kafka broker 与 ZooKeeper 保持双向通信：
- broker 启动时向 ZooKeeper 注册自身信息；
- broker 通过 ZooKeeper 监听集群变化（如其他 broker 加入/退出）；
- 控制器（Controller）节点从 ZooKeeper 获取元数据并同步给其他 broker。
2. 必选配置参数
2.1 ZooKeeper 连接配置
| 参数名 |
说明 |
zookeeper.connect |
ZooKeeper 集群连接地址，格式：主机:端口[/路径]，多个地址用逗号分隔。
示例：zk1:2181,zk2:2181,zk3:2181/kafka |
zookeeper.connection.timeout.ms |
连接 ZooKeeper 的超时时间（默认 18000ms），超时则 broker 启动失败。 |
zookeeper.session.timeout.ms |
ZooKeeper 会话超时时间（默认 6000ms），超时后 broker 被标记为下线。 |
2.2 Broker 基础配置
| 参数名 |
说明 |
broker.id |
每个 broker 的唯一整数标识（如 0、1、2），集群内不可重复。 |
listeners |
broker 监听的网络地址和协议，格式：协议://主机:端口。
示例：PLAINTEXT://:9092 |
log.dirs |
消息日志存储路径，建议挂载高性能磁盘，可配置多个路径（用逗号分隔）。 |
3. Topic 与分区配置
| 参数名 |
说明 |
num.partitions |
新建 Topic 的默认分区数，吞吐量敏感场景建议设为 3 或更高。 |
default.replication.factor |
新建 Topic 的默认副本数，生产环境建议设为 3（容忍 1-2 个节点故障）。 |
auto.create.topics.enable |
是否允许自动创建 Topic（默认 true），生产环境建议关闭（设为 false）。 |
4. 消息留存策略
| 参数名 |
说明 |
log.retention.hours |
消息保留时长（默认 168 小时，即 7 天）。 |
log.retention.bytes |
单个分区的最大日志大小（默认 -1，不限制）。 |
log.segment.bytes |
日志分段（segment）的大小（默认 1GB），达到此大小后创建新 segment。 |
5. 性能调优参数
| 参数名 |
说明 |
num.network.threads |
处理网络请求的线程数（默认 3），高并发场景建议增至 8-16。 |
num.io.threads |
处理磁盘 I/O 的线程数（默认 8），SSD 环境可增至 16-32。 |
socket.send.buffer.bytes |
网络发送缓冲区大小（默认 100KB），大消息场景可增至 1MB。 |
6. 安全配置
| 参数名 |
说明 |
security.inter.broker.protocol |
broker 间通信协议（如 PLAINTEXT、SSL、SASL_SSL）。 |
sasl.mechanism.inter.broker.protocol |
broker 间认证机制（如 SCRAM-SHA-256）。 |
ssl.keystore.location |
SSL 密钥库路径（启用 SSL 时必填）。 |
二、KRaft 模式配置详解
1. 核心架构概述
KRaft（Kafka Raft）模式是 Kafka 3.0+ 引入的无 ZooKeeper 架构，通过内置的 Raft 协议自主管理元数据。核心组件包括：
- 控制器（Controller）：负责元数据管理（替代 ZooKeeper 角色），支持多节点组成控制器集群；
- 元数据日志（Metadata Log）：使用 Raft 协议复制和持久化元数据变更；
- Broker：与控制器通信获取元数据，无需依赖外部服务。
2. 必选配置参数
2.1 角色与集群配置
| 参数名 |
说明 |
process.roles |
节点角色，必填参数，取值：
- broker：仅作为消息代理；
- controller：仅作为控制器；
- broker,controller：同时承担两种角色（单节点测试场景）。 |
controller.quorum.voters |
控制器集群的投票成员列表，格式：节点ID@主机:端口。
示例：1@controller1:9093,2@controller2:9093,3@controller3:9093 |
controller.listener.names |
控制器使用的监听器名称（默认 CONTROLLER），需与 listeners 中定义的一致。 |
inter.broker.listener.name |
broker 间通信使用的监听器名称（如 PLAINTEXT）。 |
2.2 节点标识与网络配置
| 参数名 |
说明 |
node.id |
节点的唯一标识（整数），用于控制器集群身份识别，默认与 broker.id 相同。 |
listeners |
需包含控制器监听器，示例：PLAINTEXT://:9092,CONTROLLER://:9093。 |
log.dirs |
消息日志和控制器元数据日志的存储路径（与 ZooKeeper 模式相同）。 |
3. 控制器配置
| 参数名 |
说明 |
controller.quorum.election.timeout.ms |
控制器选举超时时间（默认 2500ms），超时未完成则重新选举。 |
controller.socket.request.max.bytes |
控制器处理的最大请求大小（默认 100MB），需与 broker 消息大小匹配。 |
controller.log.dir |
控制器元数据日志的存储路径（默认与 log.dirs 相同）。 |
4. 与 ZooKeeper 模式通用的配置
KRaft 模式保留了大部分与消息处理相关的参数：
| 参数名 |
说明 |
num.partitions |
新建 Topic 的默认分区数（与 ZooKeeper 模式相同）。 |
default.replication.factor |
新建 Topic 的默认副本数（与 ZooKeeper 模式相同）。 |
log.retention.hours |
消息保留时长（与 ZooKeeper 模式相同）。 |
message.max.bytes |
允许接收的最大消息大小（与 ZooKeeper 模式相同）。 |
acks |
生产者确认机制（与 ZooKeeper 模式相同）。 |
auto.offset.reset |
消费者偏移量重置策略（与 ZooKeeper 模式相同）。 |
5. 性能调优参数
| 参数名 |
说明 |
num.network.threads |
处理网络请求的线程数（与 ZooKeeper 模式相同）。 |
num.io.threads |
处理磁盘 I/O 的线程数（与 ZooKeeper 模式相同）。 |
KAFKA_HEAP_OPTS |
JVM 堆内存配置（建议设为物理内存的 50%，不超过 64GB）。 |
三、两种模式配置对比表
| 配置项 |
ZooKeeper 模式 |
KRaft 模式 |
| 元数据管理 |
依赖 ZooKeeper 集群 |
内置控制器（Controller）集群 |
| 核心配置文件 |
server.properties + ZooKeeper 配置 |
仅需 server.properties |
| 必选参数 |
zookeeper.connect |
process.roles, controller.quorum.voters |
| 节点角色 |
所有 broker 角色相同 |
分为 broker 和 controller 角色 |
| 控制器选举 |
自动从 broker 中选举一个作为控制器 |
由 controller.quorum.voters 指定 |
| 网络监听器 |
仅需配置 broker 监听器 |
需额外配置 CONTROLLER 监听器 |
| 迁移方式 |
不支持直接迁移至 KRaft |
需通过 kafka-metadata-shell.sh 工具迁移 |
四、选择建议与最佳实践
1. 模式选择
| 场景 |
推荐模式 |
理由 |
| 新集群部署 |
KRaft 模式 |
架构更简单，减少外部依赖 |
| 现有 ZooKeeper 集群 |
逐步迁移至 KRaft |
降低运维复杂度，提升元数据处理性能 |
| 小规模测试 |
KRaft 模式 |
单节点即可运行，无需部署 ZooKeeper |
2. KRaft 模式最佳实践
- 控制器节点数量：建议部署 3-5 个控制器节点（奇数个），保证高可用和容错性；
- 资源隔离：生产环境建议将控制器节点与 broker 节点分离部署，避免资源竞争；
- 网络优化：控制器间通信对延迟敏感，建议使用专用网络或高带宽链路；
- 监控重点：关注控制器选举耗时、元数据复制延迟等指标。
3. 通用配置建议
- 禁用自动创建 Topic：生产环境设置
auto.create.topics.enable=false，避免意外创建；
- 合理设置副本数：通常
default.replication.factor=3，兼顾可用性和磁盘成本；
- 消息压缩：启用
compression.type=lz4 或 zstd，减少网络和存储开销；
- JVM 调优：设置
KAFKA_HEAP_OPTS="-Xmx8G -Xms8G"（根据实际内存调整），并启用 G1 垃圾回收器。