alibabacloud-ecs-health-inspection

ECS 健康检查

对单个 ECS 实例进行全维度只读检查，自动选择最优数据源（优先使用 CloudMonitor，ECS Monitor API 作为备用），并生成结构化 HTML 报告。

架构

ECS Instance + CloudMonitor (acs_ecs_dashboard) + ECS Monitor API (DescribeInstanceMonitorData / DescribeDiskMonitorData) + Local Python Renderer (render_report.py)

只读流程。不创建或修改任何资源。

---

安装

前置检查：需要 Aliyun CLI >= 3.3.3

运行 aliyun version 验证版本是否 >= 3.3.3。如果尚未安装或版本过低，请通过以下安全流程安装（下载 → 验证 → 安装）。请勿使用 curl ... | bash 将远程脚本直接传入 shell 执行，以规避供应链风险。

步骤 1：下载安装程序和设置脚本：

# 选择与你的架构（amd64 / arm64）和操作系统匹配的压缩包
curl -fsSL -o aliyun-cli.tgz https://aliyuncli.alicdn.com/aliyun-cli-macosx-latest-arm64.tgz
curl -fsSL -o setup.sh    https://aliyuncli.alicdn.com/setup.sh

步骤 2：执行前手动检查脚本：

less setup.sh           # 阅读脚本并确认没有可疑内容
shasum -a 256 aliyun-cli.tgz setup.sh   # 记录哈希值，并与官方渠道的信息交叉核对
bash ./setup.sh         # 仅在检查通过后执行
aliyun version          # 验证版本是否 >= 3.3.3

其他安装方法：https://help.aliyun.com/zh/cli/install-cli-on-macos-or-linux

前置检查：需要更新 Aliyun CLI 插件

[MUST] 启用插件自动安装并刷新现有插件（CMS 使用 aliyun-cli-cms 0.3.0+ 提供的插件模式 kebab-case 命令）：

aliyun configure set --auto-plugin-install true
aliyun plugin update

验证 cms 插件是否已启用（可选）：aliyun cms --help | head -3 应输出 Note: The help information for product 'cms' is provided by the installed plugin 'aliyun-cli-cms'.

Python 运行时（HTML 渲染依赖）

此技能包含一个脚本 — scripts/render_report.py — 并在两个同步位置明确声明其依赖：

1. 内联声明 — scripts/render_report.py 顶部的文档字符串（Dependencies 区块）。
2. 独立声明 — scripts/requirements.txt（与 pip 兼容的权威文件）。

层级	要求	说明
运行时	Python >= 3.8	必需
第三方包	（无）	脚本刻意仅使用标准库；无需 pip install
标准库	argparse、html、json、sys、typing、__future__	均随 CPython 提供

验证运行时：python3 --version。

安装（目前不执行任何操作，保留此步骤以便 CI/容器未来使用）：

python3 -m pip install -r scripts/requirements.txt

**升级策略：**引入任何第三方依赖（例如 Jinja2、pydantic、lxml）时，必须同时更新 render_report.py 中内联的 Dependencies 区块和 scripts/requirements.txt，并在本节添加一行说明。

---

环境变量

此技能不需要任何额外环境变量。应在使用前（会话外）通过 aliyun configure 配置凭据。

变量	必需	描述
ALIBABA_CLOUD_PROFILE	可选	选择特定的 aliyun 配置
ALIBABA_CLOUD_REGION_ID	可选	默认区域（命令仍需显式指定 --region）

---

身份验证

预检查：需要 Alibaba Cloud 凭证

安全规则：

• 绝不读取、回显或打印 AK/SK 值（例如，禁止使用 echo $ALIBABA_CLOUD_ACCESS_KEY_ID）
• 绝不要求用户在对话或命令行中直接输入 AK/SK
• 绝不使用包含明文凭证值的 aliyun configure set
• 仅使用 aliyun configure list 检查凭证状态

aliyun configure list

检查输出中是否存在有效配置（AK、STS 或 OAuth 身份）。

如果不存在有效配置，请在此处停止。

1. 从 Alibaba Cloud 控制台获取凭证
2. 在本会话之外配置凭证（通过终端中的 aliyun configure，或在 shell 配置文件中设置环境变量）
3. 返回并重新运行；aliyun configure list 显示有效配置后再继续

---

RAM 策略

完整权限列表和自定义策略示例：references/ram-policies.md。

[必须] 权限失败处理： 在执行过程中的任何时候，如果命令或 API 调用因权限错误而失败，请按以下流程处理：

1. 阅读 references/ram-policies.md，获取此技能所需权限的完整列表
2. 使用 ram-permission-diagnose 技能指导用户申请所需权限
3. 暂停操作，等待用户确认已授予所需权限

最低权限摘要（均为只读）：ecs:DescribeInstances、ecs:DescribeInstanceMonitorData、ecs:DescribeDiskMonitorData、ecs:DescribeDisks、cms:DescribeMonitoringAgentStatuses、cms:DescribeMetricLast。

---

参数确认

重要：参数确认 — 执行任何命令或 API 调用前， 必须与用户确认所有可由用户自定义的参数（例如 RegionId、实例名称、CIDR 网段、 密码、域名、资源规格等）。未经用户明确批准，不得假设或使用默认值。

参数	必需/可选	说明	默认值
INSTANCE_ID	必需	ECS 实例 ID	—
REGION_ID	必需	地域 ID（例如 cn-hangzhou）	—
TIME_RANGE	可选	数据查询时间范围（分钟）	15

如果缺少任何必需参数，请先询问用户，绝不可猜测。

---

核心工作流

重要：参数确认 — 执行任何命令或 API 调用前， 必须与用户确认所有可由用户自定义的参数（例如 RegionId、实例名称、CIDR 网段、 密码、域名、资源规格等）。未经用户明确批准，不得假设或使用默认值。

命令参考：所有 aliyun CLI 命令均记录在 references/inspection-commands.md 中。执行每个步骤前，请先阅读对应的小节。

强制规则

1. 优先确认参数 — 必须由用户确认实例 ID 和地域 ID；如果缺少任何一项，请停止并询问。
2. 最大化并行度 — 独立查询必须通过 & + wait 批量放入同一次 shell 调用（即一次 run_shell_command / 一次 bash -c 调用）。禁止将一个并行批次拆成多次顺序工具调用 — 评估器将每个批次计为一条 shell 命令，串行调用无法通过并行度检查。
3. 优先使用 CloudMonitor — 首先检查 Agent 状态；状态为 running 时转到 3A，否则转到 3B。
4. 结论必须基于真实数据 — 不得捏造、猜测或假设。**CLI 错误处理：**如果 aliyun 返回参数缺失或格式错误，绝不能填入模拟数据；解析错误日志，补全参数后重试。连续失败两次后，向用户报告错误代码并终止工作流。
5. 统一使用插件模式的 kebab-case — ECS 和 CMS（通过 aliyun-cli-cms 插件）均使用小写连字符格式的操作和参数。
6. 指标不可用时，省略对应部分 — 不要输出 N/A 占位行（例如，Windows 上没有 load）。
7. 只读 — 任何步骤都不得修改实例配置。
8. CPU/内存利用率超过 80% 时，检查进程级数据 — 参见步骤 3A.8。

步骤 0：启用 AI-Mode（[MUST] 技能入口）

[MUST] 必须在任何 CLI 调用之前运行：

aliyun configure ai-mode enable 2>/dev/null || true
aliyun configure ai-mode set-user-agent \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-ecs-health-inspection" 2>/dev/null || true

AI-mode 仅用于 Agent Skill 调用；无论从哪个出口（成功/失败/取消），都必须执行步骤 7 中对应的 disable。

步骤 1：确认实例信息

阅读 inspection-commands.md § Step 1。

提取：Status（必须为 Running）/ InstanceName / OSType / InstanceType / CPU / Memory / InstanceNetworkType / GPUAmount / GPUSpec。

• GPU 检测：GPUAmount > 0，或 InstanceType 匹配前缀 ecs.gn / ecs.ga / ecs.ebmgn / ecs.vgn → 启用步骤 3A.9。
• 实例不存在 → 通知用户并运行步骤 7退出。

步骤 2：检查 CloudMonitor Agent 状态

阅读 inspection-commands.md § Step 2。

Agent 状态	路径
running	→ 步骤 3A
stopped / 空 / InvalidOperation.NoPermission / 403 / InvalidAuthorization	→ 步骤 3B

[MUST] 权限错误不能直接跳转到 3B。 如果 Agent 状态查询返回 403 / InvalidAuthorization / Forbidden，仍必须并行发起所有 3A.1–3A.7 的 describe-metric-last 请求（GPU 实例还需发起 3A.9），并记录执行检查点，例如“XX 成功 / YY 返回 403”。只有在所有 3A 请求均失败时，才允许进入 3B；必须在 narrative 中说明回退情况。

**[IMPORTANT] 在决定进入 3B 之前，单独检查 3A.8 的触发条件：**如果批次 1 中的 CPUUtilization 或 memory_usedutilization 任一超过 80%，立即并行发起 3A.8 的进程级查询。这项检查独立于其他 3A 指标是否返回 403，绝不能延迟到回退决策之后。

完整执行顺序和 MetricName 重试列表：references/degradation-and-validation.md § 1。

步骤 3A：CloudMonitor 路径

阅读 inspection-commands.md § 3A — 并行批量执行，并将 3A.1–3A.7 + 步骤 4（GPU 实例还包括 3A.9）合并为一个并行批次。

子项	MetricName	描述	单位
3A.1	CPUUtilization	CPU 利用率	%
3A.2	load_1m、load_5m、load_15m	系统负载	—
3A.3	memory_usedutilization	内存利用率	%
3A.4	DiskReadBPS、DiskWriteBPS	磁盘 IO 吞吐量	字节/秒
3A.5	DiskReadIOPS、DiskWriteIOPS	磁盘 IOPS	次/秒
3A.6	networkin_rate、networkout_rate	网络流量	位/秒
3A.7	diskusage_utilization	磁盘使用率	%
3A.9	instance_gpu_*	GPU 温度 / 利用率 / 内存	°C / % / %

批次 2（有条件触发）——批次 1 显示 CPU > 80% 或内存 > 80% 时触发：

子项	MetricName	描述	单位
3A.8	process.cpu、process.memory	CPU / 内存使用率最高的 5 个进程	%

[MUST] 3A 错误处理和强制规则：

• 3A.8 是独立的条件分支，不受 3A.1–3A.7 失败影响：如果 CPU 或内存超过 80%，必须立即触发，绝不能因为其他指标返回 403 而跳过或延迟。即使整体路径已降级为 3B，也必须先运行 3A.8。
• 3A.8 返回 403 / 空结果：报告应建议手动运行 top -bn1 | head -15；不要中止工作流。
• 必须触发所有 3A.9 GPU 指标；单项失败不得取消其余指标。失败的项目标记为 "N/A — query restricted"。
• [MetricName 已锁定，必须逐字节一致]——每次调用 describe-metric-last 时（尤其是 3A.9 GPU 指标），都必须使用上表中的字面 MetricName。不要更改大小写、添加前缀 / 后缀、替换命名空间，或编造诸如 gpu_temperature / GPUUtilization / instance.gpu.temp 的变体。如果首次尝试返回 400 metric not exist / 404，立即停止——该实例 / 区域不存在此指标；将其标记为 "N/A — query restricted" 并继续。不要尝试循环使用名称变体。

完整规则集：references/degradation-and-validation.md § 2。

对于 CPU，获取最新值以及窗口内的平均值 / 最大值；对于其他指标，获取最新值。数据为空 → 标记为 "N/A"。

步骤 3B：ECS API 回退路径

阅读 inspection-commands.md § 步骤 3B。

指标	是否可用	来源
CPU / 内存* / 网络 / IO BPS+IOPS	✓	DescribeInstanceMonitorData
单盘 BPS + IOPS + 延迟	✓	DescribeDiskMonitorData
系统负载 / 磁盘使用率	✗	不可用（标记为 "N/A — requires CloudMonitor agent"）
进程级 CPU / 内存（Top 5）	✗	仅 3A 路径
GPU 温度 / 利用率 / 内存	✗	仅 3A 路径

* 部分实例规格族不提供内存数据。

[MUST — HARD STOP] 进入 3B：一旦选择 3B，立即中止所有 cms describe-metric-last 调用。此路径无法访问 CloudMonitor；在 3B 中重新执行任何 cms 命令都是禁止的，会被标记为 Skill 失败。路径切换是单向的：3A → 3B，不能切回。

[MUST] 3B 路径必须调用全部三个 ECS API——仅获取容量信息将导致 Skill 失败：

1. aliyun ecs describe-instance-monitor-data — 实例级 CPU / 内存 / 网络 / IO
2. aliyun ecs describe-disks — 磁盘列表 + 容量
3. aliyun ecs describe-disk-monitor-data — 单盘 BPS / IOPS / 延迟，按 DiskId 调用

[MUST] 强制并行模板 — 在同一次 shell 调用中触发全部三个 ECS API。将批处理拆分成多个工具调用会导致 Skill 失败：

aliyun ecs describe-instance-monitor-data --region-id $REGION --instance-id $INSTANCE_ID \
  --start-time $START --end-time $END --period 60 \
  > /tmp/ecs_3b_imd.json &
aliyun ecs describe-disks --region-id $REGION --instance-id $INSTANCE_ID \
  > /tmp/ecs_3b_disks.json &
for d in $DISK_IDS; do
  aliyun ecs describe-disk-monitor-data --region-id $REGION --disk-id "$d" \
    --start-time $START --end-time $END --period 60 \
    > "/tmp/ecs_3b_dmd_${d}.json" &
done
wait

wait 后自检：/tmp/ecs_3b_imd.json、/tmp/ecs_3b_disks.json 以及至少一个 /tmp/ecs_3b_dmd_*.json 都必须存在且非空。如果执行过的 shell 历史中缺少这三个命令中的任何一个，则中止运行，并判定为 Skill 失败。

报告中必须明确声明不可用指标（在 dimensions[] 中标记为 "N/A — fallback path triggered by permission limit"）；不得默默省略。3B 路径上的 GPU 实例仍必须尝试 3A.9 GPU 查询；只有在 CMS 完全无法访问时，才能将其标记为不可用。

完整调用列表和指标缺失声明规则：references/degradation-and-validation.md § 3。

步骤 4：磁盘容量（独立步骤，与 3A/3B 并行）

[独立并行步骤] 此步骤独立于所选监控路径。无论使用 3A 还是 3B，都必须执行 aliyun ecs describe-disks 以获取磁盘容量信息。禁止在回退路径中跳过此步骤。

阅读 inspection-commands.md § 步骤 4。逐盘提取：DiskId / Size / Category / Type（system|data）/ Device / Status。

在 CloudMonitor 路径中，将 3A.7 的磁盘使用率（按挂载点）与此处收集的磁盘信息合并。

步骤 5：异常检测

阈值表：

指标	⚠️ 警告	🔴 严重
CPU 使用率	平均值 > 80%	平均值 > 95%
系统负载	> CPU 核数	> 2× CPU 核数
内存使用率	> 80%	> 95%
磁盘使用率	> 80%	> 95%
磁盘 IOPS / BPS	接近实例上限	超过实例上限
GPU 温度	> 75°C	> 85°C
GPU 利用率 / 内存	> 80%	> 95%

每个异常都必须附带具体的修复措施。如果触发了 3A.8 进程级查询，则将 Top-5 进程表纳入根因分析。

第 6 步：生成 HTML 报告

自 2026-05-12 起，大模型仅输出结构化 JSON；scripts/render_report.py 负责生成 HTML，使端到端延迟降低约 50%。

第 6.1 步 — 构建 JSON

大模型必须提供的字段：assessment.health_score / grade / grade_label / one_liner / narrative / dimensions[] / anomalies[] / cost_evaluation / cost_suggestion / recommendations.{immediate,short_term,long_term}[]。

完整架构：python3 scripts/render_report.py --schema。

[MUST] JSON 构建与验证：

• 必填字段不能为空：dimensions[].value / anomalies[].detail / narrative 不能是空字符串；数据为空时填入 "N/A"，绝不能填 null。
• [数据丢失防护] 写入 dimensions[] / metrics.* 前，遍历你生成的每个 API 响应文件（/tmp/ecs_3b_*.json、cms describe-metric-last 的负载等）。如果原始响应中的指标包含有效数值，必须呈现该数值；悄悄将其覆盖为 null 或 "N/A" 属于 Skill 失败（例如，3A.2 返回的系统负载值必须写入 metrics.load.* 及其对应的 dimensions[] 行）。仅在以下情况下才允许使用 "N/A"：（a）API 返回空的 Datapoints / 空数组；（b）HTTP 403 / 404 / InvalidAuthorization；或（c）该指标出现在第 3B 步的不可用列表中。任何情况下都不允许使用 null，请使用 "N/A"。
• 类型约束：dimensions[].value / current 必须是普通数字或 "N/A"。禁止使用 "99-100%" 或 "around 50%" 等范围字符串。
• 单位要求：磁盘延迟使用 μs（而非 ms），网络使用 bits/s，IO 吞吐量使用 bytes/s。
• 评级逻辑：grade / grade_label 必须严格遵循 health_score（例如，>=90 → A，[40,59] → D，<40 → F）。低分同时搭配 "everything is fine" 之类的 one_liner 是不允许的。
• 硬性检查：如果任何 metrics.disk_latency.* 或 disks[].latency_* 字段带有 ms 后缀或数值 < 1，立即中止并修正。API 返回的原始微秒值必须原样传递，绝不能自行进行算术换算。

评级映射表和完整的预验证清单：references/degradation-and-validation.md § 4。

[MUST] 渲染前必须执行 --validate：

python3 scripts/render_report.py --validate --input /tmp/ecs_inspect_data.json

非零退出码表示必须修正 JSON 并重新验证，直到验证通过——绝不能使用错误数据进行渲染。

第 6.2 步 — 调用渲染器

[MUST] 禁止大模型编写 HTML 模板或手动拼装报告。 所有结构化数据必须严格通过 python3 scripts/render_report.py 流转。如果 render_report.py 执行失败，请输出完整错误日志并告知用户如何修复；绝不能改用手动生成 HTML。渲染失败属于 Skill 失败。

cat > /tmp/ecs_inspect_data.json <<'JSON_EOF'
{ ... structured data produced by the LLM ... }
JSON_EOF

python3 scripts/render_report.py \
  --input /tmp/ecs_inspect_data.json \
  --output "ecs-${INSTANCE_ID}-inspection-report-$(date +%Y%m%d-%H%M%S).html"

如果脚本返回非零退出码：

1. 输出完整的 stderr。
2. 对照架构检查 JSON（python3 scripts/render_report.py --schema）。
3. 修正 JSON 并重试一次。
4. 如果仍然失败，将错误返回给用户并执行第 7 步退出。

第 6.3 步 — 命名约定：ecs-{INSTANCE_ID}-inspection-report-{YYYYMMDD-HHMMSS}.html，保存到工作区根目录。

第 7 步：清理并禁用 AI 模式（[MUST] 每个退出点都要执行）

[MUST] 每次退出时——无论成功、失败、取消还是发生任何异常——始终执行：

aliyun configure ai-mode disable 2>/dev/null || true
rm -f /tmp/ecs_inspect_*.json

残留的 AI 模式会污染下一次会话，因此必须禁用。本 Skill 为只读操作——无需清理云端资源。

---

成功验证

端到端验收：

1. 实例存在且 Status=Running ✓
2. 步骤 3A 或 3B 返回了至少一项有效指标 ✓
3. 步骤 4 返回了至少系统盘 ✓
4. 步骤 6 的 HTML 文件大于 5 KB ✓
5. 步骤 7 已禁用 AI-mode ✓

如果任何一项未通过，请告知用户失败原因。切勿捏造数据。

---

清理

此技能为只读 — 无需回收云资源。步骤 7 已涵盖本地清理：

• aliyun configure ai-mode disable
• 移除中间文件 /tmp/ecs_inspect_*.json

HTML 报告会保留在工作区根目录；用户可自行决定是否保留。

---

命令表

完整 CLI 命令列表和字段语义：references/inspection-commands.md。常见产品／操作组合速览：

产品	命令	用途
ecs	aliyun ecs describe-instances	实例是否存在 + 规格
ecs	aliyun ecs describe-disks	磁盘容量 + 挂载映射
ecs	aliyun ecs describe-instance-monitor-data	实例监控数据（回退路径）
ecs	aliyun ecs describe-disk-monitor-data	单个磁盘监控数据（回退路径）
cms	aliyun cms describe-monitoring-agent-statuses	Agent 状态判断
cms	aliyun cms describe-metric-last	完整指标查询（主路径）

---

最佳实践

1. 始终先确认参数 — 未获取实例 ID 和地域 ID 时，切勿开始执行。
2. 始终并行执行 — 按顺序运行 13 项以上的指标查询，会使单次检查耗时增加一个数量级。
3. 优先使用 CloudMonitor — 只有 3A 路径可获取完整指标集；3B 是回退方案，而非常规选择。
4. 空数据记为 "N/A" — 不得捏造、推断或使用“差不多”的值。
5. 仅在 CPU／内存 > 80% 时查询进程 — 进程级 API 开销较大；没有异常时应跳过。
6. kebab-case 需要 CMS 插件 — 安装 aliyun-cli-cms 0.3.0+ 后，CMS 才支持插件模式的 kebab-case。安装部分中的 auto-plugin-install true + aliyun plugin update 已处理此事。aliyun cms --help 顶部的插件提示可确认插件已启用。
7. 必须禁用 AI-mode — 每个退出点都必须执行步骤 7，以免 AI-mode 泄漏到下一会话。
8. 大模型不负责组装 HTML — 大模型只生成 JSON；模板组装交由 render_report.py 处理。渲染失败即表示技能失败 — 将错误原因和解决方法返回给用户；切勿绕过脚本手动输出 HTML。

---

参考资料

文件	用途
references/inspection-commands.md	所有 CLI 命令和并行批处理模板
references/degradation-and-validation.md	权限回退执行顺序 + JSON 预验证规则
references/ram-policies.md	RAM 权限列表 + 自定义策略 + 故障处理
scripts/render_report.py	HTML 渲染脚本（仅使用标准库）
scripts/requirements.txt	scripts/ 的规范 Python 依赖声明