版本 2.4.7.20261116085428 · 最新
增值防护方案 protect-schemes
防重放、防泄露、防篡改各一份方案(租户各自一份,管理员编辑平台方案);保存时一并改「按方案」的站点,单独设置的不动;属 WAF 增强。
点击任一接口,右侧显示对应的调用示例。
防护鉴权: 用户(部分参数仅管理员)10 个接口
鉴权
请求头带 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。
GET
/api/v2/protect-schemes/leak获取防泄露方案
鉴权: 用户(部分参数仅管理员)
PUT
/api/v2/protect-schemes/leak保存防泄露方案
鉴权: 用户(部分参数仅管理员)
请求体 application/json
| 字段 | 类型 | 说明 |
|---|---|---|
auto_join | object | 「以后新加入范围的网站自动加入方案」的规则;没开时不返回。 |
custom必填 | SiteLeakGuardCustom[] | 自定义正则,最多 16 条。 |
detect必填 | SiteLeakGuardDetect | 内置识别各类的处置;不写 = 不查这一类。 |
enabled | boolean | 方案总开关:开着时「按方案」的站跟这份方案生效;关着时这些站关闭(各自的值保留),自动加入规则暂停。没保存过为 false。 |
exclude必填 | string[] | 不检测的路径前缀(末尾 * 可省),最多 32 条。 |
expected_updated_at | string | 乐观锁:调用方读到的 updated_at(读到为空 = 还没保存过,用 1970-01-01T00:00:00Z)。与库里当前值不等则回 409 stale_version、不保存;不带则不检查。 |
observe_days必填 | integer | 站点按方案新开启时观察多少天(只记录不处置);0 = 不观察直接处置。 |
override_custom | boolean | 不带即 false,也只能为 false:单独设置的站不跟着改(计入 apply.skipped_custom),要覆盖用按方案重设。 |
selection | object | 本次要加入方案的网站范围;只在保存后总开关为开、且这次改了范围时带。不带 = 不加新站。 |
GET
/api/v2/protect-schemes/replay获取防重放方案
鉴权: 用户(部分参数仅管理员)
PUT
/api/v2/protect-schemes/replay保存防重放方案
鉴权: 用户(部分参数仅管理员)
请求体 application/json
| 字段 | 类型 | 说明 |
|---|---|---|
action | ReplayGuardAction | 没有令牌或重放时:block 回 403;challenge 出 JS 挑战。不写 = block。 |
app_salt | string | 签名盐(应用密钥,32 字节 hex);app_sign 开而没有它 = 签名头一律不认。 |
app_sign | boolean | App 签名校验:请求带签名头即按签名校验,不需要令牌。 |
auto_join | object | 「以后新加入范围的网站自动加入方案」的规则;没开时不返回。 |
bind_ip | boolean | 令牌再绑客户端 IP(换 IP 即失效)。 |
enabled | boolean | 方案总开关:开着时「按方案」的站跟这份方案生效;关着时这些站关闭(各自的值保留),自动加入规则暂停。没保存过为 false。 |
expected_updated_at | string | 乐观锁:调用方读到的 updated_at(读到为空 = 还没保存过,用 1970-01-01T00:00:00Z)。与库里当前值不等则回 409 stale_version、不保存;不带则不检查。 |
methods | ReplayGuardMethod[] | 受保护方法;不写 = POST/PUT/PATCH/DELETE。 |
override_custom | boolean | 不带即 false,也只能为 false:单独设置的站不跟着改(计入 apply.skipped_custom),要覆盖用按方案重设。 |
paths | ReplayGuardPath[] | 保护接口路径表,最多 64 条;空 = 不保护。 |
selection | object | 本次要加入方案的网站范围;只在保存后总开关为开、且这次改了范围时带。不带 = 不加新站。 |
ttl_s | integer | 令牌有效期(秒),签名头的时间戳也按它判;不写 = 120。 |
GET
/api/v2/protect-schemes/replay/suggestions列出防重放保护接口建议
鉴权: 用户(部分参数仅管理员)
GET
/api/v2/protect-schemes/tamper获取防篡改方案
鉴权: 用户(部分参数仅管理员)
PUT
/api/v2/protect-schemes/tamper保存防篡改方案
鉴权: 用户(部分参数仅管理员)
请求体 application/json
| 字段 | 类型 | 说明 |
|---|---|---|
action必填 | ReplayGuardAction | 没有令牌或重放时:block 回 403;challenge 出 JS 挑战。不写 = block。 |
auto_join | object | 「以后新加入范围的网站自动加入方案」的规则;没开时不返回。 |
enabled | boolean | 方案总开关:开着时「按方案」的站跟这份方案生效;关着时这些站关闭(各自的值保留),自动加入规则暂停。没保存过为 false。 |
expected_updated_at | string | 乐观锁:调用方读到的 updated_at(读到为空 = 还没保存过,用 1970-01-01T00:00:00Z)。与库里当前值不等则回 409 stale_version、不保存;不带则不检查。 |
mode必填 | string | 检查范围:structure 仅结构变化;full 整页任意变化。 |
observe_days必填 | integer | 站点按方案新开启时观察多少天(只记录不处置);0 = 不观察直接处置。 |
override_custom | boolean | 不带即 false,也只能为 false:单独设置的站不跟着改(计入 apply.skipped_custom),要覆盖用按方案重设。 |
scopes必填 | SiteTamperScope[] | 保护范围,最多 50 条。 |
selection | object | 本次要加入方案的网站范围;只在保存后总开关为开、且这次改了范围时带。不带 = 不加新站。 |
POST
/api/v2/protect-schemes/{kind}/apply把方案批量应用到网站
鉴权: 用户(部分参数仅管理员)
请求体 application/json
| 字段 | 类型 | 说明 |
|---|---|---|
auto_join | object | 「以后新加入范围的网站自动加入方案」的规则;没开时不返回。 |
dry_run | boolean | 为 true 只返回会发生什么的计数,不写任何东西。 |
mode | string | 检查范围:structure 仅结构变化;full 整页任意变化。 |
override_custom | boolean | 不带即 false,也只能为 false:单独设置的站不跟着改(计入 apply.skipped_custom),要覆盖用按方案重设。 |
selection | object | 本次要加入方案的网站范围;只在保存后总开关为开、且这次改了范围时带。不带 = 不加新站。 |
GET
/api/v2/protect-schemes/{kind}/sites列出已设置这项防护的网站
鉴权: 用户(部分参数仅管理员)
查询参数
| 字段 | 类型 | 说明 |
|---|---|---|
page | integer | 页码,从 1 开始。 |
page_size | integer | 每页条数。 |
tenant_id | integer | 仅管理员可用:按租户过滤(格式错 422)。租户凭据调用时忽略,只返回本租户数据。 |
q | string | 按网站域名或站点名模糊搜索(不区分大小写)。 |
status | ProtectSchemeSiteStatus | 按状态过滤。 |
source | ProtectSiteSource | 按来源过滤:scheme 按方案;custom 单独设置(含单独关闭)。 |
POST
/api/v2/protect-schemes/{kind}/sites/bulk批量重设或关闭网站的这项防护
鉴权: 用户(部分参数仅管理员)
请求体 application/json
| 字段 | 类型 | 说明 |
|---|---|---|
action必填 | ReplayGuardAction | 没有令牌或重放时:block 回 403;challenge 出 JS 挑战。不写 = block。 |
filter | ProtectSchemeSiteFilter | 与列表同样的过滤条件,服务端展开成网站集合。 |
ids | integer[] | 网站 id 列表。 |
增值防护方案对象
| 字段 | 类型 | 说明 |
|---|---|---|
action | ReplayGuardAction | 没有令牌或重放时:block 回 403;challenge 出 JS 挑战。不写 = block。 |
app_salt | string | 签名盐(应用密钥,32 字节 hex);app_sign 开而没有它 = 签名头一律不认。 |
app_sign | boolean | App 签名校验:请求带签名头即按签名校验,不需要令牌。 |
applied | integer | 写入(dry_run 时为将写入)的网站数。 |
apply | object | 本次保存应用到网站的结果(只在保存的回包里有)。 |
auto_join | object | 「以后新加入范围的网站自动加入方案」的规则;没开时不返回。 |
bind_ip | boolean | 令牌再绑客户端 IP(换 IP 即失效)。 |
counts | ProtectSchemeCounts | 站点计数:调用方看得到的站点里,开着的、按方案的、单独设置的、套餐不含的各几个。 |
custom | SiteLeakGuardCustom[] | 自定义正则,最多 16 条。 |
demoted_sites | integer | 本次保存因属主没开通 WAF 增强、改为单独设置并保留原值的站点数(只在保存的回包里有)。 |
detect | SiteLeakGuardDetect | 内置识别各类的处置;不写 = 不查这一类。 |
domain | string | 网站主域名(没有域名时为站点名)。 |
dry_run | boolean | 为 true 只返回会发生什么的计数,不写任何东西。 |
enabled | boolean | 方案总开关:开着时「按方案」的站跟这份方案生效;关着时这些站关闭(各自的值保留),自动加入规则暂停。没保存过为 false。 |
exclude | string[] | 不检测的路径前缀(末尾 * 可省),最多 32 条。 |
expected_updated_at | string | 乐观锁:调用方读到的 updated_at(读到为空 = 还没保存过,用 1970-01-01T00:00:00Z)。与库里当前值不等则回 409 stale_version、不保存;不带则不检查。 |
failed | ProtectSchemeFailure[] | 没能处理的网站及原因,最多 100 条。 |
failed_total | integer | 没能处理的网站总数(failed 被截断时大于其长度)。 |
filter | ProtectSchemeSiteFilter | 与列表同样的过滤条件,服务端展开成网站集合。 |
gate | ProtectSchemeGate | 方案属主(租户本人或平台)的 WAF 增强判定档:full 可改;readonly、basic 只许减不许增。 |
ids | integer[] | 网站 id 列表。 |
is_default | boolean | 没保存过方案时为 true,其余设置是缺省值(不落库);保存过不返回。 |
items | ReplaySchemeSuggestion[] | 按 POST 次数从多到少,最多 3 条;没有数据或没接 ClickHouse 为空。 |
matched | integer | 范围内调用方看得到的网站数。 |
methods | ReplayGuardMethod[] | 受保护方法;不写 = POST/PUT/PATCH/DELETE。 |
mode | string | 检查范围:structure 仅结构变化;full 整页任意变化。 |
observe_days | integer | 站点按方案新开启时观察多少天(只记录不处置);0 = 不观察直接处置。 |
observe_until | integer | 观察期截止(Unix 毫秒时间戳);只有防泄露开着且仍在观察期内才有值,已过期、没有观察期、关着或其余方案为空。 |
override_custom | boolean | 不带即 false,也只能为 false:单独设置的站不跟着改(计入 apply.skipped_custom),要覆盖用按方案重设。 |
owner | string | 属主用户名。 |
paths | ReplayGuardPath[] | 保护接口路径表,最多 64 条;空 = 不保护。 |
scopes | SiteTamperScope[] | 保护范围,最多 50 条。 |
selection | object | 本次要加入方案的网站范围;只在保存后总开关为开、且这次改了范围时带。不带 = 不加新站。 |
site_id | integer | 网站 id。 |
skipped_custom | integer | 因单独设置而没覆盖的网站数(override_custom 为 false)。 |
skipped_gate | integer | 因属主 WAF 增强不是 full 而没写的网站数。 |
source | ProtectSiteSource | 站点这一项的来源:scheme 按方案(保存方案时跟着变);custom 单独设置(含关闭、存量迁移来的行)。 |
status | ProtectSchemeSiteStatus | 站点这一项的状态:enabled 开着;disabled 关着;pending 开着但防篡改基准还在排队采集;capture_failed 开着但基准采集多次失败、已停止重试(只有防篡改有后两种)。 |
tenant_id | integer | 属主用户 id。 |
today_blocked | integer | 今日(UTC)拦截与换错误页次数,不含观察期内的命中(只有防泄露有,与方案回包 counts.today_blocked 同口径);其余方案、没接 ClickHouse 或查询失败为空。 |
today_hits | integer | 今日命中数(防泄露为今日 UTC 非观察期的打码与拦截次数之和,即 today_masked + today_blocked,防篡改为今日检出篡改的页数);防重放为空。 |
today_masked | integer | 今日(UTC)打码次数,不含观察期内的命中(只有防泄露有,与方案回包 counts.today_masked 同口径);其余方案、没接 ClickHouse 或查询失败为空。 |
ttl_s | integer | 令牌有效期(秒),签名头的时间戳也按它判;不写 = 120。 |
updated_at | string | 版本(没保存过为空);修改时用 expected_updated_at。 |
updated_sites | integer | 本次保存一并改到的按方案站点数(只在保存的回包里有)。 |
will_change | integer | 只在 dry_run 回包:按 mode 保存后会变的网站数(enable 会开启或加入的、update 会一起更新的、disable 会关掉的)。 |
返回与错误
成功直接回资源 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"
}