Files
usdt/docs/admin-access-whitelist.md
T
2026-11-17 03:12:44 -05:00

2.7 KiB

管理后台全局接口 IP 白名单

部署

  1. 执行 sql/admin_access_whitelist.sql(增量建表,无默认放行规则)。
  2. 通过管理接口或 SQL 配置允许访问的路径/IP,必须包含管理员访问的 /login、/captchaImage、/getInfo、/getRouters 等实际调用路径;固定管理员 IP 可配置 /**。
  3. 在后台 application 配置添加以下内容,重启启用:
admin:
  access-whitelist:
    enabled: true # 默认 false,部署前先配置规则
    refresh-delay-ms: 30000

全局过滤覆盖此后台服务所有入口,包括登录、退出、匿名开放 API、回调和静态资源,没有隐式豁免,也不会绕过原有签名、登录和业务权限。公共支付/回调接口如需对任意 IP 开放,可显式配置该路径与 *。空规则、全部停用、首次加载失败时,启用状态下均拒绝访问。关闭开关需要修改配置并重启,可用于规则误配后的恢复。

规则

每行 pathPattern 与 ipPattern 同时匹配即放行,多行取或。路径采用 Ant 规则:* 为单段、** 为多段、? 为单字符;/system/** 匹配系统接口。IP 支持精确 IPv4/IPv6 以及 *、?,如 192.168.*.*,不是 CIDR。IPv6 按文本匹配,使用实际连接地址表示形式。

仅匹配应用内路径,不含 context-path、查询串;使用 Servlet 路径解码/分号移除规则。IP 从 request.getRemoteAddr() 读取,不直接读取 X-Forwarded-For 或 X-Real-IP。反向代理部署时它默认是代理地址:需要在容器层仅对受信代理做地址还原,且禁止客户端绕过该代理直连后台;否则这里只能限制代理本身。不要配置无边界信任所有代理头。

管理接口

基路径 /system/accessWhitelist,沿用 system:config:* 权限,并保留若依操作审计。

方法 路径 权限 说明
GET /list list 获取全部规则
POST 基路径 add 新建
PUT /{id} edit 更新、启停
DELETE /{id} remove 删除
POST /refresh edit 触发当前节点刷新

新增/更新请求示例:

{"pathPattern":"/**","ipPattern":"192.168.1.*","enabled":true,"remark":"管理网络"}

更改写入数据库,正常情况下约 30 秒后生效(刷新间隔不含查询耗时);各后台实例独立定时拉取,可调用刷新接口提前更新当前实例。每次刷新完整构建后原子替换快照,请求线程不查库;数据库故障或规则无效会保留最后成功快照并输出不含配置内容的错误日志。首次初始化后调度持续重试。刷新接口返回刷新成功或失败信息。

本次仅新增后台配置 API,未添加前端管理页面。