🌐 代理请求 API
通过 DeepShield 住宅代理节点池发起任意 HTTP/HTTPS 请求。可手动选择节点（指定地域、运营商），观察出口 IP、延迟、真实响应，常用于全球可达性探测、反爬绕过、本地化内容抓取。
BASE https://api.deepshields.com/v1
主接口 POST /fetch
认证 Authorization: Bearer <api_key>
节点池 GET /proxy/nodes
📖 参数说明
所有参数通过 JSON Body 传递到 POST /v1/fetch，鉴权通过 Authorization 请求头。
| 参数 | 必填 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
url | 是 | string | — | 目标 URL，必须以 http:// 或 https:// 开头 |
node | 否 | string | 当前选中节点 | 指定出口节点名。留空使用代理池当前 GLOBAL 选择。可用节点名通过 GET /v1/proxy/nodes 获取 |
method | 否 | string | GET | HTTP 方法。可选：GET、POST、PUT、DELETE、HEAD、PATCH、OPTIONS |
headers | 否 | object | {} | 请求头字典（仅允许安全白名单头，如 User-Agent、Accept-Language、Referer 等） |
body | 否 | string | — | 请求体（POST/PUT/PATCH 时使用）。字符串形式，由调用方自行 JSON.stringify |
timeout | 否 | number | 30 | 请求超时（秒），上限 60 |
follow_redirects | 否 | bool | true | 是否自动跟随重定向 |
return_body | 否 | bool | true | 是否返回响应体。设为 false 只返回元数据（状态码、头、尺寸），适用于大文件探测 |
💡 节点切换机制：当指定 node 时，服务端会原子切换 mihomo 代理选择器，并临时切至 global 模式，确保任意 URL 都经过该节点；请求完成后恢复原模式。同一时刻只有一个 /fetch 或搜索租约持有代理，串行调度避免节点冲突。
📦 响应结构
成功响应 HTTP 200，JSON 对象字段如下：
| 字段 | 类型 | 说明 |
|---|---|---|
ok | bool | 请求是否成功（true 表示与目标服务器完成交互，与 HTTP 状态码无关） |
status_code | int | 目标服务器返回的 HTTP 状态码 |
headers | object | 目标服务器的响应头 |
body | string | 响应体（UTF-8 解码）。超过 max_response_bytes 时会被截断，返回头中会带 X-DeepShield-Truncated |
size_bytes | int | 原始响应体字节数（截断前） |
node_used | string | 实际使用的节点名 |
final_url | string | 最终 URL（经过重定向后的落地地址） |
duration_ms | int | 端到端耗时（毫秒），包含代理切换 + 请求往返 |
失败时返回 HTTP 502 + {ok:false, error:"...", node_used, duration_ms}。
⚠️ 错误码
| HTTP 状态码 | 说明 | 常见原因 |
|---|---|---|
| 200 | 成功 | 代理转发成功（注意：目标服务器也可能返回 4xx/5xx，见响应体中的 status_code） |
| 400 | 请求错误 | 缺少或非法 URL、JSON 解析失败、未知节点名 |
| 401 | 未认证 | 未提供 Authorization 请求头 |
| 403 | 认证失败 | api_key 无效 |
| 429 | 限流 | 超过速率限制 |
| 502 | 代理转发失败 | 目标服务器连接失败、超时、证书错误；响应体 {ok:false, error:...} |
| 503 | 服务不可用 | fetch 功能已在服务端被禁用 |