IP 黑白名单 API

能力与隔离

用于您的服务端将业务系统的封禁、放行同步到 waf.bi CDN。网页与 API 共用一份名单:可以读取、删除在网页添加的记录,也可以在网页管理 API 添加的记录。仅能访问密钥所属账户,A 用户的规则不会作用于 B 用户。

接口基址:https://api.waf.bi/api/v1/open。全部 ID 用字符串传输和保存;时间统一为北京时间 yyyy-MM-dd HH:mm:ss。不要把大整数 ID 转为 JavaScript Number。

创建密钥与认证

在用户面板的 IP 黑白名单 页面创建专用 API 密钥,设置名称及到期时间。明文仅显示一次,数据库只保存哈希;遗失请撤销后重建。密钥仅有本账户 IP 名单和只读站点列表权限,不是登录凭据,不能修改源站、资金或证书。

Authorization: Bearer <YOUR_IP_API_KEY>
Content-Type: application/json

仅从可信服务端调用,不使用登录 Cookie,不放在浏览器、App、URL 参数、日志或公开仓库。不提供跨域网页调用授权。撤销、到期或账户封禁后新请求不可继续调用;已经开始执行的请求可能完成。

范围与冲突规则

  • 账户级:写入/按 IP 删除时必须明确传 scope: "account",不传 site_id。仅作用于您自己的全部 CDN 站点(含之后新增的站点)。
  • 站点级:传 scope: "site" 和字符串 site_id。通过 GET /sites 获取本账户站点 ID;被墙跳转不是 CDN 站点,不支持此名单。
  • 站点级作用于主域名、关联 SPA API 域名、额外前端域名;不同站点可分别拉黑和放白同一 IP,不互相干扰。
  • 同站点,以及账户级与任一站点级之间,黑白名单不能有 IP / CIDR 交集。例如黑名单 203.0.113.0/24 与白名单 203.0.113.9 冲突。
  • 冲突返回 code=40901,指出已有规则、范围和记录 ID。必须先删除另一名单规则,不会自动覆盖、转换或删除。

获取站点

curl --fail-with-body 'https://api.waf.bi/api/v1/open/sites' \
  -H "Authorization: Bearer $WAF_IP_API_KEY"

{"code":0,"message":"ok","data":{"list":[{"id":"123","slug":"example-slug","domain":"example.com"}]}}

拉取名单(含网页设置)

GET /ip-rules,可选参数:type=black/white、site_id(只查该站点直接设置的规则)、scope=account(只查账户级)、ip(规范化后的精确规则匹配)、page_size、after_id。默认及上限 100 条;超过上限截断。省略范围时查询本账户全部记录,包括过期记录;expires_at 可用于判断是否仍有效。site_id 与 scope=account 不能同时传。

curl --fail-with-body 'https://api.waf.bi/api/v1/open/ip-rules?page_size=100' \
  -H "Authorization: Bearer $WAF_IP_API_KEY"

{"code":0,"message":"ok","data":{
  "list":[{"id":"456","ip":"203.0.113.9","list_type":"black","site_id":"123",
    "scope":"example.com","remark":"业务系统封禁","expires_at":null,"created_at":"2026-11-13 12:00:00"}],
  "total":1,"next_after_id":"","page_size":100
}}

next_after_id 非空时,原筛选条件保持不变,带 after_id 继续请求,直到为空。刚好满一页时可能多请求一次空页。total 为当前筛选的总数,不是当前游标后的剩余数;遍历不是数据库快照,同步过程中其他新增/删除可能使总数变化。要获得站点完整生效集合,需合并账户级与该站点级记录。

新增与批量新增

POST /ip-rules:必填 ip、list_type(black/white)和明确的范围;remark 可选,最多 200 字;expires_at 可选,省略或空字符串表示永久,指定时必须为未来北京时间。支持 IPv4、IPv6、CIDR,不支持域名、带 zone 的 IPv6 或非标准 IP。网段会归一到网络地址,/32 和 /128 归一为单 IP。

curl --fail-with-body -X POST 'https://api.waf.bi/api/v1/open/ip-rules' \
  -H "Authorization: Bearer $WAF_IP_API_KEY" -H 'Content-Type: application/json' \
  -d '{"ip":"203.0.113.9","list_type":"black","scope":"site","site_id":"123","remark":"业务系统封禁"}'

# 账户级放行(仅您的全部 CDN 站点)
curl --fail-with-body -X POST 'https://api.waf.bi/api/v1/open/ip-rules' \
  -H "Authorization: Bearer $WAF_IP_API_KEY" -H 'Content-Type: application/json' \
  -d '{"ip":"2001:db8::9","list_type":"white","scope":"account","expires_at":"2027-01-01 00:00:00"}'

同范围、同类型、同规范化 IP 重复添加,返回已有记录,不覆盖其备注和有效期;到期后的同一规则可重新启用。需要修改有效规则时先删除再添加。并发重试不会创建重复记录。

POST /ip-rules/batch:把 ip 换为 ips 字符串数组,其余字段相同。每批 1~200 条,先校验全部再提交;任意一条冲突或无效则整批不写入。返回新增/重新启用数量 created 和已存在数量 existing。账户最多 10000 条记录(含过期),请及时删除不用的记录。

{"ips":["203.0.113.8","203.0.113.9"],"list_type":"black","scope":"site","site_id":"123"}

{"code":0,"message":"ok","data":{"created":2,"existing":0}}

删除名单

DELETE /ip-rules/:id 按记录 ID 删除;或 DELETE /ip-rules 传 JSON,按 IP + 类型 + 范围删除。只能删除本账户规则,包括网页添加的记录。不存在或不属于本账户的记录不会被修改,删除按幂等成功返回,不泄露其他账户数据。

curl --fail-with-body -X DELETE 'https://api.waf.bi/api/v1/open/ip-rules/456' \
  -H "Authorization: Bearer $WAF_IP_API_KEY"

curl --fail-with-body -X DELETE 'https://api.waf.bi/api/v1/open/ip-rules' \
  -H "Authorization: Bearer $WAF_IP_API_KEY" -H 'Content-Type: application/json' \
  -d '{"ip":"203.0.113.9","list_type":"black","scope":"site","site_id":"123"}'

{"code":0,"message":"已删除"}

响应、错误与重试

统一结构为 code、message、可选 data。code=0 成功;业务校验失败 HTTP 200,但 code 非 0。必须检查 code,不要只看 HTTP 状态。常见业务码:40001 参数错误/数量限制,40401 站点不存在或无权操作,40901 黑白名单交集冲突。

{"code":40901,"message":"添加失败:IP / 网段与账户级(我的全部站点)的白名单规则 203.0.113.0/24(记录 ID 789)冲突,请先删除该白名单规则后再添加"}

认证失败 HTTP 401 / code=40101;限流 HTTP 429 / code=42901,Retry-After: 60;服务异常 HTTP 500 / code=50001 或 HTTP 503 / code=50301。单来源 IP 每分钟 300 次、单账户合计每分钟 120 次,多个密钥共享账户额度,每账户最多 10 个密钥;请求体上限 64 KiB。限额是当前发布配置,后续以面板/公告为准。

网络超时、429、5xx 可退避重试同一操作;参数/冲突错误先处理原因,不要无限重试。客户系统与 CDN 不是跨系统事务:请在您的后端保存待同步任务,失败后重试,并定期分页拉取核对。不做双向自动同步或全量覆盖,不会误删网页手工设置的其他规则。

何时生效

成功只代表控制面已保存。边缘正常每 10 秒拉取配置,通常下一轮同步生效;同步失败会延迟,不保证返回时全节点已应用。过期规则在下一轮成功同步后移除;节点与控制面失联期间可能继续使用旧配置。

白名单是站点级防护例外,不是“绝对放行”:不会解除平台全局封禁,也不会跳过全部 WAF 检查。删除黑名单不等于清除平台其他安全封禁。不要把白名单开放给任意终端用户自行设置。