IPScanner

集成

Traefik 插件

来自 Traefik Plugin Catalog 的中间件，在路由器转发请求之前检查每位访客。

安装

  1. 1在 Traefik 的静态配置中声明插件，然后重启 Traefik。
  2. 2在控制台中添加 Traefik 站点并复制其 Site ID。
  3. 3在 Traefik 容器上设置 IPSCANNER_API_KEY。
  4. 4添加带 Site ID 的 ipscanner 中间件，并挂到路由器上。

新站点默认以 Monitor 模式运行：只添加请求头，切换到 Enforce 之前不拦截任何请求。

概览见 Traefik 插件页面，源码和完整示例见 GitHub。

experimental:
  plugins:
    ipscanner:
      moduleName: github.com/ipscanner/ipscanner-traefik
      version: v0.1.0

Coolify、Compose、Kubernetes

  • Coolify

    插件参数写入代理的 command 列表，密钥写入其 environment。然后在应用的容器标签中定义中间件，追加到 Coolify 生成的每个路由器上。每个应用使用独立的中间件名称。

  • Docker Compose

    参数写在 Traefik 服务上，中间件写在应用的标签中。其他路由器可通过 ipscanner@docker 复用。

  • Kubernetes

    一个 Middleware 资源，密钥来自 Secret。在 IngressRoute 中引用，或在 Ingress 上用 router.middlewares 注解引用。

  • File provider

    中间件写在动态配置文件中，密钥来自挂载的 secret。

没有密钥时，所有请求带 X-IPScanner-Status: skipped 放行。

- '--experimental.plugins.ipscanner.modulename=github.com/ipscanner/ipscanner-traefik'
- '--experimental.plugins.ipscanner.version=v0.1.0'

environment:
  - IPSCANNER_API_KEY=pk_live_...

配置

  • apiKey

    API 密钥。插件选项会显示在 Traefik 控制台中，建议改用 IPSCANNER_API_KEY、apiKeyFile 或 urn:k8s:secret 引用。

  • apiKeyFile

    存放 API 密钥的文件，例如挂载的 Docker 或 Kubernetes secret。

  • siteId

    控制台中的 Site ID。设置后，模式和策略由控制台决定。

  • mode默认 monitor

    monitor 或 enforce。设置站点后只有 monitor 生效：让站点保持 Monitor 模式。

  • blockClasses默认 malicious_automation

    未设置站点时 Enforce 模式拦截的类别：malicious_automation、ai_agent、tor、vpn、proxy、hosting、relay 或 none。

  • trustedProxies

    信任其 IP 请求头的地址和 CIDR 网段。private 加入私有网段，cloudflare 加入 Cloudflare 网段。

  • ipHeaders默认 X-Forwarded-For

    按顺序从可信代理读取的请求头。位于 Cloudflare 之后时用 CF-Connecting-IP。

  • timeout默认 1500ms

    单次检查的时间预算。超时后请求放行。

  • cacheTTL默认 10m

    按站点、IP 和 User-Agent 复用一次结果的时长。

  • cacheSize默认 10000

    内存中保存的结果数。

  • policyTTL默认 30s

    站点策略的复用时长。

  • skipPaths默认 静态资源

    对路径匹配的正则，不区分大小写。匹配的请求不检查；none 表示检查所有路径。

  • blockMessage默认 Blocked by IPScanner edge guard.

    403 页面的文字。

  • debug默认 false

    在响应中加入 X-IPScanner-Status、-Class 和 -Action，并为每个决定记录一行日志。

  • apiUrl默认 https://ipscanner.io

    API 基础 URL。

列表可用 YAML 列表或逗号分隔的值（标签中写 blockClasses=tor,vpn）。时长使用 Go 语法：1500ms、30s、10m。无效选项会停用该路由器，并在 Traefik 日志中报错。

客户端 IP

访客即 Traefik 看到的地址，除非该地址是可信代理。

  • trustedProxies

    只从这些地址读取 X-Forwarded-For 或 ipHeaders 列表中的请求头。

  • forwardedHeaders.trustedIPs

    对于不在入口点可信 IP 中的对端，Traefik 会丢弃 X-Forwarded-For，因此两处都要设置，或改读 CF-Connecting-IP。

  • trustedProxies=cloudflare, ipHeaders=CF-Connecting-IP

    位于开启代理（橙色云朵）的 Cloudflare 之后时，在中间件上同时设置这两项。

添加的请求头

添加到应用收到的请求上。先移除传入的 X-IPScanner-* 请求头，客户端无法自带判定结果。

  • X-IPScanner-Statusok, error, timeout, backoff, skipped

    检查是否执行，未执行时说明原因。

  • X-IPScanner-Classhuman, verified_bot, ai_agent, …

    访客的流量类别。

  • X-IPScanner-Actionallow, flag, block, would_flag, would_block

    请求的处理结果。Monitor 模式下为 would_flag 和 would_block。

  • X-IPScanner-Network-Classresidential_clean, hosting, vpn, tor, …

    地址的网络类别。

  • X-IPScanner-Anonymizedtrue, false

    该网络隐藏了访客的真实位置。

  • X-IPScanner-Risk0-100

    地址的风险分。

  • X-IPScanner-CountryDE

    地址所属国家或地区。

  • X-IPScanner-Sitesite_...

    已设置时为 Site ID。

检查失败或被跳过时，只设置 X-IPScanner-Status。

发往应用的请求
X-IPScanner-Status: ok
X-IPScanner-Class: ai_agent
X-IPScanner-Action: would_block
X-IPScanner-Network-Class: hosting
X-IPScanner-Anonymized: true
X-IPScanner-Risk: 60
X-IPScanner-Country: US
X-IPScanner-Site: site_4fQ8nZ2kLm7xR1vT9cBw

缓存与故障放行

  • 站点策略GET /v1/sites/{id}/policy

    模式和按类别的策略，缓存 30 秒。刷新失败时，最近一次有效的策略最多沿用 24 小时。修改无需重载即可生效。

  • 结果缓存

    每位访客（站点、IP、User-Agent）每 10 分钟检查一次，保存在内存中，最多 10,000 位访客。重载配置后仍然保留。

  • 故障放行

    结果和策略合计 1.5 秒。超时或 API 出错时请求放行，检查暂停 30 秒；遇到 401、402、403 或 429 时暂停 5 分钟。

  • 始终放行

    已验证的爬虫、OPTIONS 请求、私有和回环地址，以及跳过列表中的路径。

  • 拦截

    返回带请求 ID 的 403 页面。Monitor 模式从不拦截。

  • Free 套餐

    Free 套餐的站点保持 Monitor 模式。

  • 费用

    每位未命中缓存的访客计 2 个请求单位。缓存期内的重复请求不计费。

发送的内容

  • POST /v1/edge/check计为 2 次请求

    每位未命中缓存的访客一次调用。

  • GET /v1/sites/{id}/policy不计入用量

    站点策略，已设置 Site ID 时请求。

  • X-IPScanner-Source: traefik

    在流量和用量中将调用标记为该集成发出。

  • User-Agent: ipscanner-traefik/<version>

    版本号，显示在控制台的站点页面上。

请求体

  • sitestring

    已设置时为 Site ID。

  • ipstring

    访客地址。

  • user_agentstring

    访客的 User-Agent。

  • headersobject

    Accept、Accept-Language、Accept-Encoding、Sec-CH-UA* 和 Sec-Fetch-*，每个截断到 512 字节。

  • request_idstring

    请求的 X-Request-Id 或新生成的 ID，也会显示在拦截页面上。

它发出的边缘检测请求
curl https://ipscanner.io/v1/edge/check \
  -H "Authorization: Bearer $IPSCANNER_API_KEY" \
  -H "X-IPScanner-Source: traefik" \
  -H "User-Agent: ipscanner-traefik/0.1.0" \
  -H "Content-Type: application/json" \
  -d '{
    "site": "site_4fQ8nZ2kLm7xR1vT9cBw",
    "ip": "203.0.113.7",
    "user_agent": "Mozilla/5.0",
    "headers": {
      "accept-language": "en-US"
    },
    "request_id": "9f2c41b7d03e77f2"
  }'