Apache Kafka KRaft 模式怎样管理集群元数据

Apache Kafka 的 KRaft 模式把集群元数据交给 controller 组成的 Raft 仲裁组管理，而不是再依赖 ZooKeeper 保存 controller 状态。topic、partition、broker 注册和配置变更先进入集群元数据日志，由多数 controller 确认后，再由 broker 加载成自己的元数据视图。

官方地址：https://kafka.apache.org/40/operations/kraft/

KRaft 把集群元数据交给 controller quorum

KRaft 的核心不是“每个 broker 自己保存一份配置”，而是把集群级变化集中到一个元数据分区。active controller 接收管理请求，把变更追加到 __cluster_metadata 日志；其他 controller 通过 Raft 复制，达到多数派后才算提交。broker 再从这个提交点加载 MetadataImage，因此 controller 选举和元数据提交是同一条控制链路。

这里要把两类复制分开看：controller quorum 复制的是集群元数据，broker 的数据副本仍由 topic partition 的副本机制负责。前者不可用时，创建 topic、调整副本和许多管理动作会受影响；它不等于所有业务消息都已经丢失。

初始化时先固定 cluster ID 和元数据目录

新集群首先要让 controller 使用同一个 cluster ID，并在元数据目录中生成自己的身份文件和初始快照。生产环境通常把 controller 与 broker 分离，避免 combined mode 把两种故障域绑在一起。下面是初始化一个独立 controller 的示意命令，变量只是示例占位符：

# 生成一次集群标识，所有节点格式化时必须使用同一个值
CLUSTER_ID="$(bin/kafka-storage.sh random-uuid)"

# 首个 controller 以 standalone voter 启动，创建初始元数据快照
bin/kafka-storage.sh format \
  --cluster-id "${CLUSTER_ID}" \
  --standalone \
  --config config/controller.properties

# 新增到已有集群的节点不要重新创建一套初始 voter
bin/kafka-storage.sh format \
  --cluster-id "${CLUSTER_ID}" \
  --config config/server.properties \
  --no-initial-controllers

真正上线前要确认 metadata.log.dir 位于持久磁盘，并把 cluster ID、node.id、controller listener 和 quorum 引导地址纳入配置管理。误删元数据目录后直接格式化，会产生一个看似能启动、实际缺少已提交元数据的新成员。

先看 quorum 状态，再判断元数据是否健康

不要只看 broker 进程是否存活。KRaft 的管理判断至少要关注 leader、HighWatermark、最大 follower lag 和当前 voters。官方工具可以从 broker 或 controller endpoint 查询：

# 查看元数据仲裁的领导者、高水位和 voter 列表
bin/kafka-metadata-quorum.sh \
  --bootstrap-server localhost:9092 \
  describe --status

# 查看每个成员是否追上元数据日志；lag 持续增长才是风险信号
bin/kafka-metadata-quorum.sh \
  --bootstrap-server localhost:9092 \
  describe --replication

如果没有多数 controller，新的元数据记录不能稳定提交；如果某个 follower lag 持续升高，先检查网络、磁盘和 controller 进程，而不是马上删除它。恢复判断应以日志追平和仲裁状态为准。

动态 quorum 的扩缩容边界

Kafka 3.9 引入动态 controller quorum 后，controller 成员不必永久写死在每个配置文件里。新增 controller 的顺序应是：格式化并启动新节点、用 describe --replication 确认它追平 active controller、再执行 add-controller。移除时则要确认剩余成员仍能形成多数派；Kafka 4.4 的发布说明还提供了 controller 注销相关命令和 API。

静态 quorum 和动态 quorum 不是运行中随意切换的开关。可以用下面的命令确认当前 feature level：

# kraft.version 为 1 或更高通常表示已启用动态 quorum
bin/kafka-features.sh \
  --bootstrap-controller localhost:9093 \
  describe

常见问题

KRaft 元数据日志和业务消息日志是一回事吗？

不是。元数据日志描述集群结构和控制面变化，业务消息仍在各个 topic partition 的数据日志中复制。

为什么新 controller 启动了却不能立刻加入 quorum？

启动只代表节点可用，加入前还要让它追上已提交的元数据。先看 replication lag，再执行成员变更。

controller 是不是越多越好？

不是。多数派越大，故障容忍度会增加，但选举和复制的协调成本也会上升；常见部署先从 3 个 controller 评估。