版本 2.4.7.20261116085428 · 最新

分层回源 L2 l2

边缘回源先经同区域的 L2 节点,L2 有缓存就不再打源站;付费功能 l2,未开通时整块不生效。

点击任一接口,右侧显示对应的调用示例。

分层回源鉴权: 仅管理员25 个接口

鉴权

请求头带 X-API-Key(在「API 密钥」页开通,密钥只在开通时显示一次);也可用登录得到的 Authorization: Bearer 令牌。

X-API-Key

鉴权失败回 401;无权回 403(code 为 insufficient_scope 等)。

约定

分页参数 page(从 1 起)、page_size;排序 sort=字段 或 -字段。

时间一律 RFC 3339(UTC);金额单位为分。

写操作成功回 200/201/204;重复提交按资源唯一键回 409。

POST/api/v2/l2/enable-batch批量加 L2

鉴权: 仅管理员

请求体 application/json

字段类型说明
apply_sitesboolean 给现有网站也开(只动从没设过的网站,手动关过的、所属租户套餐不含分层回源的不动)。
node_ids必填integer[] 要改做 L2 的边缘节点 id。
GET/api/v2/l2/groups列出 L2 组

鉴权: 仅管理员

POST/api/v2/l2/groups新建 L2 组

鉴权: 仅管理员

请求体 application/json

字段类型说明
all_regionsboolean 服务全部区域(须勾跨区域)。
balancestring 分配方式:url_hash 按网址固定,rr 轮流。
可选值 ["url_hash","rr"]
cross_regionboolean 允许跨区域使用(选了区域外的节点或全部区域必须勾,多约 50–200 毫秒)。
name必填string 组名,全平台唯一。
node_idsinteger[] 要改做 L2 的边缘节点 id。
regionsinteger[] 服务区域 id;all_regions 为真时忽略。
rulesL2Rule[] 组内规则(随组保存)。
PATCH/api/v2/l2/groups/{id}修改 L2 组

鉴权: 仅管理员

请求体 application/json

字段类型说明
all_regionsboolean 服务全部区域(须勾跨区域)。
balancestring 分配方式:url_hash 按网址固定,rr 轮流。
可选值 ["url_hash","rr"]
cross_regionboolean 允许跨区域使用(选了区域外的节点或全部区域必须勾,多约 50–200 毫秒)。
namestring 组名,全平台唯一。
node_idsinteger[] 要改做 L2 的边缘节点 id。
regionsinteger[] 服务区域 id;all_regions 为真时忽略。
rulesL2Rule[] 组内规则(随组保存)。
POST/api/v2/l2/groups/{id}/copy复制 L2 组

鉴权: 仅管理员

请求体 application/json

字段类型说明
name必填string 组名,全平台唯一。
POST/api/v2/l2/groups/{id}/reset-sites把用这个组的网站改回区域默认

鉴权: 仅管理员

PATCH/api/v2/l2/nodes/{id}修改 L2 节点

鉴权: 仅管理员

请求体 application/json

字段类型说明
access_addrstring 边缘访问它的内网地址(只收 IP,不带端口;IPv4 映射的 IPv6 存成 IPv4);空 = 公网 IP。
rolestring 主备:同组有主可用时备只待命,主全挂才用备(在组内成员间比较)。
可选值 ["primary","backup"]
weightinteger 权重 1–100,多台主按权重分网址。
POST/api/v2/l2/nodes/{id}/disable停用 L2 节点

鉴权: 仅管理员

请求体 application/json

字段类型说明
reasonstring 停用原因。
POST/api/v2/l2/nodes/{id}/enable启用 L2 节点

鉴权: 仅管理员

POST/api/v2/l2/nodes/{id}/mark-allowed标记源站已放行

鉴权: 仅管理员

POST/api/v2/l2/nodes/{id}/probe-access检测源站是否已放行

鉴权: 仅管理员

POST/api/v2/l2/nodes/{id}/revert改回边缘节点

鉴权: 仅管理员

POST/api/v2/l2/pause全网暂停分层回源

鉴权: 仅管理员

请求体 application/json

字段类型说明
auto_resume_atstring 自动恢复时刻(须在现在之后);不给 = 手动恢复。
POST/api/v2/l2/resume全网恢复分层回源

鉴权: 仅管理员

GET/api/v2/l2/revoke-impact授权失效的影响与回落窗口

鉴权: 仅管理员

查询参数

字段类型说明
pageinteger 页码,从 1 开始。
默认 1
page_sizeinteger 每页条数。
默认 20
GET/api/v2/l2/stats分层回源统计

鉴权: 仅管理员

查询参数

字段类型说明
start必填string 起始时间(含),RFC 3339。
end必填string 结束时间(不含),RFC 3339。
GET/api/v2/l2/stats/nodes按 L2 节点的统计

鉴权: 仅管理员

查询参数

字段类型说明
start必填string 起始时间(含),RFC 3339。
end必填string 结束时间(不含),RFC 3339。
GET/api/v2/l2/stats/sites按网站的分层回源统计

鉴权: 仅管理员

查询参数

字段类型说明
start必填string 起始时间(含),RFC 3339。
end必填string 结束时间(不含),RFC 3339。
pageinteger 页码,从 1 开始。
默认 1
page_sizeinteger 每页条数。
默认 20
domainstring 主域名子串,不分大小写。

分层回源 L2对象

字段类型说明
access_addrstring 边缘访问它的内网地址(只收 IP,不带端口;IPv4 映射的 IPv6 存成 IPv4);空 = 公网 IP。
all_regionsboolean 服务全部区域(须勾跨区域)。
allowstring 源站放行:空 = 不涉及(没有网站只允许 L2),pending 待放行(只接可缓存请求),allowed 已放行。
allow_sincestring 进入待放行的时刻;满 24 小时自动转已放行。
apply_sitesboolean 给现有网站也开(只动从没设过的网站,手动关过的、所属租户套餐不含分层回源的不动)。
auto_resume_atstring 自动恢复时刻(须在现在之后);不给 = 手动恢复。
balancestring 分配方式:url_hash 按网址固定,rr 轮流。
可选值 ["url_hash","rr"]
checked_atstring 检测时刻。
created_atstring 开始时间。
cross_regionboolean 允许跨区域使用(选了区域外的节点或全部区域必须勾,多约 50–200 毫秒)。
defaultsL2Defaults 默认设置(改用 PUT /configs/l2.defaults)。
disabled_atstring 停用时刻。
disabled_reasonstring 停用原因。
edge_origin_requestsinteger 边缘回源请求数(命中率分母)。
empty_groupinteger[] 去掉它后没有可用 L2 的组(用这些组的网站将暂时绕过)。
enabledboolean 启用;停用时仍是 L2、缓存保留。
featurestring 付费功能 l2 开通档:on 开通;limited 冻结、即将停用或授权失效后的回落窗口(照常下发,只能停用、暂停等,见 GET /l2/revoke-impact);off 没开通(不下发)。
可选值 ["on","limited","off"]
finished_atstring 结束时间。
groupsinteger[] 所在 L2 组 id。
hit_ratenumber 命中率 0–1;没有回源为 0。
hoststring 网站主域名。
idinteger 组 id。
ipstring 公网 IP。
is_region_defaultboolean 区域默认组(每区域一个,不能删,只能改分配方式)。
itemsL2Group[] L2 组。
kindstring 任务种类:enable 加 L2,revert 改回边缘。
可选值 ["enable","revert"]
l2_group_idinteger 网站选的 L2 组;null = 区域默认。
l2_group_namestring L2 组名;区域默认时为空串。
l2_hit_requestsinteger L2 接住的回源请求数(命中率分子)。
l2_pickstring 网站生效的选 L2 方式(网站单独设的,否则默认设置):region 跟边缘同区域;near 离源站最近。
可选值 ["region","near"]
low_hitboolean 命中率低于 30% 且源站请求不少于 1000 次(动态内容多,建议关)。
manual_off_sitesinteger 手动关过分层回源的网站数(一键启用勾「给现有网站也开」时不动它们;IP 站不计)。
name必填string 组名,全平台唯一。
node_idinteger 节点 id。
node_ids必填integer[] 要改做 L2 的边缘节点 id。
nodes_pendinginteger 待放行的 L2 数。
nodes_servinginteger 在接回源的 L2 数(启用且没在改回)。
nodes_totalinteger L2 节点总数(含停用、改回中)。
onlineboolean 在线(最近 2 分钟有心跳)。
only_blockboolean 有网站开了「源站只允许 L2 访问」(改回后源站要撤掉它的放行)。
only_block_sitesinteger 开了「源站只允许 L2 访问」的网站数(only_block 为真时大于 0)。
origin_l2_onlyboolean 开了「源站只允许 L2 访问」:回落窗口满后源站没放行边缘节点就会整站不可用。
origin_requestsinteger 实际到源站的请求数。
origin_requests_estinteger 未开分层时的估算(= 边缘回源请求数)。
owner_idinteger 所属用户 ID。
owner_namestring 所属用户名。
pausedboolean 全网暂停中。
paused_atstring 暂停时刻。
progressinteger 进度 0–100。
reasonstring 停用原因。
region_idinteger 区域默认组所属区域;自建组 0。
region_lastboolean 它是本区域最后一台启用中的 L2。
regionsinteger[] 服务区域 id;all_regions 为真时忽略。
revert_atstring 开始改回的时刻。
rolestring 主备:同组有主可用时备只待命,主全挂才用备(在组内成员间比较)。
可选值 ["primary","backup"]
rulesL2Rule[] 组内规则(随组保存)。
saved_bytesinteger 省的回源流量(L2 命中字节)。
site_idinteger 网站 ID。
sitesinteger 用这个组的网站数;区域默认组为开着 L2 且没指定组的网站数(各区域默认组同数)。
sites_only_l2integer 开了「源站只允许 L2 访问」的网站数(暂停、新加节点时写进提醒)。
statestring 状态:active 正常,reverting 改回边缘中。
可选值 ["active","reverting"]
thresholdsL2Thresholds 判定阈值(只读)。
updated_atstring 最后修改时间。
weightinteger 权重 1–100,多台主按权重分网址。

返回与错误

成功直接回资源 JSON(HTTP 2xx);失败回 application/problem+json(code、detail,校验失败带 errors);列表为 items + total。

成功
{
  "id": 1,
  "name": "example"
}
列表
{
  "items": [
    {
      "id": 1
    }
  ],
  "page": 1,
  "page_size": 20,
  "total": 1
}
失败
{
  "code": "validation_failed",
  "detail": "请求参数不合法",
  "errors": [
    {
      "code": "required",
      "field": "/name",
      "message": "name 必填"
    }
  ],
  "request_id": "0123456789abcdef",
  "status": 422,
  "title": "Unprocessable Entity",
  "type": "about:blank"
}
开始使用

123

123