目录
- Kafka 配置参数详解：ZooKeeper 模式与 KRaft 模式对比
- 一、ZooKeeper 模式配置详解
- 1. 核心架构概述
- 2. 必选配置参数
- 2.1 ZooKeeper 连接配置
- 2.2 Broker 基础配置
- 3. Topic 与分区配置
- 4. 消息留存策略
- 5. 性能调优参数
- 6. 安全配置
- 二、KRaft 模式配置详解
- 1. 核心架构概述
- 2. 必选配置参数
- 3. 控制器配置
- 4. 与 ZooKeeper 模式通用的配置
- 5. 性能调优参数
- 三、两种模式配置对比表
- 四、选择建议与最佳实践
- 1. 模式选择
- 2. KRaft 模式最佳实践
- 3. 通用配置建议
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 垃圾回收器。
