1. 从“会用的中间件”到“懂原理的工程师”为什么我要啃 Kafka Raft很多人用 Kafka 用了好几年日常就是写 Producer、调 Consumer、偶尔看看 Lag觉得这套东西“会用就行”。但一旦集群出现 Controller 频繁切换、元数据不一致、Partition Leader 选举卡住这类问题光靠翻文档和重启大法就完全不够用了。我真正下决心把 Kafka Raft 从头到尾捋一遍就是因为一次线上事故一个三节点的元数据集群在滚动重启后Controller 反复易主日志里全是选举超时和日志截断相关的报错当时团队里没人能说清楚底层到底发生了什么。Kafka Raft准确说是KRaftKafka Raft Metadata Mode是 Kafka 用来替代 ZooKeeper 做元数据管理的共识协议实现。它把原本托管在外部协调组件里的元数据——比如 Broker 注册、Topic 配置、分区副本分配、ACL、ISR 变更——全部收回到 Kafka 自己内部通过一个 Raft 共识组来维护。这件事的意义不只是“少部署一个组件”而是让元数据的读写路径、一致性模型、故障恢复逻辑都统一到同一套体系里。这篇文章适合三类人看第一类是把 Kafka 当黑盒用、但想搞清楚元数据层到底怎么运转的开发和运维第二类是正在做 Kafka 版本升级、考虑从 ZooKeeper 模式迁移到 KRaft 的架构同学第三类是准备面试、被问到“Kafka 为什么能去掉 ZooKeeper”却答不深的朋友。我会从设计思路、核心概念、实操部署、故障排查几个角度把 KRaft 这套东西拆开讲透尽量做到看完能自己搭一套、出问题能自己定位。2. KRaft 的整体设计与核心思路拆解2.1 为什么非要干掉 ZooKeeper要理解 KRaft得先理解 ZooKeeper 模式下的痛点。在旧架构里Kafka 的元数据分成两半一部分存在 ZooKeeper 的 znode 里比如 Broker 列表、Topic 配置、Controller 选举另一部分存在 Controller 的内存里比如分区状态机、副本分配。这两半之间靠 Controller 监听 ZooKeeper 事件来同步问题就出在这个“同步”上。当集群规模变大比如上千个 Broker、几万个分区Controller 需要处理的元数据变更事件会急剧膨胀。ZooKeeper 的 watch 机制在大量事件同时触发时Controller 会收到海量通知然后串行处理很容易成为瓶颈。更麻烦的是Controller 切换时新 Controller 必须先从 ZooKeeper 全量拉取元数据再重建内存状态这个过程中整个集群的元数据操作基本处于半停滞状态。我见过一个中等规模集群Controller 切换一次要花好几分钟期间新建 Topic、分区重分配全部卡住。KRaft 的思路是把元数据当成一条日志流来管理。所有元数据变更都写成一条条记录追加到一个 Raft 日志里然后由 Raft 协议保证这条日志在多个节点之间一致复制。每个节点都按相同顺序回放这条日志最终得到完全一致的状态机。这样一来元数据不再有“两半”而是单一事实来源Controller 也不再是单点瓶颈因为元数据日志本身就是高可用的。2.2 Raft 在 Kafka 里的角色定位Raft 本身是一个共识算法核心解决的是“多个节点如何就一系列操作达成一致”。它把问题拆成三块Leader 选举、日志复制、安全性约束。Kafka 并没有直接照搬某个现成的 Raft 库而是自己实现了一套原因在于 Kafka 的元数据场景有特殊需求。第一个特殊点是元数据日志和消息日志的分离。KRaft 里的 Raft 日志只存元数据不存用户消息。用户消息还是走原来的 Partition 副本机制。这样 Raft 组的负载相对可控不会被消息流量拖垮。第二个特殊点是快照机制。Raft 日志不能无限增长否则重启回放会越来越慢。KRaft 会定期对状态机做快照然后把快照之前的日志截断。快照里存的是当前完整的元数据状态新加入的节点或者落后太多的节点可以直接拉快照不用从第一条日志开始回放。第三个特殊点是动态成员变更。KRaft 支持在运行中调整 Controller 节点集合比如从三节点扩到五节点。这个过程中要保证不出现两个 Leader 同时存在的情况Raft 用联合共识joint consensus的思路来处理Kafka 的实现里叫“动态 Quorum 重配置”。2.3 Controller、Broker、Quorum 三者的关系在 KRaft 模式下节点角色可以分成两类Controller和Broker。Controller 负责元数据管理Broker 负责消息读写。一个节点可以同时扮演两个角色也可以只做其中一个。生产环境里通常会把 Controller 和 Broker 分开部署避免元数据操作和消息流量互相干扰。Controller 们组成一个Quorum也就是 Raft 组。Quorum 里有一个 Active ControllerLeader其余是 Standby。所有元数据写请求都发给 Active Controller它把变更写成日志条目复制给多数派然后应用到自己的状态机。Standby 们持续从 Leader 拉日志保持状态同步。一旦 Leader 挂了Standby 里会重新选出一个 Leader整个过程通常在秒级完成。Broker 则通过一个叫BrokerRegistration的机制向 Quorum 注册自己定期发送心跳。如果 Broker 长时间不心跳Quorum 会把它标记为下线并触发分区 Leader 重选举。这里的关键是Broker 不直接参与 Raft 共识它只是元数据的消费者和生产者通过 Controller 来间接操作元数据。3. 核心概念与关键机制深度解析3.1 日志、任期、索引Raft 的三块基石Raft 日志里的每一条记录都有一个偏移量Offset从 0 开始单调递增。这个偏移量是全局唯一的所有节点上的同一条日志必须有相同的偏移量。日志条目里除了元数据变更内容还带着一个任期号Term。任期号是个单调递增的整数每次 Leader 选举都会加一。任期号的作用是区分不同 Leader 的日志防止旧 Leader 的残留日志被误认为有效。选举过程中候选人会把自己的任期号加一然后向其他节点拉票。其他节点如果发现候选人的任期号比自己大就更新自己的任期号并投票如果发现候选人的日志不如自己新就拒绝投票。这里“日志新不新”的比较规则是先比最后一条日志的任期号任期号大的更新任期号相同再比偏移量偏移量大的更新。这个规则保证了新选出的 Leader 一定拥有最完整的日志不会丢失已经提交的条目。索引Index在 KRaft 里有两个层面。一个是日志偏移量另一个是快照索引。快照是对状态机在某个偏移量上的完整记录。当节点重启时它会先加载最新的快照然后从快照对应的偏移量之后开始回放日志。这样就不用从零开始重建状态启动速度大幅提升。3.2 Leader 选举什么时候选、怎么选、选不出来怎么办Leader 选举的触发条件主要有三个集群启动时没有 Leader、Leader 心跳超时、Leader 主动退位。心跳超时时间由controller.quorum.election.timeout.ms控制默认是 1000 毫秒。也就是说如果 Follower 超过 1 秒没收到 Leader 的心跳就会认为 Leader 挂了开始新一轮选举。选举过程是这样的Follower 先变成 Candidate任期号加一投自己一票然后向其他所有节点发送 RequestVote 请求。其他节点收到请求后先比较任期号再比较日志新旧决定是否投票。如果 Candidate 拿到了多数派的票就变成 Leader开始发送心跳。如果这一轮没选出来就等待一个随机超时controller.quorum.election.backoff.max.ms然后任期号再加一重新发起选举。选不出来最常见的原因是网络分区或者节点数不满足多数派。比如三节点 Quorum 挂了一个剩下两个还能选挂两个剩下一个永远选不出来因为拿不到多数派。这时候集群会进入不可用状态元数据写操作全部阻塞。所以生产环境里 Quorum 节点数必须是奇数三节点能容忍一个故障五节点能容忍两个。3.3 日志复制与提交数据怎么写进去、什么时候算写成功客户端发来的元数据写请求比如创建 Topic会先到 Active Controller。Controller 把请求转成一条日志条目追加到自己的本地日志末尾然后并行发送给所有 Follower。Follower 收到后先写入本地日志然后返回确认。当 Leader 收到多数派的确认后就把这条日志标记为已提交Committed然后应用到状态机最后返回给客户端成功。这里有个关键点已提交的日志一定会被所有未来的 Leader 包含。Raft 通过选举限制来保证这一点——只有拥有最完整日志的节点才能当选 Leader。所以即使某个 Follower 落后很多它也不可能在落后状态下当选从而避免了已提交数据丢失。日志复制是流水线式的Leader 会维护每个 Follower 的nextIndex和matchIndex。nextIndex是下一条要发给该 Follower 的日志偏移量matchIndex是该 Follower 已经确认复制的最高偏移量。如果 Follower 的日志和 Leader 不一致Leader 会逐步回退nextIndex直到找到一致点然后从那里开始覆盖 Follower 的冲突日志。这个过程叫日志修复。3.4 快照机制日志不能无限长怎么截断Raft 日志如果一直不清理磁盘会爆重启回放也会慢到无法接受。KRaft 的解决办法是定期做快照。快照的内容是当前状态机的完整序列化比如所有 Topic 的配置、所有分区的副本分配、所有 Broker 的注册信息。快照生成后对应的日志就可以被截断只保留快照点之后的日志。快照的触发条件由controller.quorum.snapshot.interval.ms控制默认是 10 分钟。也就是说每隔 10 分钟Controller 会把当前状态机做一次快照。如果日志增长太快也可以基于日志条数触发由controller.quorum.snapshot.interval.records控制。新节点加入 Quorum 时如果它的日志落后太多Leader 会直接发一个快照给它而不是逐条回放日志。这个机制叫InstallSnapshot。快照传输是分块的避免一次性传输大文件导致网络阻塞。节点收到快照后先加载快照再从快照点开始拉后续日志。4. 实操部署从零搭一套 KRaft 集群4.1 环境准备与版本选择KRaft 模式从 Kafka 2.8 开始有实验性支持3.3 之后基本稳定3.5 以后生产可用。我建议至少用 3.6 或更高版本因为早期版本在动态 Quorum 重配置和快照恢复上还有一些边界问题。JDK 用 17 或 21 都行Kafka 对 JDK 17 的支持已经很成熟。假设我们要搭一个三节点 Quorum 三节点 Broker 的集群但为了演示方便先用三个节点同时扮演 Controller 和 Broker 角色。每台机器配置 4 核 8G 起步磁盘用 SSD因为 Raft 日志对 fsync 性能比较敏感。网络延迟要低Quorum 节点之间最好在同一个机房或同一个可用区跨机房部署会显著增加选举超时和日志复制延迟。4.2 关键配置项逐条解读KRaft 模式下server.properties里最核心的几个配置如下process.rolescontroller,broker node.id1 controller.quorum.voters1node1:9093,2node2:9093,3node3:9093 listenersPLAINTEXT://node1:9092,CONTROLLER://node1:9093 controller.listener.namesCONTROLLER listener.security.protocol.mapCONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT log.dirs/data/kafka-logs controller.quorum.election.timeout.ms1000 controller.quorum.election.backoff.max.ms1000 controller.quorum.fetch.timeout.ms2000process.roles决定这个节点是 Controller、Broker 还是两者兼有。生产环境建议分开用独立的 Controller 节点避免 Broker 的 IO 压力影响元数据一致性。controller.quorum.voters是静态 Quorum 配置格式是idhost:port所有节点必须配置一致。controller.listener.names指定 Controller 通信用的监听器名称必须和listeners里的对应。controller.quorum.election.timeout.ms是选举超时默认 1000 毫秒。如果网络延迟高可以适当调大比如 2000 毫秒。但调太大意味着故障发现变慢Leader 挂了之后要等更久才能重新选出来。controller.quorum.fetch.timeout.ms是 Follower 拉日志的超时默认 2000 毫秒通常不用改。4.3 格式化与启动流程第一次启动前必须对每个节点做格式化生成初始的元数据目录。命令是bin/kafka-storage.sh random-uuid这个命令会生成一个集群 UUID所有节点必须用同一个 UUID。然后对每个节点执行bin/kafka-storage.sh format -t cluster-uuid -c config/kraft/server.properties格式化会创建log.dirs下的meta.properties文件里面记录了集群 ID 和节点 ID。注意格式化只能在集群第一次启动前做如果已经有数据重新格式化会清空所有元数据相当于把集群重置了。启动顺序上先启动所有 Controller 节点等 Quorum 选出一个 Active Controller 后再启动 Broker 节点。可以用bin/kafka-metadata-quorum.sh --bootstrap-server node1:9092 describe --status查看 Quorum 状态确认 Leader 是谁、Follower 是否同步。4.4 验证集群是否正常集群起来后先创建一个测试 Topicbin/kafka-topics.sh --bootstrap-server node1:9092 --create --topic test-kraft --partitions 3 --replication-factor 3然后查看 Topic 描述确认分区 Leader 和 ISR 都正常。再往 Topic 里发几条消息用 Console Consumer 消费出来验证消息链路没问题。最后可以手动 kill 掉 Active Controller 进程观察 Quorum 是否在几秒内重新选出 LeaderBroker 是否正常重新注册。这个过程能帮你直观感受 KRaft 的故障恢复能力。5. 常见问题与排查技巧实录5.1 Quorum 选不出 Leader 怎么办这是最常见的问题表现是元数据操作全部超时日志里反复出现Election timeout和RequestVote相关记录。第一步先确认 Quorum 节点数和存活数。三节点 Quorum 挂两个剩下一个永远选不出来这是数学上的必然不是 bug。用kafka-metadata-quorum.sh describe --status看当前 Quorum 里有多少节点在线。如果节点都在线但选不出来检查网络连通性。Controller 之间的通信端口默认 9093必须互通防火墙、安全组、DNS 解析都要确认。我遇到过一次三台机器里有一台的 hostname 解析到了错误的 IP导致另外两台收不到它的投票响应选举一直失败。还有一次是 MTU 不匹配小包能通大包被丢日志复制正常但选举请求偶尔超时。5.2 日志复制卡住或延迟高如果 Follower 的matchIndex长时间不推进说明日志复制出了问题。先看 Leader 和 Follower 的磁盘 IORaft 日志写入是 fsync 的磁盘慢会直接拖垮复制速度。用iostat看await和%util如果磁盘利用率长期 100%考虑换 SSD 或降低日志写入频率。另一个常见原因是日志修复循环。如果 Follower 的日志和 Leader 差异太大Leader 会不断回退nextIndex试图找到一致点这个过程可能很慢。如果差异超过快照范围Leader 应该直接发快照而不是逐条回退。检查controller.quorum.snapshot.interval.ms是否设置合理太小会导致频繁快照太大又会导致日志修复变慢。5.3 快照生成失败或加载慢快照生成失败通常是因为磁盘空间不足或者状态机太大。快照文件默认存在log.dirs下的__cluster_metadata-0目录里如果磁盘满了快照写不进去日志就无法截断最终磁盘彻底爆掉。监控磁盘使用率预留至少 30% 的余量。快照加载慢一般发生在节点重启时。如果快照文件很大加载需要时间期间节点无法参与选举。可以调大controller.quorum.election.timeout.ms给节点更多时间完成加载。另外快照文件是二进制格式不要手动修改否则会导致状态机不一致。5.4 动态扩缩容 Quorum 的注意事项KRaft 支持动态调整 Quorum 成员但操作必须谨慎。扩容时先把新节点格式化并启动然后用kafka-metadata-quorum.sh add-controller把它加入 Quorum。缩容时用remove-controller把节点移出。每次变更都会触发一次联合共识过程期间 Quorum 对多数派的要求会临时变化必须确保网络稳定否则容易卡在中间状态。我踩过的一个坑是缩容时一次性移除两个节点结果剩下的节点数不满足多数派整个 Quorum 卡死。正确做法是一次只动一个节点等 Quorum 稳定后再动下一个。另外动态变更期间不要做其他元数据操作比如创建 Topic避免加重 Quorum 负担。5.5 常见问题速查表问题现象可能原因排查手段解决方向元数据操作全部超时Quorum 无 Leader查看 Quorum 状态和节点存活数恢复多数派节点检查网络选举反复失败网络分区或时钟漂移检查 Controller 间连通性和 NTP修复网络同步时钟日志复制延迟高磁盘 IO 瓶颈iostat 看磁盘利用率换 SSD降低 fsync 频率快照生成失败磁盘空间不足df -h 看磁盘使用率清理空间或扩容节点重启后无法加入快照加载超时看日志里的快照加载记录调大选举超时检查快照文件动态扩缩容卡住多数派不满足查看 Quorum 成员列表逐个操作确保多数派在线6. 一些实操心得与避坑建议6.1 监控指标别只看 BrokerQuorum 才是重点很多人监控 Kafka 只看 Broker 的请求延迟、消息吞吐、Consumer Lag但在 KRaft 模式下Quorum 的健康状况才是元数据稳定性的根基。必须监控的指标包括Active Controller 是否频繁切换、选举耗时、日志复制延迟、快照生成耗时和大小、Quorum 节点间的网络 RTT。这些指标在 Kafka 的 JMX 里都有暴露比如kafka.controller:typeKafkaController,nameActiveControllerCount和kafka.server:typeMetadataQuorum,nameCurrentLeader。我建议给 Quorum 相关指标单独配告警。比如 Active Controller 在 5 分钟内切换超过 3 次或者日志复制延迟超过 500 毫秒就应该立即介入。元数据层的问题会迅速放大到整个集群等到 Broker 开始报错再查就晚了。6.2 生产环境一定要 Controller 和 Broker 分离虽然 KRaft 允许一个节点同时做 Controller 和 Broker但生产环境强烈建议分离。原因很简单Broker 承载消息流量磁盘 IO 和网络带宽波动大Controller 需要稳定的低延迟环境来维持 Raft 共识。混部会导致 Broker 的 IO 尖峰影响 Controller 的日志复制进而拖慢整个元数据层。分离部署时Controller 节点配置可以低一些比如 2 核 4G但磁盘一定要用 SSD网络要低延迟。Broker 节点按消息量配置和传统 Kafka 集群一样。三节点 Quorum 是最小生产配置五节点能容忍两个故障适合对可用性要求更高的场景。6.3 升级和迁移要留退路从 ZooKeeper 模式迁移到 KRaft 不是一键操作Kafka 提供了kafka-metadata-quorum.sh和kafka-storage.sh来做迁移但过程比较复杂需要先做元数据快照再逐步切换。我的建议是先在测试环境完整走一遍迁移流程记录每一步的耗时和可能的问题生产环境迁移前做好全量备份包括 ZooKeeper 数据和 Kafka 日志目录迁移过程中保持 ZooKeeper 集群可用一旦 KRaft 出问题可以快速回滚。升级 Kafka 版本时也要注意 KRaft 的兼容性。不同版本之间的 Raft 日志格式可能有变化跨大版本升级要先看官方升级指南确认是否需要中间版本过渡。我见过一次从 3.3 直接升到 3.7结果快照格式不兼容节点起不来最后只能回滚重来。6.4 日志目录的磁盘规划KRaft 的元数据日志和快照都存在log.dirs下和消息数据共用磁盘。如果消息量很大元数据日志可能被挤到磁盘边缘影响写入性能。建议给元数据单独挂一块小容量 SSD通过log.dirs配置指向不同磁盘。元数据日志本身不大几 GB 足够但快照可能会到几十 GB取决于 Topic 和分区的数量。另外log.dirs支持配置多个目录Kafka 会把不同分区的日志分散到不同目录。但元数据日志只会写到一个目录所以多目录对元数据没有帮助。如果元数据磁盘满了整个 Quorum 会停止工作所以这个目录的磁盘使用率要重点监控。6.5 时钟同步不能忽视Raft 本身不依赖绝对时钟但选举超时和心跳超时是基于本地时钟的。如果节点之间时钟漂移太大比如一台机器慢了几秒它可能会误判 Leader 心跳超时频繁发起选举导致集群不稳定。生产环境必须配 NTP 或类似的时钟同步服务确保 Quorum 节点之间的时钟偏差在毫秒级。我遇到过一次时钟漂移导致的问题一台 Controller 的时钟比另外两台慢了 5 秒结果它每隔几秒就发起一次选举虽然选不出来但大量选举请求占用了网络和 CPU导致正常的日志复制也变慢。后来查了半天才发现是 NTP 服务挂了时钟慢慢漂移了。所以时钟同步不仅要配还要监控。6.6 快照和日志的清理策略KRaft 会自动清理快照之前的日志但快照本身不会自动删除。如果快照生成太频繁磁盘上会积累大量快照文件。虽然 Kafka 会保留最近几个快照但旧快照的清理不是实时的。可以手动清理旧快照但一定要保留最新的一个否则节点重启时无法加载状态。日志清理方面controller.quorum.snapshot.interval.ms控制快照频率间接影响日志保留量。如果元数据变更频繁比如大量 Topic 创建删除可以适当调小这个值让快照更频繁日志截断更及时。但快照本身也有开销太频繁会影响 Controller 性能。我的经验是元数据变更不频繁的集群10 分钟一次快照足够变更频繁的可以调到 5 分钟。7. 从原理到实战一次 Controller 频繁切换的排查记录7.1 问题现象与初步判断某天下午监控告警显示 Active Controller 在 10 分钟内切换了 7 次。Broker 日志里大量Controller not available和Metadata update failed部分 Topic 的元数据操作超时。但消息读写本身没受太大影响因为 Broker 缓存了元数据短时间内的元数据不一致还没波及到消息层。先看 Quorum 状态发现三个 Controller 节点都在线但 Leader 频繁易主。查看选举日志发现每次选举的任期号都在快速增长说明选举被反复触发。初步判断是某个 Follower 频繁发起选举导致 Leader 不断退位。7.2 深入排查网络、磁盘、时钟先查网络。用ping和traceroute看 Controller 之间的延迟发现其中两台之间偶尔有 200 毫秒以上的抖动。但 Raft 的选举超时是 1000 毫秒200 毫秒抖动不至于触发选举。继续查磁盘三台机器的磁盘 IO 都正常没有明显瓶颈。然后查时钟。用ntpq -p看 NTP 同步状态发现其中一台机器的偏移量在 300 毫秒左右而且还在缓慢增大。这台机器正是频繁发起选举的那个。时钟漂移导致它的本地时间比另外两台快它认为 Leader 心跳超时了于是发起选举。虽然它选不上但选举请求会干扰 Leader导致 Leader 也误判最终引发连锁反应。7.3 解决与后续加固临时解决很简单重启 NTP 服务强制同步时钟。同步完成后选举立刻停止Controller 恢复稳定。但根本解决要加监控对 NTP 偏移量设告警超过 100 毫秒就通知对选举频率设告警5 分钟内超过 3 次就介入。另外把controller.quorum.election.timeout.ms从 1000 毫秒调到 1500 毫秒给网络抖动和时钟偏差更多容错空间。这个调整的代价是故障发现变慢但在这个场景下稳定性比快速发现更重要。调整后观察了一周没有再出现频繁选举。7.4 这次排查给我的启发Raft 的选举机制对时钟和网络非常敏感而这两个因素在分布式环境里恰恰是最容易出问题的。很多人排查 Kafka 问题习惯只看 Broker 层但在 KRaft 模式下Controller 层的稳定性才是根基。时钟同步、网络质量、磁盘 IO 这三样必须纳入日常巡检。还有一点选举超时不是越小越好。默认 1000 毫秒在大多数环境够用但如果网络质量一般或者时钟同步不够精确适当调大反而更稳。调参的本质是在“快速发现故障”和“避免误判”之间找平衡没有标准答案只能根据实际环境试。8. 关于 KRaft 后续演进的一些观察KRaft 目前已经能覆盖绝大多数 ZooKeeper 模式的场景但还有一些边界情况在完善中。比如超大规模集群下的 Quorum 性能、跨机房部署的延迟优化、动态成员变更的平滑度这些都在持续改进。从社区动向看KRaft 是 Kafka 元数据管理的唯一方向ZooKeeper 模式迟早会退出历史舞台。对普通用户来说现在就可以开始学习和测试 KRaft不用等到必须迁移时才临时抱佛脚。先在测试环境搭一套跑一些元数据操作密集的场景比如批量创建删除 Topic、频繁调整分区副本观察 Quorum 的表现。踩过坑之后生产迁移时心里就有底了。我个人在实际操作中的体会是KRaft 把 Kafka 的元数据层从“黑盒”变成了“白盒”虽然学习曲线陡了一些但一旦理解了 Raft 的日志复制和选举机制排查元数据问题就不再是靠猜了。这套知识不仅对 Kafka 有用对其他基于 Raft 的系统比如 etcd、Consul也有触类旁通的效果。