IP 质量检测

IP 质量检测让每台 Agent 评估自身 VPS 出口 IP，并将结果上报到 Server。它做两件事：

1. 服务解锁检测 — Agent 从自身出口 IP 发送 HTTP 请求，判断流媒体、AI、社交等热门服务的解锁状态。
2. IP 元数据与风险信号 — Server 通过本地 GeoIP 数据库获取国家和地区，再使用已配置的第三方提供商补充其支持的网络类型标记，并在响应包含评分字段时计算欺诈风险分。

检测结果展示在专属的 IP 质量 侧边栏路由（全局概览）、各服务器详情 Tab，以及——在每个状态页单独开启后——公共状态页。

前置条件

• Agent 必须启用 CAP_IP_QUALITY（位值 1024）。默认开启（属于 CAP_DEFAULT）。
• 本地基础元数据需要加载可用的 GeoIP MMDB。未加载数据库时，这些字段不可用；第三方富化仍可提供其支持的风险与网络类型字段。详见配置页中的 geoip.mmdb_path。

能力（由 Agent 拥有）

与所有能力一样，CAP_IP_QUALITY 由 Agent 主机拥有 —— Server 无法开启或关闭它。它默认启用，因此无需任何操作即可使用 IP 质量功能。如需在某台主机上关闭它，在 Agent 的 [capabilities] deny 列表中加入 ip_quality（或传 --deny-cap ip_quality）并重启 Agent：

[capabilities]
deny = ["ip_quality"]

# 或通过命令行
./serverbee-agent --deny-cap ip_quality

若 Agent 未上报 ip_quality，则 Agent 不运行任何检测，UI 显示标准的已关闭占位状态。见 功能开关。

内置服务

启动时预置 9 个服务，每个都有一个硬编码的检测器，从 Agent 出口 IP 发送 HTTP 请求并解析响应来判断解锁状态。

每个服务均可在 Settings → IP Quality → Service Catalog 中单独启用或停用。内置服务不能删除，检测逻辑不可修改。

自定义服务

除内置服务外，管理员还可以在 Settings → IP Quality → Service Catalog → 添加服务 中定义自定义服务。

每个自定义服务包含：

• URL — 探测目标地址。必须使用 https:// 或 http://，且端口只允许 80 或 443。私有 / 回环地址在创建时被拒绝，并由 Agent 在每次请求及重定向跳转时重新校验（SSRF 防护）。
• Method — HTTP 方法（GET、HEAD 等）及可选请求头。
• 匹配规则 — 按顺序评估的规则列表，首条匹配的规则生效。每条规则基于以下之一进行匹配：
  • HTTP 状态码（精确匹配或范围）
  • 响应体正则表达式
  • 重定向目标 URL 模式

可能的结果为 unlocked（解锁）、restricted（受限）、blocked（封锁）、failed（失败）或 unsupported（不支持）。

检测频率

Agent 在以下情况运行检测：

• 定时 — 默认每 12 小时一次，可在 Settings → IP Quality → Settings → 检测间隔 中调整。
• 出口 IP 变化时 — 检测到 IP 变更后 Agent 自动重新运行。
• 手动触发 — 在任意服务器的 IP 质量 Tab 点击立即检测。

检测计划由 Agent 自主维护，Server 只推送服务目录和转发手动触发信号。

IP 元数据与风险评分

收到 Agent 上报的解锁结果后，Server 会：

1. 从已加载的本地 GeoIP MMDB 获取可用的基础元数据，无需外部请求。可下载的 DB-IP Lite Country 数据库提供国家和地区。若 MMDB 缺失、无法读取或不包含该地址，本地基础字段将保持为空。
2. 除非将 risk_provider 设为 none，否则查询已配置的第三方提供商。 匿名 ipapi.is 会返回代理、VPN、数据中心、Tor 和滥用标记，ServerBee 也据此派生 IP 类型，但精简响应不含嵌套的评分字段。数值型 0–100 风险分及风险等级（low / medium / high）需要配置 ipapi.is API Key 并使用其完整响应。结果按 IP 缓存 24 小时，相同 IP 的多次检测不会重复调用 API。

若没有提供商返回数值评分，risk_score 和 risk_level 分别为 null / unknown。只有加载了可用的 MMDB，才会显示本地元数据。

配置风险提供商

在 server.toml 中设置 ip_quality.risk_provider（或环境变量 SERVERBEE_IP_QUALITY__RISK_PROVIDER），可选值：

默认行为（无需任何配置）：Server 匿名调用 ipapi.is。匿名访问限制为每个客户端 IP 每天 100 次（按 UTC 日计），返回的标记可用于风险信号和派生 IP 类型，但不提供数值风险分。只有主请求失败时（包括配额耗尽后的 HTTP 429）才会触发 ip-api 兜底；成功响应即使没有评分也不会触发兜底。该兜底可提供代理/托管标记及派生的 IP 类型，但不提供数值风险分。详见 ipapi.is 官方的开发者限额和定价页。

创建免费 ipapi.is 账号并配置 API Key 后，可获得每日 1,000 次请求及计算 0–100 风险分所需的完整响应：

[ip_quality]
risk_provider = "ipapi_is"
risk_provider_fallback = "ip-api"  # 默认值；设为 "none" 可禁用兜底

[ip_quality.ipapi_is]
api_key = "your_api_key"
# endpoint = "https://api.ipapi.is"  # 可选；自托管实例时可覆盖默认接口

若需完全关闭风险评分：

[ip_quality]
risk_provider = "none"

完整配置参考：配置 → IP 质量检测。

查看结果

解锁状态更新通过 WebSocket 实时推送，无需刷新页面。

解锁状态说明

公共状态页展示

所有公共状态页默认不展示 IP 质量信息。若要在某个状态页上启用：

1. 进入 Settings → Status Pages，编辑对应页面。
2. 打开 Show IP Quality 开关。

未登录的访客看到的出口 IP 会被遮盖为 *.*.*.*，已登录用户可看到完整 IP。

数据保留

状态变更历史事件（unlock_event 日志）默认保留 90 天。可通过 retention.ip_quality_event_days（环境变量 SERVERBEE_RETENTION__IP_QUALITY_EVENT_DAYS）调整。每小时清理任务自动删除过期记录。

每台服务器最新的解锁结果和 IP 质量快照会持续保留（每次运行后覆盖更新，不会累积）。

数据链路

Agent
  │  (CAP_IP_QUALITY 有效)
  ├─ 按 interval_hours / IP 变化 / 手动触发 运行解锁检测
  │   AgentMessage::UnlockResults  (WebSocket)
  ▼
Server
  ├─ 更新 unlock_result + 状态变化时追加 unlock_event
  ├─ 广播 BrowserMessage::IpQualityUpdate（解锁结果，ip_quality: null）
  ├─ 后台任务：IP 风险评分（GeoIP + 可选第三方提供商，缓存优先）
  ├─ 更新 ip_quality_snapshot
  └─ 广播 BrowserMessage::IpQualityUpdate（ip_quality: 完整数据）
                    │
                    ▼
          /ip-quality  +  IP Quality Tab  +  公共状态页