首页›文档›OpenAPI

OpenAPI v1 PRO 专属 HTTPS 强制 Bearer Token

FOXWAF OpenAPI 参考

无需面板登录，通过 API Key 直接调用 WAF 管理接口 —— 适合脚本自动化、监控告警与 CI/CD 集成。每次请求实时校验 PRO 授权，Scope 细粒度控权，高危操作永久屏蔽。

https://<WAF管理地址>:<端口>/openapi/v1/<path>

鉴权Authorization: Bearer <api_key>

路径映射/openapi/v1/* → 内部 /api/*

限流120 次 / Key / 60 秒

状态即将发布 · 文档先行

通告：OpenAPI 通道即将面向 PRO 用户正式发布。本文档已与实现对齐，可在测试环境提前熟悉调用方式。关注通告中心获取上线通知。

1. 概述

FOXWAF OpenAPI 允许 PRO 用户通过 API Key 调用 WAF 管理接口，与面板加密通道完全独立。

Bearer Token 鉴权，调用方式与主流云厂商一致
细粒度 Scope 权限（按模块 + 读/写）
每次请求实时验证 PRO 授权，降级后立即失效
屏蔽升级 / 重启 / 面板配置 / 订单等高危路径

2. 快速开始

生成 API Key

登录 FOXWAF 管理面板 → 系统设置 → OpenAPI 密钥
点击「+ 生成密钥」，填写名称、选择作用域、可选过期时间
弹窗一次性展示完整 Key —— 立即复制保存，关闭后无法再次查看

第一个请求

WAF="https://127.0.0.1:8088"
KEY="fwk_你的前缀_你的secret"

curl -k \
  -H "Authorization: Bearer $KEY" \
  "$WAF/openapi/v1/acl/rules"

-k 用于跳过自签名证书；生产环境请配置可信证书后去掉。

3. API Key 管理

Key 格式

fwk_<前缀10位>_<secret32位>

示例：fwk_lu2LAk9HFj_qL9ioS4cmjVhW7dEfBxzRpYKnuA1G

面板操作

操作	说明
生成	填写名称、作用域、过期时间；Secret 仅创建时展示一次；支持「全选 / 清空 / 仅只读」一键选择
禁用 / 启用	临时停用某个 Key，不删除记录
吊销	永久删除，立即生效；已有调用收到 `invalid_key`
吊销选中	勾选多个密钥后批量吊销
全部吊销	一键吊销当前全部密钥

列表中作用域较多时会自动折叠，点击 +N 可展开查看全部。

面板管理接口（加密通道 `/api`，需登录）

以下接口不可通过 OpenAPI Key 调用，防止 Key 泄漏后提权管理自身。

方法	路径	说明
`GET`	`/api/openapi/keys`	密钥列表
`POST`	`/api/openapi/keys`	生成（返回明文 secret，仅一次）
`POST`	`/api/openapi/keys/:id/toggle`	启用/禁用，Body `{"enabled":true/false}`
`DELETE`	`/api/openapi/keys/:id`	吊销单个
`DELETE`	`/api/openapi/keys`	批量吊销 Body `{"ids":[1,2,3]}`；全部吊销 Body `{"all":true}`

Key 列表字段

字段	说明
`name`	备注名称
`prefix`	Key 前缀（显示为 `fwk_前缀_***`）
`scopes`	作用域列表
`enabled`	是否启用
`expire_at`	过期时间（Unix 秒，0 = 永不过期）
`last_used_at`	最近使用时间（30 秒异步持久化）

4. 作用域（Scopes）

创建 Key 时必须至少选择一个作用域。

write 自动蕴含 read（有写权限即可读）
* 为通配符，匹配所有模块
GET / HEAD / OPTIONS 需要 read；POST / PUT / DELETE 需要 write

预设作用域

Scope	说明
`*:read`	全部模块只读
`*:write`	全部模块读写（含 read）
`acl:read` / `acl:write`	ACL 规则只读 / 读写
`cc:read` / `cc:write`	CC 防护只读 / 读写
`custom-rules:read` / `custom-rules:write`	自定义规则只读 / 读写
`site:read` / `site:write`	站点管理只读 / 读写
`settings:read` / `settings:write`	全局设置只读 / 读写

attack:read cache:read rule:read monitor:read obs:read plugins:read waf:read letsencrypt:read feedbacks:read

各模块均有对应的 :write 作用域；不确定时可使用 *:read 或 *:write。

作用域与路径对应

接口路径前缀	所需模块
`/openapi/v1/acl/*`	`acl`
`/openapi/v1/cc/*`	`cc`
`/openapi/v1/custom-rules/*`	`custom-rules`
`/openapi/v1/sites`、`/openapi/v1/site/`、`/openapi/v1/health`	`site`
`/openapi/v1/attack/*`	`attack`
`/openapi/v1/cache/*`	`cache`
`/openapi/v1/rule`、`/openapi/v1/rules`	`rule`
`/openapi/v1/monitor/`、`/openapi/v1/traffic/`、`/openapi/v1/stats`	`monitor` / `traffic` / `stats`
`/openapi/v1/obs/*`	`obs`
`/openapi/v1/cert-template*`	`cert-template`
`/openapi/v1/plugins/*`	`plugins`
`/openapi/v1/waf/*`	`waf`
`/openapi/v1/settings`	`settings`
`/openapi/v1/feedbacks`	`feedbacks`
`/openapi/v1/letsencrypt/*`	`letsencrypt`
`/openapi/v1/cert/*`	`cert`
`/openapi/v1/realtime/*`	`realtime`
`/openapi/v1/qrcode`	`qrcode`
`/openapi/v1/ping`、`/openapi/v1/config`、`/openapi/v1/maintenance-server`、`/openapi/v1/captcha/`、`/openapi/v1/waf/language`	公开（无需 scope）

5. 请求格式

请求头

Authorization: Bearer <api_key>
Content-Type: application/json   # POST / PUT / DELETE 时需要

路径映射

OpenAPI 路径与面板内部 API 一一对应：

/openapi/v1/<path> → /api/<path>

OpenAPI 路径	内部路径
`/openapi/v1/acl/rules`	`/api/acl/rules`
`/openapi/v1/cc/rules/5`	`/api/cc/rules/5`
`/openapi/v1/sites`	`/api/sites`

查询参数

分页接口需传 page 和 page_size：

curl -k -H "Authorization: Bearer $KEY" \
  "$WAF/openapi/v1/attack/logs?page=1&page_size=20"

6. 错误码

所有错误响应统一格式：

{ "error": "错误描述", "code": "error_code" }

HTTP	code	原因
`401`	`missing_token`	缺少 `Authorization: Bearer` 头
`401`	`invalid_key`	Key 不存在或 secret 错误
`403`	`https_required`	使用了 HTTP 而非 HTTPS
`403`	`key_disabled`	Key 已被手动禁用
`403`	`key_expired`	Key 已超过设定的过期时间
`403`	`pro_required`	PRO 授权到期或无效（实时检测）
`403`	`scope_denied`	Key 作用域不含所需权限
`403`	`endpoint_not_exposed`	该路径不对外开放（敏感模块）
`429`	`rate_limited`	触发限流（每 Key 每 60 秒上限 120 次）

PRO 门控功能（CC、自定义规则、观察室、HTTP/3 等）在授权失效时额外返回 {"error":"此功能需要 Pro 授权","pro_required":true}。

7. 限流

项	值
粒度	每个 API Key 独立计数
窗口	60 秒固定窗口
上限	120 次 / 60 秒
触发响应	HTTP 429 + `{"code":"rate_limited"}`

8. 接口列表

通用响应约定

写操作成功：统一返回 {"message":"…成功"}；创建类接口额外带资源 ID
读操作：返回对应的数据对象（见各接口响应示例）
Pro 门控：CC、自定义规则、观察室等 PRO 功能授权失效时返回 403 + pro_required: true
下文示例均使用 WAF="https://127.0.0.1:8088"、KEY="fwk_…"

8.1 ACL 规则 acl

GET/openapi/v1/acl/rules查询规则列表

POST/openapi/v1/acl/rules添加规则

PUT/openapi/v1/acl/rules/:id更新规则

POST/openapi/v1/acl/rules/:id/toggle启用 / 禁用

DELETE/openapi/v1/acl/rules/:id删除规则

GET /openapi/v1/acl/rules 查询规则列表

curl -k -H "Authorization: Bearer $KEY" "$WAF/openapi/v1/acl/rules"

响应示例

{ "rules": [ { "id": 1, "type": "global", "rule_type": "ip", "pattern": "1.2.3.4", "action": "block", "enabled": true, "description": "恶意 IP" } ] }

POST /openapi/v1/acl/rules 添加规则

请求体字段

字段	类型	必填	说明
`type`	string	必填	`global`（全局）或 `host`（按域名）
`rule_type`	string	必填	`ip`、`ua`、`url`、`header`、`country` 等
`pattern`	string	必填	匹配内容
`action`	string	必填	`block`（拦截）或 `allow`（放行）
`enabled`	bool	必填	是否启用
`host`	string	条件	`type=host` 时必填
`description`	string	可选	备注

# 封禁 IP
curl -k -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"type":"global","rule_type":"ip","pattern":"1.2.3.4","action":"block","enabled":true,"description":"恶意扫描"}' \
  "$WAF/openapi/v1/acl/rules"

# 按域名封禁 UA
curl -k -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"type":"host","host":"example.com","rule_type":"ua","pattern":"sqlmap","action":"block","enabled":true}' \
  "$WAF/openapi/v1/acl/rules"

响应

{"id": 10, "message": "ACL 规则添加成功"}

PUT /openapi/v1/acl/rules/:id 更新规则

请求体字段同「添加规则」。

curl -k -X PUT -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"type":"global","rule_type":"ip","pattern":"1.2.3.4","action":"allow","enabled":true}' \
  "$WAF/openapi/v1/acl/rules/10"

POST /openapi/v1/acl/rules/:id/toggle 启用 / 禁用

Body: {"enabled": false}

8.2 CC 防护 cc Pro

GET/openapi/v1/cc/rulesCC 规则列表

POST/openapi/v1/cc/rules添加 CC 规则

PUT/openapi/v1/cc/rules/:id更新

DELETE/openapi/v1/cc/rules/:id删除

GET/openapi/v1/cc/stats统计概览

GET/openapi/v1/cc/logs日志（分页）

DELETE/openapi/v1/cc/logs删除日志

POST/openapi/v1/cc/clear-counters清空计数器

POST /openapi/v1/cc/rules 添加 CC 规则

字段	类型	必填	说明
`host`	string	必填	域名，`*` 匹配所有
`path`	string	必填	路径前缀
`threshold`	int	必填	时间窗口内最大请求数
`window`	int	必填	时间窗口（秒）
`ban_duration`	int	必填	封禁时长（秒）
`action`	string	必填	`block` 或 `challenge`
`enabled`	bool	必填	是否启用

curl -k -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"host":"*","path":"/api/login","threshold":10,"window":60,"ban_duration":300,"action":"block","enabled":true}' \
  "$WAF/openapi/v1/cc/rules"

GET /openapi/v1/cc/stats CC 统计 & 日志

/cc/logs 需分页参数 ?page=1&page_size=20
删除日志 Body: {"all": true} 或 {"ids": [1,2,3]}

/cc/stats 响应

{"total_blocked": 0, "today_blocked": 0, "active_attacks": 0, "top_blocked_ips": null, "rule_stats": null}

/cc/logs 响应

{"logs": null, "total": 0, "page": 1, "page_size": 20, "total_pages": 0}

写操作响应

{"message": "CC计数器已清空"} {"message": "CC规则删除成功"} {"message": "CC规则更新成功"}

8.3 自定义规则 custom-rules Pro

GET/openapi/v1/custom-rules规则列表

POST/openapi/v1/custom-rules添加规则

PUT/openapi/v1/custom-rules/:id更新

POST/openapi/v1/custom-rules/:id/toggle启停

DELETE/openapi/v1/custom-rules/:id删除

GET/openapi/v1/custom-rules/export导出 ZIP

POST/openapi/v1/custom-rules/import导入 ZIP

POST/openapi/v1/custom-rules/reload热重载

POST /openapi/v1/custom-rules 添加自定义规则

字段	类型	必填	说明
`name`	string	必填	规则名称
`method`	string	必填	HTTP 方法，`any` 匹配所有
`action`	string	必填	`block`（拦截）
`relation`	string	必填	`and`（全部满足）或 `or`（任一满足）
`judges`	array	必填	判断条件列表
`enabled`	bool	可选	是否启用

judges[] 子字段

字段	说明
`position`	`uri`、`parameter_key`、`parameter_value`、`request_header`、`request_body`、`any`
`keyword`	关键词（与 `content` / `rix` 三选一）
`content`	内容匹配（string / array）
`rix`	正则表达式
`negate`	是否取反

curl -k -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"name":"拦截敏感文件探测","method":"any","action":"block","enabled":true,"relation":"or",
       "judges":[{"position":"uri","keyword":"/.env"},{"position":"uri","keyword":"/.git/config"}]}' \
  "$WAF/openapi/v1/custom-rules"

响应

{"message": "自定义规则添加成功", "rule_id": "a1b2c3d4", "rule": {...}}

GET /custom-rules/export 返回 application/zip
POST /custom-rules/import 表单字段 file（ZIP）→ {"message":"自定义规则导入成功","count":N}
POST /custom-rules/reload → {"message":"自定义规则重新加载成功"}

8.4 站点管理 site

GET/openapi/v1/sites站点列表

POST/openapi/v1/site/add添加站点

POST/openapi/v1/site/add-with-cert带证书添加

POST/openapi/v1/site/delete删除站点

GET/openapi/v1/site/:id/certificate标准证书

GET/openapi/v1/site/:id/sm2-certsSM2 证书

POST/openapi/v1/site/status启用 / 禁用

POST/openapi/v1/site/https开关 HTTPS

PUT/openapi/v1/site/update更新站点

POST/openapi/v1/site/update-cert更新站点证书

POST/openapi/v1/site/:id/renew-certificate续期证书

POST/openapi/v1/site/:id/replace-certificate替换证书

POST/openapi/v1/site/:id/remove-certificate移除证书

POST/openapi/v1/site/:id/sm2-certs绑定 SM2 证书

DELETE/openapi/v1/site/:id/sm2-certs移除 SM2 绑定

GET/openapi/v1/health全部健康检查

GET/openapi/v1/health/:id单站点健康检查

GET /openapi/v1/sites 查询站点列表

{ "sites": [ {"id": 1, "name": "主站", "domain": "example.com", "target_url": "http://127.0.0.1:8080", "status": 1, "enable_https": true} ] }

POST /openapi/v1/site/add 添加站点

字段	类型	必填	说明
`name`	string	是	站点名称
`domain`	string	是	域名（多域名可用逗号、分号、换行分隔）
`target_url`	string	否	回源目标 URL
`enable_https`	bool	否	启用 HTTPS（自动生成自签名证书）
`force_https_redirect`	bool	否	强制 HTTP→HTTPS 跳转
`enable_http2_upstream`	bool	否	回源启用 HTTP/2（默认 true）
`enable_anti_devtools` 等 Pro 字段	bool	否	反 DevTools / 反爬虫 / UA 检测 / 响应检测 / 缓存 / 负载均衡

curl -k -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -X POST "$WAF/openapi/v1/site/add" \
  -d '{"name":"主站","domain":"example.com","target_url":"http://127.0.0.1:8080"}'

{"message": "站点添加成功", "site": {"id": 1, "name": "主站", "domain": "example.com", "status": 1, "enable_https": false}}

需要 site:write scope。免费版最多 2 个站点，Pro 无限制。
POST /site/delete Body: {"id":1} → {"message":"站点删除成功"}
POST /site/add-with-cert 使用 multipart/form-data，附加 cert_file、key_file

POST /openapi/v1/site/status 站点状态与证书操作

POST/openapi/v1/site/status

Body{"id":1,"status":1}

响应{"message":"站点启用成功","status":1}

status：1=启用，0=禁用

POST/openapi/v1/site/https

Body{"id":1,"enable_https":true}

响应{"message":"站点证书更新成功","cert_type":"..."}

PUT/openapi/v1/site/update

Body站点完整字段

响应{"message":"站点更新成功"}

POST/openapi/v1/site/update-cert

Body{"id":1,"cert_name":"..."} 或 PEM 文本

响应{"message":"站点证书更新成功"}

POST/openapi/v1/site/:id/renew-certificate

无 Body。重新签发自签名证书。

POST/openapi/v1/site/:id/replace-certificate

multipart：cert_file + key_file。替换 PEM 证书。

POST/openapi/v1/site/:id/remove-certificate

取消 HTTPS，不删除证书库文件。

POST/openapi/v1/site/:id/sm2-certs

Body{"sign_cert_id":5,"enc_cert_id":6}

说明绑定 SM2 签名/加密证书

DELETE/openapi/v1/site/:id/sm2-certs

移除 SM2 绑定。

GET /openapi/v1/health 健康检查

{ "health_status": { "19": {"site_id": 19, "domain": "example.com", "is_alive": true, "status": 200, "latency": 2, "last_check": "2026-06-06 11:44:53"} }, "timestamp": "2026-06-06 11:44:56" }

8.5 攻击日志 attack

GET/openapi/v1/attack/logs日志列表

GET/openapi/v1/attack/logs/:id单条详情

GET/openapi/v1/attack/stats统计概览

GET/openapi/v1/attack/ip-groups按 IP 分组

GET/openapi/v1/attack/export导出 json/csv

DELETE/openapi/v1/attack/logs删除日志

GET /openapi/v1/attack/logs 查询攻击日志

参数	说明
`page`	页码（必填，min=1）
`page_size`	每页条数（必填，1–100）
`host`	按域名过滤
`client_ip`	按客户端 IP 过滤
`method`	按 HTTP 方法过滤
`rule_id`	按规则 ID 过滤
`start_time` / `end_time`	时间范围（Unix 秒）

curl -k -H "Authorization: Bearer $KEY" \
  "$WAF/openapi/v1/attack/logs?page=1&page_size=20&host=example.com"

{ "logs": [{ "id": 1896080, "method": "GET", "url": "example.com/", "host": "example.com", "rule_name": "[scan-guard] scan-guard: 30 次 4xx / 10s", "rule_id": "acl_15", "client_ip": "1.2.3.4", "attack_type": "acl", "created_at": "2026-06-02 18:05:12" }], "total": 1, "page": 1, "page_size": 20 }

GET /openapi/v1/attack/stats 统计 & 导出

/attack/export?format=json 或 format=csv 返回文件流
DELETE /attack/logs → {"message":"删除成功","affected":N}

{ "total_attacks": 500000, "today_attacks": 0, "top_rules": [{"rule_name": "[scan-guard] ...", "rule_id": "acl_15", "count": 500000}] }

8.6 缓存管理 cache

GET/openapi/v1/cache/stats缓存统计

GET/openapi/v1/cache/stats/detail详细统计

GET/openapi/v1/cache/files文件列表

POST/openapi/v1/cache/files查询文件内容

POST/openapi/v1/cache/config更新配置

POST/openapi/v1/cache/clear清空缓存

DELETE/openapi/v1/cache/files/delete删除指定文件

POST/openapi/v1/cache/js-obfuscate启动 JS 混淆

GET/openapi/v1/cache/js-obfuscate/status混淆进度

POST /openapi/v1/cache/config 更新缓存配置

curl -k -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"enabled": true, "ttl": 3600}' "$WAF/openapi/v1/cache/config"

POST /cache/files Body: {"file": "/path"}
/cache/clear 全站 → {"message":"全部缓存已清空"}；按站点 → {"message":"该站点缓存已清空","host":"..."}
POST /cache/js-obfuscate Body: {"host":"example.com"} → {"message":"JS混淆任务已启动","task_id":"..."}
GET /cache/js-obfuscate/status?host=... 返回进度百分比

8.7 规则管理 rule

GET/openapi/v1/rule/blockRuleId已禁用规则 ID

GET/openapi/v1/rules/reload热重载 WAF 规则

POST/openapi/v1/rules/status批量更新规则状态

GET/openapi/v1/rule/blockRuleId→{"id": [], "rules": []}

GET/openapi/v1/rules/reload→{"message": "规则重新加载成功", "preserved_status": 609}

POST/openapi/v1/rules/status→{"message": "规则状态更新成功"}

8.8 系统监控 monitor

GET/openapi/v1/monitor/systemCPU / 内存 / 负载

GET/openapi/v1/monitor/connections连接数

GET/openapi/v1/monitor/history历史监控

GET/openapi/v1/traffic/trend流量趋势

GET/openapi/v1/statsWAF 全局统计

GET /openapi/v1/monitor/system 系统指标

{ "port_stats": {"port_80_rate": "0 req/s", "port_443_rate": "0 req/s", "total_qps": "0 req/s"}, "cpu_stats": {"usage_percent": "5.94%", "load_average_1": "0.27", "cores": 8}, "memory_stats": {"total": "19.53 GB", "used": "3.73 GB", "available": "15.80 GB", "usage_percent": "19.10%"}, "timestamp": "2026-06-06 11:44:57" }

GET /openapi/v1/stats WAF 全局统计

{ "total_requests": 125840, "blocked_requests": 312, "cache_hit_rate": "42.50%", "total_rules": 1500, "total_sites": 3, "client_ip": "127.0.0.1" }

8.9 观察室 obs Pro

GET/openapi/v1/obs/config观察室配置

PUT/openapi/v1/obs/config更新配置

GET/openapi/v1/obs/rules观察规则

POST/openapi/v1/obs/rules添加规则

PUT/openapi/v1/obs/rules/:id更新规则

DELETE/openapi/v1/obs/rules/:id删除规则

GET/openapi/v1/obs/records观察记录

GET/openapi/v1/obs/records/:id记录详情

GET/openapi/v1/obs/records/:id/raw原始请求/响应

POST/openapi/v1/obs/records/clear清空记录

GET/openapi/v1/obs/stats观察统计

观察室为 PRO 功能，授权失效时统一返回 {"error":"此功能需要 Pro 授权","pro_required":true}
写操作成功返回 {"message":"…成功"}

8.10 插件管理 plugins

GET/openapi/v1/plugins已安装插件

GET/openapi/v1/plugins/config插件配置

POST/openapi/v1/plugins/config更新配置

POST/openapi/v1/plugins/reload重载插件

POST/openapi/v1/plugins/:name/toggle启停插件

POST/openapi/v1/plugins/:name/order调整顺序

PUT/openapi/v1/plugins/:name/sites站点作用域

DELETE/openapi/v1/plugins/:name删除插件

POST/openapi/v1/plugins/upload上传 zip

POST/openapi/v1/plugins/import-urlURL 导入

GET/openapi/v1/plugins/marketplace插件市场

GET/openapi/v1/plugins/events/recent最近事件

GET/openapi/v1/plugins/events/stats事件统计

GET/openapi/v1/plugins/events/ws事件 WebSocket

POST/openapi/v1/plugins/events/clear清空事件

curl -k -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"enabled": false}' "$WAF/openapi/v1/plugins/ai-shield-1.0.0/toggle"

toggle → {"message":"插件 ai-shield-1.0.0 已禁用"}
reload → {"message":"插件配置重新加载成功"}
PUT /plugins/:name/sites Body: {"sites":[1,2]}（空数组 = 全局生效）
/upload 表单字段 file（zip）；/import-url Body: {"url":"https://..."}
/events/ws 为 WebSocket 长连接（AES-GCM 加密帧），不建议脚本调用

8.11 证书模板 cert-template

GET/openapi/v1/cert-templates模板列表

POST/openapi/v1/cert-template添加模板

GET/openapi/v1/cert-template/:id模板详情

PUT/openapi/v1/cert-template/:id更新模板

DELETE/openapi/v1/cert-template/:id删除模板

POST/openapi/v1/cert/upload上传证书到库

POST/openapi/v1/cert/reload热重载证书

POST /cert/upload：multipart/form-data，字段 cert_file、key_file、可选 name；自动识别 RSA/ECDSA/SM2
POST /cert/reload → {"message":"证书重新加载成功"}（将证书库全部加载到 TLS 引擎）

8.12 WAF 协议设置 waf Pro

GET/openapi/v1/waf/http3HTTP/3 状态

POST/openapi/v1/waf/http3开启/关闭 HTTP/3

GET/openapi/v1/waf/tls-versionsTLS 版本

POST/openapi/v1/waf/tls-versions更新 TLS 版本

POST/openapi/v1/waf/cc-challenge/generate生成 CC 挑战

POST/openapi/v1/waf/cc-challenge/verify验证 CC 挑战

GET/openapi/v1/waf/language面板语言（公开）

curl -k -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"enabled": true}' "$WAF/openapi/v1/waf/http3"

GET/openapi/v1/waf/http3→{"enabled": true}

POST/openapi/v1/waf/http3→{"success": true, "enabled": true, "message": "HTTP/3 已开启（UDP :443）"}

POST/openapi/v1/waf/tls-versions

Body{"versions": ["1.2","1.3"]}

8.13 全局设置 settings

GET/openapi/v1/settings查询设置

POST/openapi/v1/settings更新设置

GET/openapi/v1/settings→{"settings": {"base64_depth": 2, "url_depth": 2, "unicode_depth": 2, "rule_match_rate": 100}}

POST/openapi/v1/settings→{"message": "系统设置更新成功"}

8.14 反馈管理 feedbacks

GET/openapi/v1/feedbacks反馈列表（分页）

PUT/openapi/v1/feedbacks/:id/status更新状态

DELETE/openapi/v1/feedbacks删除反馈

8.15 Let's Encrypt letsencrypt

GET/openapi/v1/letsencrypt/alerts到期提醒

GET/openapi/v1/letsencrypt/list待处理订单

GET/openapi/v1/letsencrypt/status/:id订单状态

GET/openapi/v1/letsencrypt/check-dns/:id检查 DNS

POST/openapi/v1/letsencrypt/order创建订单

POST/openapi/v1/letsencrypt/save保存证书

POST/openapi/v1/letsencrypt/renew-order续期

POST/openapi/v1/letsencrypt/cancel/:id取消订单

POST/openapi/v1/letsencrypt/dismiss-alert/:id忽略提醒

curl -k -H "Authorization: Bearer $KEY" "$WAF/openapi/v1/letsencrypt/alerts"

8.16 统计 & 健康检查

与 8.8 系统监控、8.4 站点管理 · 健康检查共用以下端点：

GET/openapi/v1/statsWAF 全局统计

GET/openapi/v1/health全部站点健康

GET/openapi/v1/health/:id单站点健康

GET/openapi/v1/realtime/ws实时数据 WebSocket

8.17 公开辅助接口（无需 scope / 无需 API Key）

用于面板健康探测、配置初始化、验证码等；也可用于监控脚本，不需要 Authorization 头。

GET/openapi/v1/ping健康探测 → pong

GET/openapi/v1/config面板公共配置

GET/openapi/v1/maintenance-server-status维护服务器状态

GET/openapi/v1/maintenance-server维护服务器地址

GET/openapi/v1/captcha/challenge滑块验证码 challenge

POST/openapi/v1/captcha/verify提交滑块验证

GET/openapi/v1/qrcode二维码图片（data URI）

curl -k "https://127.0.0.1:8088/openapi/v1/ping"
# → "pong"

POST /captcha/verify Body: {"challenge_id":"...","user_ratio":0.5,"trail":[...],"duration_ms":N}
公开接口不记录审计日志

9. 屏蔽接口说明

以下接口永远不对外暴露，即使使用 *:write 也会返回 endpoint_not_exposed (403)：

前缀	原因
`/openapi/v1/update/*`	升级 / 重启 / 回滚，高危操作
`/openapi/v1/panel/*`	面板配置（端口、TLS、密码），高危操作
`/openapi/v1/license/*`	License 激活 / 迁移
`/openapi/v1/order*`	订单相关（order-config / order-list 等）
`/openapi/v1/internal/*`	内部接口
`/openapi/v1/openapi/*`	禁止用 API Key 管理 API Key 自身（防提权）

10. 安全说明

Key 安全

Secret 仅在创建时明文展示一次，请立即保存到密码管理器
不同用途建议创建不同 Key（最小权限原则）
定期吊销不再使用的 Key
不要将 Key 明文写入代码仓库，使用环境变量或密钥管理服务

网络安全

强制 HTTPS，请确认 WAF 面板已配置有效证书
生产环境建议在 Key 上设置 IP 白名单（后续版本支持）
面板管理端口不应直接暴露到公网

PRO 授权

OpenAPI 通道是 PRO 专属功能，Key 生成和调用均实时验证
授权到期后，无需吊销 Key，调用会自动返回 pro_required (403)
续期后，所有 Key 立即恢复可用

审计

每次成功调用会记录到审计日志（含 Key 前缀、路径、时间、来源 IP）
last_used_at 字段每 30 秒持久化一次，用于判断 Key 活跃度

文档基于 FOXWAF 当前版本生成，接口行为以实际部署版本为准。