reviewing-cluster-health

检查集群健康状况

全面检查 CockroachDB 集群的健康状况。运行诊断前，此技能会收集部署环境信息，以便为操作员所在层级提供合适的查询和工具。

何时使用此技能

• 每日或每班开始时进行运维健康检查
• 开始维护前（Self-Hosted、Advanced、BYOC）
• 事件发生后确认已恢复
• 验证生产就绪情况
• 监控容量和性能

对于实时查询问题： 使用 triaging-live-sql-activity。 对于后台作业： 使用 monitoring-background-jobs。 对于范围分析： 使用 analyzing-range-distribution。

---

步骤 1：收集环境信息

必需的环境信息

问题	选项	重要原因
部署层级？	Self-Hosted、Advanced、BYOC、Standard、Basic	决定可用的诊断方式和操作员职责
健康检查的原因？	每日检查、维护前、事件后、升级前	决定优先检查哪些方面

其他环境信息（按层级）

如果是 Self-Hosted：

问题	选项	重要原因
是否有访问权限？	SQL + CLI、仅 SQL	决定可以使用哪些工具
云服务提供商？	AWS、GCP、Azure、本地部署	影响基础设施层面的检查
是否部署在 Kubernetes 上？	是（Operator、Helm、手动）、否	会改变 CLI 命令和监控方式
节点数量和区域？	例如，9 个节点、3 个区域	为查询结果设定预期

如果是 Advanced 或 BYOC：

问题	选项	重要原因
云服务提供商？（仅限 BYOC）	AWS、GCP、Azure	用于监控你云账户中的基础设施

如果是 Standard：

问题	选项	重要原因
当前已预配的 vCPU 数量？	数量	为计算资源利用率评估提供背景信息

如果是 Basic： 无需其他环境信息。

按环境信息选择路径

层级	前往
Self-Hosted	Self-Hosted 健康检查
Advanced	Advanced 健康检查
BYOC	BYOC 健康检查
Standard	Standard 健康检查
Basic	Basic 健康检查

---

Self-Hosted 健康检查

适用条件： 层级 = Self-Hosted

Self-Hosted 节点级健康状况主要通过 cockroach node status（CLI）和 DB Console 查看。集群设置和作业通过公开 SQL（SHOW ALL CLUSTER SETTINGS、SHOW JOBS）查看。用于查看集群拓扑、存储和证书的 crdb_internal 虚拟表不适用于生产环境——请参阅文档了解可用于生产环境的表。

检查 1：节点存活状态、版本和复制

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

关键列：

• is_live — false 表示需要立即调查
• is_draining、is_decommissioning、membership — 标记正在进行的生命周期操作
• started_at — 对比多次运行的结果，以发现节点抖动（节点重启）
• build — 每个节点的版本；应只有一个值（滚动升级期间可能有两个）
• ranges_underreplicated — 非零表示范围副本数低于区域配置的 num_replicas

如需更细致的范围分类，请使用 DB Console 中的 Replication 页面。

检查 2：存储容量

没有可在生产环境安全使用的 SQL 视图可以显示每个存储节点的容量。请使用：

• DB Console 概览 → 存储，查看每个节点的用量
• 每个节点上的 Prometheus 指标端点：curl -ks https://<node>:8080/_status/vars | grep '^capacity'（capacity、capacity_used、capacity_available）

检查 3：证书到期时间

没有 SQL 视图可以显示节点证书的到期时间。请使用以下任一方式：

• cockroach cert list --certs-dir=<certs-dir>，在每个节点本地检查证书
• openssl x509 -in <cert.crt> -noout -enddate，检查单个证书文件
• Prometheus 指标端点：curl -ks https://<node>:8080/_status/vars | grep '^security_certificate_expiration_'（UNIX 时间戳，单位为秒；node、ca、client_ca、ui_ca）

将 90 天内到期的证书视为 EXPIRING_SOON。

检查 4：关键设置

SELECT variable, value FROM [SHOW ALL CLUSTER SETTINGS]
WHERE variable IN (
  'kv.rangefeed.enabled', 'sql.stats.automatic_collection.enabled',
  'server.time_until_store_dead', 'admission.kv.enabled',
  'cluster.preserve_downgrade_option'
) ORDER BY variable;

gc.ttlseconds 是区域配置参数，而非集群设置；请针对相关表、数据库或范围使用 SHOW ZONE CONFIGURATION FOR ... 检查生效值。

检查 5：汇总概览

DB Console 的 集群概览 页面汇总了存活/故障节点数、版本分布、范围数和存储信息。使用 CLI：

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

然后在 shell 中汇总所需列。集群的逻辑版本可通过 SQL 获取：

SELECT value AS cluster_version FROM [SHOW CLUSTER SETTING version];

如果原因为维护前检查，还要检查正在运行的作业：

WITH j AS (SHOW JOBS)
SELECT job_type, COUNT(*) FROM j WHERE status = 'running' GROUP BY job_type;

检查 6：生产就绪情况评估

在验证集群是否已准备好承载生产工作负载，或进行定期运营评审时使用。

# Node count, liveness, and locality diversity
cockroach node status --decommission --certs-dir=<certs-dir> --host=<any-live-node>

在输出中，统计 is_live = true 的行数（生产环境要求 ≥ 3），并检查 locality 是否显示了多个区域/可用区。

-- Critical production settings check
SELECT variable, value,
  CASE
    WHEN variable = 'kv.rangefeed.enabled' AND value = 'true' THEN 'OK'
    WHEN variable = 'kv.rangefeed.enabled' AND value = 'false' THEN 'WARN: should be true for CDC'
    WHEN variable = 'sql.stats.automatic_collection.enabled' AND value = 'true' THEN 'OK'
    WHEN variable = 'sql.stats.automatic_collection.enabled' AND value = 'false' THEN 'WARN: should be true'
    WHEN variable = 'admission.kv.enabled' AND value = 'true' THEN 'OK'
    WHEN variable = 'admission.kv.enabled' AND value = 'false' THEN 'WARN: recommended for production'
    WHEN variable = 'cluster.preserve_downgrade_option' AND value != '' THEN 'INFO: finalization pending'
    ELSE 'OK'
  END AS assessment
FROM [SHOW ALL CLUSTER SETTINGS]
WHERE variable IN (
  'kv.rangefeed.enabled', 'sql.stats.automatic_collection.enabled',
  'admission.kv.enabled', 'cluster.preserve_downgrade_option',
  'server.time_until_store_dead'
) ORDER BY variable;

-- Enterprise license status (Self-Hosted only)
SELECT value AS organization FROM [SHOW CLUSTER SETTING cluster.organization];

完整的生产就绪检查清单请参阅生产就绪参考。

---

高级健康检查

**适用条件：**层级 = Advanced

Advanced 集群是由 Cockroach Labs 管理的专用单租户集群。你可通过 Cloud Console 和 SQL 查看节点级信息。

Cloud Console 检查

1. 集群概览——确认所有节点均处于存活状态，并检查节点数
2. 指标——CPU 利用率、QPS、P99 延迟、存储利用率
3. 告警——检查是否有活动告警

CLI + SQL 检查

# Node liveness, version, and replication status
cockroach node status --decommission --certs-dir=<certs-dir> --host=<any-live-node>

检查每个节点的 is_live、build 和 ranges_underreplicated。

-- Recent failed jobs
WITH j AS (SHOW JOBS)
SELECT job_type, status, COUNT(*) FROM j
WHERE status IN ('running', 'failed') AND created > now() - INTERVAL '24 hours'
GROUP BY job_type, status;

Cloud API

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

---

BYOC 健康检查

**适用条件：**层级 = BYOC

BYOC 集群是专用集群，运行在你的云账户中。你可获得与 Advanced 相同的 CockroachDB 可见性，以及对底层基础设施的直接访问权限。

CockroachDB 健康状况

执行高级健康检查中的所有步骤。

云服务商基础设施检查

如果使用 AWS：

aws ec2 describe-instance-status --filters "Name=tag:cockroach-cluster,Values=<cluster-name>"

如果使用 GCP：

gcloud compute instances list --filter="labels.cockroach-cluster=<cluster-name>"

如果使用 Azure：

az vm list --resource-group <rg> --query "[?tags.cockroachCluster=='<cluster-name>']"

BYOC 其他检查

• 验证 VPC/网络连接（PrivateLink、PSC、VPC Peering）
• 检查 IAM 角色，确认 CRL 服务账户权限仍然有效
• 查看云服务商的监控信息，检查基础设施层面的异常

---

Standard 健康检查

**适用条件：**层级 = Standard

Standard 是一项多租户托管服务。没有需要监控的独立节点——Cockroach Labs 负责管理所有基础设施、复制和容量。健康检查侧重于工作负载性能和已配置的计算资源。

Cloud Console 检查

1. 集群概览——确认集群状态为 RUNNING
2. SQL 活动——语句和事务延迟、错误率
3. 存储——当前用量
4. 计算资源——已配置 vCPU 的利用率

SQL 检查

-- Verify connectivity
SELECT 1;

-- Current version
SELECT version();

-- Recent failed jobs
WITH j AS (SHOW JOBS)
SELECT job_type, status, description FROM j
WHERE status = 'failed' AND created > now() - INTERVAL '24 hours';

监控内容

• P99 SQL 延迟——通过 Cloud Console Metrics 跟踪
• 错误率——检查语句错误是否激增
• 存储增长——根据用量趋势制定计划
• 计算资源利用率——如果利用率持续偏高，请增加已配置的 vCPU 数量

**注意：**Standard 不提供节点级可见性。请使用 Cloud Console 监控所有基础设施健康状况。

---

基本健康检查

适用于： Tier = Basic

Basic 是一种无服务器服务，可自动扩展。没有需要监控的节点或预配计算资源。Cockroach Labs 管理所有基础设施。健康检查重点关注连接性、消耗量和支出。

Cloud Console 检查

1. 集群概览 — 确认状态为 RUNNING
2. 请求单元 — 查看消耗速率和剩余预算
3. 存储 — 查看当前用量（包含 10 GiB 免费额度）
4. 支出限额 — 确认已配置限额，以避免意外费用

SQL 检查

-- Verify connectivity
SELECT 1;

-- Current version
SELECT version();

-- Recent failed jobs
WITH j AS (SHOW JOBS)
SELECT job_type, status, description FROM j
WHERE status = 'failed' AND created > now() - INTERVAL '24 hours';

监控事项

• 请求单元（RU）消耗量 — 通过 Cloud Console 跟踪，以确保不超出支出限额
• 存储用量 — 监控相对于 10 GiB 免费额度的增长情况
• 查询效率 — 优化消耗过多 RU 的查询
• 冷启动延迟 — Basic 集群在不活动期间可能会缩容至零；空闲后首次连接的延迟可能较高

---

安全注意事项

此技能中的所有检查均为只读操作，不会修改数据。

• Self-Hosted： cockroach node status 需要 CLI 访问权限（如果需要改用内部表，则需要管理员 SQL 权限）。大多数节点级健康查询都没有适用于生产环境的 SQL 替代方案。
• Advanced/BYOC： cockroach node status 的工作方式相同；证书检查由 Cockroach Labs 管理。
• Standard/Basic： 按设计不提供节点级可见性 — 请使用 Cloud Console。

故障排除

问题	Tier	解决方法
cockroach node status 因权限被拒绝而报错	SH	使用具有管理员权限或 VIEWCLUSTERMETADATA 权限的证书
cockroach node status 输出中缺少节点	SH	检查节点进程；确认 --join 地址
Standard/Basic SQL 不公开节点表	STD/BAS	这是预期行为 — 请使用 Cloud Console
Cloud Console 显示状态降级	ADV/BYOC	查看 Cloud 状态页面；联系支持团队
RU 消耗量过高	BAS	分析查询；设置支出限额
Cloud API 返回 401	ADV/BYOC	重新生成 API 密钥
首次连接延迟较高	BAS	空闲后冷启动属于预期情况

参考资料

技能参考：

• 生产就绪清单

相关技能：

• 升级集群版本
• 管理集群容量
• 执行集群维护
• 监控后台作业

CockroachDB 官方文档：

• 监控与告警
• cockroach node status
• 生产环境检查清单
• Cloud Console 监控
• 导出指标（Advanced）