返回技能市场
开发运维 安全

API网关巡检

@aliyun/alibabacloud-apigw-inspection

对API网关实例进行巡检，检测实例cpu、实例内存等是否存在异常

云Skills门户 热度 62v0.0.1

云原生 API 网关 / AI 网关 / API 网关实例巡检

场景说明

对阿里云网关实例执行健康巡检，获取监控指标数据并生成巡检报告。

架构：Cloud Monitor (CMS) + API Gateway (cloudapi) + Cloud-Native API Gateway / AI Gateway (apig)

支持的产品类型： | 产品类型 | 实例 ID 格式 | 查询命令 | |---------|-----------|----------| | 云原生 API 网关 | gw-xxxxxxx | aliyun apig list-gateways | | AI 网关 | gw-xxxxxxx | aliyun apig list-gateways | | API 网关（专享型） | apigateway-xx-xxxxxxx | aliyun cloudapi describe-instances |

注意：API 网关共享实例（VPC_SHARED）不支持巡检。仅支持专享实例（VPC_DEDICATED）。

---

安装

前置检查：阿里云 CLI 版本必须 >= 3.3.3

运行 aliyun version 验证版本是否 >= 3.3.3。如果尚未安装或版本过低，
请按照以下升级/安装说明操作。

升级/安装阿里云 CLI（根据您的平台选择一种方式）：

  • macOS (Homebrew):

    • ``bash brew install aliyun-cli # fresh install brew upgrade aliyun-cli # upgrade existing ``

  • Linux / macOS（二进制）：

    • ``bash curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash ``

  • Windows (PowerShell):

    • ``powershell Invoke-WebRequest -Uri "https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip" -OutFile "aliyun-cli.zip" Expand-Archive -Path aliyun-cli.zip -DestinationPath C:\aliyun-cli ``

升级后，请使用 aliyun version 进行验证。 有关更多平台和详细说明，请参阅 references/cli-installation-guide.md。

前置检查：必须更新阿里云 CLI 插件

[必须] 运行 aliyun configure set --auto-plugin-install true 以启用插件自动安装。
[必须] 运行 aliyun plugin update，确保所有已安装的插件始终保持最新。

---

可观测性（每条 aliyun 命令均必须遵循）

加载此 skill 后，针对整个会话仅生成一次随机会话 ID（32 位小写十六进制字符串）。 在下文中将其用作 {session-id}。

规则：所有调用云 API 的 aliyun CLI 命令都必须包含 --user-agent 标志。

本地实用命令（例如 configure、plugin、version）不支持此标志， 应将其排除在外。

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-apigw-inspection/{session-id}

---

环境变量

无需其他环境变量。凭证通过 aliyun configure 配置。

---

身份认证

前置检查：必须具备阿里云凭证
安全规则：
- 严禁读取、回显或打印 AK/SK 值（例如，echo $ALIBABA_CLOUD_ACCESS_KEY_ID 是禁止的）
- 严禁要求用户直接在对话或命令行中输入 AK/SK
- 严禁在 aliyun configure set 中使用明文凭证值
- 只能使用 aliyun configure list 检查凭证状态
```bash
aliyun configure list
```
检查输出中是否存在有效的配置文件（AK、STS 或 OAuth 身份）。
如果不存在有效的配置文件，必须在此处停止。
1. 从阿里云控制台获取凭证
2. 在此会话之外配置凭证（通过终端中的 aliyun configure，或 shell 配置文件中的环境变量）
3. 当 aliyun configure list 显示有效的配置文件后，返回并重新运行

---

RAM 权限策略

此 skill 仅涉及只读操作，且必须具备以下最低 RAM 权限：

| 产品 | RAM 操作 | 说明 | |------|-----------|------| | API 网关 | apigateway:DescribeInstances | 列出 API 网关实例 | | API 网关 | apigateway:DescribeInstanceDropPacket | 查看丢包数 | | API 网关 | apigateway:DescribeInstanceDropConnections | 查看丢弃的连接数 | | API 网关 | apigateway:DescribeInstanceSlbConnect | 查看并发连接数 | | API 网关 | apigateway:DescribeInstanceTraffic | 查看流量信息 | | API 网关 | apigateway:DescribeInstanceQps | 查看 QPS 数据 | | 云原生 API 网关 / AI 网关 | apig:ListGateways | 查询网关列表 | | 云监控 | cms:QueryMetricData | 查询监控数据 |

完整策略文档：[references/ram-policies.md](references/ram-policies.md)

[必须] 权限失败处理： 如果在执行过程中的任何时候，任一命令或 API 调用因权限错误而失败，必须遵循以下流程：
1. 阅读 references/ram-policies.md，获取此 SKILL 所需的完整权限列表
2. 使用 ram-permission-diagnose skill 引导用户申请所需权限
3. 暂停并等待，直至用户确认已授予所需权限

---

参数确认

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

| 参数 | 必填/可选 | 说明 | 默认值 | |-------|---------|------|-------| | 产品类型 | 必填 | 云原生 API 网关 / AI 网关 / API 网关 | 无 | | RegionId | 必填 | 实例所在的地域 | 无 | | 实例 ID | 必填 | 网关实例的唯一标识符 | 无 | | 时间范围 | 可选 | 查询时间点或时间范围 | 当前时间 |

可用地域检查：

---

核心工作流

步骤 1：收集所需信息

开始查询前，必须确认以下信息（如未提供，应主动询问用户）。禁止使用默认配置：

  1. 云产品类型——用户要查询哪种云产品（云原生 API 网关 / AI 网关 / API 网关）。
  2. 地域（RegionId）——实例所在的地域。
  3. 实例 ID——实例的唯一标识符。
  4. 时间范围——查询的时间点或时间范围。

步骤 2：查询实例信息

[必须] API 调用要求：
必须通过 CLI 插件模式调用 Apig ListGateways API 来查询网关列表。
这是强制步骤——不得跳过网关列表查询。
[必须] 仅限插件模式：
此 skill 中的所有命令都必须使用 CLI 插件模式执行。不得使用传统 API 格式（PascalCase 操作名称）。
如果未安装插件，请运行 aliyun plugin install --names apig 进行安装，然后重试。

2.1 云原生 API 网关 / AI 网关

API 映射：产品 Apig | 操作 ListGateways | 版本 2019-01-01

aliyun apig list-gateways --region ${region_id} \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-apigw-inspection/{session-id}

注意：响应中的 gatewayType 表示实例类型：API（云原生 API 网关）、AI（AI 网关）

2.2 API 网关

aliyun cloudapi describe-instances --api-version 2016-07-14 --region ${region_id} \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-apigw-inspection/{session-id}

注意：响应中的 InstanceType 表示实例类型。仅支持 VPC_DEDICATED（专享）实例。VPC_SHARED 共享实例不支持巡检。

步骤 3：获取监控指标数据

3.1 云原生 API 网关 / AI 网关

[必须] API 调用要求：
必须通过 CLI 插件模式使用 Cms DescribeMetricData API 查询监控指标
关键要求——禁止使用的 APIs：
- 不得使用 DescribeMetricList（aliyun cms describe-metric-list）— 其返回的响应格式不同，不予接受
- 不得使用 DescribeMetricMetaList（aliyun cms describe-metric-meta-list）— 不得调用此 API 来发现或列出可用指标
下方已提供所有指标名称。无需发现指标：
- 对于云原生 API 网关实例：从下方的云原生 API 网关支持的指标表中选择指标名称
- 对于AI 网关实例：从下方的AI 网关支持的指标表中选择指标名称
- 直接使用对应表中的准确 Metric Name 值作为 --metric-name 参数

API 映射：产品 Cms | 操作 DescribeMetricData | 版本 2019-01-01 | 命名空间 acs_cnapigateway

aliyun cms describe-metric-data \
--namespace acs_cnapigateway \
--region ${region} \
--api-version 2019-01-01 \
--metric-name ${metric-name} \
--period 60 \
--start-time ${start-time} \
--end-time ${end-time} \
--dimensions '[{"instanceId": "${instanceId}"}]' \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-apigw-inspection/{session-id}

注意事项：

  • start-time / end-time 使用 Unix 毫秒时间戳
  • 必须在维度中传递 instanceId
  • 必须查询以下所有指标类别：CPU 使用率、内存使用率、连接数、网络 IO、限流
  • 仅检查 CPU、内存、连接数、网络 IO、限流和带宽

云原生 API 网关支持的指标： | 指标名称 | 显示名称 | 维度 | 指标周期 | 单位 | |---|---|---|---|---| | EnvoyClientActiveConnection | 当前活跃连接数（网关到客户端） | userId,regionId,instanceId | 60300 | count | | EnvoyClientDestroyConnection | 每秒销毁的连接数（网关到客户端） | userId,regionId,instanceId | 60300 | count/s | | EnvoyClientDestroySSL | 每秒 SSL 握手失败次数（网关到客户端） | userId,regionId,instanceId | 60300 | count/s | | EnvoyClientNewConnection | 每秒新建连接数（网关到客户端） | userId,regionId,instanceId | 60300 | count/s | | EnvoyClientNewSSL | 每秒 SSL 握手次数（网关到客户端） | userId,regionId,instanceId | 60300 | count/s | | EnvoyClientReuseSSL | 每秒 SSL 握手复用次数（网关到客户端） | userId,regionId,instanceId | 60300 | count/s | | EnvoyCpuUsageRate | 网关 CPU 使用率 | userId,instanceId | 60300 | % | | EnvoyFsReadBytes | 磁盘读取负载 | userId,instanceId | 60300 | B/s | | EnvoyFsWriteBytes | 磁盘写入负载 | userId,instanceId | 60300 | B/s | | EnvoyMemoryUsage | 内存负载 | userId,instanceId | 60300 | MiB | | EnvoyMemoryUsageRate | 网关内存使用率 | userId,instanceId | 60300 | % | | EnvoyNetworkInBytes | 入站网络 IO 负载 | userId,instanceId | 60300 | B/s | | EnvoyNetworkOutBytes | 出站网络 IO 负载 | userId,instanceId | 60300 | B/s | | EnvoyRateLimitRequests | 限流请求数 | userId,instanceId | 60300 | count/s | | EnvoyUpstreamActiveConnection | 当前活跃连接数（网关到后端） | userId,instanceId | 60300 | count | | EnvoyUpstreamDestroyConnection | 每秒销毁的连接数（网关到后端） | userId,instanceId | 60300 | count/s | | EnvoyUpstreamNewConnection | 每秒新建连接数（网关到后端） | userId,instanceId | 60300 | count/s | | Ipv4EipRateIn | 公网 IPv4 入站带宽 | userId,instanceId | 60300 | bit/s | | Ipv4EipRateOut | 公网 IPv4 出站带宽 | userId,instanceId | 60300 | bit/s | | Ipv6GatewayRateIn | 公网 IPv6 入站带宽 | userId,instanceId | 60300 | bit/s | | Ipv6GatewayRateOut | 公网 IPv6 出站带宽 | userId,instanceId | 60300 | bit/s | | SlbInstanceTrafficRX | 私网入站带宽 | userId,instanceId | 60300 | bit/s | | SlbInstanceTrafficTX | 私网出站带宽 | userId,instanceId | 60300 | bit/s |

AI 网关支持的指标： | 指标名称 | 显示名称 | 维度 | 指标周期 | 单位 | |---|---|---|---|---| | AIGatewayEnvoyClientActiveConnection | 当前活跃连接数（网关到客户端） | userId,regionId,instanceId | 60300 | count | | AIGatewayEnvoyClientDestroyConnection | 每秒销毁的连接数（网关到客户端） | userId,regionId,instanceId | 60300 | count/s | | AIGatewayEnvoyClientDestroySSL | 每秒 SSL 握手失败次数（网关到客户端） | userId,regionId,instanceId | 60300 | count/s | | AIGatewayEnvoyClientNewConnection | 每秒新建连接数（网关到客户端） | userId,regionId,instanceId | 60300 | count/s | | AIGatewayEnvoyClientNewSSL | 每秒 SSL 握手次数（网关到客户端） | userId,regionId,instanceId | 60300 | count/s | | AIGatewayEnvoyCpuUsageRate | 网关 CPU 使用率 | userId,regionId,instanceId | 60300 | % | | AIGatewayEnvoyFsReadBytes | 磁盘读取负载 | userId,regionId,instanceId | 60300 | B/s | | AIGatewayEnvoyFsWriteBytes | 磁盘写入负载 | userId,regionId,instanceId | 60300 | B/s | | AIGatewayEnvoyMemoryUsage | 内存负载 | userId,regionId,instanceId | 60300 | MiB | | AIGatewayEnvoyMemoryUsageRate | 网关内存使用率 | userId,regionId,instanceId | 60300 | % | | AIGatewayEnvoyNetworkInBytes | 入站网络 IO 负载 | userId,regionId,instanceId | 60300 | B/s | | AIGatewayEnvoyNetworkOutBytes | 出站网络 IO 负载 | userId,regionId,instanceId | 60300 | B/s | | AIGatewayEnvoyRateLimitRequests | 被限流的请求 | userId,regionId,instanceId | 60300 | count/s | | AIGatewayEnvoyUpstreamActiveConnection | 当前活跃连接数（网关到后端） | userId,regionId,instanceId | 60300 | count | | AIGatewayEnvoyUpstreamDestroyConnection | 每秒销毁连接数（网关到后端） | userId,regionId,instanceId | 60300 | count/s | | AIGatewayEnvoyUpstreamNewConnection | 每秒新建连接数（网关到后端） | userId,regionId,instanceId | 60300 | count/s | | Ipv4EipRateIn | 公网 IPv4 入方向带宽 | userId,instanceId | 60300 | bit/s | | Ipv4EipRateOut | 公网 IPv4 出方向带宽 | userId,instanceId | 60300 | bit/s | | Ipv6GatewayRateIn | 公网 IPv6 入方向带宽 | userId,instanceId | 60300 | bit/s | | Ipv6GatewayRateOut | 公网 IPv6 出方向带宽 | userId,instanceId | 60300 | bit/s | | SlbInstanceTrafficRX | 私网入方向带宽 | userId,instanceId | 60300 | bit/s | | SlbInstanceTrafficTX | 私网出方向带宽 | userId,instanceId | 60300 | bit/s |

3.2 API 网关专享实例

[必须] API 调用要求：
对于 API 网关专享实例，必须通过 CLI 插件模式使用 CloudAPI 专用 APIs 查询监控数据。
不得对 API 网关专享实例使用云监控（CMS）。 CMS 仅用于云原生 API 网关 / AI 网关（步骤 3.1）。
以下 5 个 API 调用全部为强制要求：
| # | API | 产品 | 操作 | 版本 | 说明 |
|---|-----|---------|--------|---------|-------|
| 1 | 丢包 | cloudapi | DescribeInstanceDropPacket | 2016-07-14 | |
| 2 | 丢弃连接 | cloudapi | DescribeInstanceDropConnections | 2016-07-14 | |
| 3 | SLB connections | cloudapi | DescribeInstanceSlbConnect | 2016-07-14 | |
| 4 | 流量 | cloudapi | DescribeInstanceTraffic | 2016-07-14 | 分别查询 RELEASE、PRE 和 TEST |
| 5 | QPS | cloudapi | DescribeInstanceQps | 2016-07-14 | 分别查询 RELEASE、PRE 和 TEST |
关键要求：流量和 QPS 均必须查询 3 次——每个环境各查询一次（RELEASE、PRE、TEST）。
这意味着总共需要 7 次 API 调用（5 个基础 APIs，但流量和 QPS 均需分别查询 3 个环境）。

注意：对于 API 网关，跳过 3.1 并直接执行此步骤。时间格式使用 ISO8601 UTC（YYYY-MM-DDThh:mm:ssZ）

# 1. Dropped packets
aliyun cloudapi describe-instance-drop-packet \
--start-time ${start-time} --end-time ${end-time} \
--instance-id ${instanceId} --sbc-name Maximum \
--api-version 2016-07-14 --region ${region} \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-apigw-inspection/{session-id}

# 2. Dropped connections
aliyun cloudapi describe-instance-drop-connections \
--start-time ${start-time} --end-time ${end-time} \
--instance-id ${instanceId} --sbc-name Maximum \
--api-version 2016-07-14 --region ${region} \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-apigw-inspection/{session-id}

# 3. SLB connections
aliyun cloudapi describe-instance-slb-connect \
--start-time ${start-time} --end-time ${end-time} \
--instance-id ${instanceId} --sbc-name Maximum \
--api-version 2016-07-14 --region ${region} \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-apigw-inspection/{session-id}

# 4. Traffic — MUST query RELEASE, PRE, and TEST environments separately (3 calls)
aliyun cloudapi describe-instance-traffic \
--start-time ${start-time} --end-time ${end-time} \
--instance-id ${instanceId} --stage-name RELEASE \
--api-version 2016-07-14 --region ${region} \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-apigw-inspection/{session-id}

aliyun cloudapi describe-instance-traffic \
--start-time ${start-time} --end-time ${end-time} \
--instance-id ${instanceId} --stage-name PRE \
--api-version 2016-07-14 --region ${region} \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-apigw-inspection/{session-id}

aliyun cloudapi describe-instance-traffic \
--start-time ${start-time} --end-time ${end-time} \
--instance-id ${instanceId} --stage-name TEST \
--api-version 2016-07-14 --region ${region} \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-apigw-inspection/{session-id}

# 5. QPS — MUST query RELEASE, PRE, and TEST environments separately (3 calls)
aliyun cloudapi describe-instance-qps \
--start-time ${start-time} --end-time ${end-time} \
--instance-id ${instanceId} --stage-name RELEASE \
--api-version 2016-07-14 --region ${region} \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-apigw-inspection/{session-id}

aliyun cloudapi describe-instance-qps \
--start-time ${start-time} --end-time ${end-time} \
--instance-id ${instanceId} --stage-name PRE \
--api-version 2016-07-14 --region ${region} \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-apigw-inspection/{session-id}

aliyun cloudapi describe-instance-qps \
--start-time ${start-time} --end-time ${end-time} \
--instance-id ${instanceId} --stage-name TEST \
--api-version 2016-07-14 --region ${region} \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-apigw-inspection/{session-id}

步骤 4：生成巡检报告

4.1 异常检查规则

| 指标 | 正常 | 警告 | 严重 | |------|------|------|------| | CPU 使用率 | < 70% | 70%-85% | > 85% | | 内存使用率 | < 75% | 75%-90% | > 90% | | 连接数 | < 最大值的 70% | 70%-85% | > 85% | | 网络 IO | < 带宽的 70% | 70%-85% | > 85% | | 限流 | 未触发 | > 0 次 | 持续增加 |

突增检测：当一个周期内的增幅超过阈值时告警（CPU > 30%、内存 > 25%、连接数 > 50%、网络 IO > 40%）

4.2 报告结构

巡检报告应包含以下部分：

  1. 基本信息——产品类型、实例 ID、地域、巡检时间
  2. 巡检结果概览——以表格形式展示各项指标的状态
  3. 详细分析——各项指标的峰值、趋势和分析
  4. 风险评估——高风险和中风险项列表
  5. 优化建议——根据实际问题提出建议（若所有指标均正常则省略）
  6. 结论——巡检结果总结

重要：所有数据必须来自实际的 API 响应。严禁伪造数据。

---

成功验证

验证方法请参见 [references/verification-method.md](references/verification-method.md)

---

清理

此 skill 仅涉及只读操作。无需清理资源。

---

命令列表

完整命令列表请参见 [references/related-commands.md](references/related-commands.md)

---

最佳实践

  1. 仅限插件模式：所有命令必须使用 aliyun CLI 插件模式执行。不得使用传统 API 格式（PascalCase 操作名称）。如果所需插件尚未安装，请先运行 aliyun plugin install --names <plugin-name> 进行安装。
  2. 确认参数：执行前必须确认所有用户可自定义参数
  3. 检查地域：确保该地域属于相应产品的可用地域
  4. 检查实例类型：API 网关仅支持专享实例巡检
  5. 时间格式：云监控使用毫秒时间戳；API 网关使用 ISO8601 UTC
  6. 数据准确性：报告数据必须来自实际的 API 响应
  7. 风险分级：严格遵循阈值标准进行风险评估

---

参考链接

| 文档 | 路径 | |------|------| | CLI 安装指南 | [references/cli-installation-guide.md](references/cli-installation-guide.md) | | RAM 权限策略 | [references/ram-policies.md](references/ram-policies.md) | | 相关命令 | [references/related-commands.md](references/related-commands.md) | | 验证方法 | [references/verification-method.md](references/verification-method.md) | | 验收标准 | [references/acceptance-criteria.md](references/acceptance-criteria.md) | | AI 网关可用地域 | https://help.aliyun.com/zh/api-gateway/ai-gateway/product-overview/supported-regions | | 云原生 API 网关可用地域 | https://help.aliyun.com/zh/api-gateway/cloud-native-api-gateway/product-overview/regions | | API 网关可用地域 | https://help.aliyun.com/zh/api-gateway/traditional-api-gateway/developer-reference/api-cloudapi-2016-07-14-endpoint |

qianwen skills install @aliyun/alibabacloud-apigw-inspection