腾讯云TCHouse-C 集群健康诊断与故障排查

集群健康诊断与故障排查

概述

本 Skill 提供 TCHouse-C（ClickHouse）集群的健康诊断与故障排查能力，包含三个子能力：

1. 集群全面健康巡检：拉取监控指标、节点状态、告警事件，输出健康评分和全面诊断报告
2. 告警事件排查与根因定位：针对具体告警事件（磁盘/CPU/内存/副本延迟），定位根因并给出修复建议
3. 节点故障诊断与修复建议：针对节点异常（宕机/不可达/资源耗尽），分析原因并给出恢复方案

依赖与运行环境

本 Skill 的所有调用通过 MCP Tool 完成（云 API 类工具由平台封装为 MCP Tool，Agent 直接调用工具名即可）。

依赖工具清单：

凭证 / 环境变量

• instance_id：从会话 context 的 X-Context header 自动注入
• region_id：从会话 context 的 X-Context header 自动注入（可能是 RegionId 数字，也可能是 Region 字符串，也可能是中文地域名）
• 若以上参数缺失，通过 ask_user（WorkBuddy 中为 AskUserQuestion）询问用户

⚠️ 地域参数强制规则：任何工具调用前都必须先按 地域映射表 把上下文中的地域信息补齐为 Region（字符串）+ RegionId（数字） 两种形式，禁止凭记忆填写。不同工具对参数形式的要求见 工具传参形式速查：

• TCHouseCXxx 系工具：只传 Region 字符串
• MonitorDescribeDashboardMetricData：同时传 Region 字符串 和 RegionId 数字

💡 多平台兼容说明：本文档中所有提到的 ask_user 工具，在 WorkBuddy 平台中对应为 AskUserQuestion。后文不再重复标注。

核心工作流

步骤 0：参数确认

必需参数：

• instance_id（集群 ID）
• region_id（地域）

可选参数（从用户问题中提取，缺失时使用默认值，不自行假设）：

• 时间范围：未指定 → 默认最近 24 小时
• 具体告警事件或节点 IP：从用户问题中提取

判断逻辑：

• ✅ 参数齐全 → 强制按 地域映射表 把地域补齐为 Region（字符串）+ RegionId（数字）两种形式（任何输入形式都要过这一步：中文名、英文串、数字 ID 都不例外），补齐后进入步骤 1
• ❌ instance_id 或 region_id 缺失 → 调用 ask_user 询问
• ❌ 地域信息在映射表中匹配不到（或大区模糊，如"华南地区"）→ 调用 ask_user 确认后再补齐

步骤 1：确认集群信息与状态

调用一次 TCHouseCDescribeInstance 同时获取集群基本信息和当前状态。状态与流程进度从 InstanceInfo.InstanceStateInfo 子对象读取（含 InstanceState/InstanceStateDesc/FlowName/FlowProgress/FlowMsg），无需额外调用 DescribeInstanceState。

判断逻辑：

• ✅ 集群状态 InstanceInfo.InstanceStateInfo.InstanceState（或外层 InstanceInfo.Status）为 Serving → 进入步骤 2
• ❌ 状态为 Init/Modify → 告知用户集群当前状态，说明可能的影响；若有正在进行的流程（FlowName + FlowProgress），建议等待完成后再诊断
• ❌ 状态为 Deleted/Deleting → 告知用户集群已下线，无法执行诊断，建议通过控制台检查或提工单
• ❌ 调用失败（AuthFailure）→ 报告鉴权失败，提示检查权限
• ❌ 调用失败（ResourceNotFound）→ 检查 instance_id 格式（应为 cdwch- 前缀），格式错则修正重试，格式对则请用户确认
• ❌ 调用超时/网络错误 → 等 3 秒重试，最多 3 次；仍失败 → 告知用户服务暂时不可用

记录信息：ClickHouse 版本号、节点规格和数量、是否为 HA 集群。

步骤 2：获取节点状态矩阵

调用 TCHouseCDescribeInstanceNodes 获取所有节点详细信息：

• 分别传 NodeRole=DATA 和 NodeRole=COMMON 获取数据节点和 ZK 节点
• 使用 ForceAll=true 获取全量节点

判断逻辑：

• ✅ 所有节点状态为 Running → 继续步骤 3
• ❌ 存在非 Running 状态的节点 → 标记为异常节点，记录 IP 和状态，作为后续重点关注对象
• ❌ 调用失败 → 跳过节点级分析，基于集群级数据（事件、配置）给出有限诊断建议

记录信息：节点 IP 列表、规格（Core/Memory/Disk）、磁盘类型（DiskType）。

步骤 3：检查告警/事件历史

调用 TCHouseCDescribeEventTasks 获取集群的告警和事件历史。

参数策略：

• 时间范围：根据用户描述确定，未指定则默认最近 7 天
• 时间格式：YYYY-MM-DD HH:MM:SS（如 2026-06-11 20:00:00）
• 状态过滤：优先查看待处理（Status=1）和处理中（Status=3）的事件
• 排序：按 create_time 降序，最新事件优先

判断逻辑：

• ✅ 存在未处理的高严重度事件 → 优先分析该事件，作为诊断重点，进入步骤 4
• ✅ 无告警事件 → 继续全面巡检流程（步骤 4）
• ❌ 调用失败 → 告知用户指定时间范围内事件查询失败，继续基于监控指标进行主动巡检
• ❌ 返回为空 → 告知用户无告警事件，继续基于监控指标巡检

告警严重度分级详见 诊断分析框架。

步骤 4：拉取监控指标

调用 MonitorDescribeDashboardMetricData 获取集群核心监控指标。

⚠️ 该接口属于 Monitor 产品（非 cdwch），MetricName 需使用驼峰格式（如 cpu_usage → CpuUsage）。 节点级指标需先通过步骤 2 获取节点 IP 列表，传入 NodeIps 参数；集群聚合指标需传入 NodeCount 参数。 时间格式：ISO 8601（如 2026-06-11T20:00:00+08:00），与 TCHouseCDescribeEventTasks 的 YYYY-MM-DD HH:MM:SS 格式不同，注意区分。

时间范围策略：

• 用户指定了时间 → 按用户要求
• 用户说"刚才"/"刚刚" → 最近 1 小时
• 用户说"今天" → 当天 0 点到当前
• 未指定 → 默认最近 1 小时（Period=60）

推荐查询策略：

⚠️ 前置条件：步骤 2 已通过 TCHouseCDescribeInstanceNodes 获取节点列表（CK 节点数和各节点 IP）。

• 集群聚合指标（Sum/Ck 开头）：传 NodeCount 参数（= CK 节点数），不传 NodeIps
• CK 节点级指标：传 NodeIps 参数（CK 节点 IP，逗号分隔），不传 NodeCount
• ZK/Keeper 节点指标：传 NodeIps 参数（ZK/Keeper 节点 IP，通过 NodeRole=COMMON 获取，逗号分隔），不传 NodeCount

1. 第一步：查集群聚合指标（传 NodeCount = CK 节点数）：
   • SumCpuUsage、SumMemUsage、SumDiskUsage、SumQuery、SumFailedselectquery
2. 第二步：发现异常后下钻到 CK 节点级（传 NodeIps = CK 节点 IP 列表）：
   • CPU 异常 → 查 CpuUsage、CpuUsageAvg、NodeLoad1
   • 内存异常 → 查 MemUsage
   • 磁盘异常 → 查 DiskUsage、NodeDiskIoUtil、NodeDiskIoWait
   • 网络异常 → 查 NodeNetworkReceiveBytesTotal、NodeNetworkTransmitBytesTotal
3. 第三步：检查 Keeper/ZK 节点健康（传 NodeIps = Keeper/ZK 节点 IP 列表，通过 NodeRole=COMMON 获取）：
   • 存活检查 → 查 KeeperUp / ZkUp
   • Leader 状态 → 查 KeeperIsLeader / ZkIsLeader
   • 节点资源 → 查 CpuUsage、MemUsage、DiskUsage（⚠️ 同名指标，但需用 Keeper/ZK 节点 IP 查询，采集的是 Keeper/ZK 节点资源）

指标分组查询：按 诊断分析框架 中的指标列表和阈值进行判断。

判断逻辑：

• ✅ 所有指标正常 → 进入步骤 7（综合分析）
• ❌ 发现 CPU 高或查询堆积 → 进入步骤 5（检查运行查询）
• ❌ 发现配置相关问题（内存不足/并发过高）→ 进入步骤 6（检查配置）
• ❌ 监控数据缺失（采集中断）→ 标注数据缺失时段，基于可用数据做分析，报告中注明
• ❌ 调用失败 → 等 3 秒重试，最多 3 次；仍失败 → 跳过监控分析，基于节点状态和事件数据给出有限诊断

步骤 5：检查当前运行查询（条件触发）

触发条件（满足任一即触发）：

• 步骤 4 发现 CPU 高或查询堆积
• 步骤 4 调用失败（监控数据不可用时，作为补充信息源）

调用 TCHouseCDescribeRunningQuery 查看当前正在执行的查询。

判断逻辑：

• ✅ 发现长时间运行的查询（> 60 秒）→ 纳入根因分析
• ✅ 发现大量并发查询导致资源争抢 → 纳入根因分析
• ✅ 无异常 → 继续步骤 7
• ❌ 调用失败 → 跳过此步骤，基于已有数据给出建议

步骤 6：检查集群配置（条件触发）

触发条件（满足任一即触发）：

• 步骤 4 发现可能与配置相关的问题（内存不足/并发过高）
• 步骤 4 调用失败（监控数据不可用时，配置信息可提供间接诊断线索）

调用 TCHouseCDescribeClusterConfigs 获取关键性能配置，重点关注：

• max_connections — 最大连接数上限
• max_concurrent_queries — 最大并发查询数
• max_memory_usage — 单查询内存上限
• max_thread_pool_size — 线程池大小
• merge_tree.parts_to_throw_insert / parts_to_delay_insert — parts 阈值

判断逻辑：

• ✅ 成功 → 纳入综合分析
• ❌ 获取失败 → 跳过配置分析，基于已有数据给出建议，报告中注明

步骤 6.5：检查分片拓扑（条件触发）

触发条件（满足任一即触发）：

• HA 集群或多分片集群，且怀疑副本/分片相关问题
• 步骤 4 调用失败（监控数据不可用时，分片拓扑信息可辅助诊断）

调用 TCHouseCDescribeInstanceShards 获取分片信息：确认分片数量和副本配置、ZooKeeper 连接状态、分片间数据均衡情况。

判断逻辑：

• ✅ 成功 → 纳入综合分析
• ❌ 获取失败 → 跳过分片分析，基于已有数据给出建议

步骤 7：综合分析与生成报告

基于收集到的所有信息，按 诊断分析框架 进行根因分析，按 输出报告格式 生成诊断报告。

报告必须包含：

1. 集群概况（ID/名称/版本/状态/节点数/HA 模式）
2. 健康评分（🟢/🟡/🔴 + 一句话总结）
3. 节点状态矩阵
4. 告警事件列表（如有）
5. 异常项详情与根因分析
6. 修复建议（按优先级排序：P0 防数据丢失 → P1 性能恢复 → P2 长期优化）

多异常并发时的优先级排序：

1. 先解磁盘（防数据丢失）
2. 再处理查询堆积（恢复服务）
3. 再优化 CPU/内存（性能调优）

频率控制

超限处理：连续收到 RequestLimitExceeded → 等 5 秒重试，连续 3 次仍失败 → 降低调用频率，告知用户被限流。

错误码与处理策略

安全规则

1. 本 Skill 为纯只读诊断：所有操作均为查询类（Describe），不涉及写操作，无需用户确认即可执行
2. 修复建议仅为建议：涉及重启、配置变更等操作时，仅输出建议和步骤，不直接执行；需明确告知影响范围和建议执行时间（低峰期）
3. 凭据安全：不在输出中展示任何凭据信息
4. 敏感信息控制：节点 IP、配置内容等仅在诊断报告中展示，不在非必要场景暴露
5. 数据量控制：监控指标查询时间范围不超过 7 天，避免 token 消耗过大
6. 关联诊断边界：如果发现问题根因是慢 SQL 导致的资源耗尽，建议用户使用"慢 SQL 诊断与自动调优" Skill 进一步分析，不越界处理

经验沉淀库