# 代理检测

检测调用方自己是否在使用代理或 VPN: 服务端对比请求头里的出口 IP 与国内、国外两路解析到的 IP, 给出是否使用代理、代理类型与置信度。只能检测发起请求的这一端, 不能传入任意 IP。返回结构遵循 [统一响应格式](/docs/conventions#统一响应格式)。

> 查询任意 IP 是否属于代理 / VPN / Tor / 机房, 用 [IP 归属查询](/docs/query) 返回的 `traits` 字段。

## 接口

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| `GET` | `/api/proxy-detection` | 检测调用方 |
| `POST` | `/api/proxy-detection` | 同上, 请求体必须为 `{ "enableProxyDetection": true }` |

```bash
curl https://ip.czl.net/api/proxy-detection

curl -X POST https://ip.czl.net/api/proxy-detection \
  -H "Content-Type: application/json" \
  -d '{"enableProxyDetection": true}'
```

检测在浏览器里调用最有意义: 浏览器的代理设置与用户实际走的线路一致, 服务端转发的请求看到的是服务器自己的出口。

## 响应示例

```json
{
  "code": 200,
  "data": {
    "isUsingProxy": false,
    "proxyType": "",
    "confidence": 0,
    "headerIP": "1.2.3.4",
    "domesticIP": null,
    "foreignIP": null,
    "errors": [],
    "detectionTime": 1721200000
  },
  "msg": "success"
}
```

## 字段说明

| 字段 | 说明 |
| --- | --- |
| `isUsingProxy` | 是否判定为使用代理 |
| `proxyType` | 代理类型, 未检出时为空字符串 |
| `confidence` | 置信度, 0 ~ 1 |
| `headerIP` | 请求头识别出的调用方 IP |
| `domesticIP` / `foreignIP` | 国内 / 国外解析到的 IP, 解析失败时为 `null` |
| `errors` | 检测过程中的错误列表, 部分解析失败不影响整体返回 |
| `detectionTime` | 检测时间, Unix 秒级时间戳 |

## 错误

| code | 场景 |
| --- | --- |
| `400` | `POST` 请求体缺少 `enableProxyDetection: true` |
| `429` | 超过 30 次 / 分钟, 见 [限速](/docs/conventions#限速) |
| `500` | 检测失败 |

成功响应带 `Cache-Control: public, max-age=60`。限额较低, 页面里只在用户主动触发或进入页面时检测一次, 不要轮询。
