alibabacloud-cloudfw-vpc-firewall-diagnosis

VPC 防火墙开通失败诊断

前提条件

CLI 工具

• aliyun-cli 版本：>= 3.3.0。
• 验证：aliyun version。

Python 运行时

• Python 版本：运行 scripts/analyze_routes.py 和 scripts/closure_precheck.py 需要 Python 3.6+。
• 依赖项：仅使用标准库（json、subprocess、sys）。

Alibaba Cloud 凭证

使用 aliyun configure 配置 CLI 配置文件，然后在每条命令中通过 --profile <profile> 传递凭证。

aliyun configure --profile <profile-name>
# Enter AccessKey ID, AccessKey Secret, Region, and output format as prompted.

切勿在命令、脚本或文档中硬编码 AccessKey 值。请参阅 references/profile_setup_guide.md。

必需的 RAM 权限

此技能是只读诊断工具。仅授予以下最低限度的只读操作权限。

操作	用途
cloudfw:DescribeTrFirewallsV2List	查询 VPC 防火墙列表和关键状态字段。
cloudfw:DescribeVpcFirewallList	查询 VPC 边界防火墙信息。
cloudfw:DescribeVpcFirewallPrecheckDetail	查询预检查详情。此 API 使用 --Region，而非 --RegionId。
cloudfw:DescribeFirewallTask	查询流量引流任务状态和 ErrorDetail。
cloudfw:DescribeTrFirewallPolicyBackUpAssociationList	查询回滚目标路由表。
cloudfw:DescribeVpcFirewallControlPolicy	查询 VPC 防火墙 ACL 策略。
actiontrail:LookupEvents	查询近期操作历史。
cbn:ListTransitRouters	查询 CEN 实例下的转发路由器。
cbn:ListTransitRouterRouteTables	查询转发路由器路由表。
cbn:ListTransitRouterRouteEntries	查询路由条目，以便进行路由比较。
cbn:ListTransitRouterVpcAttachments	查询 VPC 挂载项。
vpc:DescribeVpcs / vpc:DescribeVpcAttribute	查询 VPC 基本属性。
sts:GetCallerIdentity	验证配置文件身份。

完整权限详情请参阅 references/ram-policies.md。

User-Agent 要求

所有 Alibaba Cloud 服务调用都必须包含：

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-cloudfw-vpc-firewall-diagnosis

Alibaba Cloud CLI AI-Mode 和插件更新

在此技能中运行任何 Alibaba Cloud 服务 CLI 命令之前，先初始化 CLI AI-Mode 并刷新插件：

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent AlibabaCloud-Agent-Skills/alibabacloud-cloudfw-vpc-firewall-diagnosis
aliyun plugin update

诊断工作流结束后，禁用 AI-Mode：

aliyun configure ai-mode disable

规则：

• 仅在诊断工作流期间启用 AI-Mode，并且必须在完成后禁用。
• set-user-agent 必须使用完整的技能标识符：AlibabaCloud-Agent-Skills/alibabacloud-cloudfw-vpc-firewall-diagnosis。
• plugin update 是本地/系统 CLI 命令，必须在调用服务 API 前运行，以确保小写连字符格式的插件操作处于最新状态；不要为此系统命令添加 --user-agent。
• aliyun version、aliyun configure list 和 python3 --version 等仅在本地执行的环境命令不会调用 Alibaba Cloud 服务 API，因此无需添加 User-Agent 标志。

环境验证

诊断前运行以下只读检查：

aliyun version
aliyun configure list
aliyun sts get-caller-identity --profile <profile> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-cloudfw-vpc-firewall-diagnosis
python3 --version

强制执行规则

每次执行前：

1. 阅读完整的 SKILL.md。
2. 阅读 references/execution_standards.md。
3. 确定适用的场景。
4. 严格遵循该场景的流程；不得跳过强制步骤。

核心原则：只读诊断

此技能是只读诊断助手。

绝对禁止

1. 切勿执行创建、修改、删除、挂载、卸载、启用、禁用或任何会更改配置的操作。
2. 切勿提供带有具体参数值的完整可执行写入命令。
3. 切勿修改 Alibaba Cloud 资源。
4. 切勿硬编码凭证或配置文件名称。

正确的修复建议方式

• 仅提供文本形式的配置指导。
• 列出所需的配置字段和控制台导航路径。
• 说明风险、依赖项和验证要点。
• 由用户在控制台或其自行批准的工作流中手动完成所有配置更改。

标准报告声明

每份诊断报告都必须以以下内容开头：

Notice: This tool is a read-only diagnostic assistant. It only provides analysis and configuration guidance and will not perform any configuration changes.
Please apply all configuration changes manually in the Alibaba Cloud Console or through your own approved process.

允许的命令类别

• AI-Mode 设置命令：aliyun configure ai-mode enable、aliyun configure ai-mode set-user-agent、aliyun plugin update，以及最后执行的 aliyun configure ai-mode disable。
• aliyun cloudfw describe-* 只读查询。
• aliyun cbn list-* 和 aliyun cbn describe-* 只读查询。
• aliyun actiontrail lookup-events 只读操作历史查询。
• aliyun sts get-caller-identity 身份验证。
• 环境检查：aliyun version、aliyun configure list、python3 --version。
• 本地只读检查命令，例如 cat、ls、grep、find、pwd、which、date、stat 和 file。
• 随附的只读脚本：scripts/analyze_routes.py 和 scripts/closure_precheck.py。

任何不符合白名单的 Bash 命令都必须返回 permissionDecision=ask。

必需的用户输入

诊断前一次性收集所有信息：

1. CLI 配置文件名称，例如 default。
2. 是否为跨地域场景。
3. CEN 实例 ID。
4. 涉及跨地域时的地域 ID，例如 cn-hangzhou。
5. 问题类型：创建失败、路由策略配置失败或闭环预检查。

确认所需输入前，不要继续。

闭环预检查铁律

• 切勿手动比较路由。
• 始终保存路由表 JSON 输出并运行 scripts/analyze_routes.py。
• 切勿仅凭 TotalCount 推断路由是否安全。
• 根据脚本输出生成最终路由风险结论。

详细流程：references/closure_precheck_guide.md。

场景速查

场景 1：VPC 防火墙创建失败

首先查询 describe-tr-firewalls-v2-list，然后检查 PrecheckStatus、ResultCode 和防火墙状态字段。请参阅 references/diagnosis_steps.md。

场景 2：路由策略配置失败

首先使用 --TaskType VPC 和 --ChildInstanceId <vpc-id> 查询 describe-firewall-task。请参阅 references/diagnosis_steps.md。

场景 3：闭环预检查，自动引流模式

识别模式，获取 OriginalRouteTableId，运行 scripts/analyze_routes.py，检查 ACL 策略并评估风险。

场景 4：闭环预检查，手动引流模式

收集当前和目标路由表 ID，运行 scripts/analyze_routes.py，检查 ACL 策略并评估风险。

严格禁止事项

• 切勿跳过场景规定的首个必需 API。
• 除非用户明确要求扩大范围，否则切勿查询超过 24 小时之前的日志。
• 切勿使用 DescribeFirewallV2List；此 API 对此技能无效。
• 切勿仅依赖预检查结果。最终证据应使用 ErrorDetail 和 ActionTrail。
• 切勿依赖记忆或外部历史知识进行诊断。此技能必须能够独立完成诊断。

关键 API 与 CLI 操作

API	CLI 操作	服务	必需参数	用途
DescribeTrFirewallsV2List	describe-tr-firewalls-v2-list	cloudfw	--RegionId	查询 VPC 防火墙列表。
DescribeFirewallTask	describe-firewall-task	cloudfw	--TaskType VPC、--ChildInstanceId <vpc-id>	查询路由策略任务状态。
DescribeTrFirewallPolicyBackUpAssociationList	describe-tr-firewall-policy-back-up-association-list	cloudfw	--FirewallId、--TrFirewallRoutePolicyId	查询回滚目标路由表。
DescribeVpcFirewallControlPolicy	describe-vpc-firewall-control-policy	cloudfw	--VpcFirewallId、--PageSize、--CurrentPage	查询 ACL 策略。
LookupEvents	lookup-events	actiontrail	--StartTime、--EndTime、--LookupAttribute.1.Key、--LookupAttribute.1.Value	查询操作历史。
ListTransitRouterRouteTables	list-transit-router-route-tables	cbn	--RegionId、--TransitRouterId	查询路由表。
ListTransitRouterRouteEntries	list-transit-router-route-entries	cbn	--TransitRouterRouteTableId	查询路由条目。

重要说明：

• DescribeVpcFirewallPrecheckDetail 使用 --Region，而不是 --RegionId。
• ListTransitRouterRouteEntries 不需要 --TransitRouterId。
• LookupEvents 使用点号表示法：--LookupAttribute.1.Key。
• 所有阿里云服务 CLI 命令都必须包含 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-cloudfw-vpc-firewall-diagnosis。
• aliyun version、aliyun configure list、aliyun configure ai-mode enable/disable 和 aliyun plugin update 等本地／系统命令不得添加 User-Agent 标志。
• 诊断前必须启用 AI-Mode，并将其配置为使用技能的 User-Agent；工作流结束后必须禁用 AI-Mode。
• CLI 配置文件选项为小写：--profile。

输出格式

针对故障场景，报告：根本原因、证据和建议的补救措施。 针对关闭前检查场景，报告：路由回滚风险、ACL 策略风险、建议的人工操作和验证点。 证据应简洁；除非诊断所需，否则避免披露完整资源清单或敏感标识符。

参考资料

• 关闭前检查指南
• 完整诊断步骤
• 诊断规则
• 完整 API 参考
• 防火墙生命周期
• 执行规范