aliyun-vpc-manage

类别：服务

Virtual Private Cloud（VPC）

验证

mkdir -p output/aliyun-vpc-manage
for f in skills/network/vpc/aliyun-vpc-manage/scripts/*.py; do
  python3 -m py_compile "$f"
done
echo "py_compile_ok" > output/aliyun-vpc-manage/validate.txt

通过标准：命令以 0 退出，并生成 output/aliyun-vpc-manage/validate.txt。

输出与证据

• 将列表/摘要输出保存到 output/aliyun-vpc-manage/。
• 在每个证据文件中保留命令参数和地域范围。

使用 Alibaba Cloud OpenAPI（RPC）及官方 SDK 或 OpenAPI Explorer 管理 VPC 资源。 所有示例和执行操作均优先使用 Python SDK。

前置条件

pip install alibabacloud_vpc20160428 alibabacloud_tea_openapi alibabacloud_credentials

• 准备 AccessKey（遵循最小权限原则的 RAM 用户/角色）。
• 选择正确的地域和终端节点（公网/VPC）。
• VPC OpenAPI 采用 RPC 风格；优先使用 SDK 或 OpenAPI Explorer，避免手动签名。

API 行为说明（摘自 VPC 文档）

• DescribeVpcs 和 DescribeVSwitches 支持通过 PageNumber + PageSize 分页。
• DescribeVpcs 请求中必须包含 RegionId。
• CreateVpc 会立即返回 VpcId，但 VPC 会进入 Pending 状态；使用 DescribeVpcs 轮询，直到状态变为 Available。
• CreateVSwitch 要求已存在状态为 Available 的 VPC，且 ZoneId 有效。
• 如果 VPC 仍关联着 VSwitch、安全组或其他资源，DeleteVpc 将失败。
• 如果 VSwitch 仍有 ECS 实例或其他资源，DeleteVSwitch 将失败。

工作流

1. 确认地域、资源标识符和所需操作。
2. 在 references/api_overview.md 中查找 API 组和准确的操作名称。
3. 使用 Python SDK（优先）或 OpenAPI Explorer 调用 API。
4. 使用 describe/list API 验证结果。
5. 如果需要可重复执行的资源清单或摘要，请使用 scripts/，并将输出写入 output/aliyun-vpc-manage/。

SDK 优先级

1. Python SDK（优先）
2. OpenAPI Explorer
3. 其他 SDK（仅在无法使用 Python 时）

Python SDK 快速入门（列出 VPC）

建议使用虚拟环境（避免受到 PEP 668 系统安装限制）。

python3 -m venv .venv
. .venv/bin/activate
pip install alibabacloud_vpc20160428 alibabacloud_tea_openapi alibabacloud_credentials

from alibabacloud_vpc20160428.client import Client as Vpc20160428Client
from alibabacloud_vpc20160428 import models as vpc_models
from alibabacloud_tea_openapi import models as open_api_models


def create_client(region_id: str) -> Vpc20160428Client:
    config = open_api_models.Config(
        region_id=region_id,
        endpoint=f"vpc.{region_id}.aliyuncs.com",
    )
    return Vpc20160428Client(config)


def list_vpcs(region_id: str):
    client = create_client(region_id)
    resp = client.describe_vpcs(vpc_models.DescribeVpcsRequest(
        region_id=region_id,
        page_number=1,
        page_size=50,
    ))
    for v in resp.body.vpcs.vpc:
        print(v.vpc_id, v.vpc_name, v.cidr_block, v.status)


if __name__ == "__main__":
    list_vpcs("cn-hangzhou")

Python SDK 脚本（建议用于资源清单）

• 列出某地域中的 VPC：scripts/list_vpcs.py
• 列出某地域中的 VSwitch：scripts/list_vswitches.py
• 创建 VPC：scripts/create_vpc.py
• 创建 VSwitch：scripts/create_vswitch.py
• 删除 VPC：scripts/delete_vpc.py
• 删除 VSwitch：scripts/delete_vswitch.py
• 查询可用区：scripts/describe_zones.py

VPC 网络规划设计原则

CIDR 地址规划

• 每个地域的业务 VPC 使用独立的 /16 网段，避免跨地域互联时 CIDR 冲突。推荐分配方式：

地域	推荐 CIDR
cn-hangzhou	10.1.0.0/16
cn-shanghai	10.2.0.0/16
ap-southeast-1	10.3.0.0/16
cn-beijing	10.4.0.0/16
更多地域	10.5~254.0.0/16

• 不要使用过大的 CIDR（如 10.0.0.0/8），即使 VSwitch 只使用了其中很小的一部分。大网段会阻止通过 CEN 与其他 10.x 网段的 VPC 互联。
• VSwitch 统一使用 /24（252 个可用 IP），足以满足大多数业务需求。如果单个可用区需要大量实例，可使用 /20（4092 个 IP）。
• 为未来扩展预留网段间隔。例如，应用层使用 0-9，数据库层使用 10-19，中间件使用 20-29。

可用区与高可用

• 生产环境至少覆盖 2~3 个可用区，每个可用区至少配置 1 个 VSwitch。
• 将应用层和数据层部署在不同的可用区，确保单个 AZ 故障时服务不中断。
• 创建 VSwitch 前，先使用 scripts/describe_zones.py 查询可用区列表。不同地域的可用区编号不同。

VSwitch 分层隔离

按业务功能对 VSwitch 进行分段，便于通过 ACL 和安全组实现网络隔离：

10.x.0~9.0/24    → 应用层（Web/API 服务器）
10.x.10~19.0/24  → 数据层（RDS、Redis、MongoDB）
10.x.20~29.0/24  → 中间件（MQ、ES、Nacos）
10.x.30~39.0/24  → 管理层（跳板机、运维工具）

VSwitch 命名规范

推荐格式：vsw-{region简写}-{可用区}-{用途}

示例：vsw-sg-a-app、vsw-hz-h-db、vsw-sh-e-middleware

跨地域互联（CEN）

• 需要互联的 VPC 的 CIDR 必须不重叠。
• 自动生成的 VPC（如 FC 组件创建的）通常使用 10.0.0.0/8，不要将其加入 CEN，否则会与其他地域的 10.x 网段冲突。
• 规划业务 VPC 时应预先考虑 CEN 互联需求，从一开始就使用不重叠的 /16 网段。

常见陷阱

问题	原因	解决方案
CEN 挂载失败，提示 CIDR 冲突	两个 VPC 使用了重叠的 CIDR	新建 VPC 时使用不重叠的 /16 网段
DeleteVpc 失败	VPC 下仍有 VSwitch/安全组/NAT 等资源	先删除所有子资源，再删除 VPC
DeleteVSwitch 失败	VSwitch 下仍有 ECS/RDS 等实例	先释放或迁移实例
创建 VSwitch 时提示 ZoneId 无效	该可用区不受支持或已售罄	使用 describe_zones.py 查询有效可用区
使用默认 VPC 运行生产环境	默认 VPC 网段不可控，且无法与其他 VPC 合理互联	生产环境始终新建 VPC，并规划好 CIDR

常见操作映射

• VPC 生命周期：CreateVpc、DeleteVpc、ModifyVpcAttribute
• VPC 查询：DescribeVpcs、DescribeVpcAttribute
• VSwitch 生命周期：CreateVSwitch、DeleteVSwitch、ModifyVSwitchAttribute
• VSwitch 查询：DescribeVSwitches、DescribeVSwitchAttributes
• 路由表：CreateRouteTable、DeleteRouteTable、DescribeRouteTables、CreateRouteEntry、DeleteRouteEntry
• NAT Gateway：CreateNatGateway、DeleteNatGateway、DescribeNatGateways
• EIP：AllocateEipAddress、AssociateEipAddress、UnassociateEipAddress、ReleaseEipAddress、DescribeEipAddresses
• 标签：TagResources、UntagResources、ListTagResources

查询模式

• 列出 VPC：DescribeVpcs（支持的筛选条件：VpcId、VpcName、IsDefault、ResourceGroupId）
• 列出 VSwitch：DescribeVSwitches（支持的筛选条件：VpcId、VSwitchId、ZoneId、VSwitchName、IsDefault）
• 可用可用区：使用 ECS DescribeZones API 查找创建 VSwitch 时可用的有效可用区

AccessKey 优先级（必须遵循，与 README 保持一致）

1. 环境变量：ALIBABACLOUD_ACCESS_KEY_ID / ALIBABACLOUD_ACCESS_KEY_SECRET / ALIBABACLOUD_REGION_ID 区域策略：ALIBABACLOUD_REGION_ID 是可选的默认值。若未设置，则为任务选择最合适的区域；若无法确定，请询问用户。
2. 共享配置文件：~/.alibabacloud/credentials（区域仍从环境变量读取）

身份验证设置（与 README 保持一致）

环境变量：

export ALIBABACLOUD_ACCESS_KEY_ID="your-ak"
export ALIBABACLOUD_ACCESS_KEY_SECRET="your-sk"
export ALIBABACLOUD_REGION_ID="cn-hangzhou"

Alibaba Cloud SDK 也支持：

export ALIBABA_CLOUD_ACCESS_KEY_ID="your-ak"
export ALIBABA_CLOUD_ACCESS_KEY_SECRET="your-sk"

旧版兼容性：

export ALICLOUD_ACCESS_KEY_ID="your-ak"
export ALICLOUD_ACCESS_KEY_SECRET="your-sk"

共享配置文件：

~/.alibabacloud/credentials

[default]
type = access_key
access_key_id = your-ak
access_key_secret = your-sk

API 发现

• 产品代码：Vpc
• 默认 API 版本：2016-04-28
• 使用 OpenAPI 元数据端点列出 API 并获取架构（参见参考资料）。

输出策略

如果需要保存响应或生成的产物，请将它们写入： output/aliyun-vpc-manage/

参考资料

• API 概览：references/api_overview.md
• 来源：references/sources.md