Pages — 边缘页面部署

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

部署 HTML 页面流程

CreateRoutine → GetRoutineStagingCodeUploadInfo → 上传代码到OSS
→ CommitRoutineStagingCode → PublishRoutineCodeVersion(staging)
→ PublishRoutineCodeVersion(production) → GetRoutine(获取访问URL)

部署静态目录流程

CreateRoutine → CreateRoutineWithAssetsCodeVersion → 打包zip上传OSS
→ 轮询 GetRoutineCodeVersionInfo(等待available)
→ CreateRoutineCodeDeployment(staging) → CreateRoutineCodeDeployment(production)
→ GetRoutine(获取访问URL)

zip 包结构

zip 包结构取决于 EDGE_ROUTINE_TYPE（由 checkEdgeRoutineType 根据 entry 文件和 assets 目录是否存在自动判断）：

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

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

关键注意事项

• 函数名规则 : 小写字母/数字/连字符，以小写字母开头，长度 >= 2
• 同名函数 : 若已存在则复用，部署新版本代码
• 默认同时部署到 staging 和 production
• 部署成功后通过 GetRoutine 获取 defaultRelatedRecord 作为访问域名

详细参考: references/pages.md

Edge Routine (ER) — 边缘函数

通过 Python SDK 管理 Serverless 边缘函数的完整生命周期。

核心工作流

CreateRoutine → GetRoutineStagingCodeUploadInfo → 上传代码到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 摘要

• Namespace : CreateKvNamespace, DeleteKvNamespace, GetKvNamespace, GetKvAccount, DescribeKvAccountStatus
• 单键操作 : PutKv, GetKv, GetKvDetail, DeleteKv, PutKvWithHighCapacity
• 批量操作 : BatchPutKv, BatchDeleteKv, BatchPutKvWithHighCapacity, BatchDeleteKvWithHighCapacity, ListKvs

快速使用

client = create_client()

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

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

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

详细参考: references/kv.md

Site Management — 站点管理

使用 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 分组和确切的 API 操作名称。
3. 使用 Python SDK（首选）或 OpenAPI Explorer 调用 API。
4. 使用 describe/list API 验证结果。
5. 如果需要可重复的清单或摘要，请使用 scripts/ 下的脚本，并将输出写入 output/alicloud-network-esa/ 目录。

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

常见操作映射

站点管理

• 创建站点：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")

常见模式

# 匹配文件扩展名
--Rule '(http.request.uri.path.extension eq "html")'

# 匹配多个扩展名
--Rule '(http.request.uri.path.extension in {"js" "css" "png" "jpg"})'

# 匹配 URL 前缀
--Rule '(starts_with(http.request.uri, "/api/"))'

# 匹配 URL 后缀
--Rule '(ends_with(http.request.uri, ".html"))'

# 匹配包含子字符串的 URL（值必须以 / 开头）
--Rule '(http.request.uri contains "/test")'

# 匹配特定主机
--Rule '(http.host eq "www.example.com")'

# 组合条件
--Rule '(http.request.uri contains "/test" and ip.geoip.country eq "CN")'

# 按国家匹配
--Rule '(ip.geoip.country eq "CN")'

# 排除路径
--Rule '(not starts_with(http.request.uri, "/admin/"))'

# 否定集合成员资格
--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 在字段前），而不是 not in。

套餐限制

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

1. 环境变量：ALICLOUD_ACCESS_KEY_ID / ALICLOUD_ACCESS_KEY_SECRET / ALICLOUD_REGION_ID 区域策略：ALICLOUD_REGION_ID 是一个可选的默认值。如果未设置，请决定最适合任务的区域；如果不确定，请询问用户。
2. 共享配置文件：~/.alibabacloud/credentials（区域仍来自环境变量）

认证设置（与 README 保持一致）

环境变量：

export ALICLOUD_ACCESS_KEY_ID="your-ak"
export ALICLOUD_ACCESS_KEY_SECRET="your-sk"
export ALICLOUD_REGION_ID="cn-hangzhou"

阿里云 SDK 也支持：

export ALIBABA_CLOUD_ACCESS_KEY_ID="your-ak"
export ALIBABA_CLOUD_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/alicloud-network-esa/

参考资料

Pages、ER 和 KV

• Pages 部署参考 : references/pages.md
• Edge Routine 参考 : references/er.md
• Edge KV 存储参考 : references/kv.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

每周安装数

89

仓库

cinience/alicloud-skills

GitHub 星标数

345

首次出现

8 天前

安全审计

Gen Agent Trust HubPassSocketFailSnykPass

安装于

gemini-cli88

github-copilot88

codex88

amp88

cline88

kimi-cli88