10.2.4 核心配置参数与示例

核心配置参数与示例#

本节聚焦 Kafka Broker 核心配置参数，包含原理草图、完整示例、安装落地、排错与练习，便于在生产环境快速验证与优化。

0. 原理草图（Broker 配置影响面）#

文章图片

1. Broker 基础参数（含示例）#

  • broker.id：节点唯一标识，集群内必须唯一
  • listeners：服务端监听地址与端口
  • advertised.listeners：对外公布地址，客户端必须可达
  • log.dirs：消息存储目录，建议多盘分散
  • num.network.threads/num.io.threads：网络与 I/O 线程
  • socket.send.buffer.bytes/socket.receive.buffer.bytes：网络缓冲
  • message.max.bytes：Broker 端单条消息最大值

2. 主题与分区默认参数#

  • num.partitions：新建主题默认分区数
  • default.replication.factor：默认副本数
  • min.insync.replicas：最小 ISR 副本数
  • unclean.leader.election.enable：是否允许非 ISR 选主

3. 日志与保留策略#

  • log.retention.hours：按时间保留（小时）
  • log.retention.bytes：按大小保留（字节）
  • log.segment.bytes：单个段文件大小
  • log.retention.check.interval.ms：保留策略检查周期

4. 副本与同步相关#

  • replica.fetch.max.bytes：副本拉取最大字节数
  • replica.lag.time.max.ms：副本允许最大滞后
  • replica.fetch.wait.max.ms：副本拉取等待时间
  • leader.imbalance.check.interval.seconds：领导者不均衡检查周期

5. KRaft/ZooKeeper 连接参数（按模式选择）#

  • ZooKeeper 模式：zookeeper.connect、zookeeper.connection.timeout.ms
  • KRaft 模式：process.roles、node.id、controller.quorum.voters

6. 安装与目录规划（最小可运行）#

# 1) 解压并规划目录
tar -xf kafka_2.13-3.6.1.tgz -C /opt/
ln -s /opt/kafka_2.13-3.6.1 /opt/kafka
mkdir -p /data/kafka-logs

# 2) 核心配置文件路径
ls /opt/kafka/config/
# server.properties 是 Broker 核心配置文件

7. 完整示例配置（server.properties）#

# /opt/kafka/config/server.properties
broker.id=1
listeners=PLAINTEXT://0.0.0.0:9092
advertised.listeners=PLAINTEXT://10.0.0.11:9092
log.dirs=/data/kafka-logs

num.network.threads=3
num.io.threads=8
socket.send.buffer.bytes=102400
socket.receive.buffer.bytes=102400
message.max.bytes=10485760

num.partitions=6
default.replication.factor=3
min.insync.replicas=2
unclean.leader.election.enable=false

log.retention.hours=168
log.retention.bytes=-1
log.segment.bytes=1073741824
log.retention.check.interval.ms=300000

# ZooKeeper 模式示例（启用其一）
zookeeper.connect=10.0.0.11:2181,10.0.0.12:2181,10.0.0.13:2181
zookeeper.connection.timeout.ms=18000

# KRaft 模式示例（启用其一）
#process.roles=broker,controller
#node.id=1
#controller.quorum.voters=1@10.0.0.11:9093,2@10.0.0.12:9093,3@10.0.0.13:9093

8. 启动与验证（命令+解释）#

# 启动（ZooKeeper 模式）
/opt/kafka/bin/kafka-server-start.sh -daemon /opt/kafka/config/server.properties

# 查看端口监听（验证 listeners）
ss -lntp | grep 9092

# 查看 Broker 是否注册（ZooKeeper 模式）
/opt/kafka/bin/zookeeper-shell.sh 10.0.0.11:2181 ls /brokers/ids

# 查看主题默认参数是否生效
/opt/kafka/bin/kafka-topics.sh --bootstrap-server 10.0.0.11:9092 \
  --create --topic demo-topic
/opt/kafka/bin/kafka-topics.sh --bootstrap-server 10.0.0.11:9092 \
  --describe --topic demo-topic

9. 关键参数调整示例（对比修改）#

# 高可靠性（最少 ISR=2，禁止非 ISR 选主）
min.insync.replicas=2
unclean.leader.election.enable=false

# 高吞吐（增加 I/O 线程与网络缓冲）
num.io.threads=16
socket.send.buffer.bytes=262144
socket.receive.buffer.bytes=262144

# 磁盘压力控制（同时按时间/大小保留）
log.retention.hours=72
log.retention.bytes=53687091200

10. 排错清单（现象-原因-处理）#

  • 客户端连不上 Broker
    现象：Connection refused / 超时
    排查：advertised.listeners 配置不可达
    处理：
    bash # 验证可达性 nc -vz 10.0.0.11 9092 # 若不可达，修正 advertised.listeners 并重启

  • 分区无法选主 / ISR 过小
    现象：NotEnoughReplicas
    排查：min.insync.replicas 过高或副本落后
    处理：
    bash /opt/kafka/bin/kafka-topics.sh --bootstrap-server 10.0.0.11:9092 \ --describe --topic demo-topic # 根据实际副本数降低 min.insync.replicas 或扩容副本

  • 磁盘爆满
    现象：数据目录快速增长
    排查：log.retention.bytes 未设置、log.retention.hours 过大
    处理：
    bash du -sh /data/kafka-logs/* # 设置 log.retention.bytes 与 log.retention.hours 后重启

11. 练习（可执行）#

1) 修改 message.max.bytes 为 2MB，验证大消息生产是否被拒绝。
2) 将 num.partitions 改为 3，新建主题并观察默认分区数变化。
3) 调整 log.retention.hours=1，写入数据后等待过期，验证段文件是否被清理。 

# 练习1：发送 3MB 消息验证拒绝
python3 - <<'PY'
msg = "A" * (3*1024*1024)
print(msg)
PY | /opt/kafka/bin/kafka-console-producer.sh --bootstrap-server 10.0.0.11:9092 --topic demo-topic

# 练习2：创建主题并查看分区数
/opt/kafka/bin/kafka-topics.sh --bootstrap-server 10.0.0.11:9092 \
  --create --topic demo-topic-2
/opt/kafka/bin/kafka-topics.sh --bootstrap-server 10.0.0.11:9092 \
  --describe --topic demo-topic-2

# 练习3：写入消息并观察日志段清理
/opt/kafka/bin/kafka-console-producer.sh --bootstrap-server 10.0.0.11:9092 --topic demo-topic <<EOF
msg1
msg2
EOF
ls -lh /data/kafka-logs | head