performing-cluster-maintenance

执行集群维护

管理所有部署层级的计划性集群维护。对于 Self-Hosted，这意味着排空并重启各个节点。对于 Advanced/BYOC，这意味着为通过 CRL 应用的补丁配置和管理维护窗口。对于 Standard 和 Basic，维护由系统全权管理，无需客户采取任何操作。

何时使用此技能

• 规划操作系统补丁、硬件变更或配置更新（Self-Hosted）
• 配置或修改维护窗口（Advanced、BYOC）
• 设置补丁延期策略（Advanced、BYOC）
• 在 CRL 管理的维护事件期间进行监控（Advanced、BYOC）
• 执行维护前验证检查（Self-Hosted、Advanced、BYOC）
• 了解维护对应用程序的影响（所有层级）
• 为维护事件准备应用程序（所有层级）

如需永久移除节点： 使用 managing-cluster-capacity。 如需维护前健康检查： 使用 reviewing-cluster-health。 如需升级版本： 使用 upgrading-cluster-version。

---

步骤 1：收集上下文

必需的上下文

问题	选项	重要性
部署层级？	Self-Hosted、Advanced、BYOC、Standard、Basic	决定维护流程
目标？	规划维护、配置维护窗口、延期补丁、维护期间监控、准备应用程序	指向相应流程

其他上下文（按层级）

如果是 Self-Hosted：

问题	选项	重要性
维护类型？	操作系统补丁、硬件变更、二进制文件升级、配置变更、计划重启	影响操作顺序和维护后的步骤
部署平台？	裸机、VM、Kubernetes（Operator/Helm/手动）	会改变排空和重启命令
进程管理器？	systemd、手动、容器编排器	会改变停止/启动命令
目标节点 ID？	节点 ID	排空命令必需
是否预期有长时间运行的查询？	是（增加排空超时时间）、否（默认超时时间）	决定 drain-wait 参数

如果是 Advanced 或 BYOC：

问题	选项	重要性
是否已配置维护窗口？	是（具体安排）、否	决定是否需要设置维护窗口
是否有待处理的补丁？	是、否、不确定	决定紧急程度
云服务提供商？（仅 BYOC）	AWS、GCP、Azure	用于基础设施层面的监控

如果是 Standard 或 Basic： 无需上下文 — 维护由系统全权管理。

根据上下文选择流程

层级	前往
Self-Hosted	Self-Hosted 节点维护
Advanced	Advanced 维护管理
BYOC	BYOC 维护管理
Standard	Standard 维护
Basic	Basic 维护

---

Self-Hosted 节点维护

适用条件： 层级 = Self-Hosted

Self-Hosted 运维人员直接管理所有维护工作。核心操作是排空节点，以便在停止节点前安全迁移租约和连接。

维护前检查

在执行任何维护操作前运行所有检查。如果任何检查失败，请停止。

检查 1-3、5（节点存活状态、排空状态、复制、版本一致性）：

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

输出中的停止条件：

• 出现任何 is_live = false（检查 1）
• 出现任何 is_draining = true（检查 2）
• 出现任何 ranges_underreplicated > 0（检查 3）
• build 列中存在多个不同的值（检查 5）

检查 4：没有正在运行的中断性作业（继续前等待或暂停）：

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');

检查 6：存储利用率安全（如果任何节点超过 70%，则发出警告）：

没有适用于生产环境的 SQL 视图可显示每个存储的容量。请使用 DB Console Overview → Storage 页面，或抓取每个节点的 Prometheus 端点：

curl -ks https://<node>:8080/_status/vars | grep -E '^capacity( |_used|_available)'

停止条件： 如果任何节点未处于存活状态、范围副本不足、另一个节点正在排空，或正在进行滚动升级，请勿继续维护。等待正在运行的作业完成，或将其暂停。

请参阅 维护前检查参考，了解汇总的维护前检查脚本。

执行排空

如果平台 = 裸机或 VM：

cockroach node drain --self --certs-dir=<certs-dir> --host=<node-address>

如果预计会有长时间运行的查询：

cockroach node drain --self --certs-dir=<certs-dir> --host=<node-address> --drain-wait=60s

如果平台 = Kubernetes：

# Operator handles drain automatically during pod eviction
kubectl delete pod <pod-name>
# Or for rolling restart:
kubectl rollout restart statefulset cockroachdb

停止、维护、重启

如果进程管理器 = systemd：

sudo systemctl stop cockroachdb
# ... perform maintenance ...
sudo systemctl start cockroachdb

如果进程管理器 = 手动：

kill -TERM $(pgrep -f 'cockroach start')
# ... perform maintenance ...
cockroach start --certs-dir=<certs-dir> --store=<path> --join=<addresses> --background

除非进程对 SIGTERM 没有响应，否则绝不要使用 kill -9。

重启后验证

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

重启的节点应显示 is_live = true。在接下来的几分钟内，该节点的 replicas_leaseholders 列值应随着租约重新平衡而增加。

请参阅 排空详情参考，了解排空阶段、超时配置和高级监控。

存储维护

自托管集群的定期存储维护：

Ballast 文件验证：

ls -lh <store-path>/auxiliary/EMERGENCY_BALLAST
# If missing, create: cockroach debug ballast <store-path>/auxiliary/EMERGENCY_BALLAST --size=1GiB

磁盘利用率检查：

请使用 DB Console Overview → Storage 页面，或每个节点的 Prometheus 端点：

curl -ks https://<node>:8080/_status/vars | grep -E '^capacity( |_used|_available)'

应在维护前处理利用率超过 70% 的节点——排空节点会暂时增加其余节点的负载。

---

高级维护管理

适用条件： Tier = Advanced

高级集群由 Cockroach Labs 管理。CRL 会在配置的维护时段内应用补丁并执行基础设施维护。您无需排空或重启节点——CRL 会通过滚动重启处理这些操作。

配置维护时段

1. Cloud Console → Cluster → Settings → Maintenance
2. 设置每周 6 小时的时段
   • 选择星期几（例如，星期日）
   • 选择 UTC 开始时间（例如，02:00 UTC）
   • 时段时长为 6 小时

如果未配置时段，CRL 会自行选择时间应用补丁。

查看当前维护时段

Cloud Console → Cluster → Settings → Maintenance 会显示当前计划。

Cloud API：

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

延后补丁

如果需要延后待应用的补丁（例如，为了进行测试）：

1. Cloud Console → Cluster → Settings → Upgrades
2. 选择延后期限：30、60 或 90 天

延后的补丁仍会在延后期限结束时应用。延后只会推迟补丁应用，不会跳过补丁。

维护期间会发生什么

1. CRL 通过滚动重启应用补丁——每次处理一个节点
2. 每个节点会先排空（迁移连接和租约），然后更新并重启
3. 整个过程中集群始终保持可用（多节点集群）
4. 由于容量暂时减少，时段内的性能可能略有下降

单节点集群在维护期间会停机。对于生产工作负载，请考虑扩展至 3 个或更多节点。

维护期间监控

Cloud Console：

• Cluster Overview 会显示滚动重启期间的节点状态
• Metrics 页面会显示 QPS 和容量的暂时下降
• 短暂的节点不可用可能会触发告警

维护期间：

# Check which nodes are currently live and what version they're on
cockroach node status --decommission --certs-dir=<certs-dir> --host=<any-live-node>

最佳实践

• 安排在流量最低的时段
• 在维护时段期间及之后监控 P99 延迟
• 在生产环境部署前，先在预发布集群中测试补丁
• 使用延期功能，使维护与测试及发布节奏保持一致
• 配置告警，确保在维护时段内收到通知
• 确保应用实现带指数退避的连接重试

---

BYOC 维护管理

适用于： Tier = BYOC

BYOC 维护遵循与 Advanced 相同的 CRL 管理流程。请按照Advanced 维护管理中的所有步骤，配置维护时段、延期补丁并进行监控。

云服务提供商可见性

由于 BYOC 集群运行在您的云账户中，您可以直接查看维护操作：

如果使用 AWS：

• EC2 控制台会显示滚动补丁期间的实例重启
• CloudWatch 指标会显示节点轮换期间的短暂下降
• 为实例状态变化设置 CloudWatch Alarms

如果使用 GCP：

• Compute Engine 控制台会显示 VM 重启
• Cloud Monitoring 会显示实例级事件
• 为实例运行时间配置告警策略

如果使用 Azure：

• Azure 门户会显示 VM 轮换
• Azure Monitor 会捕获实例重启事件
• 为 VM 可用性设置 Azure Alerts

BYOC 基础设施维护

对于 CRL 不管理的云账户基础设施变更（VPC、安全组、IAM、DNS）：

• 在进行可能影响集群的变更前，请与 CRL 协调
• 请勿修改 CRL 管理的资源（实例、磁盘、网络接口）
• 先在预发布 BYOC 集群中测试基础设施变更
• 网络变更（PrivateLink、PSC、VPC Peering）可能需要与 CRL 协调

---

Standard 维护

适用于： Tier = Standard

Standard 是多租户托管服务。没有节点，无需配置维护时段，也无需延期补丁。Cockroach Labs 会透明地管理所有维护工作。

预期情况

• 补丁由 CRL 选择在低流量时段应用
• 维护期间不会停机
• 常规补丁无需通知客户
• 主版本升级也会自动进行

应用准备

• 实现带指数退避的连接重试逻辑
• 妥善处理短暂的延迟波动
• 关注 Cloud Console 中的服务通知

---

Basic 维护

适用于： Tier = Basic

Basic 是无服务器服务。所有维护均由 Cockroach Labs 全权管理。无服务器架构旨在实现零停机维护。

预期情况

• 所有补丁和升级都以透明方式进行
• 无需客户采取任何操作
• 无需维护通知

应用准备

• 实现连接重试逻辑（建议所有生产应用都这样做）
• 请注意，空闲集群可能会缩容至零 — 非活动后首次重新连接时延迟可能较高（这与维护无关）

---

安全注意事项

所有层级上的只读监控查询都是安全的。

自托管节点维护：

• 每次仅排空一个节点
• 排空开始后无法取消
• 应用必须实现连接重试逻辑
• 负载均衡器会通过 /health?ready=1 返回错误来检测已排空的节点
• 除非进程对 SIGTERM 无响应，否则绝不要使用 SIGKILL

Advanced/BYOC 维护时段：

• 单节点集群在维护期间会停机
• 补丁延期过久会延误安全修复 — 请评估 CVE 影响
• 维护时段期间请勿修改 CRL 管理的基础设施

Standard/Basic： 客户无需承担维护风险 — 所有维护均由 CRL 全权管理。

详细风险矩阵请参阅 安全指南参考。

故障排查

问题	层级	解决方法
排空速度很慢	SH	检查 SHOW CLUSTER STATEMENTS，查看是否有卡住的查询
排空卡住	SH	检查日志；如果没有响应，则发送 SIGTERM
重启后节点无法重新加入	SH	验证 --join 标志；检查网络连接
租约未返回节点	SH	等待 5-10 分钟；监控 lease_count
客户端未重新连接	SH	验证负载均衡器的运行状况检查是否通过
错过维护时段	ADV/BYOC	联系支持团队
在维护时段外进行意外维护	ADV/BYOC	可能会在维护时段外应用紧急补丁；查看 Cloud Console 通知
维护期间出现延迟	ADV/BYOC	属于预期情况——容量会暂时降低；监控并验证维护时段结束后是否恢复

参考资料

技能参考：

• 排空阶段和超时时间
• 维护前检查
• 安全指南

相关技能：

• 检查集群运行状况
• 管理集群容量
• 升级集群版本

CockroachDB 官方文档：

• 节点关闭
• cockroach node drain
• 管理 Advanced Cluster
• Cloud 升级策略