aliyun-cdn-skill（阿里云 cdn 技能）

能力概述

目录结构

aliyun-cdn-skills/
├── SKILL.md
├── reference/                    # API 定义（YML），含入参与返回值
│   ├── describe_user_domains.yml
│   ├── describe_cdndomain_detail.yml
│   ├── describe_cdndomain_configs.yml
│   ├── describe_domain_cname.yml
│   ├── check_cdndomain_icp.yml
│   ├── describe_verify_content.yml
│   ├── describe_domain_verify_data.yml
│   ├── verify_domain_owner.yml
│   ├── add_cdndomain.yml
│   ├── batch_update_cdndomain.yml
│   ├── batch_set_cdndomain_config.yml
│   ├── refresh_object_caches.yml
│   ├── start_cdndomain.yml
│   └── set_cdndomain_sslcertificate.yml
└── scripts/                      # 可执行脚本与依赖清单
    ├── describe_user_domains.py
    ├── describe_cdndomain_detail.py
    ├── describe_cdndomain_configs.py
    ├── describe_domain_cname.py
    ├── check_cdndomain_icp.py
    ├── describe_verify_content.py
    ├── describe_domain_verify_data.py
    ├── verify_domain_owner.py
    ├── add_cdndomain.py
    ├── batch_update_cdndomain.py
    ├── batch_set_cdndomain_config.py
    ├── refresh_object_caches.py
    ├── start_cdndomain.py
    ├── set_cdndomain_sslcertificate.py
    └── requirements.txt

• reference/：存放 API 相关信息，包括入参、返回值等（YML），供查阅契约与字段含义。
• scripts/：可直接运行的 Python 脚本（例如 python scripts/describe_user_domains.py）；也可阅读其实现，在此基础上编写或改写新代码。
• 依赖：requirements.txt 位于 scripts/ 目录；初次使用请先执行 pip install -r aliyun-cdn-skills/scripts/requirements.txt 安装依赖。

本 skill 提供以下独立能力，可根据实际需求单独调用或组合使用：

重要说明：

• 每个能力对应一个独立 API，无固定调用顺序；可按业务组合（例如先列表再详情、加域名前做备案检查）。
• 写操作（添加、批量更新、批量设配置、刷新缓存、归属校验提交、启用、证书等）需要账号或 RAM 用户具备相应 CDN 写权限；生产环境变更前建议先在控制台或测试域名验证。RefreshObjectCaches 会使缓存立即失效、回源量增加，请控制批量与频率。

前置检查（必须首先执行）

执行任何调用前，必须先确认 AK/SK 已配置。

检查顺序

1. 优先检查环境变量

echo "AK_ID: ${ALIBABA_CLOUD_ACCESS_KEY_ID:+已设置}"
echo "AK_SECRET: ${ALIBABA_CLOUD_ACCESS_KEY_SECRET:+已设置}"

2. 如果未设置，检查当前工作目录的 .env 文件

find . -maxdepth 1 -name ".env" -exec cat {} \;

.env 文件格式：

ALIBABA_CLOUD_ACCESS_KEY_ID=your-access-key-id
ALIBABA_CLOUD_ACCESS_KEY_SECRET=your-access-key-secret

3. Python 代码中加载凭证

from dotenv import load_dotenv
import os

access_key_id = os.environ.get("ALIBABA_CLOUD_ACCESS_KEY_ID", "").strip()
access_key_secret = os.environ.get("ALIBABA_CLOUD_ACCESS_KEY_SECRET", "").strip()

if not access_key_id or not access_key_secret:
    load_dotenv()
    access_key_id = os.environ.get("ALIBABA_CLOUD_ACCESS_KEY_ID", "").strip()
    access_key_secret = os.environ.get("ALIBABA_CLOUD_ACCESS_KEY_SECRET", "").strip()

if not access_key_id or not access_key_secret:
    raise RuntimeError("缺少阿里云凭证。请先设置 ALIBABA_CLOUD_ACCESS_KEY_ID 和 ALIBABA_CLOUD_ACCESS_KEY_SECRET")

未通过凭证检查时，不应继续执行后续步骤。

安装依赖

pip install -r aliyun-cdn-skills/scripts/requirements.txt

或手动安装：

pip install alibabacloud_cdn20180510 alibabacloud_credentials alibabacloud_tea_openapi alibabacloud_tea_util python-dotenv

客户端初始化（CDN）

使用凭据链初始化 Cdn20180510Client，endpoint 固定为 cdn.aliyuncs.com（与现有脚本一致）：

from alibabacloud_cdn20180510.client import Client as Cdn20180510Client
from alibabacloud_credentials.client import Client as CredentialClient
from alibabacloud_tea_openapi import models as open_api_models

credential = CredentialClient()
config = open_api_models.Config(credential=credential)
config.endpoint = "cdn.aliyuncs.com"
client = Cdn20180510Client(config)

各 API 的请求模型位于 alibabacloud_cdn20180510.models，调用形态为 client.<api>_with_options(request, runtime)，具体见对应 scripts/*.py。

分页（DescribeUserDomains）

reference/describe_user_domains.yml 中 PageSize 取值 1～500（默认 20），PageNumber 为页码。需要拉取全量域名时，应在代码中循环递增 PageNumber，直到返回数据不足一页或达到总页数。

仓库内 scripts/describe_user_domains.py 为最小示例（未填分页参数）；生产或全量同步需自行实现分页循环。

常见组合（非强制）

• 运维排查：DescribeUserDomains → DescribeCdnDomainDetail / DescribeCdnDomainConfigs。
• 接入与解析：DescribeDomainCname 验证 CNAME；DescribeCdnDomainDetail 查看分配的 CNAME。
• 新域名上线前：CheckCdnDomainICP 与业务要求核对后，再 AddCdnDomain 或后续改配。
• 域名归属：DescribeVerifyContent / DescribeDomainVerifyData 获取校验方式与数据，按控制台或文档完成 DNS/文件等验证后，再 VerifyDomainOwner 提交校验（具体参数与流程以 YML、官方文档为准）。
• 批量改功能项：BatchSetCdnDomainConfig 与 BatchUpdateCdnDomain 关注点不同（前者偏域名上的 Functions 批量配置），按 YML 限制控制单次域名数与功能项数。
• 发布与缓存：RefreshObjectCaches 在资源更新后刷新 URL/目录；注意单次任务 URL 域名个数等配额（见 YML）。
• HTTPS：DescribeCdnDomainDetail 看证书状态后，SetCdnDomainSSLCertificate 更新证书或开关。

错误处理建议

• 401/403：AK/SK 无效、未配置或 RAM 权限不足。
• InvalidAccessKeyId：AccessKeyId 错误。
• SignatureDoesNotMatch：AccessKeySecret 错误或签名不一致。
• 若异常包含 data 且其中有 Recommend，优先按诊断链接排查。

各 API 说明（简要）

以下仅作索引；请求/响应字段以对应 YML 为准，示例调用以 scripts 为准。

DescribeUserDomains

查询账号下加速域名列表，支持域名模糊匹配、状态等筛选。详见 reference/describe_user_domains.yml，示例：scripts/describe_user_domains.py。

DescribeCdnDomainDetail

查询单个加速域名的基本信息（源站、CNAME、业务类型、运行状态等）。详见 reference/describe_cdndomain_detail.yml，示例：scripts/describe_cdndomain_detail.py。

DescribeCdnDomainConfigs

查询域名上已配置的功能项（如 FunctionNames 逗号分隔）。详见 reference/describe_cdndomain_configs.yml，示例：scripts/describe_cdndomain_configs.py。

DescribeDomainCname

对加速域名做 CNAME 解析检测（单次最多域名个数见 YML 说明）。详见 reference/describe_domain_cname.yml，示例：scripts/describe_domain_cname.py。

CheckCdnDomainICP

查询域名备案相关信息。读接口，用于合规核对。详见 reference/check_cdndomain_icp.yml，示例：scripts/check_cdndomain_icp.py。

DescribeVerifyContent

查询加速域名归属校验所需内容（单域名）。读接口。详见 reference/describe_verify_content.yml，示例：scripts/describe_verify_content.py。

DescribeDomainVerifyData

根据域名及是否开启全球资源计划等条件，返回对应的校验数据/内容（单域名）。读接口。详见 reference/describe_domain_verify_data.yml，示例：scripts/describe_domain_verify_data.py。

VerifyDomainOwner

对域名归属权进行校验（单域名）。OpenAPI 标记为写类操作，调用前通常需先完成 DNS/文件等验证步骤。写接口。详见 reference/verify_domain_owner.yml，示例：scripts/verify_domain_owner.py。

AddCdnDomain

新增加速域名。写接口，需具备创建与配置权限；参数较多（源站、加速区域、业务类型等），务必对照 YML 填写。详见 reference/add_cdndomain.yml，示例：scripts/add_cdndomain.py。

BatchUpdateCdnDomain

批量更新加速域名基本信息。写接口，变更前建议确认影响范围。详见 reference/batch_update_cdndomain.yml，示例：scripts/batch_update_cdndomain.py。

BatchSetCdnDomainConfig

对多个加速域名批量设置功能配置（Functions 等）。写接口；单次域名个数、与功能项数量的乘积上限等以 YML 为准。详见 reference/batch_set_cdndomain_config.yml，示例：scripts/batch_set_cdndomain_config.py。

私有 OSS Bucket 回源配置

当源站为阿里云 OSS 私有 Bucket 时，需要开启私有回源功能，CDN 才能正常回源拉取资源：

import json
from alibabacloud_cdn20180510 import models as cdn_20180510_models

# 配置私有 OSS 回源
functions = [{
    "functionName": "l2_oss_key",
    "functionArgs": [
        {
            "argName": "private_oss_auth",
            "argValue": "on"
        }
    ]
}]

request = cdn_20180510_models.BatchSetCdnDomainConfigRequest(
    domain_names="www.example.com",
    functions=json.dumps(functions)
)

关键参数说明：

• functionName: l2_oss_key - OSS 私有 Bucket 回源功能
• argName: private_oss_auth - 私有 OSS 鉴权开关
• argValue: on 开启私有回源，off 关闭私有回源

RefreshObjectCaches

按 URL 或目录刷新节点缓存，使对应对象缓存失效并回源拉取最新内容；支持批量，写接口。注意回源与配额（单次 URL 中域名个数等见 YML）。详见 reference/refresh_object_caches.yml，示例：scripts/refresh_object_caches.py。

StartCdnDomain

将停用状态的加速域名启用为 Online。写接口，需域名与账户状态正常。详见 reference/start_cdndomain.yml，示例：scripts/start_cdndomain.py。

SetCdnDomainSSLCertificate

配置 HTTPS 证书开关（SSLProtocol）及证书内容或 CAS 证书引用等。写接口；涉及证书与私钥时注意保密与权限。详见 reference/set_cdndomain_sslcertificate.yml，示例：scripts/set_cdndomain_sslcertificate.py。

注意事项

• reference/ 中的 YML 用于查阅 API 入参与返回值；scripts/ 中的脚本可直接运行以验证环境与 SDK 调用。
• 若业务场景与示例不同，在阅读 YML 与脚本后自行改写或新建代码。
• 写操作类 API 请遵循最小权限原则，为 RAM 用户配置所需动作即可。

能力扩展

本 skill 可继续增加其他 CDN OpenAPI（例如停用域名、预热等），建议同样以「reference YML + scripts 示例 + 本表追加一行」的方式扩展，保持与 aliyun-domain-skills 一致的使用体验。