# IP 质量检测

> 检测 Agent 出口 IP 的流媒体和 AI 服务解锁情况，并对代理、VPN 及欺诈风险进行评分。

URL: https://docs.serverbee.app/zh/docs/ip-quality

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。未加载数据库时，这些字段不可用；第三方富化仍可提供其支持的风险与网络类型字段。详见[配置](/zh/docs/configuration)页中的 `geoip.mmdb_path`。

## 能力（由 Agent 拥有） [#能力由-agent-拥有]

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

```toml
[capabilities]
deny = ["ip_quality"]
```

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

若 Agent 未上报 `ip_quality`，则 Agent 不运行任何检测，UI 显示标准的**已关闭**占位状态。见 [功能开关](/zh/docs/capabilities)。

## 内置服务 [#内置服务]

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

| 服务                 | 分类  | 说明                |
| ------------------ | --- | ----------------- |
| Netflix            | 流媒体 | 区分完全解锁、仅限自制内容、已封禁 |
| Disney+            | 流媒体 |                   |
| YouTube Premium    | 流媒体 |                   |
| Amazon Prime Video | 流媒体 |                   |
| HBO Max            | 流媒体 |                   |
| Spotify            | 社交  |                   |
| ChatGPT            | AI  |                   |
| Gemini             | AI  |                   |
| TikTok             | 社交  |                   |

每个服务均可在 **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 元数据与风险评分 [#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`），可选值：

| 提供商            | 值          | 说明                                                                                           |
| -------------- | ---------- | -------------------------------------------------------------------------------------------- |
| ipapi.is（默认）   | `ipapi_is` | 匿名访问：每个客户端 IP 每天 100 次（按 UTC 日计），返回标记但不提供数值评分。免费账号/API Key：每日 1,000 次，返回计算 0–100 风险分所需的完整响应。 |
| ip-api.com（兜底） | `ip-api`   | **免费版仅限非商业用途，接口为 HTTP（非 HTTPS）。** 无需 API Key。提供代理/托管标记及派生的 IP 类型，但不提供数值风险分。                  |
| 禁用             | `none`     | 仅在加载可用 MMDB 时提供本地 GeoIP 元数据；无风险评分。                                                           |

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

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

```toml
[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"  # 可选；自托管实例时可覆盖默认接口
```

若需完全关闭风险评分：

```toml
[ip_quality]
risk_provider = "none"
```

<Callout type="warn">
  `ip-api`（ip-api.com）免费版仅限非商业用途，其 API 接口为 HTTP 而非 HTTPS。生产环境使用前，请先阅读其[服务条款](https://ip-api.com/docs/legal)。
</Callout>

<Callout type="info">
  **从旧版配置迁移？** 旧有提供商名称（`scamalytics`、`ipqs`、`proxycheck`、`abuseipdb`）已不再支持。如果您的 `server.toml` 或环境变量中仍引用这些名称，Server 启动时会输出警告日志并静默跳过风险评分。请将 `risk_provider` 更新为 `ipapi_is`（或设为 `none` 关闭评分）。
</Callout>

完整配置参考：[配置 → IP 质量检测](/zh/docs/configuration)。

## 查看结果 [#查看结果]

| 入口                             | 内容                                                         |
| ------------------------------ | ---------------------------------------------------------- |
| **IP 质量** 侧边栏路由（`/ip-quality`） | 全服务器 × 服务解锁矩阵；每台服务器的 IP 质量卡片（ASN、IP 类型、风险分与等级徽章、代理/VPN 标记） |
| 服务器详情 → **IP 质量** Tab          | 单台服务器的 IP 质量卡片、解锁矩阵、状态变更历史及**立即检测**按钮                      |
| 公共状态页                          | 解锁矩阵区块，仅当该状态页开启了 `show_ip_quality` 时显示                     |

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

## 解锁状态说明 [#解锁状态说明]

| 状态            | 含义                      |
| ------------- | ----------------------- |
| `unlocked`    | 该出口 IP 可完全访问此服务         |
| `restricted`  | 受限访问（如 Netflix 仅能看自制内容） |
| `blocked`     | 该出口 IP 无法访问此服务          |
| `failed`      | 检测过程中网络错误或超时            |
| `unsupported` | 此 IP 类型不适用该服务检测         |

## 公共状态页展示 [#公共状态页展示]

所有公共状态页**默认不展示** 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 质量快照会持续保留（每次运行后覆盖更新，不会累积）。

## 数据链路 [#数据链路]

```text
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  +  公共状态页
```

<Cards>
  <Card title="Capabilities" href="/zh/docs/capabilities" />

  <Card title="配置参考" href="/zh/docs/configuration" />

  <Card title="安全事件检测" href="/zh/docs/security-events" />

  <Card title="公共状态页" href="/zh/docs/status-page" />
</Cards>