# 腾讯云TCHouse-C 集群健康诊断与故障排查 > TCHouse-C（ClickHouse）集群健康诊断与故障排查 Skill。AI 拉取集群监控指标（CPU/内存/磁盘/IOPS/连接数/副本延迟）、告警历史及节点状态，输出集群健康评分，定位异常根因，并给出修复建议（参数调整/分区清理/节点重启等）。 触发词：集群健康、健康检查、巡检、节点故障、磁盘告警、CPU告警、内存告警、OOM、磁盘满、磁盘空间不足、节点异常、副本延迟、查询堆积、连接数满、集群状态、cluster health、node failure、disk alert、replica lag、集群诊断、故障排查、监控异常、告警处理、节点状态、资源告警、性能瓶颈、IO高、网络异常、ZooKeeper异常、parts过多、merge压力、cdwch、TCHouse-C、ClickHouse集群。 本 Skill 包含 3 个子能力：①集群全面健康巡检 ②告警事件排查与根因定位 ③节点故障诊断与修复建议。 何时不触发：慢 SQL 诊断与自动调优（单条 SQL 性能分析）、集群选型与架构推荐、智能建表与数据建模、NL2SQL、AI Function 智能编排、集群扩缩容操作、权限管理、数据导入导出等非集群健康/故障相关问题不走本 Skill。 - Skill: `ahang1598/tchouse-c-2` (Agent Skill, multi-file: 12 files) - Install (CLI): `npx skillmds@latest add ahang1598/tchouse-c-2` - Raw SKILL.md: https://api.skillmd.com/api/skills/ahang1598/tchouse-c-2/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Data & Analytics - Author: ahang1598 (https://skillmd.com/u/ahang1598) - Updated: 2026-09-09 - Page: https://skillmd.com/skills/ahang1598/tchouse-c-2 --- # 集群健康诊断与故障排查 ## 概述 本 Skill 提供 TCHouse-C（ClickHouse）集群的健康诊断与故障排查能力，包含三个子能力： 1. **集群全面健康巡检**：拉取监控指标、节点状态、告警事件，输出健康评分和全面诊断报告 2. **告警事件排查与根因定位**：针对具体告警事件（磁盘/CPU/内存/副本延迟），定位根因并给出修复建议 3. **节点故障诊断与修复建议**：针对节点异常（宕机/不可达/资源耗尽），分析原因并给出恢复方案 ## 依赖与运行环境 本 Skill 的所有调用通过 MCP Tool 完成（云 API 类工具由平台封装为 MCP Tool，Agent 直接调用工具名即可）。 **依赖工具清单**： | # | Tool 名称 | 能力定位 | 参考文档 | | --- | ---------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------ | | 1 | TCHouseCDescribeInstance | 集群基本信息获取（含状态与流程进度 `InstanceStateInfo`） | [参考](references/tchousec-describe-instance.md) | | 2 | TCHouseCDescribeInstanceNodes | 节点列表与状态 | [参考](references/tchousec-describe-instance-nodes.md) | | 3 | TCHouseCDescribeEventTasks | 告警/事件历史查询 | [参考](references/tchousec-describe-event-tasks.md) | | 4 | TCHouseCDescribeClusterConfigs | 集群配置参数获取 | [参考](references/tchousec-describe-cluster-configs.md) | | 5 | TCHouseCDescribeInstanceShards | 分片拓扑信息 | [参考](references/tchousec-describe-instance-shards.md) | | 6 | MonitorDescribeDashboardMetricData | 集群监控指标查询（Monitor 产品） | [参考](references/monitor-describe-dashboard-metric-data.md) | | 7 | TCHouseCDescribeRunningQuery | 当前运行中的查询 | [参考](references/tchousec-describe-running-query.md) | | 8 | ask_user | 向用户询问确认信息（WorkBuddy 中为 AskUserQuestion） | — | ## 凭证 / 环境变量 - `instance_id`：从会话 context 的 X-Context header 自动注入 - `region_id`：从会话 context 的 X-Context header 自动注入（可能是 `RegionId` 数字，也可能是 `Region` 字符串，也可能是中文地域名） - 若以上参数缺失，通过 `ask_user`（WorkBuddy 中为 `AskUserQuestion`）询问用户 > ⚠️ **地域参数强制规则**：**任何工具调用前**都必须先按 [地域映射表](references/region-mapping.md) 把上下文中的地域信息补齐为 **`Region`（字符串）+ `RegionId`（数字）** 两种形式，禁止凭记忆填写。不同工具对参数形式的要求见 [工具传参形式速查](references/region-mapping.md#工具传参形式速查)： > > - `TCHouseCXxx` 系工具：**只传 `Region` 字符串** > - `MonitorDescribeDashboardMetricData`：**同时传 `Region` 字符串 和 `RegionId` 数字** > 💡 **多平台兼容说明**：本文档中所有提到的 `ask_user` 工具，在 WorkBuddy 平台中对应为 `AskUserQuestion`。后文不再重复标注。 ## 核心工作流 ### 步骤 0：参数确认 **必需参数**： - `instance_id`（集群 ID） - `region_id`（地域） **可选参数**（从用户问题中提取，缺失时使用默认值，不自行假设）： - 时间范围：未指定 → 默认最近 24 小时 - 具体告警事件或节点 IP：从用户问题中提取 **判断逻辑**： - ✅ 参数齐全 → **强制**按 [地域映射表](references/region-mapping.md) 把地域补齐为 `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） - ❌ 调用失败 → 告知用户指定时间范围内事件查询失败，继续基于监控指标进行主动巡检 - ❌ 返回为空 → 告知用户无告警事件，继续基于监控指标巡检 **告警严重度分级**详见 [诊断分析框架](references/diagnosis-framework.md#告警事件分级)。 ### 步骤 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 节点资源） **指标分组查询**：按 [诊断分析框架](references/diagnosis-framework.md#监控指标阈值) 中的指标列表和阈值进行判断。 **判断逻辑**： - ✅ 所有指标正常 → 进入步骤 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：综合分析与生成报告 基于收集到的所有信息，按 [诊断分析框架](references/diagnosis-framework.md#常见故障模式) 进行根因分析，按 [输出报告格式](references/report-template.md) 生成诊断报告。 **报告必须包含**： 1. 集群概况（ID/名称/版本/状态/节点数/HA 模式） 2. 健康评分（🟢/🟡/🔴 + 一句话总结） 3. 节点状态矩阵 4. 告警事件列表（如有） 5. 异常项详情与根因分析 6. 修复建议（按优先级排序：P0 防数据丢失 → P1 性能恢复 → P2 长期优化） **多异常并发时的优先级排序**： 1. 先解磁盘（防数据丢失） 2. 再处理查询堆积（恢复服务） 3. 再优化 CPU/内存（性能调优） ## 频率控制 | 限制 | 阈值 | 说明 | | --------------------------------------- | ------------- | ------------------------------------ | | 工具总调用频率 | ≤ 15 次/分钟 | 避免触发平台限流 | | MonitorDescribeDashboardMetricData 调用 | ≤ 5 次/轮诊断 | 每次可批量查询多个指标（Query 数组） | | TCHouseCDescribeEventTasks 翻页 | ≤ 3 次/轮 | 避免拉取过多历史事件 | **超限处理**：连续收到 `RequestLimitExceeded` → 等 5 秒重试，连续 3 次仍失败 → 降低调用频率，告知用户被限流。 ## 错误码与处理策略 | 错误码/场景 | Agent 行为 | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `AuthFailure.*` | 报告鉴权失败，提示用户检查集群访问权限 | | `ResourceNotFound` | 检查 ID 格式（`cdwch-` 前缀）；格式错 → 修正重试；格式对 → 请用户确认 | | `InvalidParameter.*` | 检查参数格式（时间范围、节点角色），尝试修正后重试 1 次；无法修正 → 报告具体问题 | | `UnsupportedRegion` | 该地域未开通 TCHouseC 产品。**不重试、不自动切换地域**，必须调用 `ask_user` 让用户确认地域。详见 [error-handling.md §1](references/error-handling.md#1-unsupportedregion该接口不支持此地域访问) | | `InternalError` | 等 3 秒重试，最多 3 次；仍失败 → 报告错误码 + RequestId | | `RequestLimitExceeded` | 等 5 秒重试；连续 3 次 → 降低频率，告知被限流 | | 监控数据缺失 | 标注缺失时段，基于可用数据分析，报告中注明 | | 节点信息获取失败 | 跳过节点级分析，基于集群级数据给出有限诊断 | | 网络超时 | 等 3 秒重试，最多 3 次；仍失败 → 告知用户服务暂时不可用 | | 兜底（未列出错误码） | 报告完整错误信息 + RequestId | ## 安全规则 1. **本 Skill 为纯只读诊断**：所有操作均为查询类（Describe），不涉及写操作，无需用户确认即可执行 2. **修复建议仅为建议**：涉及重启、配置变更等操作时，仅输出建议和步骤，不直接执行；需明确告知影响范围和建议执行时间（低峰期） 3. **凭据安全**：不在输出中展示任何凭据信息 4. **敏感信息控制**：节点 IP、配置内容等仅在诊断报告中展示，不在非必要场景暴露 5. **数据量控制**：监控指标查询时间范围不超过 7 天，避免 token 消耗过大 6. **关联诊断边界**：如果发现问题根因是慢 SQL 导致的资源耗尽，建议用户使用"慢 SQL 诊断与自动调优" Skill 进一步分析，不越界处理 ## 经验沉淀库 | 经验 | 置信度 | 说明 | | ----------------------------------------------- | ------ | -------------------------------------------------------------------------- | | 磁盘告警最常见原因是 TTL 未生效或过期分区未清理 | ⭐⭐⭐ | 检查 TTL 策略和分区保留策略，`OPTIMIZE TABLE xxx FINAL` 可强制触发清理 | | CPU 持续高负载通常伴随慢查询堆积 | ⭐⭐⭐ | 先检查 running_queries，Kill 异常长时间查询后 CPU 通常立即下降 | | 副本延迟高优先检查 ZooKeeper 状态 | ⭐⭐ | ZK 连接异常是副本延迟的最常见根因，其次是网络和写入压力 | | parts 过多通常是高频小批量写入导致 | ⭐⭐⭐ | 合并小批量写入为大批量（建议单批 ≥ 10000 行），或调高 background_pool_size | | 内存 OOM 多因单查询无内存限制 | ⭐⭐ | 设置 `max_memory_usage` 限制单查询内存，建议 ≤ 节点内存的 70% | | 连接数耗尽多因客户端连接池配置不当 | ⭐⭐ | 检查客户端是否正确释放连接，建议连接池 max_idle_time ≤ 300s |