跳转至

IP 黑白名单

Website Defender 提供 IP 黑名单和白名单机制，实现基于 IP 地址的访问控制。

IP 白名单

允许特定 IP 或 CIDR 网段直接跳过认证，适合信任的内部网络或固定 IP 的服务。

功能特点

  • 支持精确 IP 匹配（如 192.168.1.100）
  • 支持 CIDR 网段匹配（如 192.168.1.0/24、10.0.0.0/8）
  • 白名单命中后直接放行，跳过后续所有认证检查（JWT、Git Token、许可证等）

典型使用场景

  • 公司内网 IP 段：10.0.0.0/8
  • CI/CD 服务器固定 IP
  • 监控系统的健康检查 IP
  • 第三方可信服务的回调 IP

IP 黑名单

通过精确匹配或 CIDR 网段封禁恶意 IP，是安全防护的第一道防线。

功能特点

  • 支持精确 IP 匹配和 CIDR 网段
  • 优先级最高：黑名单检查在所有其他认证之前执行
  • 命中黑名单的请求直接返回 403 Forbidden

临时封禁

黑名单条目支持可选的过期时间，实现临时封禁：

  • 永久 -- 无过期时间（默认）
  • 定时 -- 可选择预设时长：1 小时、6 小时、24 小时、7 天、30 天
  • 自动封禁 -- 威胁检测引擎在阈值超出时自动创建临时黑名单条目

过期条目每 10 分钟自动清理一次。

备注

每个黑名单条目可以包含可选的备注字段（如 "可疑扫描活动"、"auto-banned: brute force"）。自动封禁的条目会自动标注备注信息。

优先级说明

IP 黑名单的优先级高于白名单。如果某个 IP 同时存在于黑名单和白名单中，该 IP 将被拒绝访问。

授权域绑定

每个 IP 白名单条目可以绑定一个授权域，指定该 IP 白名单适用于哪个受保护域名。添加白名单条目时，域名字段提供一个下拉选择器，选项来自授权域管理注册表。

如果白名单条目绑定了授权域，则该 IP 仅在访问该域名时才被白名单放行。访问其他域名时将继续进行令牌认证。如果域名字段为空，则该 IP 对所有域名均生效。

管理方式

通过管理后台

  1. 登录管理后台（默认 http://localhost:9999/wall/admin/）
  2. 进入 IP 黑名单 或 IP 白名单 管理页面
  3. 添加、查看或删除 IP 条目（白名单支持绑定授权域）

通过 API

IP 名单支持通过 REST API 进行管理：

方法 路径 说明
POST /ip-black-list 添加黑名单条目
GET /ip-black-list 查询黑名单列表
DELETE /ip-black-list/:id 删除黑名单条目
POST /ip-white-list 添加白名单条目
GET /ip-white-list 查询白名单列表
DELETE /ip-white-list/:id 删除白名单条目

API 鉴权

以上所有 API 均需要管理员认证。路径前缀为可配置的 ROOT_PATH（默认 /wall）。完整的 API 文档请参阅 API 参考。

相关页面