隧道代理开发手册 - 代理IP

文档中心 / 开发指南 / 开发手册 /

隧道代理开发手册

站大爷官方 2024-12-31

总览

新手开发者可通过两步高效接入隧道代理：

1、开通实例后，在控制台获取隧道配置参数，完成本机环境连通性验证。

2、参考隧道代理控制面板的代码样例，快速构建代理，访问目标站点。

高阶策略支持：区域定位策略｜IP轮换周期｜运营商优选。

API接口文档说明

接口名称	接口功能
GetIP	获取当前隧道代理服务器
GetTransRuleIP	查询隧道及当前IP
GetIpWhiteList	获取IP白名单
SetIpWhiteList	设置IP白名单
AddWhiteIp	添加IP白名单
DelWhiteIp	删除IP白名单
ClearWhiteIp	清空IP白名单
GetProvCode	获取隧道代理省份编码
GetCityCode	获取隧道代理城市编码

隧道代理服务部署

隧道代理支持两种验证策略（IP白名单/账号密码），若是首次部署，建议在本地环境完成功能测试，测试通过后即可接入业务。

查看测试步骤

关于IP白名单数量

白名单认证模式：IP绑定额度上限200个，适用于固定终端访问场景。

用户名密码认证：IP调用数量无上限（仅受套餐并发阈值约束），适配高弹性业务架构。

ip地区、换ip周期、自主选择IP池

控制台设置

请在控制台访问路径：实例管理 > 隧道代理 > 管理 > 控制面板，进行四维策略动态配置：

◆ 地理定位策略（地区）

◆ IP轮换周期策略

◆ 运营商优选策略

◆ 资源池调度策略

策略生效时间为热更新模式（≤60秒）

编码设置

如果您想要更精细化地控制隧道转发，可以添加不同的参数来实现。例如您的用户名是20250114387972168168，密码是hywh8168，以下是参数说明：

period ：换ip周期

请求格式需包含周期参数标识period(单位：秒钟)，标准形式为：{username}-period-{15}:{password}。period取值范围0、15、30、60、120、180、240、300……取值为0即每次请求更换ip。

20250114387972168168-period-15:hywh8168  # 每15s更换ip
20250114387972168168-period-30:hywh8168  # 每30s更换ip
20250114387972168168-period-60:hywh8168  # 每60s更换ip
20250114387972168168-period-120:hywh8168  # 每120s更换ip
20250114387972168168-period-180:hywh8168  # 每180s更换ip
20250114387972168168-period-240:hywh8168  # 每240s更换ip
20250114387972168168-period-300:hywh8168  # 每300s更换ip
...

如果您的业务场景需要多种不同周期的IP，可以通过搭配参数sid（指定多个通道）来使用。。

20250114387972168168-period-30-sid-aa0001:hywh8168  # 每30s更换ip通道
20250114387972168168-period-60-sid-ab0007:hywh8168  # 每60s更换ip通道
20250114387972168168-period-120-sid-ac0010:hywh8168  # 每120s更换ip通道
...  # 可以设置多条通道

area、prov、city ：出口ip地区

area 七大自然地理分区：
华东地区 EC（East China 包含：上海，江苏，浙江，山东，安徽）

华南地区 SC（South China 包含：广东，广西，海南，福建）

华北地区 NC（North China 包含：北京，天津，河北，山西，内蒙古）

华中地区 CC（Central China 包含：湖北，湖南，河南，江西）

东北地区 NEC（Northeast China 包含：辽宁，吉林，黑龙江）
西南地区 SWC（Southwest China 包含：四川，重庆，贵州，云南，西藏）
西北地区 NWC（Northwest China 包含：陕西，甘肃，新疆，青海，宁夏）

20250114387972168168-area-EC:hywh8168  # 指定华东地区
20250114387972168168-area-SC:hywh8168  # 指定华南地区

省份编码（prov）与城市编码（city）可通过调用站大爷API接口动态获取，GetProvCode：专用于提取省份编码；GetCityCode：专用于提取城市编码。

20250114387972168168-prov-21:hywh8168  # 指定辽宁省
20250114387972168168-prov-33-city-330100:hywh8168  # 指定浙江省杭州市

当配置多层级地区参数（如 area-NEC-prov-21-city-210200）时，系统将自动采用最细的层级参数（如 city 级），其余参数视为无效。

地区参数仅作用于 IP 切换周期短于 5 分钟（即 period ≤ 5）的请求；若切换周期 ≥6 分钟，地区参数配置将自动失效。

isp ：自主选择运营商

isp取值说明：1. isp-CT选择使用电信运营商的IP资源 2. isp-CMCC选择使用移动运营商的IP资源。不传值则默认随机运营商。

20250114387972168168-isp-CT:hywh8168  #指定使用电信IP
20250114387972168168-isp-CU:hywh8168  #指定使用联通IP
20250114387972168168-isp-CMCC:hywh8168  #指定使用移动IP
20250114387972168168-isp-CERNET:hywh8168  #指定使用教育网IP

pool ：自主选择ip资源池

pool取值说明：

1. pool-std：多源IP混合池，跨平台兼容性≥99.8%，适用于常规数据采集/批量操作。2. pool-enh：星辰智能IP池，（含边缘计算节点），真人行为模拟度≥98.5%，适用于高防封业务/身份敏感场景。

当未显式传递池类型参数时，系统自动启用pool-enh星辰池。

20250114387972168168-pool-std:hywh8168  #选择使用企业IP池
20250114387972168168-pool-enh:hywh8168  #选择使用星辰IP池

您可针对不同的使用场景，动态组合 period、sid、area、prov、city、isp 等参数。

20250114387972168168-city-370100-period-60-sid-aa0001:hywh8168  # 济南市每分钟换ip
20250114387972168168-area-NC-period-300:hywh8168  # 华北地区每5分钟换ip
20250114387972168168-prov-34-city-340100-isp-CT-period-120-sid-ab0008:hywh8168  # 合肥市电信每2分钟换IP
...

当通过编码方式配置以下策略时：

◆ 地理定位策略

◆ IP轮换周期策略

◆ 运营商策略

◆ 资源池调度策略

将自动覆盖控制台（实例管理 > 隧道代理 > 控制面板）中的对应策略配置。

隧道代理请求频率控制机制

◆ 核心控制逻辑

请求频率上限由购买时设定的并发资源配额决定，默认配额为 5 req/s（每秒5次请求）

◆ 超频风险预警

超出并发配额将触发 441 异常状态码

◆ 效能优化建议

定期监控隧道使用统计中的请求量统计图和请求状态统计图

基于历史峰值数据进行请求频率策略调整

◆ 资源扩容路径

通过控制台 >实例管理 > 隧道代理 > 管理 > 升级并发数可执行并发配额扩容

频率控制提示

隧道代理启用弹性频率控制，允许短期突破并发阈值，以适应多样化场景需求。

但需注意，持续超频将触发系统限制，超出部分将被拒绝处理。

错误码说明

HTTP返回码	Response body 内容	说明
407	情况一：Proxy Authentication Failed:%auth 情况二：White IP Failed:$client_ip	情况一：用户名密码鉴权失败情况二：白名单鉴权失败
440	Bandwidth Over Limit	带宽超出限制
441	Request Rate Over Limit	HTTP请求/TCP连接过载
442	Authentication Type Error	认证方式校验失败
443	Foreign Client Forbidden	海外客户端禁止访问
444	Download Not Allowed	禁止下载
445	illegal Request Forbidden	非法请求禁止
446	Host DNS Failed	DNS解析失败
447	Real-name Authentication Required	需要实名认证
448	Target Port Forbidden	目标端口被禁止
449	Foreign Host Forbidden	境外主机禁止访问
450	IP As Host Forbidden	禁止IP访问
451	Miss Host	代理请求格式错误
452	Public Host Required	目标地址非公网IP
453	Proxy Port Error	代理端口错误
454	Proxy Authentication Expired	代理身份验证过期
457	Backend Proxy Bandwidth Over Limit	上级代理带宽超出限制
458	Backend Proxy Refused	上级代理拒绝连接
464	Invalid Param	参数不合法
458	Null Proxy	没有ip资源
462	Target Domain WhiteList Not Match	目标域名未匹配白名单
463	Target Domain BlackList Forbidden	目标域名黑名单禁止
503	Proxy Connect Error	代理连接错误

隧道使用统计

通过隧道使用统计功能，您可以：

◆ 实时掌控请求流量与错误分布；

◆ 洞察采集程序运行趋势，及时定位异常；

◆ 依据系统分析的高频错误及应对建议，优化配置与流程，显著提高成功率。

请求量统计

请求状态统计

隧道带宽监控可实时追踪平均与峰值带宽占用，并以折线图可视化呈现，助您精准把控用量动态，优化资源分配。

隧道带宽监控

开发建议

以下开发建议有助于优化调试流程与稳定性：

控制请求频率：同一IP访问同一站点建议 ≤ 1次/秒，以规避目标站点的反爬策略。

禁用Keep-Alive：关闭HTTP协议的Keep-Alive功能，防止连接复用干扰隧道IP切换效果。

启用GZIP压缩：在请求头中添加 Accept-Encoding: gzip，提升数据传输效率。

监控返回码：密切关注隧道接口返回的HTTP状态码，加速错误定位与排查。

使用gzip详解

启用 Gzip 压缩传输可显著提高访问速度，操作仅需两步：

请求配置：在 HTTP 请求头中设置 Accept-Encoding: gzip；

响应处理：若响应头携带 Content-Encoding: gzip 标识，则对响应体进行 Gzip 解压以还原原始数据。