版本 2.4.8 · 最新
上传防护设置 upload-scan-settings
平台级上传文件扫描(只查 multipart 表单上传的文件):总开关、危险扩展名、双扩展名、伪装文件、木马特征、病毒库、单文件上限、扫描超时、处置与例外,仅管理员可改;木马特征、病毒库与 sha256 黑名单属付费功能 WAF 增强。
点击任一接口,右侧显示对应的调用示例。
防护鉴权: 仅管理员2 个接口
鉴权
请求头带 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。
PUT
/api/v2/upload-scan-settings修改上传防护设置
鉴权: 仅管理员
请求体 application/json
| 字段 | 类型 | 说明 |
|---|---|---|
action | string | 命中后:block 拦截、log 只记录、observe 先观察 3 天(期间只记录,之后拦截);危险文件不设观察期。 |
disguise | boolean | 伪装文件检测(扩展名为图片、文件头魔数为脚本或可执行程序)。 |
double_ext | boolean | 双扩展名检测(如 a.php.jpg、a.asp;.jpg)。 |
enabled | boolean | 总开关;false = 所有站点都不扫描。 |
enhanced | string | WAF 增强判定档:full 已开通、readonly 到期只读缓冲内(License.readonly_days,缺省 7 天;增强项照常生效但只读)、basic 未开通或缓冲已过(增强项不生效,设置保留);修改时忽略。 |
exceptions | UploadScanException[] | 例外:网站与路径前缀命中时跳过该特征(sig 空 = 该路径不扫描)。租户标记误报加的条目(source=false_positive)整体替换时请原样带回,否则被覆盖。 |
expected_updated_at | string | 乐观锁:调用方读到的 updated_at(配置 node.global 的版本,与 CC/WAF 设置共用;读到为空用 1970-01-01T00:00:00Z)。与库里当前值不等则回 409 stale_version、不保存;不带则不检查。 |
exts | string[] | 危险扩展名(小写、不带点);没带回缺省 php phtml jsp jspx asp aspx ashx cer war sh cgi shtml。按族展开(php 带 php3-8 pht phtml phar,asp 带 asa cdx cer,jsp 带 jspx jspf,shtml 带 shtm stm);点开头的名字(.php)按扩展名判;表非空时 .htaccess、.user.ini、web.config 也拦。站点 waf.upload_exts 可覆盖。 |
max_file_mb | integer | 单个文件扫描上限(MB,缺省 20);超出的只查扩展名,按 oversize 处置。 |
observe_until | string | 观察期截止(action 为 observe 时有值);修改时忽略,由服务端写。 |
on_parse_error | string | multipart 解析出错(定界符不对、头过大、体被截断、段数超限等)时:block 拦截、allow 放行并记录(缺省 block)。 |
on_timeout | string | 扫描超时(或读请求体失败)时:allow 放行并记录、block 拦截(缺省 allow)。 |
on_virus_error | string | 病毒库扫描出错(clamd 连不上、读写超时、回包异常)时:allow 放行并记录、block 拦截(缺省 allow);clamd 没装/没起不扫不算出错。 |
oversize | string | 超过单文件上限:allow 放行并记录、block 拦截。 |
sha256 | object[] | 本主控 sha256 黑名单(WAF 增强)。 |
sig | boolean | 木马 / Webshell 特征(WAF 增强)。 |
timeout_s | integer | 每个请求的扫描超时(秒,缺省 2)。 |
updated_at | string | 响应里的版本(node.global 配置键的 updated_at,没改过为空);修改时忽略。 |
virus | string | 病毒库(ClamAV,WAF 增强):off 关、mem4g 内存 ≥4GB 的节点、all 所有节点。 |
上传防护设置对象
| 字段 | 类型 | 说明 |
|---|---|---|
action | string | 命中后:block 拦截、log 只记录、observe 先观察 3 天(期间只记录,之后拦截);危险文件不设观察期。 |
disguise | boolean | 伪装文件检测(扩展名为图片、文件头魔数为脚本或可执行程序)。 |
double_ext | boolean | 双扩展名检测(如 a.php.jpg、a.asp;.jpg)。 |
enabled | boolean | 总开关;false = 所有站点都不扫描。 |
enhanced | string | WAF 增强判定档:full 已开通、readonly 到期只读缓冲内(License.readonly_days,缺省 7 天;增强项照常生效但只读)、basic 未开通或缓冲已过(增强项不生效,设置保留);修改时忽略。 |
exceptions | UploadScanException[] | 例外:网站与路径前缀命中时跳过该特征(sig 空 = 该路径不扫描)。租户标记误报加的条目(source=false_positive)整体替换时请原样带回,否则被覆盖。 |
expected_updated_at | string | 乐观锁:调用方读到的 updated_at(配置 node.global 的版本,与 CC/WAF 设置共用;读到为空用 1970-01-01T00:00:00Z)。与库里当前值不等则回 409 stale_version、不保存;不带则不检查。 |
exts | string[] | 危险扩展名(小写、不带点);没带回缺省 php phtml jsp jspx asp aspx ashx cer war sh cgi shtml。按族展开(php 带 php3-8 pht phtml phar,asp 带 asa cdx cer,jsp 带 jspx jspf,shtml 带 shtm stm);点开头的名字(.php)按扩展名判;表非空时 .htaccess、.user.ini、web.config 也拦。站点 waf.upload_exts 可覆盖。 |
max_file_mb | integer | 单个文件扫描上限(MB,缺省 20);超出的只查扩展名,按 oversize 处置。 |
observe_until | string | 观察期截止(action 为 observe 时有值);修改时忽略,由服务端写。 |
on_parse_error | string | multipart 解析出错(定界符不对、头过大、体被截断、段数超限等)时:block 拦截、allow 放行并记录(缺省 block)。 |
on_timeout | string | 扫描超时(或读请求体失败)时:allow 放行并记录、block 拦截(缺省 allow)。 |
on_virus_error | string | 病毒库扫描出错(clamd 连不上、读写超时、回包异常)时:allow 放行并记录、block 拦截(缺省 allow);clamd 没装/没起不扫不算出错。 |
oversize | string | 超过单文件上限:allow 放行并记录、block 拦截。 |
sha256 | object[] | 本主控 sha256 黑名单(WAF 增强)。 |
sig | boolean | 木马 / Webshell 特征(WAF 增强)。 |
timeout_s | integer | 每个请求的扫描超时(秒,缺省 2)。 |
updated_at | string | 响应里的版本(node.global 配置键的 updated_at,没改过为空);修改时忽略。 |
virus | string | 病毒库(ClamAV,WAF 增强):off 关、mem4g 内存 ≥4GB 的节点、all 所有节点。 |
返回与错误
成功直接回资源 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"
}