【Kafka源码解读和使用指南】第07篇：Kafka的配置圣经——broker配置参数全解析

上一篇：【第06篇】Kafka集群搭建实战——三节点集群从零到一 下一篇：【第08篇】Kafka硬件选型指南——磁盘、内存、网络怎么配才不踩坑

摘要

server.properties里有上百个参数，哪些是必须改的？哪些保持默认就好？本文把Kafka broker的核心配置参数按功能分为六大类——节点身份、网络通信、存储引擎、数据保留、Topic默认值、线程与性能——逐类逐一讲解。每个参数都给出含义、默认值、推荐值和踩坑提醒。不管你是在搭开发环境还是准备上线，这份配置速查手册都能帮你少走弯路。读完这篇，你不会再对着server.properties一脸茫然。

一、配置全景图

【Kafka Broker 配置分类】

┌────────────────────────────────────────────────────┐
│ server.properties │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ ① 节点身份 │ │ ② 网络与通信 │ │
│ │ node.id │ │ listeners │ │
│ │ process.roles │ │ advertised.* │ │
│ │ controller.* │ │ socket/buffer │ │
│ └──────────────────┘ └──────────────────┘ │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ ③ 存储引擎 │ │ ④ 数据保留 │ │
│ │ log.dirs │ │ log.retention.* │ │
│ │ log.segment.* │ │ log.cleanup.* │ │
│ │ log.flush.* │ │ log.cleaner.* │ │
│ └──────────────────┘ └──────────────────┘ │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ ⑤ Topic默认值 │ │ ⑥ 线程与性能 │ │
│ │ num.partitions │ │ num.network.* │ │
│ │ default.replica* │ │ num.io.threads │ │
│ │ offsets.topic.* │ │ num.replica.* │ │
│ └──────────────────┘ └──────────────────┘ │
│ │
└────────────────────────────────────────────────────┘

二、节点身份配置

node.id

node.id=1 # 默认0，但生产环境请显式设置

• 含义：Broker在集群中的唯一标识
• 规则：集群内每个Broker的node.id必须唯一，可以是任意整数
• 推荐：用与主机名相关的数字，如host1 → 1, host2 → 2

process.roles（KRaft模式专有）

process.roles=broker,controller

• 含义：节点角色，broker=数据面，controller=元数据管理面
• 可选值：broker、controller、broker,controller（合体模式）
• 推荐：小集群（≤3节点）全部用broker,controller；大集群可以把controller单独拆出来

controller.quorum.voters（KRaft模式专有）

controller.quorum.voters=1@host1:9093,2@host2:9093,3@host3:9093

• 含义：参与Raft法定人数的投票者列表
• 格式：node.id@host:port，逗号分隔
• 规则：所有节点的此配置必须完全一致

三、网络与通信配置

listeners 与 advertised.listeners

# 内部监听
listeners=PLAINTEXT://0.0.0.0:9092,CONTROLLER://0.0.0.0:9093

# 对外广播（告诉客户端和别的Broker怎么连过来）
advertised.listeners=PLAINTEXT://公网IP:9092

这两个参数的区别：

• listeners：Broker实际绑定的地址
• advertised.listeners：Broker告诉客户端"用这个地址来连我"

如果你在云上（AWS/阿里云），机器有内网IP和外网IP：

listeners=PLAINTEXT://内网IP:9092
advertised.listeners=PLAINTEXT://外网IP:9092

Socket缓冲区

socket.send.buffer.bytes=102400 # 100KB，默认值一般够用
socket.receive.buffer.bytes=102400 # 100KB

调优方向：高吞吐场景可调到1MB（1048576），但要确保OS参数支持。

最大请求大小

socket.request.max.bytes=104857600 # 100MB，默认值

注意：如果Producer的max.request.size大于这个值，Broker会直接拒绝请求。

连接数限制

max.connections.per.ip=2147483647 # 默认值，几乎无限制
max.connections=2147483647 # 总连接数限制

推荐：生产环境建议设个合理上限，防止某个客户端恶意占满连接。

四、存储引擎配置

log.dirs

log.dirs=/data/kafka-logs # 绝对路径，可以配多个逗号分隔

推荐：

• 多块物理磁盘的话，每块配一个目录，Kafka会自动分散负载
• 千万不要用NAS/NFS做log.dirs，延迟和可靠性都不行
• 开发环境用SSD，生产环境用SSD或SAS HDD的RAID

log.segment.bytes

log.segment.bytes=1073741824 # 默认1GB

• 每个分区日志被分成多个segment文件，此参数控制每个segment的大小
• 影响：
  • 值越小 → segment越频繁关闭 → 更多文件 → 文件句柄开销大
  • 值越大 → 数据保留策略执行越慢
• 推荐：高吞吐场景保持默认1GB即可；低流量Topic可以调小到128MB

log.segment.ms

log.segment.ms=604800000 # 7天后强制关闭segment，默认不设置

• 即使segment没达到log.segment.bytes大小，到时间也关闭

log.flush.interval.messages 与 log.flush.interval.ms

# 建议不要设置！依赖操作系统页缓存管理
log.flush.interval.messages=9223372036854775807 # 默认永不触发
log.flush.interval.ms=9223372036854775807 # 默认永不触发

重要警告：这两参数默认值是"从不主动flush"，由Linux的脏页机制管理。不要随意设置小值——会造成大量fsync，性能断崖式下跌！

五、数据保留配置

log.retention.ms（时间保留）

log.retention.ms=604800000 # 7天，默认值
log.retention.hours=168 # 也是7天（已废弃，但还能用）
log.retention.minutes=10080 # 也是7天（已废弃）

优先级：ms > minutes > hours（取最小值生效）

推荐：

• 日志类数据：3-7天
• 业务事件：14-30天
• 审计数据：按合规要求

log.retention.bytes（大小保留）

log.retention.bytes=-1 # 默认无限制

注意：这个值作用在每个分区上，不是整个Topic！如果Topic有10个分区，设1GB，实际最多保留10GB。

时间和大小同时设置

log.retention.ms=86400000 # 1天
log.retention.bytes=1073741824 # 1GB
# 效果：时间或大小任意一个条件满足就删除

log.cleanup.policy（清理策略）

log.cleanup.policy=delete # 默认：删除过期数据
# 可选：compact（保留每个key的最新值）

• delete：普通的TTL模式，过期就删
• compact：保留每个key的最新的那条消息，旧版本被压缩掉（用于__consumer_offsets等场景）

六、Topic默认配置

num.partitions

num.partitions=3 # 默认1，建议改

这是最容易被遗忘但影响最大的配置之一。

• 开发环境：3个分区够用
• 生产环境：按吞吐量估算
  • 如果你需要每秒消费100MB，单个Consumer每秒能处理50MB，那至少2个分区
  • 总原则：分区数 >= 目标吞吐量 / 单Consumer处理能力

default.replication.factor

default.replication.factor=3 # 默认1，生产环境建议3

• 生产环境最少3个副本（P0是Leader，P1和P2是Follower）
• 永远不要让这个值超过Broker数量

offsets.topic.replication.factor

offsets.topic.replication.factor=3 # 默认3（Kafka 3.3+)，建议确认

• __consumer_offsets 这个内部Topic的副本数
• 如果这个Topic丢数据，所有消费者组的offset都丢了

auto.create.topics.enable

auto.create.topics.enable=false # 生产环境建议设为false

• 生产环境建议关闭自动创建Topic
• 理由：自动创建的Topic使用默认参数（可能分区数、副本数都不对）
• 改为手动创建Topic，参数一目了然

七、线程与性能配置

num.network.threads

num.network.threads=3 # 默认值，处理网络请求的线程数

推荐：

• 常规场景：保持默认3
• 高吞吐场景（>100MB/s）：调到6-9
• 公式参考：num.network.threads = CPU核心数

num.io.threads

num.io.threads=8 # 默认值，处理磁盘I/O的线程数

推荐：

• 常规场景：保持默认8
• 高吞吐+SSD：12-16
• 公式参考：num.io.threads = 2 × CPU核心数

num.replica.fetchers

num.replica.fetchers=1 # 默认值，Follower拉取Leader数据的线程数

推荐：高吞吐副本同步建议调到2-4。但注意：num.replica.fetchers必须小于num.io.threads % num.network.threads

num.recovery.threads.per.data.dir

num.recovery.threads.per.data.dir=1 # 每个数据目录的恢复线程数

推荐：分区数多（>1000）时调到4-8。启动和崩溃恢复时能省很多时间。

【线程分配一览】
Acceptor(1) ← 接收新连接
│
┌────────┼────────┐
▼ ▼ ▼
Processor Processor Processor ← num.network.threads
│ │ │
└────────┼────────┘
▼
RequestQueue
│
┌────────┼────────┐
▼ ▼ ▼
Handler Handler Handler … ← num.io.threads
│ │ │
└────────┼────────┘
▼
磁盘读写/日志操作

八、生产环境推荐配置速查

# ====== 节点身份 ======
node.id=1
process.roles=broker,controller
controller.quorum.voters=1@kafka1:9093,2@kafka2:9093,3@kafka3:9093
controller.listener.names=CONTROLLER

# ====== 网络 ======
listeners=PLAINTEXT://0.0.0.0:9092,CONTROLLER://0.0.0.0:9093
advertised.listeners=PLAINTEXT://kafka1.yourdomain.com:9092

# ====== 存储 ======
log.dirs=/data1/kafka-logs,/data2/kafka-logs
log.segment.bytes=1073741824
log.retention.ms=604800000
log.cleanup.policy=delete

# ====== Topic默认值 ======
num.partitions=6
default.replication.factor=3
offsets.topic.replication.factor=3
auto.create.topics.enable=false

# ====== 性能 ======
num.network.threads=6
num.io.threads=12
num.replica.fetchers=2
num.recovery.threads.per.data.dir=4

# ====== 最大消息大小 ======
message.max.bytes=10485760 # 10MB（默认1MB，根据需要调大）
replica.fetch.max.bytes=10485760 # 与上面保持一致

# ====== 压缩 ======
compression.type=producer # 保留Producer的压缩（推荐）

九、配置变更须知

哪些配置改了要重启?哪些可以动态变更?

动态变更示例：

# 动态修改某个Topic的保留时间
kafka-configs.sh –bootstrap-server localhost:9092 \\
–alter –entity-type topics –entity-name my-topic \\
–add-config retention.ms=259200000

本篇小结

Kafka broker配置六大类：

• 节点身份：node.id、process.roles、controller.quorum.voters是KRaft模式的基石
• 网络通信：listeners vs advertised.listeners的区分是云环境配置的头号坑
• 存储引擎：log.dirs多目录可以分散IO，log.segment.bytes控制文件粒度
• 数据保留：log.retention.ms和log.retention.bytes可以同时用，任一满足就清理
• Topic默认值：num.partitions和default.replication.factor是决定数据分布的全局开关
• 线程调优：num.network.threads和num.io.threads按CPU核心数调整

配置讲究"够用不浪费"。下一篇我们继续深入，讲怎么根据业务量选硬件——磁盘、内存、网络到底怎么配。

上一篇：【第06篇】Kafka集群搭建实战——三节点集群从零到一 下一篇：【第08篇】Kafka硬件选型指南——磁盘、内存、网络怎么配才不踩坑