alibabacloud-network-reachability-analysis：使用阿里云 NIS（网络智能服务）网络路径可达性分析 OpenAPI，帮助客户执行路径诊断、可视化等功能。

NIS 网络可达性分析

语言：用与用户相同的语言回复。
如果用户说中文，使用下方中文（zh-CN）提示。
如果用户说英文，使用下方英文（en）提示。

引导 agent 使用阿里云 NIS 进行交互式网络可达性分析。

覆盖正向 / 反向路径分析、拓扑可视化（Mermaid），以及路径上资源的监控诊断。

架构：NIS (CreateAndAnalyzeNetworkPath + GetNetworkReachableAnalysis) + CloudMonitor (DescribeMetricData)

⚠️ 关键：仅只读操作
本 Skill 执行只读网络诊断。不要创建、修改或删除任何云资源。
本技能仅执行只读网络诊断操作。严禁创建、修改或删除任何云资源。
允许：CreateAndAnalyzeNetworkPath、GetNetworkReachableAnalysis、DescribeMetricData、Describe* API
允许：分析任务创建与查询、监控数据查询、Describe* 类查询 API
禁止：Create*（除 CreateAndAnalyzeNetworkPath 外）、Modify*、Delete*、Start*、Stop*、Run* API
禁止：创建类 API（除 CreateAndAnalyzeNetworkPath 外）、修改、删除、启停、执行类 API

安装

前置检查：需要 Aliyun CLI >= 3.3.1
运行 aliyun version 确认 >= 3.3.1。若未安装或版本过低，
见 references/cli-installation-guide.md 获取安装说明。
然后 [必须] 运行 aliyun configure set --auto-plugin-install true 启用插件自动安装。

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

鉴权

前置检查：需要阿里云凭证
安全规则：
- 绝不读取、回显或打印 AK/SK 值（例如 echo $ALIBABA_CLOUD_ACCESS_KEY_ID 是禁止的）
- 绝不要求用户在对话或命令行中直接输入 AK/SK
- 绝不使用字面凭证值运行 aliyun configure set
- 只使用 aliyun configure list 检查凭证状态
```bash
aliyun configure list --user-agent AlibabaCloud-Agent-Skills
```
检查输出中是否有有效 profile（AK、STS 或 OAuth 身份）。
如果不存在有效 profile，就此停止。
1. 从阿里云控制台获取凭证
2. 在本会话之外配置凭证（通过终端中的 aliyun configure 或 shell profile 中的环境变量）
3. 待 aliyun configure list 显示有效 profile 后再返回并重试

RAM 权限

完整 RAM 策略见 references/ram-policies.md。

所需动作：nis:CreateAndAnalyzeNetworkPath、nis:GetNetworkReachableAnalysis、cms:DescribeMetricData。

参数确认

重要：参数确认 —— 执行任何命令或 API 调用前，
所有用户可自定义的参数（例如 RegionId、实例 ID、IP 地址、
协议、端口、资源类型等）都必须与用户确认。
未经用户明确批准，不要假设或使用默认值。

交互式收集以下参数：

交互收集逻辑

使用与用户语言匹配的提示：

步骤 1 —— 询问资源类型

步骤 2 —— 按类型提示

步骤 3 —— 协议和端口

核心工作流

步骤 1：正向路径分析

aliyun nis create-and-analyze-network-path \
  --source-id <SourceId> \
  --source-type <SourceType> \
  --target-id <TargetId> \
  --target-type <TargetType> \
  --protocol <Protocol> \
  --target-port <TargetPort> \
  --source-ip-address <SourceIpAddress> \
  --target-ip-address <TargetIpAddress> \
  --region <RegionId> \
  --user-agent AlibabaCloud-Agent-Skills

若 SourceType/TargetType 不是 vpn 或 vbr，可省略 --source-ip-address / --target-ip-address。
若 Protocol 是 icmp，可省略 --target-port。

记录返回的 NetworkReachableAnalysisId。

⚠️ 强制：正向分析完成后始终执行反向路径分析。
必须在步骤 2 完成后立即执行步骤 3（反向路径分析）。不要跳过或省略反向路径检查。
必须在正向分析完成后立即执行步骤 3（反向路径分析）。严禁跳过或省略反向路径检查。

步骤 2：轮询正向结果

aliyun nis get-network-reachable-analysis \
  --network-reachable-analysis-id <ForwardAnalysisId> \
  --region <RegionId> \
  --user-agent AlibabaCloud-Agent-Skills

重复直到 NetworkReachableAnalysisStatus 为 finish。提取 Reachable、NetworkReachableAnalysisResult。

步骤 3：反向路径分析

交换源和目的：

• 正向 SourceId/Type → 反向 TargetId/Type
• 正向 TargetId/Type → 反向 SourceId/Type
• 正向 SourceIpAddress → 反向 TargetIpAddress
• 正向 TargetIpAddress → 反向 SourceIpAddress

端口处理：

• 反向 --source-port = 正向 TargetPort（服务端监听端口）
• 反向 --target-port = 49152 ~ 65535 范围内的随机临时端口（客户端随机端口）

由于客户端发起连接时使用动态分配的临时端口，反向路径（服务端→客户端）的目的端口应使用临时端口范围（49152-65535）内的随机值来模拟真实回程流量。

aliyun nis create-and-analyze-network-path \
  --source-id <OriginalTargetId> \
  --source-type <OriginalTargetType> \
  --target-id <OriginalSourceId> \
  --target-type <OriginalSourceType> \
  --protocol <Protocol> \
  --source-port <OriginalTargetPort> \
  --target-port <RandomPort_49152_to_65535> \
  --source-ip-address <OriginalTargetIpAddress> \
  --target-ip-address <OriginalSourceIpAddress> \
  --region <RegionId> \
  --user-agent AlibabaCloud-Agent-Skills

若源 / 目的类型不是 vpn 或 vbr，可省略 --source-ip-address / --target-ip-address。

步骤 4：轮询反向结果

同步骤 2，使用反向的 NetworkReachableAnalysisId。

步骤 5：结果解读

关键：始终使用主动发起的分析任务返回的 topologyData.positive。
忽略任何响应中的 topologyData.reverse——它不可靠。
始终使用主动发起的分析任务返回的 topologyData.positive。
忽略任何响应中的 topologyData.reverse——它不可靠。

对正向和反向分别：

1. 检查 Reachable 字段。若为 true，路径可达。
2. 若为 false，从 NetworkReachableAnalysisResult 分析定位阻断点：

• errorCode —— 根因错误码
• securityGroupData —— 安全组拦截规则
• routeData —— 路由表丢包条目

步骤 6：拓扑可视化（Mermaid）

从 topologyData.positive 生成 Mermaid 图：

graph LR

• 节点：从 nodeList 提取 nodeType 和 bizInsId
• 连线：从 linkList 构建有向边

示例：

graph LR
    ECS_i-src["ECS: i-bp1xxx"] --> VRouter_vrt-1["VRouter: vrt-xxx"]
    VRouter_vrt-1 --> VSW_vsw-1["VSW: vsw-xxx"]
    VSW_vsw-1 --> ENI_eni-1["ENI: eni-xxx"]
    ENI_eni-1 --> ECS_i-dst["ECS: i-bp2xxx"]

步骤 7：途经资源监控诊断

对 topologyData 中途经的资源 ID，若匹配以下前缀，查询最近 1 小时监控数据：

查询命令（CMS 使用 PascalCase API 风格，非插件模式）：

aliyun cms DescribeMetricData \
  --Namespace <Namespace> \
  --MetricName <MetricName> \
  --Dimensions '[{"instanceId":"<ResourceId>"}]' \
  --StartTime <1HourAgoTimestamp> \
  --EndTime <NowTimestamp> \
  --Period 60 \
  --user-agent AlibabaCloud-Agent-Skills

限流：每账号每秒 10 次调用。跨多个指标批量查询时应相应控制节奏。

清理

NIS 可达性分析为只读操作——不会创建或修改任何云资源，无需清理。

使用限制

1. 仅支持 IPv4 —— 只支持 IPv4 路径分析。
2. 单向分析 —— 每次分析是单向的；反向路径需要单独任务并交换源 / 目的。
3. CMS 配额 —— DescribeMetricData 与其他 CMS 查询 API 共享每月 1,000,000 次免费调用。
4. CMS 频控 —— 每账号（含 RAM 用户）每秒 10 次调用。

最佳实践

1. 始终执行正向 + 反向分析以确认双向连通性。
2. 路径不可达时，优先检查安全组规则和路由表。
3. vpn/vbr 场景务必提供云下私网 IP。
4. 使用 Mermaid 拓扑图帮助用户可视化流量路径。
5. 仅查询实际路径上的资源监控数据以减少 API 调用。
6. 将监控异常与可达性结果一并呈现，提供完整诊断。

参考文件