aliyun-esa-manage

类别：服务

边缘安全加速（ESA）— Pages、Edge Routine、KV、站点管理、分析等

使用阿里云 OpenAPI（RPC）和官方 Python SDK 管理 ESA 的所有功能。

阿里云 ESA 提供五项核心功能：

• Pages — 将 HTML 或静态目录部署到边缘节点（基于 Edge Routine 的快速部署流程）
• Edge Routine（ER） — 全生命周期管理无服务器边缘函数
• Edge KV — 分布式边缘键值存储，支持 Namespace/Key/Value 管理
• 站点管理 — 站点管理、DNS 记录、缓存规则、证书等
• 分析 — 流量分析、时序趋势、Top-N 排名、带宽统计、请求指标

统一使用 Python SDK 调用 ESA OpenAPI。

前提条件

• 准备 AccessKey（遵循最小权限原则的 RAM 用户/角色）。
• 安装 Python SDK：pip install alibabacloud_esa20240910 alibabacloud_tea_openapi alibabacloud_credentials
• ESA OpenAPI 使用 RPC 风格；建议使用 SDK 或 OpenAPI Explorer，避免手动签名。

SDK 快速入门

from alibabacloud_esa20240910.client import Client as Esa20240910Client
from alibabacloud_esa20240910 import models as esa_models
from alibabacloud_tea_openapi import models as open_api_models


def create_client(region_id: str = "cn-hangzhou") -> Esa20240910Client:
    config = open_api_models.Config(
        region_id=region_id,
        endpoint="esa.cn-hangzhou.aliyuncs.com",
    )
    return Esa20240910Client(config)

Pages — 边缘页面部署

Pages 是基于 Edge Routine 的快速部署流程，可将 HTML 或静态目录部署到边缘节点。

HTML 页面部署流程

CreateRoutine → GetRoutineStagingCodeUploadInfo → Upload code to OSS
→ CommitRoutineStagingCode → PublishRoutineCodeVersion(staging)
→ PublishRoutineCodeVersion(production) → GetRoutine(get access URL)

静态目录部署流程

CreateRoutine → CreateRoutineWithAssetsCodeVersion → Package zip and upload to OSS
→ Poll GetRoutineCodeVersionInfo(wait for available)
→ CreateRoutineCodeDeployment(staging) → CreateRoutineCodeDeployment(production)
→ GetRoutine(get access URL)

Zip 包结构

Zip 包结构取决于 EDGE_ROUTINE_TYPE（根据是否存在入口文件和资源目录，由 checkEdgeRoutineType 自动确定）：

• JS_ONLY：routine/index.js（使用 esbuild 打包，或通过 --no-bundle 直接读取源文件）
• ASSETS_ONLY：assets/ 下的所有静态文件，并保留原始目录结构
• JS_AND_ASSETS：routine/index.js + assets/ 静态资源（最常见）

assets/ 路径相对于配置中的 assets.directory。配置优先级：CLI 参数 > esa.jsonc / esa.toml。

重要说明

• 函数名称规则：使用小写字母、数字和连字符，以小写字母开头，长度 >= 2
• 同名函数：如果已存在则复用，并部署新版本代码
• 默认部署到预发和生产环境
• 部署成功后，通过 GetRoutine 获取作为访问域名的 defaultRelatedRecord

绑定自定义域名（CNAME 接入站点）

对于 CNAME 接入站点，将自定义域名绑定到 Pages/ER routine 需要：

1. CreateRecord(A/AAAA, proxied=true)     → Register domain in ESA CDN
2. CreateRoutineRoute(rule expression)     → Route traffic to Edge Routine
3. External DNS: CNAME → record_cname      → Point domain to ESA CDN
4. ApplyCertificate(lets_encrypt)          → Provision SSL certificate

重要：CNAME 接入站点请勿使用 CreateRoutineRelatedRecord — 它不会创建可见的 DNS 记录，导致 CDN 回源。请改用 A/AAAA 记录 + 路由。

SDK 说明：CreateRoutineRoute 的参数是 rule（ESA 规则表达式，例如 (http.host eq "domain")），而不是 route。

详细参考：references/pages.md（章节：绑定自定义域名）

Edge Routine（ER）— 边缘函数

通过 Python SDK 管理无服务器边缘函数的完整生命周期。

核心工作流

CreateRoutine → GetRoutineStagingCodeUploadInfo → Upload code to OSS
→ CommitRoutineStagingCode → PublishRoutineCodeVersion
→ (CreateRoutineRoute) → GetRoutine

API 概览

• 函数管理：CreateRoutine、DeleteRoutine、GetRoutine、GetRoutineUserInfo、ListUserRoutines
• 代码版本：GetRoutineStagingCodeUploadInfo、CommitRoutineStagingCode、PublishRoutineCodeVersion、DeleteRoutineCodeVersion
• 路由：CreateRoutineRoute、UpdateRoutineRoute、DeleteRoutineRoute、GetRoutineRoute、ListRoutineRoutes、ListSiteRoutes
• 关联记录：CreateRoutineRelatedRecord、DeleteRoutineRelatedRecord、ListRoutineRelatedRecords

ER 代码格式

export default {
  async fetch(request) {
    return new Response("Hello", {
      headers: { "content-type": "text/html;charset=UTF-8" },
    });
  },
};

详细参考：references/er.md

Edge KV — 边缘键值存储

分布式边缘键值存储，可在 Edge Routine 中读写，也可通过 OpenAPI/SDK 管理。

核心概念

• Namespace：KV 数据的隔离容器，Key 最长 512 个字符，Value 最大 2MB（高容量模式下为 25MB）
• 支持 TTL 过期：Expiration（Unix 时间戳）或 ExpirationTtl（秒）

API 摘要

• 命名空间：CreateKvNamespace、DeleteKvNamespace、GetKvNamespace、GetKvAccount、DescribeKvAccountStatus
• 单键操作：PutKv、GetKv、GetKvDetail、DeleteKv、PutKvWithHighCapacity
• 批量操作：BatchPutKv、BatchDeleteKv、BatchPutKvWithHighCapacity、BatchDeleteKvWithHighCapacity、ListKvs

快速入门

client = create_client()

# Create namespace
client.create_kv_namespace(esa_models.CreateKvNamespaceRequest(namespace="my-ns"))

# Write
client.put_kv(esa_models.PutKvRequest(namespace="my-ns", key="k1", value="v1"))

# Read
resp = client.get_kv(esa_models.GetKvRequest(namespace="my-ns", key="k1"))

详细参考：references/kv.md

站点管理 — 站点管理

使用 Python SDK 管理 ESA 站点、DNS 记录、缓存规则等。

API 行为说明

• 大多数列表 API 支持通过 PageNumber + PageSize 分页。
• ListSites 会返回所有区域的站点，无需遍历各个区域。
• 新创建的站点初始状态为 pending；通过 VerifySite 完成访问验证后即可激活。
• 删除站点会移除所有关联配置。
• UpdateSiteAccessType 可以在 CNAME 和 NS 之间切换，但如果存在不兼容的 DNS 记录，切换到 CNAME 可能会失败。
• DNS 记录 API（CreateRecord、ListRecords 等）适用于通过 NS 和 CNAME 接入的站点。CNAME 站点仅支持 CNAME 和 A/AAAA 类型，且记录不能禁用加速（代理必须保持启用）。
• DNS 记录的 Type 参数必须精确匹配：使用 A/AAAA（而非 A）、CNAME、MX、TXT、NS、SRV、CAA。
• CreateCacheRule 支持两种配置类型：global（站点级默认配置）和 rule（带有匹配表达式的条件规则）。

工作流

1. 确认目标站点 ID、接入类型（CNAME/NS）以及所需操作。
2. 在 references/api_overview.md 中查找 API 分组和确切的操作名称。
3. 使用 Python SDK（优先）或 OpenAPI Explorer 调用 API。
4. 使用 describe/list API 验证结果。
5. 如果需要可重复使用的清单或摘要，请使用 scripts/，并将输出写入 output/aliyun-esa-manage/。

SDK 优先级

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

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

• 列出所有 ESA 站点：scripts/list_sites.py
• 按套餐汇总站点：scripts/summary_sites_by_plan.py
• 检查站点状态：scripts/check_site_status.py
• 列出站点的 DNS 记录：scripts/list_dns_records.py

分析 — 流量分析

使用 DescribeSiteTimeSeriesData 和 DescribeSiteTopData API 查询和分析 ESA 站点流量数据。

核心功能

• 时间序列数据：按可配置的时间粒度查询流量趋势
• Top-N 排名：按国家/IP/主机/路径/状态码等维度获取排名
• 多种指标：流量、请求数、请求流量、页面浏览量
• 丰富的维度：国家、省份、ISP、浏览器、设备、主机、路径、状态码等

两个主要 API

1. DescribeSiteTimeSeriesData — 时间序列趋势

查询随时间变化的流量趋势，并返回聚合后的数据点。

时间粒度规则：

时间范围	间隔	间隔值
<= 3 小时	1 分钟	60
3-12 小时	5 分钟	300
12 小时 - 1 天	15 分钟	900
1-10 天	1 小时	3600
10-31 天	1 天	86400

2. DescribeSiteTopData — Top-N 排名

按各种维度查询 Top-N 排名数据。

数量选项： 5、10、150

可用指标（FieldName）

字段	类型	描述
Traffic	int	从 ESA 到客户端的响应流量（字节）
Requests	int	请求数
RequestTraffic	int	客户端请求流量（字节）
PageView	int	页面浏览量

可用维度

地理维度： ClientCountryCode（国家/地区）、ClientProvinceCode（省份）、ClientISP（ISP）、ClientASN

客户端信息： ClientIP、ClientIPVersion、ClientBrowser、ClientDevice、ClientOS

请求详情： ClientRequestHost、ClientRequestMethod、ClientRequestPath、ClientRequestProtocol、ClientRequestQuery、ClientRequestReferer、ClientRequestUserAgent

响应/缓存： EdgeCacheStatus、EdgeResponseStatusCode、EdgeResponseContentType、OriginResponseStatusCode

其他： ALL（聚合）、SiteId（账户级查询）、Version、ClientSSLProtocol、ClientXRequestedWith

错误处理

HTTP 代码	错误代码	说明
400	InvalidParameter.TimeRange	时间范围超出限制（最长 31 天）
400	InvalidEndTime.Mismatch	EndTime 早于 StartTime
400	InvalidParameter.Field	字段名称无效
400	InvalidParameter.Dimension	维度无效
400	InvalidTime.Malformed	时间格式错误（请使用 yyyy-MM-ddTHH:mm:ssZ）

详细参考：references/time-series.md、references/top-data.md、references/fields.md

源站规则 — CDN 代理回源

源站规则控制 ESA CDN 如何回源到源站。当需要通过 ESA CDN 将子域名代理到后端服务器时使用。

CDN 代理回源工作流

CreateRecord(A, proxied=true) → ApplyCertificate → CreateOriginRule → 验证

API 概览

• 源站规则管理：CreateOriginRule、ListOriginRules、GetOriginRule、UpdateOriginRule、DeleteOriginRule

关键参数

参数	说明
rule	匹配条件，例如 (http.host eq "sub.example.com")
origin_scheme	回源协议：http 或 https（默认 https）
origin_port	回源端口
dns_record	回源目标 DNS 记录名称（必须是 ESA DNS 记录名称，不能是 IP）

重要注意事项

1. dns_record 必须是 ESA DNS 记录名称（如 agent.example.com），不能使用原始 IP（如 1.2.3.4），否则会报错 destination_not_found。
2. origin_scheme 默认使用 HTTPS：源站仅监听 HTTP 时，必须显式设为 http，否则会返回 502。
3. DNS 记录必须设置为 proxied=true：否则流量不会经过 CDN，源站规则也不会生效。
4. Edge Routine Route 的优先级高于源站规则：同一域名存在 ER route 时会拦截请求，需先删除该 route。

详细参考：references/origin-rules.md

常见操作映射

站点管理

• 创建站点：CreateSite
• 列出站点：ListSites（支持 SiteName、Status、AccessType、Coverage 筛选条件）
• 获取站点详情：GetSite
• 删除站点：DeleteSite
• 检查站点名称是否可用：CheckSiteName
• 验证站点所有权：VerifySite
• 更新访问类型：UpdateSiteAccessType
• 更新覆盖范围：UpdateSiteCoverage
• 获取当前名称服务器：GetSiteCurrentNS
• 更新自定义名称服务器：UpdateSiteVanityNS
• 暂停/恢复站点：UpdateSitePause、GetSitePause
• 站点独占性：UpdateSiteNameExclusive、GetSiteNameExclusive
• 版本管理：ActivateVersionManagement、DeactivateVersionManagement

站点配置

• IPv6：GetIPv6、UpdateIPv6

DNS 记录

NS 访问：支持所有记录类型。CNAME 访问：仅支持 CNAME 和 A/AAAA，代理必须保持启用。

• 创建记录：CreateRecord
• 列出记录：ListRecords（支持 Type、RecordName、Proxied 筛选条件）
• 获取记录：GetRecord
• 更新记录：UpdateRecord
• 删除记录：DeleteRecord
• 批量创建：BatchCreateRecords
• 导出记录：ExportRecords

缓存规则

• 创建缓存规则：CreateCacheRule
• 列出缓存规则：ListCacheRules
• 获取缓存规则：GetCacheRule
• 更新缓存规则：UpdateCacheRule
• 删除缓存规则：DeleteCacheRule

缓存规则表达式说明（重要）：

• CreateCacheRule 参数是扁平结构，不是嵌套的 JSON Rule 对象。
• Rule 参数是匹配条件表达式字符串。请参阅下方的规则表达式语法部分。
• 快速提示：ends_with()/starts_with() 必须采用函数调用形式；matches（正则表达式）要求使用标准版或更高版本。
• 使用 --EdgeCacheMode override_origin --EdgeCacheTtl <seconds> 设置边缘缓存 TTL。

规则表达式语法

ESA 在多项功能中（缓存规则、WAF 自定义规则、速率限制、URL 重写、标头修改等）使用统一的规则引擎表达式语法。

何时使用

对于接受匹配条件表达式的任何 ESA API，请在 Rule 参数中使用此语法：

• CreateCacheRule / UpdateCacheRule - 缓存规则
• CreateWafRule / UpdateWafRule - WAF 自定义规则
• CreateRatePlanRule - 速率限制规则
• CreateRewriteUrlRule / UpdateRewriteUrlRule - URL 重写规则
• 源站规则、重定向规则、标头修改规则等

表达式格式

(condition)
(condition1 and condition2)
(condition1) or (condition2)

最大嵌套深度：2 层。

运算符语法 - 两种形式

中缀形式（运算符位于字段和值之间）：

(field eq "value")
(field ne "value")
(field contains "value")
(field in {"value1" "value2"})
(field matches "regex")

函数形式（运算符包裹字段）：

(starts_with(field, "value"))
(ends_with(field, "value"))
(exists(field))
(len(field) gt 100)
(lower(field) eq "value")

常见模式

# Match file extension
--Rule '(http.request.uri.path.extension eq "html")'

# Match multiple extensions
--Rule '(http.request.uri.path.extension in {"js" "css" "png" "jpg"})'

# Match URL prefix
--Rule '(starts_with(http.request.uri, "/api/"))'

# Match URL suffix
--Rule '(ends_with(http.request.uri, ".html"))'

# Match URL containing substring (value MUST start with /)
--Rule '(http.request.uri contains "/test")'

# Match specific host
--Rule '(http.host eq "www.example.com")'

# Combined conditions
--Rule '(http.request.uri contains "/test" and ip.geoip.country eq "CN")'

# Match by country
--Rule '(ip.geoip.country eq "CN")'

# Exclude path
--Rule '(not starts_with(http.request.uri, "/admin/"))'

# Negating set membership
--Rule '(not http.host in {"a.com" "b.com"})'

关键注意事项

1. ends_with 和 starts_with 必须使用函数调用语法，不能使用中缀形式。
2. matches（正则表达式）要求标准版或更高版本；基础版会返回 RuleRegexQuotaCheckFailed。
3. URI 与 contains 搭配使用时必须包含路径分隔符："/test" 正确；单独使用 "test" 会导致 CompileRuleError。
4. in 运算符中的列表值在大括号内以空格分隔：{"a.com" "b.com"}。
5. 单个条件的外层括号可选。
6. “不等于”请使用 ne，切勿使用 not...eq。
7. 对集合成员关系取反时请使用 not...in（放在字段前），不要使用 not in。

套餐限制

套餐	eq/ne/in/starts_with/ends_with	contains	matches（正则表达式）
基础版	支持	支持	不支持
标准版	支持	支持	支持
企业版	支持	支持	支持

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 发现

• 产品代码：ESA
• 默认 API 版本：2024-09-10
• 元数据端点：https://api.aliyun.com/meta/v1/products/ESA/versions/2024-09-10/api-docs.json
• 使用 OpenAPI 元数据端点列出 API 并获取架构（参见参考资料）。

输出策略

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

参考资料

Pages、ER 和 KV

• Pages 部署参考：references/pages.md
• Edge Routine 参考：references/er.md
• Edge KV 存储参考：references/kv.md

源站规则

• 源站规则配置与故障排除：references/origin-rules.md

站点管理

• API 概览：references/api_overview.md
• 端点：references/endpoints.md
• 站点：references/sites.md
• DNS 记录：references/dns-records.md
• 缓存：references/cache.md
• 源站：references/sources.md
• 规则表达式 - 生成指南：references/rule-generation-guide.md
• 规则表达式 - 匹配字段：references/rule-match-fields.md
• 规则表达式 - 运算符：references/rule-operators.md
• 规则表达式 - 示例：references/rule-examples.md

分析

• 时间序列数据 API：references/time-series.md
• Top-N 数据 API：references/top-data.md
• 指标与维度参考：references/fields.md