IPScanner

集成

Caddy 模块

ipscanner 指令在 Caddy 内部检查每位访客，先于 reverse_proxy 或 file_server 执行。

安装

  1. 1用 xcaddy 构建带该模块的 Caddy，或在 caddyserver.com/download 上勾选 github.com/ipscanner/ipscanner-caddy。
  2. 2在控制台中添加 Caddy 站点并复制其 Site ID。
  3. 3在 Caddy 的环境变量中设置 IPSCANNER_API_KEY。
  4. 4在站点块中加入带 Site ID 的 ipscanner 指令。

需要 Caddy 2.8 或更高版本。用 caddy list-modules | grep ipscanner 确认。

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

概览见 Caddy 模块页面，源码见 GitHub。

xcaddy build --with github.com/ipscanner/ipscanner-caddy

Caddyfile

  • ipscanner

    模块将其排在 basic_auth 之前，无需全局 order 行。它在 header、redir 和重写之后执行，在认证、reverse_proxy 和 file_server 之前执行。

  • ipscanner /app/* { ... }

    用匹配器把检查限定在部分路径。

  • mode, block_classes

    未设置 site_id 时，由 Caddyfile 设定模式和拦截类别。

  • "handler": "ipscanner"

    在 JSON 配置中，是一个字段相同的 handler。

example.com {
	ipscanner {
		site_id site_...
	}
	reverse_proxy localhost:8080
}

配置

  • api_key默认 {env.IPSCANNER_API_KEY}

    API 密钥。支持占位符，密钥可来自环境变量或文件。

  • site_id

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

  • mode默认 monitor

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

  • block_classes默认 malicious_automation

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

  • timeout默认 1.5s

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

  • cache_ttl默认 10m

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

  • cache_size默认 10000

    内存中保存的结果数。

  • policy_ttl默认 30s

    站点策略的复用时长。

  • skip_paths默认 静态资源

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

  • block_message默认 Blocked by IPScanner edge guard.

    403 页面的文字。

  • debug默认 关闭

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

  • api_url默认 https://ipscanner.io

    API 基础 URL。

默认 skip_paths 包括 robots.txt、sitemap.xml、favicon.ico、脚本、样式表、source map、图片、字体和视频。

客户端 IP

模块使用 Caddy 解析出的客户端 IP，自身从不读取 X-Forwarded-For。未设置 trusted_proxies 时即对端地址。

  • trusted_proxies

    在全局 servers 选项中信任您的负载均衡器或 CDN。

  • trusted_proxies_strict

    取最右侧的不可信地址，访客无法在前面伪造一跳。推荐开启。

  • client_ip_headers CF-Connecting-IP

    位于 Cloudflare 之后时：信任 Cloudflare 网段并读取 CF-Connecting-IP。

Caddyfile
{
	servers {
		trusted_proxies static 10.0.0.0/8
		trusted_proxies_strict
	}
}

添加的请求头

添加到应用收到的请求上。先移除传入的 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。

占位符

  • {http.vars.ipscanner.status}

    检查状态，供指令之后的日志和匹配器使用。

  • {http.vars.ipscanner.class}

    流量类别，状态为 ok 时设置。

  • {http.vars.ipscanner.action}

    allow、flag、block、would_flag 或 would_block。

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: caddy

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

  • User-Agent: ipscanner-caddy/<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: caddy" \
  -H "User-Agent: ipscanner-caddy/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"
  }'