Kafka KRaft启动时遇UnwritableMetadataException问题求助

1. 元数据版本兼容性检查 #

• 确认集群所有节点的inter.broker.protocol.version和log.message.format.version配置统一为3.7（对应KRaft元数据版本3.7-IV3）。容器重启后可能因配置挂载异常，节点加载了旧版本配置（如3.5），引发版本不匹配。
• 执行命令查看节点元数据版本：kafka-metadata-shell.sh --snapshot /path/to/meta.properties，检查metadata.version字段是否为3.7-IV3。

2. 副本目录状态验证 #

• 检查重启节点的日志目录挂载权限：Docker重启后宿主目录权限可能变更，导致容器内kafka用户无读写权限，引发副本目录无法被识别。
• 核对log.dirs配置对应的目录，确认每个目录下的meta.properties和分区数据是否完整，无缺失或损坏。

3. KRaft元数据存储一致性排查 #

• 对比重启节点与正常节点的元数据快照（meta.properties）和日志文件（kafka-metadata.log），若存在差异，可将正常节点的元数据快照拷贝至重启节点（先停节点），替换后尝试重启。
• 确认节点process.roles配置正确性：重启节点的角色（controller/broker）必须与集群配置一致，角色不匹配会导致元数据同步异常。

4. Docker启动参数校验 #

• 验证容器启动时KAFKA_NODE_ID、KAFKA_CONTROLLER_QUORUM_VOTERS等KRaft核心参数是否正确传递，重启后无参数遗漏或错误。
• 检查容器网络连通性：重启后节点需能正常访问集群其他节点，网络隔离会导致元数据同步失败。

5. 元数据修复操作（测试环境谨慎执行） #

• 若确认是元数据版本不兼容，先统一所有节点配置为3.7，再在正常运行的controller节点执行kafka-metadata-upgrade.sh --bootstrap-server <controller-addr:port> --upgrade，完成后重启所有节点。
• 若副本目录损坏，可删除损坏的分区目录，让节点从其他副本同步数据（此操作会丢失未同步数据，仅限测试环境）。

内容的提问来源于stack exchange，提问作者tobiasbhn