Kafka 4.0.1 KRaft 模式完整部署指南

Kafka 4.0.1 KRaft 模式完整部署指南（2026 最新版）

📌 导读

从 Kafka 3.3.0 开始，KRaft 模式正式取代 ZooKeeper 成为元数据管理的新标准。本文基于 Kafka 4.0.1，从架构原理到生产部署，全流程讲解 KRaft 模式的部署方法与最佳实践，并总结实际环境中的常见坑点与优化建议。

一、为什么选择 KRaft 模式？

1. 传统架构 vs KRaft 架构

传统 Kafka 依赖 ZooKeeper 存储元数据：

复制代码

Producer/Consumer
        │
        ▼
     Kafka Broker  ←→ ZooKeeper Cluster

KRaft（Kafka Raft Metadata Mode）将元数据管理内置：

复制代码

Producer/Consumer
        │
        ▼
   Kafka Broker (内置 Raft Controller)

核心变化：Kafka 自己管理元数据，不再依赖 ZooKeeper。

2. KRaft 核心优势

特性	ZooKeeper 模式	KRaft 模式	收益
依赖组件	Kafka + ZooKeeper	仅 Kafka	运维复杂度下降
集群维护	双集群	单集群	成本降低
Partition 上限	~20 万	~200 万	扩展能力提升
Controller 选举	秒级	毫秒级	故障恢复更快
未来支持	已弃用方向	官方主推	长期可维护

二、前置准备

1. 系统要求

OS：CentOS 7+ / Ubuntu 18.04+ / macOS 10.15+
Java：JDK 11+（推荐 JDK 17）
内存：≥2GB（生产建议 ≥8GB）
磁盘：SSD，至少 10GB 可用空间

检查 Java：

bash 复制代码

java -version

2. 下载 Kafka 4.0.1

bash 复制代码

sudo mkdir -p /opt/kafka
cd /opt/kafka

wget https://downloads.apache.org/kafka/4.0.1/kafka_2.13-4.0.1.tgz
tar -xzf kafka_2.13-4.0.1.tgz
#修改目录所有者和权限
sudo  chown -R $USER:$USER kafka_2.13-4.0.1 
sudo  chmod -R 755 kafka_2.13-4.0.1 
cd kafka_2.13-4.0.1

目录说明：

目录	作用
bin	启动脚本
config	配置文件
libs	依赖库
logs	运行日志

三、单节点部署（开发 / 测试）

Step 1：生成 Cluster UUID

bash 复制代码

KAFKA_CLUSTER_ID=$(bin/kafka-storage.sh random-uuid)
echo $KAFKA_CLUSTER_ID

Step 2：准备配置文件

bash 复制代码

mkdir kraft #创建目录
vim config/kraft/server.properties

Step 3：关键配置说明

复制代码

################ 节点身份 ################
node.id=1
process.roles=broker,controller
cluster.id=<填写生成的UUID>

################ Controller ################
controller.quorum.voters=1@localhost:9093
controller.listener.names=CONTROLLER

################ 网络 ################
listeners=PLAINTEXT://:9092,CONTROLLER://:9093
advertised.listeners=PLAINTEXT://localhost:9092

listener.security.protocol.map=CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT
inter.broker.listener.name=PLAINTEXT

################ 存储 ################
log.dirs=/opt/kafka/kafka_2.13-4.0.1/logs/kafka-logs

################ 推荐参数 ################
num.partitions=3
default.replication.factor=1
min.insync.replicas=1
log.retention.hours=168
auto.create.topics.enable=true

Step 4：格式化存储目录（关键步骤）

bash 复制代码

mkdir -p logs/kafka-logs
chown -R $USER:$USER logs

bin/kafka-storage.sh format \
  -t $KAFKA_CLUSTER_ID \
  -c config/kraft/server.properties

Step 5：启动 Kafka

前台启动：

复制代码

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

后台启动：

复制代码

nohup bin/kafka-server-start.sh \
config/kraft/server.properties \
> logs/kafka-start.log 2>&1 &

Step 6：验证部署

检查进程：

bash 复制代码

ps -aux | grep kafka

检查端口：

复制代码

netstat -tlnp | grep -E "9092|9093"

创建 Topic：

复制代码

bin/kafka-topics.sh \
--create \
--topic test-topic \
--bootstrap-server localhost:9092 \
--partitions 3 \
--replication-factor 1

发送消息：

复制代码

bin/kafka-console-producer.sh \
--topic test-topic \
--bootstrap-server localhost:9092

消费消息：

复制代码

bin/kafka-console-consumer.sh \
--topic test-topic \
--from-beginning \
--bootstrap-server localhost:9092

四、多节点 KRaft 集群部署（生产）

集群规划示例

节点	IP	node.id	角色
kafka-01	192.168.1.101	1	broker+controller
kafka-02	192.168.1.102	2	broker+controller
kafka-03	192.168.1.103	3	broker+controller

核心配置差异

所有节点必须一致：

复制代码

cluster.id=同一个ID
controller.quorum.voters=
1@192.168.1.101:9093,
2@192.168.1.102:9093,
3@192.168.1.103:9093

节点唯一项：

复制代码

node.id=2
advertised.listeners=PLAINTEXT://192.168.1.102:9092

部署流程

1️⃣ 仅 Node1 生成 cluster.id

2️⃣ 所有节点配置相同 cluster.id

3️⃣ 每节点执行 format

4️⃣ 同时启动 Broker

复制代码

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

验证元数据：

复制代码

bin/kafka-metadata.sh \
--snapshot logs/kafka-logs/__cluster_metadata-0/*.log

五、Docker 快速部署（单节点）

docker-compose.yml

复制代码

version: '3.8'
services:
  kafka:
    image: apache/kafka:4.0.1
    container_name: kafka-kraft
    ports:
      - "9092:9092"
    environment:
      KAFKA_NODE_ID: 1
      KAFKA_PROCESS_ROLES: broker,controller
      KAFKA_LISTENERS: PLAINTEXT://0.0.0.0:9092,CONTROLLER://0.0.0.0:9093
      KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://localhost:9092
      KAFKA_CONTROLLER_QUORUM_VOTERS: 1@kafka:9093
      KAFKA_CLUSTER_ID: <UUID>
      KAFKA_LOG_DIRS: /var/lib/kafka/data
    volumes:
      - kafka-data:/var/lib/kafka/data
    restart: unless-stopped

volumes:
  kafka-data:

启动：

复制代码

docker compose up -d

六、常见问题排查

1️⃣ Permission denied

复制代码

chown -R $USER:$USER /opt/kafka
chmod -R 755 logs

2️⃣ Missing node.id

复制代码

node.id=1

3️⃣ No readable meta.properties

重新格式化：

复制代码

bin/kafka-storage.sh format -t $CLUSTER_ID -c config/kraft/server.properties

4️⃣ 端口占用

复制代码

lsof -i :9092

5️⃣ Cluster ID 不一致

复制代码

cat logs/kafka-logs/meta.properties

确保与配置一致。

七、性能调优建议

Broker 参数

复制代码

num.network.threads=8
num.io.threads=16
log.segment.bytes=1073741824
log.retention.hours=168

log.flush.interval.messages=10000
log.flush.interval.ms=1000

JVM 优化

复制代码

-Xms8g
-Xmx8g
-XX:+UseG1GC
-XX:MaxGCPauseMillis=20
-XX:InitiatingHeapOccupancyPercent=35
-XX:MaxDirectMemorySize=6g

八、生产环境最佳实践

systemd 管理 Kafka

sudo vim /etc/systemd/system/kafka.service

bash 复制代码

# /etc/systemd/system/kafka.service
[Unit]
Description=Apache Kafka (KRaft)
After=network.target

[Service]
Type=simple
User=$USER   #改成你对应的用户
Group=$USER  
Environment=JAVA_HOME=/usr/lib/jvm/java-17-openjdk
ExecStart=/opt/kafka/kafka_2.13-4.0.1/bin/kafka-server-start.sh /opt/kafka/kafka_2.13-4.0.1/config/kraft/server.properties
ExecStop=/opt/kafka/kafka_2.13-4.0.1/bin/kafka-server-stop.sh
Restart=on-failure
LimitNOFILE=100000

[Install]
WantedBy=multi-user.target

启动：

bash 复制代码

sudo systemctl daemon-reload
sudo systemctl enable kafka
sudo systemctl start kafka

Prometheus 告警示例

复制代码

- alert: KafkaBrokerDown
  expr: kafka_broker_state != 1

- alert: KafkaUnderReplicatedPartitions
  expr: kafka_server_replicamanager_underreplicatedpartitions > 0

- alert: KafkaConsumerLagHigh
  expr: kafka_consumer_group_lag > 10000

安全建议

复制代码

authorizer.class.name=kafka.security.authorizer.AclAuthorizer
allow.everyone.if.no.acl.found=false
auto.create.topics.enable=false

九、总结

场景	推荐方案
本地开发	Docker 单节点
测试环境	单节点 KRaft
生产环境	≥3 节点 KRaft 集群

部署 Checklist

JDK 11+ 已安装
node.id 唯一
cluster.id 全局一致
存储目录已 format
权限正确
端口监听正常
监控与告警已配置

结语

KRaft 模式已经成为 Kafka 的未来方向。对于新系统，建议直接采用 KRaft 架构；对于已有 ZooKeeper 集群，应规划分阶段迁移策略，以降低升级风险并获得更好的可扩展性与运维体验。

当 Kafka 不再依赖 ZooKeeper，Kafka 才真正成为一个完整的分布式系统。