Skip to content

Kafka 集群部署与扩展

一、集群部署概述

1.1 集群角色演进

Kafka 集群从早期依赖外部 ZooKeeper 协调,演进到自带的 KRaft (Kafka Raft) 共识协议,运维模式发生根本变化。

模式 协调组件 元数据存储 是否推荐生产 备注
ZK 模式 外部 ZooKeeper 集群 ZK znodes 不推荐 老版本遗留,Kafka 4.x 将完全移除
KRaft 模式 内置 Controller 节点 内部 __cluster_metadata topic 强烈推荐 3.3+ 生产就绪,3.5+ GA
混合模式 二选一 二选一 过渡期 仅供 ZK → KRaft 迁移时使用

1.2 节点角色

KRaft 模式下,每个 Kafka 进程可承担三种角色(由 process.roles 决定):

┌─────────────────────────────────────────────────────────────────┐
│                     Kafka 集群节点角色                           │
├────────────────┬────────────────────────────────────────────────┤
│  Broker        │ 负责处理 Producer/Consumer 请求、存储 Partition │
│                │ 默认每个 Topic Partition 有一个 Leader,         │
│                │ 其余 Follower 同步复制                          │
├────────────────┼────────────────────────────────────────────────┤
│  Controller    │ 通过 Raft 共识管理集群元数据                    │
│                │ (Topic 配置、Partition Leader、ISR 列表等)     │
│                │ 通常奇数个 (3/5/7),过半存活即能工作             │
├────────────────┼────────────────────────────────────────────────┤
│  Combined      │ 同时充当 Broker + Controller                   │
│                │ 资源紧张的小集群常用,简化部署                   │
└────────────────┴────────────────────────────────────────────────┘

1.3 部署模式选型

集群规模 推荐部署 节点数 适用场景
开发测试 单节点 Combined 1 本地验证、功能测试
小型生产 3 节点 Combined (broker+controller 同机) 3 起步阶段、QPS < 5 万
中型生产 3 controller + 3 broker 分离 6 主流生产、QPS < 50 万
大型生产 5 controller + N broker 分离 5+N 核心链路、海量吞吐
超大规模 多 AZ 跨机房 + MirrorMaker 2 数十 异地多活、灾备

二、单节点部署(开发测试)

2.1 KRaft 单节点

开发环境最常用,一个进程同时承担 broker 和 controller 角色。

目录与配置

# 假设 Kafka 已解压到 /opt/kafka
cd /opt/kafka

# 使用内置单节点配置
cp config/kraft/server.properties config/kraft/server.properties.bak

# 关键配置(其他保持默认即可)
cat > config/kraft/server.properties << 'EOF'
process.roles=broker,controller
node.id=1
controller.quorum.voters=1@localhost:9093
listeners=PLAINTEXT://:9092,CONTROLLER://:9093
inter.broker.listener.name=PLAINTEXT
advertised.listeners=PLAINTEXT://localhost:9092
controller.listener.names=CONTROLLER
listener.security.protocol.map=CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT
log.dirs=/var/lib/kafka-data
num.partitions=1
offsets.topic.replication.factor=1
transaction.state.log.replication.factor=1
transaction.state.log.min.isr=1
group.initial.rebalance.delay.ms=0
auto.create.topics.enable=true
EOF

格式化存储目录

# 必须先生成 cluster.id,format 会写入 meta.properties
bin/kafka-storage.sh format -t $(bin/kafka-storage.sh random-uuid) \
  -c config/kraft/server.properties
# 输出: Formatting ... Formatting completed.

启动

bin/kafka-server-start.sh -daemon config/kraft/server.properties

# 验证
jps | grep Kafka
bin/kafka-broker-api-versions.sh --bootstrap-server localhost:9092 | head
bin/kafka-topics.sh --bootstrap-server localhost:9092 --create \
  --topic test --partitions 3 --replication-factor 1
bin/kafka-topics.sh --bootstrap-server localhost:9092 --list

单节点必须将 offsets.topic.replication.factor=1,否则 __consumer_offsets 创建失败,消费者无法工作。


三、生产集群部署架构

3.1 3 节点 Combined 集群(小型生产)

三个节点,每个节点同时承担 broker 和 controller,部署简单、节省机器。

┌────────────────────────────────────────────────────────────┐
│                 3 节点 Combined 集群                       │
├─────────────┬─────────────┬──────────────────────────────┤
│  kafka-01   │  kafka-02   │  kafka-03                    │
│ broker+ctrl │ broker+ctrl │ broker+ctrl                  │
│ 9092/9093   │ 9092/9093   │ 9092/9093                    │
├─────────────┴─────────────┴──────────────────────────────┤
│  process.roles=broker,controller                          │
│  controller.quorum.voters=1@kafka-01:9093,                │
│                     2@kafka-02:9093,3@kafka-03:9093       │
│  listeners=PLAINTEXT://:9092,CONTROLLER://:9093          │
│  advertised.listeners=PLAINTEXT://<host-ip>:9092          │
└────────────────────────────────────────────────────────────┘

3.2 节点分离部署(中型生产)

Controller 节点只跑元数据,不接收生产/消费请求;Broker 节点专注数据 IO。

┌───────────────────────────┐    ┌──────────────────────────┐
│ Controller 集群 (3节点)   │    │ Broker 集群 (N节点)      │
├───────────────────────────┤    ├──────────────────────────┤
│ kafka-ctrl-01 (9093)      │    │ kafka-brk-01 (9092)     │
│ kafka-ctrl-02 (9093)      │◄──►│ kafka-brk-02 (9092)     │
│ kafka-ctrl-03 (9093)      │Raft│ kafka-brk-03 (9092)     │
│                           │    │ kafka-brk-04 (9092)     │
│ 配置:轻量(2C4G 即可)    │    │ 配置:重 IO(8C32G+)      │
└───────────────────────────┘    └──────────────────────────┘

优势:Controller 故障不影响数据平面 IO 性能;Broker 扩容不影响元数据平面。

配置示例(broker 节点):

process.roles=broker
node.id=101
controller.quorum.voters=1@ctrl-01:9093,2@ctrl-02:9093,3@ctrl-03:9093
listeners=PLAINTEXT://:9092
advertised.listeners=PLAINTEXT://brk-01:9092
controller.listener.names=CONTROLLER
log.dirs=/data1/kafka,/data2/kafka

配置示例(controller 节点):

process.roles=controller
node.id=1
controller.quorum.voters=1@ctrl-01:9093,2@ctrl-02:9093,3@ctrl-03:9093
listeners=CONTROLLER://:9093
log.dirs=/var/lib/kafka-data

3.3 节点规格建议

节点类型 CPU 内存 磁盘 网络
Broker (常规) 8~16 核 32~64 GB 多块 SSD/NVMe(单盘 2T+) 万兆
Broker (日志) 16~32 核 64~128 GB 10+ 块 HDD JBOD 万兆+
Controller 2~4 核 4~8 GB 普通 SSD 100GB 即可 千兆即可
操作系统调优 vm.swappiness=1、ulimit -n 65536 JVM Xms=Xmx=12G XFS 文件系统 关闭 IRQ 亲和

四、KRaft 集群详细部署

4.1 节点规划

以 3 broker + 3 controller 分离部署为例:

主机名 IP 角色 node.id 监听端口
kafka-ctrl-01 10.0.1.11 controller 1 9093
kafka-ctrl-02 10.0.1.12 controller 2 9093
kafka-ctrl-03 10.0.1.13 controller 3 9093
kafka-brk-01 10.0.2.21 broker 101 9092
kafka-brk-02 10.0.2.22 broker 102 9092
kafka-brk-03 10.0.2.23 broker 103 9092

4.2 操作系统调优

所有节点执行:

# 文件描述符
cat >> /etc/security/limits.conf << 'EOF'
*  soft  nofile  65536
*  hard  nofile  65536
EOF

# 虚拟内存 & 网络
cat >> /etc/sysctl.conf << 'EOF'
vm.swappiness=1
vm.dirty_background_ratio=5
vm.dirty_ratio=60
net.core.somaxconn=1024
net.ipv4.tcp_max_syn_backlog=1024
EOF
sysctl -p

# 关闭大页透明(对吞吐有影响)
echo never > /sys/kernel/mm/transparent_hugepage/enabled

# XFS 挂载选项:noatime,nodiratime
mount -o remount,noatime,nodiratime /data1

4.3 安装 Kafka

所有节点执行(版本以 3.6.1 为例):

useradd -r -s /sbin/nologin kafka
mkdir -p /opt/kafka /data1/kafka /data2/kafka /var/log/kafka
chown -R kafka:kafka /opt/kafka /data1/kafka /data2/kafka /var/log/kafka

cd /opt
wget https://archive.apache.org/dist/kafka/3.6.1/kafka_2.13-3.6.1.tgz
tar xzf kafka_2.13-3.6.1.tgz
mv kafka_2.13-3.6.1 /opt/kafka
chown -R kafka:kafka /opt/kafka

# JVM 调优
cat > /opt/kafka/bin/kafka-server-start.sh.local << 'EOF'
export KAFKA_HEAP_OPTS="-Xms12G -Xmx12G -XX:+UseG1GC -XX:MaxGCPauseMillis=20 \
  -XX:+UnlockExperimentalVMOptions -XX:G1NewSizePercent=30 \
  -XX:G1MaxNewSizePercent=40 -XX:G1HeapRegionSize=32M"
EOF

4.4 Controller 配置

config/kraft/controller.properties(三台 controller 共用,仅 node.id 不同):

# ============ 进程与角色 ============
process.roles=controller
node.id=1                           # ctrl-02 改为 2,ctrl-03 改为 3
controller.quorum.voters=1@ctrl-01:9093,2@ctrl-02:9093,3@ctrl-03:9093

# ============ 网络 ============
listeners=CONTROLLER://:9093
inter.controller.listener.name=CONTROLLER
controller.listener.names=CONTROLLER
listener.security.protocol.map=CONTROLLER:PLAINTEXT

# ============ 日志 ============
log.dirs=/data1/kafka-controller
num.partitions=1
log.retention.hours=168

# ============ 元数据 topic 副本数 ============
metadata.log.dir=/data1/kafka-controller

4.5 Broker 配置

config/kraft/broker.properties:

# ============ 进程与角色 ============
process.roles=broker
node.id=101                         # brk-02 改为 102,brk-03 改为 103
controller.quorum.voters=1@ctrl-01:9093,2@ctrl-02:9093,3@ctrl-03:9093

# ============ 网络 ============
listeners=PLAINTEXT://:9092
advertised.listeners=PLAINTEXT://brk-01:9092
inter.broker.listener.name=PLAINTEXT
listener.security.protocol.map=PLAINTEXT:PLAINTEXT

# ============ 日志 ============
log.dirs=/data1/kafka,/data2/kafka
num.network.threads=8
num.io.threads=16
log.retention.hours=168
log.segment.bytes=1073741824         # 1GB segment
log.retention.check.interval.ms=300000

# ============ Topic 默认参数 ============
num.partitions=3
default.replication.factor=3
min.insync.replicas=2
offsets.topic.replication.factor=3
transaction.state.log.replication.factor=3
transaction.state.log.min.isr=2
group.initial.rebalance.delay.ms=3000

# ============ 性能调优 ============
compression.type=producer
group.min.session.timeout.ms=6000
group.max.session.timeout.ms=1800000
log.cleanup.policy=delete
log.cleaner.delete.retention.ms=604800000

4.6 集群初始化

第一步:格式化 controller 节点(三台都执行)

# 生成统一的 cluster.id(必须三台一致)
export CLUSTER_ID=$(/opt/kafka/bin/kafka-storage.sh random-uuid)
echo "cluster.id=$CLUSTER_ID"

# 把该 ID 同步到三台 controller 节点的环境变量或脚本中
# 格式化为 controller 节点
/opt/kafka/bin/kafka-storage.sh format -t $CLUSTER_ID \
  -c /opt/kafka/config/kraft/controller.properties

格式化后会在 log.dirs 下生成 meta.properties:

# DO NOT EDIT!!
version=0
cluster.id=5L6g3nShT-eQTHe-m-szWA
node.id=1

第二步:格式化 broker 节点(三台都执行)

/opt/kafka/bin/kafka-storage.sh format -t $CLUSTER_ID \
  -c /opt/kafka/config/kraft/broker.properties

cluster.id 必须三台相同,否则节点找不到彼此。

第三步:启动 controller(三台)

sudo -u kafka /opt/kafka/bin/kafka-server-start.sh -daemon \
  /opt/kafka/config/kraft/controller.properties

第四步:启动 broker(三台)

sudo -u kafka /opt/kafka/bin/kafka-server-start.sh -daemon \
  /opt/kafka/config/kraft/broker.properties

4.7 systemd 托管

/etc/systemd/system/kafka.service:

[Unit]
Description=Apache Kafka Server (KRaft)
Documentation=https://kafka.apache.org/documentation/
After=network.target

[Service]
Type=simple
User=kafka
Group=kafka
Environment="KAFKA_HEAP_OPTS=-Xms12G -Xmx12G -XX:+UseG1GC"
Environment="KAFKA_JVM_PERFORMANCE_OPTS=-server -Djava.awt.headless=true"
ExecStart=/opt/kafka/bin/kafka-server-start.sh /opt/kafka/config/kraft/server.properties
ExecStop=/opt/kafka/bin/kafka-server-stop.sh
Restart=on-failure
RestartSec=10
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target
systemctl daemon-reload
systemctl enable --now kafka

4.8 集群验证

# 1. 查看集群节点列表(任一 broker 上)
bin/kafka-broker-api-versions.sh --bootstrap-server brk-01:9092 | head -3

# 2. 查看 controller 列表(任一 broker)
bin/kafka-metadata-quorum.sh --bootstrap-server brk-01:9092 describe --status

# 输出示例:
# ClusterId:              5L6g3nShT-eQTHe-m-szWA
# LeaderId:               2
# LeaderEpoch:            3
# HighWatermark:          1234
# MaxFollowerLag:         0
# MaxFollowerLagTimeMs:   0
# CurrentVoters:          [1,2,3]
# CurrentObservers:       []

# 3. 创建测试 topic
bin/kafka-topics.sh --bootstrap-server brk-01:9092 \
  --create --topic smoke-test --partitions 6 --replication-factor 3

# 4. 查看 topic 详情(确认副本分布)
bin/kafka-topics.sh --bootstrap-server brk-01:9092 \
  --describe --topic smoke-test

# 5. 验证生产/消费
bin/kafka-console-producer.sh --bootstrap-server brk-01:9092 \
  --topic smoke-test < /etc/hostname
bin/kafka-console-consumer.sh --bootstrap-server brk-01:9092 \
  --topic smoke-test --from-beginning --timeout-ms 5000

五、Kafka + ZK 传统集群(遗留)

5.1 ZK 集群部署

节点规划(3 节点 ensemble):

主机名 IP myid 监听端口
zk-01 10.0.1.31 1 2181/2888/3888
zk-02 10.0.1.32 2 2181/2888/3888
zk-03 10.0.1.33 3 2181/2888/3888

zoo.cfg(三台共用):

tickTime=2000
initLimit=10
syncLimit=5
dataDir=/data1/zookeeper
clientPort=2181
server.1=zk-01:2888:3888
server.2=zk-02:2888:3888
server.3=zk-03:2888:3888
autopurge.snapRetainCount=5
autopurge.purgeInterval=24

启动:

echo 1 > /data1/zookeeper/myid   # 其他两台分别是 2 / 3
/opt/zookeeper/bin/zkServer.sh start
/opt/zookeeper/bin/zkServer.sh status

5.2 Kafka broker 配置(ZK 模式)

config/server.properties 关键项:

# ============ ZK 连接 ============
zookeeper.connect=zk-01:2181,zk-02:2181,zk-03:2181/kafka
zookeeper.connection.timeout.ms=18000

# ============ 基础 ============
broker.id=1                        # 每台不同
listeners=PLAINTEXT://:9092
advertised.listeners=PLAINTEXT://brk-01:9092
log.dirs=/data1/kafka,/data2/kafka

# ============ Topic ============
num.partitions=3
default.replication.factor=3
min.insync.replicas=2
offsets.topic.replication.factor=3
auto.create.topics.enable=false

ZK 模式不需要 kafka-storage.sh format,直接启动即可。


六、集群扩缩容

6.1 增加 Broker 节点

扩容本质是把已有 topic 的 partition 重新分配到新 broker,默认不会自动迁移。

┌────────────────────────────────────────────────────────────┐
│ 扩容流程                                                   │
├────────────────────────────────────────────────────────────┤
│ 1. 新节点部署 Kafka,启动并加入集群                          │
│    ↓                                                       │
│ 2. broker 自动注册到 controller 元数据                      │
│    ↓                                                       │
│ 3. 对每个需要重平衡的 topic 生成 reassign 计划              │
│    ↓                                                       │
│ 4. kafka-reassign-partitions.sh --execute 渐进迁移         │
│    ↓                                                       │
│ 5. --verify 验证迁移完成                                    │
│    ↓                                                       │
│ 6. (可选)preferred replica 选举恢复均衡                     │
└────────────────────────────────────────────────────────────┘

第一步:启动新 broker

新节点使用与现有集群相同 cluster.id(KRaft 模式),node.id 不能与现有重复,启动后会自动发现集群。

第二步:准备 reassign JSON

# 查看当前所有 broker
bin/kafka-broker-api-versions.sh --bootstrap-server brk-01:9092 | grep broker

# 推荐用 --generate 自动生成(从现有分布 -> 加入新 broker)
bin/kafka-reassign-partitions.sh --bootstrap-server brk-01:9092 \
  --topics-to-move-json-file topics.json \
  --broker-list "101,102,103,104" \
  --generate
# 输出两个 JSON:current, proposed

topics.json:

{
  "topics": [
    {"topic": "order-events"},
    {"topic": "user-events"}
  ],
  "version": 1
}

第三步:渐进迁移(limit 流控)

# 把 --generate 输出的 proposed JSON 保存为 reassign.json
cat > reassign.json << 'EOF'
{
  "version": 1,
  "partitions": [
    {"topic": "order-events", "partition": 0, "replicas": [101,104,102], "log_dirs": ["any","any","any"]},
    {"topic": "order-events", "partition": 1, "replicas": [104,101,103], "log_dirs": ["any","any","any"]},
    ...
  ]
}
EOF

# 限制迁移带宽,避免影响业务(默认 50MB/s)
bin/kafka-reassign-partitions.sh --bootstrap-server brk-01:9092 \
  --reassignment-json-file reassign.json \
  --throttle 104857600 \
  --execute

第四步:验证

bin/kafka-reassign-partitions.sh --bootstrap-server brk-01:9092 \
  --reassignment-json-file reassign.json \
  --verify
# 输出 Status of partition reassignment ...

第五步:恢复 preferred replica 均衡

bin/kafka-leader-election.sh --bootstrap-server brk-01:9092 \
  --election-type PREFERRED --all-topic-partitions

6.2 重新分配副本因子

把 RF 从 3 提升到 5(或反过来):

cat > reassign-rf5.json << 'EOF'
{
  "version": 1,
  "partitions": [
    {"topic": "order-events", "partition": 0, "replicas": [101,102,103,104,105]}
  ]
}
EOF

bin/kafka-reassign-partitions.sh --bootstrap-server brk-01:9092 \
  --reassignment-json-file reassign-rf5.json \
  --throttle 52428800 \
  --execute

副本数只能增加、不能通过 reassign 减少。要从 5 降到 3,需用 kafka-topics.sh --alter 并提供完整副本列表。

bin/kafka-topics.sh --bootstrap-server brk-01:9092 \
  --alter --topic order-events \
  --partitions 6 \
  --replica-assignment "0:[101,102,103],1:[102,103,104],..."

6.3 缩容 Broker

# 1. 准备移除 broker 104 上所有 partition 的 reassign JSON
# 2. 执行渐进迁移
# 3. 迁移完成后停 broker 104
bin/kafka-server-stop.sh

# 4. (KRaft)从 quorum voters 列表中移除(若是 controller)
bin/kafka-metadata-quorum.sh --bootstrap-server brk-01:9092 \
  remove-controller --controller-id 4

6.4 扩容限速与监控

参数 默认 建议
--throttle (reassign) 50MB/s 业务高峰 < 20MB/s,空闲时可 200MB/s
num.replica.fetchers 1 大集群可调 4~8
replica.fetch.min.bytes 1 流量大可调 1KB
replica.fetch.max.bytes 1MB 大消息场景 5MB

七、跨数据中心部署

7.1 部署模式对比

模式 拓扑 写一致性 适用场景
主-主 双活 两个集群同时对外服务 各集群独立,RPO > 0 异地多活
主-备 灾备 主集群服务,备集群冷/温 异步复制,RPO 秒~分钟 容灾
聚合-分发 中央集群 + 边缘集群 边缘单向写中央 边缘计算

7.2 MirrorMaker 2 配置

MM2 是 Kafka 官方跨集群镜像工具,基于 Connect 框架。

┌─────────────┐     MM2 Source     ┌─────────────┐
│ Cluster A   │ ──────────────────► │ Cluster B   │
│ (源)        │     Connect        │ (目标)      │
│ 10.0.0.0/16 │                    │ 10.1.0.0/16 │
└─────────────┘                    └─────────────┘
      │                                  ▲
      │          MM2 反向(可选)         │
      └──────────────────────────────────┘

mm2.properties(双向同步):

# 集群定义
clusters = A, B
A.bootstrap.servers = cluster-a-broker:9092
B.bootstrap.servers = cluster-b-broker:9092

# 同步源->目标:A -> B
A->B.enabled = true
A->B.topics = order-events, user-events, .*
A->B.topics.blacklist = __.*,.*-internal
A->B.source.cluster.alias = A
A->B.target.cluster.alias = B

# 同步 B -> A(双向)
B->A.enabled = true
B->A.topics = order-events, user-events, .*
B->B.source.cluster.alias = B
B->B.target.cluster.alias = A

# 心跳、检查点
A->B.emit.heartbeats.enabled = true
A->B.emit.checkpoints.enabled = true
A->B.sync.topic.acls.enabled = false

# 同步间隔
A->B.refresh.interval.seconds = 30
A->B.sync.group.offset.enabled = true
A->B.emit.offset Syncs = true
A->B.consumer.poll.timeout.ms = 1000
A->B.producer.compression.type = lz4

# 通用
tasks.max = 4
replication.factor = 3
offset.syncs.topic.replication.factor = 3
status.storage.replication.factor = 3
config.storage.replication.factor = 3

启动:

bin/connect-mirror-maker.sh config/mm2.properties

7.3 主-备灾备脚本

#!/bin/bash
# promote-cluster.sh - 备集群升主
CLUSTER=$1   # A or B

bin/kafka-leader-election.sh --bootstrap-server $CLUSTER-brk:9092 \
  --election-type PREFERRED --all-topic-partitions

7.4 跨数据中心注意事项

关注点 建议
延迟 MM2 异步,RPO 取决于 refresh.interval
循环复制 必须设置 topics.exclude 或 topics 白名单
顺序保证 MM2 按 partition 保持顺序,跨 partition 无序
Schema 一致 双端共用 Schema Registry
容量规划 带宽预留 30%,避免跨集群同步争抢

八、集群迁移与升级

8.1 小版本升级(rolling restart)

适用:3.6.x → 3.6.y 或 3.5.x → 3.6.x。

┌─────────────────────────────────────────────────────────┐
│ 滚动升级流程(每批一台,验证后再下一台)                  │
├─────────────────────────────────────────────────────────┤
│ 1. 备份 server.properties 与 log.dirs 元数据            │
│ 2. 升级 controller 节点(先非 leader)                  │
│ 3. 验证 controller quorum 健康                         │
│ 4. 升级 broker 节点(先非 partition leader)             │
│ 5. 每台升级后观察 ISR 列表恢复                         │
│ 6. 客户端兼容性检查后,通知业务方升级 SDK                │
└─────────────────────────────────────────────────────────┘

Controller 滚动升级:

# 1. 查看当前 leader
bin/kafka-metadata-quorum.sh --bootstrap-server ctrl-01:9093 describe --status

# 2. 在非 leader 节点升级
ssh ctrl-02 "systemctl stop kafka"
scp kafka_2.13-3.6.2.tgz ctrl-02:/opt/
ssh ctrl-02 "cd /opt && tar xzf kafka_2.13-3.6.2.tgz --strip-components=1 -C /opt/kafka"
ssh ctrl-02 "systemctl start kafka"

# 3. 等待元数据追平后,逐个处理 ctrl-03、ctrl-01

Broker 滚动升级:

# 在每个 broker 节点上
ssh brk-01 "systemctl stop kafka"
ssh brk-01 "cd /opt && tar xzf kafka_2.13-3.6.2.tgz --strip-components=1 -C /opt/kafka"
ssh brk-01 "systemctl start kafka"

# 等待 ISR 收缩后恢复(可通过 JMX 监控)
bin/kafka-broker-api-versions.sh --bootstrap-server brk-01:9092

8.2 大版本升级(KRaft 迁移)

从 Kafka 2.x/3.0~3.3 KRaft 早期升级到 3.5+ GA。

┌─────────────────────────────────────────────────────────────┐
│ 大版本升级:逐节点滚动,协议兼容后一次性切流                  │
├─────────────────────────────────────────────────────────────┤
│ 1. 阅读 UPGRADE.md,确认新旧版本间消息协议兼容               │
│ 2. 备份配置与数据                                            │
│ 3. 滚动替换二进制(每台 stop -> 升级 -> start)               │
│ 4. 验证集群健康(controller quorum、ISR、under-replicated)    │
│ 5. 观察 24h 后,客户端逐步升级                               │
└─────────────────────────────────────────────────────────────┘

8.3 ZK → KRaft 迁移步骤详解

最复杂的迁移场景,Kafka 3.3+ 提供官方工具支持。

前置检查:

# 1. 确保 Kafka 版本 ≥ 3.3
bin/kafka-server-start.sh --version

# 2. 当前 ZK 集群健康
bin/zookeeper-shell.sh zk-01:2181 ls /kafka

# 3. 备份 ZK 数据
bin/zookeeper-shell.sh zk-01:2181 get /kafka/controller > ctrl.json

迁移流程:

┌────────────────────────────────────────────────────────────┐
│ ZK → KRaft 迁移(滚动切换)                                │
├────────────────────────────────────────────────────────────┤
│ 1. 部署新 KRaft controller 节点(独立进程,与 ZK 集群共存)  │
│ 2. 准备 ZK → KRaft 元数据转换工具(内置)                   │
│ 3. 滚动重启 broker,逐台切换到 KRaft mode                  │
│    ├ broker 双配置:既支持 ZK 又支持 KRaft                  │
│    └ 切换 process.roles,指向新 controller quorum          │
│ 4. 最后切换第一台 broker 后,controller quorum 选主         │
│ 5. 验证元数据一致(Topic 数量、副本分配、ISR)              │
│ 6. 所有 broker 切换完成后,可下线 ZK 集群                  │
└────────────────────────────────────────────────────────────┘

关键命令(在每台 broker 上):

# 第一步:停 broker
systemctl stop kafka

# 第二步:修改配置,添加 KRaft 相关
cat >> config/kraft/server.properties << 'EOF'
process.roles=broker
controller.quorum.voters=1@ctrl-01:9093,2@ctrl-02:9093,3@ctrl-03:9093
listeners=PLAINTEXT://:9092,CONTROLLER://:9093
controller.listener.names=CONTROLLER
EOF

# 第三步:从 ZK 元数据导出并转换为 KRaft 格式
# (Kafka 3.4+ 提供 kafka-migration-tool,旧版本手动转换)
bin/kafka-storage.sh format -t $CLUSTER_ID \
  --ignore-formatted \
  -c config/kraft/server.properties

# 第四步:启动(此时 broker 加入 KRaft 集群,不再连 ZK)
systemctl start kafka

验证迁移:

bin/kafka-topics.sh --bootstrap-server brk-01:9092 --list | wc -l
bin/kafka-consumer-groups.sh --bootstrap-server brk-01:9092 --list

bin/kafka-metadata-quorum.sh --bootstrap-server brk-01:9092 describe --status

回滚:迁移过程中任何一步出现严重问题,可把 broker 切回 ZK 模式(保留旧 server.properties),前提是 ZK 集群仍存活。

8.4 跨大版本兼容性矩阵

升级路径 协议兼容 是否需要 client 升级
3.5 → 3.6 是(消息协议不变) 客户端可后升
3.4 → 3.5 是 客户端可后升
3.3 → 3.4 是 客户端可后升
3.0 → 3.5 部分 旧 producer/consumer 可能需要升级
2.8 → 3.6 否 必须升级所有客户端

九、配置管理最佳实践

9.1 配置版本化

# 配置仓库结构
kafka-config/
├── base/
│   ├── server.properties        # 通用基线
│   └── kraft/server.properties
├── envs/
│   ├── prod-east/server.properties
│   ├── prod-west/server.properties
│   └── staging/server.properties
└── README.md
# 使用 Git 管理配置变更
git init kafka-config
git add -A && git commit -m "feat: 调整 retention 为 14d"
git tag v2026.08.18

# 部署时拉取
git pull && ansible-playbook deploy-kafka.yml

9.2 灰度发布

┌──────────────────────────────────────────────────────────┐
│ 配置变更灰度流程                                         │
├──────────────────────────────────────────────────────────┤
│ 灰度 1 台 (brk-03) → 观察 15min → 验证                  │
│                                                          │
│ 灰度 1/3 (brk-03) → 观察 30min → 验证                   │
│                                                          │
│ 灰度 2/3 (brk-02,03) → 观察 1h → 验证                   │
│                                                          │
│ 全量 (brk-01,02,03) → 持续监控                          │
└──────────────────────────────────────────────────────────┘

通过 Ansible 或自定义脚本实现:

# playbook-灰度.yaml
- hosts: kafka-brk-03
  roles:
    - kafka-reconfig
- pause:
    minutes: 15
- hosts: kafka-brk-02
  roles:
    - kafka-reconfig
- hosts: kafka-brk-01
  roles:
    - kafka-reconfig

9.3 配置回滚

# 保留最近 5 个配置版本
cd /opt/kafka/config/kraft
cp server.properties server.properties.$(date +%Y%m%d_%H%M)

# 回滚
ln -sf server.properties.bak.20260817 server.properties
systemctl restart kafka

关键配置变更(如 inter.broker.listener.name、log.dirs、process.roles)需重启生效;其他部分可通过动态配置(kafka-configs.sh --alter)热生效。

# 动态修改 topic 级配置
bin/kafka-configs.sh --bootstrap-server brk-01:9092 \
  --entity-type topics --entity-name order-events \
  --alter --add-config retention.ms=604800000

# 动态修改 broker 级配置
bin/kafka-configs.sh --bootstrap-server brk-01:9092 \
  --entity-type brokers --entity-name 101 \
  --alter --add-config log.cleaner.io.max.bytes.per.second=52428800

十、实战案例:3 broker + 3 controller 完整部署

10.1 docker-compose 部署

docker-compose.yml:

version: '3.8'

networks:
  kafka-net:
    driver: bridge

services:
  # ============ Controllers ============
  ctrl-01:
    image: bitnami/kafka:3.6
    container_name: kafka-ctrl-01
    networks:
      - kafka-net
    ports:
      - "9093:9093"
    environment:
      - KAFKA_CFG_NODE_ID=1
      - KAFKA_CFG_PROCESS_ROLES=controller
      - KAFKA_CFG_CONTROLLER_QUORUM_VOTERS=1@ctrl-01:9093,2@ctrl-02:9093,3@ctrl-03:9093
      - KAFKA_CFG_LISTENERS=CONTROLLER://:9093
      - KAFKA_CFG_CONTROLLER_LISTENER_NAMES=CONTROLLER
      - KAFKA_CFG_LISTENER_SECURITY_PROTOCOL_MAP=CONTROLLER:PLAINTEXT
      - KAFKA_KRAFT_CLUSTER_ID=MkU3OEVBNTcwNTJENDM2Qk
      - ALLOW_PLAINTEXT_LISTENER=yes
    volumes:
      - ctrl-01-data:/bitnami/kafka

  ctrl-02:
    image: bitnami/kafka:3.6
    container_name: kafka-ctrl-02
    networks:
      - kafka-net
    environment:
      - KAFKA_CFG_NODE_ID=2
      - KAFKA_CFG_PROCESS_ROLES=controller
      - KAFKA_CFG_CONTROLLER_QUORUM_VOTERS=1@ctrl-01:9093,2@ctrl-02:9093,3@ctrl-03:9093
      - KAFKA_CFG_LISTENERS=CONTROLLER://:9093
      - KAFKA_KRAFT_CLUSTER_ID=MkU3OEVBNTcwNTJENDM2Qk
      - ALLOW_PLAINTEXT_LISTENER=yes
    volumes:
      - ctrl-02-data:/bitnami/kafka

  ctrl-03:
    image: bitnami/kafka:3.6
    container_name: kafka-ctrl-03
    networks:
      - kafka-net
    environment:
      - KAFKA_CFG_NODE_ID=3
      - KAFKA_CFG_PROCESS_ROLES=controller
      - KAFKA_CFG_CONTROLLER_QUORUM_VOTERS=1@ctrl-01:9093,2@ctrl-02:9093,3@ctrl-03:9093
      - KAFKA_CFG_LISTENERS=CONTROLLER://:9093
      - KAFKA_KRAFT_CLUSTER_ID=MkU3OEVBNTcwNTJENDM2Qk
      - ALLOW_PLAINTEXT_LISTENER=yes
    volumes:
      - ctrl-03-data:/bitnami/kafka

  # ============ Brokers ============
  brk-01:
    image: bitnami/kafka:3.6
    container_name: kafka-brk-01
    networks:
      - kafka-net
    ports:
      - "9092:9092"
    environment:
      - KAFKA_CFG_NODE_ID=101
      - KAFKA_CFG_PROCESS_ROLES=broker
      - KAFKA_CFG_CONTROLLER_QUORUM_VOTERS=1@ctrl-01:9093,2@ctrl-02:9093,3@ctrl-03:9093
      - KAFKA_CFG_LISTENERS=PLAINTEXT://:9092
      - KAFKA_CFG_ADVERTISED_LISTENERS=PLAINTEXT://localhost:9092
      - KAFKA_CFG_INTER_BROKER_LISTENER_NAME=PLAINTEXT
      - KAFKA_CFG_LISTENER_SECURITY_PROTOCOL_MAP=PLAINTEXT:PLAINTEXT
      - KAFKA_CFG_LOG_DIRS=/bitnami/kafka/messages
      - KAFKA_CFG_NUM_PARTITIONS=3
      - KAFKA_CFG_DEFAULT_REPLICATION_FACTOR=3
      - KAFKA_CFG_MIN_INSYNC_REPLICAS=2
      - KAFKA_CFG_OFFSETS_TOPIC_REPLICATION_FACTOR=3
      - KAFKA_CFG_TRANSACTION_STATE_LOG_REPLICATION_FACTOR=3
      - KAFKA_CFG_TRANSACTION_STATE_LOG_MIN_ISR=2
      - KAFKA_CFG_AUTO_CREATE_TOPICS_ENABLE=true
      - KAFKA_KRAFT_CLUSTER_ID=MkU3OEVBNTcwNTJENDM2Qk
      - ALLOW_PLAINTEXT_LISTENER=yes
    depends_on:
      - ctrl-01
      - ctrl-02
      - ctrl-03
    volumes:
      - brk-01-data:/bitnami/kafka

  brk-02:
    image: bitnami/kafka:3.6
    container_name: kafka-brk-02
    networks:
      - kafka-net
    environment:
      - KAFKA_CFG_NODE_ID=102
      - KAFKA_CFG_PROCESS_ROLES=broker
      - KAFKA_CFG_CONTROLLER_QUORUM_VOTERS=1@ctrl-01:9093,2@ctrl-02:9093,3@ctrl-03:9093
      - KAFKA_CFG_LISTENERS=PLAINTEXT://:9092
      - KAFKA_CFG_ADVERTISED_LISTENERS=PLAINTEXT://brk-02:9092
      - KAFKA_CFG_INTER_BROKER_LISTENER_NAME=PLAINTEXT
      - KAFKA_CFG_LOG_DIRS=/bitnami/kafka/messages
      - KAFKA_CFG_DEFAULT_REPLICATION_FACTOR=3
      - KAFKA_KRAFT_CLUSTER_ID=MkU3OEVBNTcwNTJENDM2Qk
      - ALLOW_PLAINTEXT_LISTENER=yes
    depends_on:
      - ctrl-01
    volumes:
      - brk-02-data:/bitnami/kafka

  brk-03:
    image: bitnami/kafka:3.6
    container_name: kafka-brk-03
    networks:
      - kafka-net
    environment:
      - KAFKA_CFG_NODE_ID=103
      - KAFKA_CFG_PROCESS_ROLES=broker
      - KAFKA_CFG_CONTROLLER_QUORUM_VOTERS=1@ctrl-01:9093,2@ctrl-02:9093,3@ctrl-03:9093
      - KAFKA_CFG_LISTENERS=PLAINTEXT://:9092
      - KAFKA_CFG_ADVERTISED_LISTENERS=PLAINTEXT://brk-03:9092
      - KAFKA_CFG_INTER_BROKER_LISTENER_NAME=PLAINTEXT
      - KAFKA_CFG_LOG_DIRS=/bitnami/kafka/messages
      - KAFKA_CFG_DEFAULT_REPLICATION_FACTOR=3
      - KAFKA_KRAFT_CLUSTER_ID=MkU3OEVBNTcwNTJENDM2Qk
      - ALLOW_PLAINTEXT_LISTENER=yes
    depends_on:
      - ctrl-01
    volumes:
      - brk-03-data:/bitnami/kafka

volumes:
  ctrl-01-data:
  ctrl-02-data:
  ctrl-03-data:
  brk-01-data:
  brk-02-data:
  brk-03-data:

启动与验证:

docker-compose up -d
docker-compose ps

# 验证 controller quorum
docker exec -it kafka-brk-01 /opt/bitnami/kafka/bin/kafka-metadata-quorum.sh \
  --bootstrap-server localhost:9092 describe --status

# 创建 topic
docker exec -it kafka-brk-01 /opt/bitnami/kafka/bin/kafka-topics.sh \
  --bootstrap-server localhost:9092 \
  --create --topic demo --partitions 6 --replication-factor 3

docker exec -it kafka-brk-01 /opt/bitnami/kafka/bin/kafka-topics.sh \
  --bootstrap-server localhost:9092 --describe --topic demo

10.2 Ansible 批量部署示例

roles/kafka/tasks/main.yml:

- name: 拷贝安装包
  copy: src=kafka_2.13-3.6.1.tgz dest=/opt/

- name: 解压
  unarchive:
    src: /opt/kafka_2.13-3.6.1.tgz
    dest: /opt/
    remote_src: yes
    creates: /opt/kafka

- name: 推送配置
  template:
    src: server.properties.j2
    dest: /opt/kafka/config/kraft/server.properties

- name: 格式化目录
  command: /opt/kafka/bin/kafka-storage.sh format -t {{ kraft_cluster_id }} \
    -c /opt/kafka/config/kraft/server.properties
  when: not meta_file.stat.exists

- name: 推送 systemd
  copy:
    src: kafka.service
    dest: /etc/systemd/system/kafka.service

- name: 启动
  systemd:
    name: kafka
    state: started
    enabled: yes
    daemon_reload: yes

十一、集群巡检清单

11.1 健康检查

#!/bin/bash
# kafka-health-check.sh
BS=brk-01:9092
echo "===== 1. 集群节点 ====="
/opt/kafka/bin/kafka-broker-api-versions.sh --bootstrap-server $BS 2>/dev/null | grep broker | wc -l

echo "===== 2. Controller quorum ====="
/opt/kafka/bin/kafka-metadata-quorum.sh --bootstrap-server $BS describe --status 2>/dev/null | grep -E "LeaderId|MaxFollowerLag|CurrentVoters"

echo "===== 3. Under-replicated partitions ====="
/opt/kafka/bin/kafka-topics.sh --bootstrap-server $BS \
  --describe --under-replicated-partitions 2>/dev/null | wc -l

echo "===== 4. 没有 Leader 的 partition ====="
/opt/kafka/bin/kafka-topics.sh --bootstrap-server $BS \
  --describe --unavailable-partitions 2>/dev/null | wc -l

echo "===== 5. 消费者 lag ====="
/opt/kafka/bin/kafka-consumer-groups.sh --bootstrap-server $BS \
  --all-groups --describe 2>/dev/null | awk '$5 > 1000 {print}'

echo "===== 6. 磁盘使用 ====="
df -h /data1 /data2 | grep -v tmpfs

echo "===== 7. Broker 进程 ====="
jps | grep -i kafka | wc -l

11.2 巡检 Checklist

检查项 命令 阈值 处理
节点存活 kafka-broker-api-versions.sh broker 数 == 预期 异常节点需排查
Controller quorum kafka-metadata-quorum.sh describe --status MaxFollowerLag < 1000 过高说明 controller 不健康
Under-replicated kafka-topics.sh --describe --under-replicated-partitions 应为 0 持续 > 0 表示 Follower 掉队
Unavailable partition kafka-topics.sh --describe --unavailable-partitions 应为 0 > 0 立即告警
消费者 lag kafka-consumer-groups.sh --describe P99 lag < 10000 异常 group 排查消费逻辑
磁盘使用率 df -h log.dirs < 75% 触达 80% 需扩盘或清理
文件描述符 lsof -p <pid> \| wc -l < 80% ulimit 调高 ulimit
网络流量 sar -n DEV 1 < 70% 带宽 排查热点 partition
JVM GC jstat -gcutil Full GC < 1 次/小时 调内存或 GC 参数
Controller 日志 grep ERROR controller.log 无 ERROR 关注 IllegalState 类错误
磁盘 IO 等待 iostat -x 1 %util < 80% 换 SSD 或加盘
配置漂移 比对 server.properties git 仓库 无差异 记录漂移来源

11.3 常见告警与处置

告警 可能原因 处置
Under-replicated > 0 Follower 掉队、网络抖动、磁盘满 查 broker 日志、检查网络/磁盘
LEADER_NOT_AVAILABLE Leader broker 故障 重启故障 broker,或触发 leader 选举
InvalidReplicationFactorException RF > broker 数 减少 RF 或加 broker
NotEnoughReplicasException ISR < min.insync.replicas 修复 Follower,或临时调小 min.insync
Controller Leader 频繁切换 网络抖动、GC 暂停 隔离 controller 到独立节点、调大 GC

十二、核心要点速记

  • 首选 KRaft:Kafka 3.3+ 生产就绪、3.5+ GA,新部署不再用 ZK 模式,4.x 将完全移除 ZK
  • 节点角色:process.roles 可为 broker、controller 或 broker,controller,大集群分离部署性能更稳定
  • Controller 数量:奇数(3/5/7),过半存活即能工作;2 节点 quorum 不容错,禁止生产
  • Controller 节点规格:CPU/内存要求低(2C4G 足够),与 broker 分离避免相互影响
  • cluster.id 必须一致:KRaft 模式下三台节点 meta.properties 中 cluster.id 必须相同,否则节点失联
  • format 是必经步骤:KRaft 启动前必须 kafka-storage.sh format,否则进程无法启动
  • 关键配置三元组:replication.factor=3 + min.insync.replicas=2 + acks=all 是生产不丢消息的黄金组合
  • offsets.topic.replication.factor:KRaft 集群建议设为 3,单节点集群必须设为 1
  • advertised.listeners:客户端访问失败 90% 是这个配置错,必须配置可路由地址,不能用 localhost
  • 扩容流程:新节点启动 → 生成 reassign JSON → --throttle 流控执行 → --verify 验证 → preferred replica 选举恢复均衡
  • reassign 限速:--throttle 默认 50MB/s,业务高峰期建议 < 20MB/s,避免影响在线流量
  • 副本数调整:reassign 可加副本不可减副本;减副本需用 --alter 重新指定完整副本列表
  • rolling restart 顺序:先 controller 非 leader → 后 broker 非 partition leader,逐台验证
  • 小版本升级:协议兼容,可滚动重启;大版本升级:先读 UPGRADE.md,确认兼容性
  • ZK → KRaft 迁移:3.3+ 支持,流程是部署 controller → 滚动切换 broker → 验证 → 下线 ZK,保留回滚方案
  • MirrorMaker 2:跨集群复制官方方案,必须配置 topic 白名单或黑名单,避免循环复制
  • 跨数据中心:MM2 异步复制,RPO 取决于 refresh.interval;生产/消费顺序仅分区内保证
  • 配置管理:Git 版本化、灰度单台 → 1/3 → 2/3 → 全量;动态配置用 kafka-configs.sh --alter
  • systemd 托管:生产环境推荐,避免 kill -9 导致消息丢失
  • 巡检四件套:节点存活、under-replicated=0、unavailable=0、消费者 lag 正常
  • 巡检命令三件套:kafka-topics.sh --describe --under-replicated、kafka-consumer-groups.sh --describe、kafka-metadata-quorum.sh describe --status
  • docker-compose 部署:bitnami/kafka 镜像最方便,通过环境变量配置 KRaft,KAFKA_KRAFT_CLUSTER_ID 必须三节点一致
  • JVM 调优:-Xms=Xmx=12G + G1GC + MaxGCPauseMillis=20,broker 内存不宜超过 32G(指针压缩边界)
  • 操作系统调优:vm.swappiness=1、ulimit -n 65536、XFS 文件系统 noatime
  • 常见坑点:
  • 单节点集群 RF 必须为 1,否则 __consumer_offsets 创建失败
  • kill -9 导致未刷盘消息丢失,务必用 kafka-server-stop.sh 或 kill -TERM
  • topic 副本数只能增加不能直接减少
  • KRaft 启动前必须 format,否则进程退出
  • MM2 必须配置 topic 白名单或黑名单,否则会形成复制循环