如何排查CockroachDB集群无法完成版本升级的问题？

1. 确认所有节点的二进制版本一致性 #

• 在集群每个节点上执行cockroach version，检查输出版本是否与预期的新版本完全一致
• 若存在节点仍运行旧版本二进制，需确认该节点是否已完成重启、二进制文件是否正确替换
• 滚动升级场景下，必须确保所有旧版本节点已完成重启并重新加入集群，未下线的旧节点会直接阻碍集群版本推进

2. 检查降级保留选项状态 #

• 执行SHOW CLUSTER SETTING cluster.preserve_downgrade_option，该参数用于限制集群实际运行版本，确保对旧节点的兼容性
• 如果返回值为旧版本号，说明集群仍处于兼容旧节点的状态，SHOW CLUSTER SETTING version会显示这个限制版本而非二进制版本
• 解决步骤：先确认所有节点均已升级至新版本，再执行SET CLUSTER SETTING cluster.preserve_downgrade_option = 'none';解除版本限制

3. 验证集群节点健康状态 #

• 执行cockroach node status，查看所有节点的状态是否为live
• 若存在节点处于decommissioning、unavailable状态，集群无法完成升级的最终元数据同步步骤
• 针对异常节点：可尝试修复并重新加入集群；若节点已废弃，需执行cockroach node decommission <node-id>完成彻底下线

4. 排查节点升级日志 #

• 查看每个节点的CockroachDB日志（默认路径为logs/cockroach.log），搜索upgrade、version相关关键词
• 重点关注leader节点日志，检查是否存在升级步骤失败、版本协商报错等信息
• 常见报错如upgrade step failed、mismatched node versions会直接指向升级失败的具体原因

5. 检查系统元数据版本 #

• 执行SELECT version FROM system.descriptor WHERE id = 1;，确认元数据版本是否与二进制版本匹配
• 若元数据版本仍为旧版本，说明升级过程中的元数据迁移步骤未完成，需结合日志排查迁移失败原因

6. 分析新功能报错的具体信息 #

• 提取报错的完整内容，若报错包含requires version X but cluster is running version Y，则直接对应集群运行版本被cluster.preserve_downgrade_option限制的情况
• 根据报错提示的版本差异，回到前面的步骤确认节点版本和降级选项设置

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