隧道代理开发手册
总览
新手开发者可通过如下2个步骤使用隧道代理：
一、购买成功后，先在会员中心查看隧道信息，进行本地调试和验证。
二、 参考代码样例请求隧道代理访问目标网站。
API接口
隧道代理API接口一览
| 接口名称 | 接口功能 |
|---|---|
| TpsCurrentIp | 查询隧道当前IP |
| ChangeTpsIp | 立即更换隧道IP |
| GetTps | 获取隧道代理IP |
| GetIpWhitelist | 获取隧道IP白名单 |
| SetIpWhitelist | 设置隧道IP白名单 |
| AddWhiteIP | 添加白名单IP |
| DelWhiteIP | 删除白名单IP |
| GetProxyAuthorization | 获取隧道鉴权信息 |
| GetTpsProvCode | 获取隧道代理省份编码 |
| GetTpsCityCode | 获取隧道代理城市编码 |
测试隧道可用性
隧道代理支持白名单和用户名密码两种验证方式，建议您先在本机测试，测试OK后就可以正常使用了。
关于IP白名单数量
如果您选择设置白名单访问隧道，最多可设置50个白名单IP。
只要请求不超过购买时选择的每秒并发数，通过用户名密码访问隧道的IP数量没有限制。
锁定IP
对于每次请求更换IP的隧道代理，如果您需要多个请求使用一个IP（如：登录时，获取数据的多个请求需要使用同一IP），则可在password后加上:${任意字符串}，即可锁定此IP30秒。
带上相同字符串的请求使用同一个IP，不带字符串的请求随机使用IP。示例如下：
通过password后添加:${任意字符串}锁定IP
例如您的订单用户名为t18725652473456，密码为jkr369ry
普通模式（每次请求换ip）：t18725652473456:jkr369ry
锁定IP模式（同一字符串锁定同一IP）：t18725652473456:jkr369ry:abc
使用多通道
对于换IP周期15秒~1小时的隧道代理，支持多通道使用，在同一换IP周期内每个通道会转发一个独立的代理IP。
目前支持2种转发模式：
| 转发模式 | 说明 |
|---|---|
| 按IP转发 | 来自同一客户端IP的请求会转发到固定的通道。 |
| 随机转发 | 每次请求会随机转发到1个通道。 |
您可以在会员中心-隧道订单管理里查看和修改转发模式。
您发起的请求中没有明确指定转发哪个通道的情况下，系统会按上述配置进行转发。
编程使用多通道
以10通道的隧道订单为例，可划分通道编号为1~10。
您可以在程序中通过如下两种方式指定转发到哪个编号的通道：
方式一：通过用户名密码指定通道
用户名、密码和通道号生成Proxy-Authorization。
例如用户名为t18725652473456，密码为jkr369ry，本次请求转发第3号通道。
t18725652473456:jkr369ry:3
方式二：通过Header指定通道（只支持http）
以本次请求转发第3号通道为例，在发起http请求时携带如下Header（Header不区分大小写）：
kdl-tps-channel: 3
开发提示
以10通道为例，通道号的取值无需为1~10，您也可以用任意随机数或字符串作为通道号，系统会自动转换为最终的通道号，确保同一随机数机或字符串转发到同一通道，且不同随机数或字符串尽可能均匀转发到每个通道。
当您通过程序指定通道时，系统会忽略您在会员中心-隧道订单管理里的转发模式配置。
手动更换IP
对于换IP周期>=1分钟的隧道代理，隧道会根据您购买时选择的周期自动切换IP，但使用途中如果您发现该IP不可用，可以调用更换隧道IP接口让隧道立即更换一个新IP。
手动换IP的频率限制
在隧道的1个换IP周期内，调用更换隧道IP接口换IP的次数不能超过2次。
举例说明：您购买的是5分钟换IP的隧道，那么5分钟内您最多可以调用此接口2次。
频率限制
隧道代理的请求频率在购买时选择的并发数决定，默认的并发数是1秒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 | 上级代理拒绝连接 |
| 503 | Proxy Connect Error | 连接目标网站失败 |
隧道使用统计
隧道使用统计功能提供了对请求量和请求错误的统计分析。
您可以随时关注采集程序的运行走势，了解发生的错误并及时修正。我们还为几种常见的错误提供了分析和提示，帮助您提升采集程序运行的成功率。
隧道带宽监控方便您跟踪平均带宽和峰值带宽占用。 通过带宽监控折线图，您可以更好地把控带宽使用情况。
开发建议
参考如下开发建议，可以帮助您更加顺利地完成开发和调试：
-
控制好请求频率，用同一IP请求同一网站建议不超过1秒1次，避免IP被目标网站屏蔽。
- 建议关闭HTTP协议的keep-alive功能，避免因连接复用导致隧道不能切换IP
- 尽可能采用gzip压缩加速访问，在header里添加：Accept-Encoding: gzip
- 关注隧道返回码可协助您排查错误。
使用gzip详解
使用gzip压缩传输数据可显著提升访问速度，方法非常简单：
只需在http请求的header里加上：
Accept-Encoding: gzip
收到HTTP Response后检查header里是否包含：
Content-Encoding: gzip
如果包含，则对body进行gzip解压，就能得到原始内容。