Kafka 配置参数详解：ZooKeeper 模式与 KRaft 模式对比

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 垃圾回收器。