upgrading-cluster-version

升级集群版本

端到端指导 CockroachDB 版本升级。在提供操作步骤之前，此技能会收集部署上下文，只提供与操作者所在层级相关的步骤。

何时使用此技能

• 规划或执行版本升级（Self-Hosted）
• 通过 Cloud Console 启动主版本升级（Advanced、BYOC）
• 配置补丁的应用方式（Advanced、BYOC）
• 验证升级是否完成（所有层级）
• 决定是完成升级还是回滚（Self-Hosted）

升级前健康检查： 使用 reviewing-cluster-health。 Self-Hosted 升级期间的节点排空： 使用 performing-cluster-maintenance。 维护窗口配置： 使用 performing-cluster-maintenance。

---

第 1 步：收集上下文

必要上下文

问题	选项	重要原因
部署层级？	Self-Hosted、Advanced、BYOC、Standard、Basic	不同层级的升级流程完全不同
当前版本？	例如，v24.2.5	验证升级路径和兼容性

其他上下文（按层级）

如果是 Self-Hosted：

问题	选项	重要原因
升级类型？	主版本（例如，24.2→24.3）、补丁（例如，24.2.5→24.2.8）	主版本升级需要完成升级；补丁升级不需要
目标版本？	例如，v24.3.1	确认版本可用且按顺序升级
部署平台？	裸机、VM、Kubernetes（Operator/Helm/手动）	会影响二进制文件替换和重启流程
进程管理器？	systemd、手动、容器编排器	会影响停止/启动命令
节点数？	数量	会影响升级顺序

如果是 Advanced 或 BYOC：

问题	选项	重要原因
升级类型？	主版本、补丁	主版本升级需要从 Console 启动；补丁升级使用维护窗口
云服务提供商？（仅限 BYOC）	AWS、GCP、Azure	用于升级期间的基础设施级监控
发布渠道？	Regular、Innovation	Innovation 提供最新功能，但支持期限较短

如果是 Standard 或 Basic： 无需其他上下文——升级完全自动进行。

基于上下文的路由

层级	前往
Self-Hosted	Self-Hosted 升级
Advanced	Advanced 升级
BYOC	BYOC 升级
Standard	Standard 升级
Basic	Basic 升级

---

Self-Hosted 升级

适用条件： 层级 = Self-Hosted

主版本与补丁版本

方面	主版本（例如，24.2→24.3）	补丁（例如，24.2.5→24.2.8）
是否需要完成升级	是	否
是否可以回滚	完成升级之前	始终可以（二进制文件替换）
自动完成升级	默认启用（建议禁用）	不适用

升级前验证

# All nodes live, version-consistent, fully replicated
cockroach node status --decommission --certs-dir=<certs-dir> --host=<any-live-node>

在输出中：每个节点都应显示 is_live = true，build 列应只有一个值，并且所有节点的 ranges_underreplicated 都应为 0。

-- No bulk operations running
WITH j AS (SHOW JOBS)
SELECT job_id, job_type, status, now() - created AS running_for FROM j
WHERE status IN ('running', 'paused')
  AND job_type IN ('SCHEMA CHANGE', 'BACKUP', 'RESTORE', 'IMPORT', 'NEW SCHEMA CHANGE');

-- No pending finalization from a previous upgrade
SHOW CLUSTER SETTING cluster.preserve_downgrade_option;

禁用自动完成升级（主版本——建议）

SET CLUSTER SETTING cluster.preserve_downgrade_option = '<current_version>';
-- Example: SET CLUSTER SETTING cluster.preserve_downgrade_option = '24.2';

逐个升级节点（对每个节点重复）

如果进程管理器是 systemd：

cockroach node drain --self --certs-dir=<certs-dir> --host=<node-address>
sudo systemctl stop cockroachdb
cp /path/to/new/cockroach /usr/local/bin/cockroach
cockroach version  # verify new binary
sudo systemctl start cockroachdb

如果是 Kubernetes（Operator）：

kubectl patch crdbcluster <name> --type merge -p '{"spec":{"cockroachDBVersion":"<new-version>"}}'
# Operator handles rolling restart automatically

如果是 Kubernetes（Helm）：

helm upgrade cockroachdb cockroachdb/cockroachdb --set image.tag=<new-version>

如果是 Kubernetes（手动 StatefulSet）：

kubectl set image statefulset/cockroachdb cockroachdb=cockroachdb/cockroach:<new-version>

继续操作下一个节点之前，验证当前节点：

cockroach node status --certs-dir=<certs-dir> --host=<any-live-node> <upgraded-node-id>

目标节点应显示 is_live = true，且 build 为新版本。

监控进度

cockroach node status --certs-dir=<certs-dir> --host=<any-live-node>

比较所有行中的 build 列。仍运行旧版本的节点尚待升级；当每一行都显示新版本时，滚动升级即告完成。

完成升级（仅限主版本 — 不可逆）

通过 cockroach node status 确认 build 列只有一个值（所有节点均已升级）。然后：

RESET CLUSTER SETTING cluster.preserve_downgrade_option;
SHOW CLUSTER SETTING version;  -- Monitor until updated

回滚（仅限完成升级前）

确认 cluster.preserve_downgrade_option 仍返回旧版本，然后将每个节点的二进制文件替换为先前版本并重启。所有节点恢复后：

RESET CLUSTER SETTING cluster.preserve_downgrade_option;

---

高级升级

**适用范围：**层级 = Advanced

Advanced 集群由 Cockroach Labs 管理。你可以发起主版本升级；补丁会自动应用。

主版本升级

1. Cloud Console → Cluster → Settings → Upgrade
2. 选择目标版本
3. CRL 自动在各节点上执行滚动升级
4. 在 Cloud Console 中监控进度
5. 测试完成后，通过 Cloud Console 完成升级

升级期间的验证：

cockroach node status --certs-dir=<certs-dir> --host=<any-live-node>

统计 build 列，查看有多少节点运行新版本，有多少运行旧版本。

补丁升级

补丁会在配置的维护时段内自动应用。有关维护时段配置和推迟补丁的信息，请参阅 performing-cluster-maintenance。

发布渠道

• **Regular：**注重稳定性，支持期限较长
• **Innovation：**提供最新功能，支持期限较短，可以跳过

通过 Cloud Console → Cluster → Settings → Upgrades 进行配置。

在支持终止前升级

你有责任在当前版本达到支持终止（EOS）之前发起主版本升级。未能在 EOS 前升级可能会影响 SLA 保证。

Cloud API

# Check current version
curl -s -H "Authorization: Bearer $COCKROACH_API_KEY" \
  "https://cockroachlabs.cloud/api/v1/clusters/<cluster-id>" | jq '.cockroach_version'

---

BYOC 升级

**适用范围：**层级 = BYOC

BYOC 升级流程与 Advanced 相同。请遵循所有 Advanced Upgrade 步骤。

升级期间的云提供商监控

由于 BYOC 集群运行在你的云账户中，你可以在自己的基础设施中观察滚动升级：

**如果使用 AWS：**EC2 控制台会显示实例重启；CloudWatch 指标会显示节点轮换期间的短暂下降。

**如果使用 GCP：**Compute Engine 控制台会显示 VM 重启；Cloud Monitoring 会显示实例级事件。

**如果使用 Azure：**Azure 门户会显示 VM 重启；Azure Monitor 会记录实例事件。

BYOC 的其他注意事项

• 确认 PrivateLink/PSC/VPC Peering 连接在升级期间保持正常
• 预留实例和承诺使用折扣不受影响（实例类型不会改变）

---

Standard 升级

**适用范围：**层级 = Standard

Standard 是一项多租户托管服务。你无需管理节点或基础设施。所有升级——包括主版本和补丁——均由 Cockroach Labs 自动应用。

• 仅提供 Regular 版本（无 Innovation 渠道）
• 无法配置维护时段
• 无法推迟升级
• 升级期间不会停机

升级后

1. 在 Cloud Console 中监控升级通知
2. 查看发行说明，了解行为变更
3. 验证应用兼容性：

   SELECT version();
   

---

Basic 升级

**适用范围：**层级 = Basic

Basic 是一项无服务器服务。所有升级均由系统全权管理且对用户透明。无服务器架构旨在实现零停机升级，无需客户采取任何操作。

升级后

1. 查看发行说明，了解行为变更
2. 如有需要，验证版本：SELECT version();

---

安全注意事项

操作	层级	可逆？
设置 preserve_downgrade_option	SH	是
替换节点二进制文件	SH	是（完成升级前可换回）
完成升级	SH	否 — 不可逆
发起 Cloud Console 升级	ADV/BYOC	联系支持团队进行讨论
自动升级	STD/BAS	N/A（由 CRL 管理）

重要：

• 绝不要跳过主版本（SH）——升级必须按顺序进行
• 测试前绝不要完成升级（SH）——完成升级不可逆
• 升级期间绝不要更改集群设置（SH、ADV、BYOC）

故障排查

问题	层级	修复方法
无法设置 preserve_downgrade_option	SH	值必须与 SHOW CLUSTER SETTING version 的输出一致
最终确定卡住	SH	取消失效节点的服务；确保所有正常运行的节点都已升级
提前触发自动最终确定	SH	无法撤销；在新版本上测试应用程序
Console 中没有可用升级	ADV/BYOC	查看发布计划；联系支持团队
自动升级后行为发生变化	STD/BAS	查看发行说明；联系支持团队

参考资料

相关技能：

• 检查集群运行状况 — 升级前后的运行状况
• 执行集群维护 — 节点排空（SH）和维护时段（ADV/BYOC）
• 管理集群设置 — preserve_downgrade_option

CockroachDB 官方文档：

• 升级自托管版本
• 升级云集群
• 云升级策略
• 在 Kubernetes 上升级