CockroachDB集群故障求助：副本GC超时+集群组建失败及调试模式开启

问题 #

在GCP的GKE Kubernetes集群上通过Helm部署了3节点CockroachDB集群（版本：22.2.14，Helm Chart版本：6.0.3），突然Pod出现异常，集群无法正确组建。所有Pod已优雅重启，但仍出现以下错误：

E240708 09:53:55.048576 277 kv/kvserver/queue.go:1127 ⋮ [n1,replicaGC,s1,r755/1:‹/Table/61{0-1}›] 1 ‹operation “replicaGC queue process replica 755” timed out after 1m0.001s (given timeout 1m0s)›: aborted in DistSender: context deadline exceeded
initiating graceful shutdown of server
too early to drain; used hard shutdown instead

需解决集群异常问题，同时咨询如何开启CockroachDB调试模式，以及除查看日志外的其他排查措施。

一、解决集群组建失败问题 #

• 验证节点网络连通性：确认所有CockroachDB Pod间TCP 26257（集群通信端口）和8080（HTTP端口）可正常互通。进入目标Pod执行cockroach node status --host=<目标PodIP>:26257测试节点状态，或用nc -zv <目标PodIP> 26257验证端口可达性。
• 调大Replica GC超时阈值：当前错误显示Replica GC队列处理超时，可通过Helm临时调整超时参数：

  helm upgrade cockroachdb cockroachdb/cockroachdb --set args="--replica-gc.queue-timeout=2m"
  

  也可修改Helm values.yaml的args字段添加该参数后重新部署。
• 清理异常副本：若r755副本持续引发问题，进入可运行的Pod执行SQL命令定位并清理：
  1. 进入Pod：kubectl exec -it <正常Pod名> -- cockroach sql --host=<PodIP>:26257
  2. 查询副本信息：SELECT * FROM crdb_internal.replicas WHERE replica_id = 755;
  3. 确认无效后删除：ALTER TABLE system.replicas DELETE WHERE replica_id = 755;（操作前需确认副本已失效）
• 检查资源配额：查看Pod资源使用情况：kubectl top pod -l app.kubernetes.io/name=cockroachdb，若CPU/内存不足，调整Helm的resources配置，提高资源请求和限制值。

二、开启CockroachDB调试模式 #

• 通过Helm部署时配置：升级或部署时添加调试日志参数：

  helm upgrade cockroachdb cockroachdb/cockroachdb --set args="--v=2 --vmodule=kv=2,kvserver=2,replica=2"
  

  其中--v=2为全局日志级别，--vmodule可指定特定模块（如kv、kvserver）的调试级别。
• 临时修改运行中Pod：无需重新部署的情况下，进入Pod调整启动参数后重启：
  1. 进入Pod：kubectl exec -it <CockroachDB Pod名> -- bash
  2. 修改启动命令，添加调试参数（如--v=3 --vmodule=kv/kvserver/queue.go=3）
  3. 重启Pod：kubectl delete pod <CockroachDB Pod名>，GKE会自动重建Pod应用新参数。

三、额外排查措施 #

• 查看集群节点状态：若有节点正常运行，执行cockroach node status --all --host=<PodIP>:26257，获取所有节点的存活状态、副本分布详情。
• 检查存储卷健康：查看PV/PVC状态：kubectl get pv,pvc -l app.kubernetes.io/name=cockroachdb，确认无挂载失败、磁盘空间不足等问题。
• 分析Pod事件日志：执行kubectl describe pod <CockroachDB Pod名>，排查是否存在启动失败、资源不足、网络异常等事件。
• 查看GKE节点系统日志：通过GCP控制台日志浏览器，筛选resource.type="k8s_node"和目标Pod相关日志，排查内核级磁盘、网络故障。

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