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,单节点集群必须设为 1advertised.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 白名单或黑名单,否则会形成复制循环