欢迎使用Pangolin的产品与方案.我们致力于提供更好的动态数据传输方案及技术平台.
我们全新升级的产品,进一步提升系统弹性与可扩展性,避免依赖某一技术节点导致单点失败等问题.我们的创新架构,允许客户进行更灵活的部署,在保障网络数据传输性能 带宽利用率最大化的同时,确保了数据内容的隐私性.
请详细阅读此手册,以顺利完成系统部署及使用,充分利用Pangolin的卓越性能,我们开始吧.
一 Service API 调用须知
- Service提供3个HTTP API request(常用) release(不常用) services
- 所有API调用时候均需要提供token参数, token由我司提供, 为 ‘user:password’的base64编码
- 关于Service的IP地址, 以下用x.x.x.x指代, 如是我方提供的Service,则由我司提供, 如由客户自行部署的Service,则由客户自行记住(如客户部署了多个Service,只需记住其中一个的IP即可)
二 Service接口及调用方式一览,所有返回数据都是JSON格式:
| 接口 | 说明 | 参数 / 是否必须 | 调用示例 |
|---|---|---|---|
| /services | 获取所有可用Service | token[取值:用户的token]/ 必须 | http://x.x.x.x:2002/services?token=xxxx; |
| /resources | 获取可用国家列表 | token[取值:用户的token]/ 必须 | http://x.x.x.x:2002/resources?token=xxxx; |
| /request | 分配线路资源,会在属于客户的所有Service上选择某些线路. | token[取值:用户的token]/ 必须, number[取值:需申请的端口数量] / 非必须,默认为1,expire[取值:线路的使用时间]/ 非必须,默认取值为10, 单位为分钟, region[取值:想要申请资源所在国家的代码]/非必须,默认为unkown,资源会随机分配 | http://x.x.x.x:2002/request?token=xxxxx&number=3&expire=10®ion=155; |
| /release | 释放用户自己持有的线路资源,我们会限制单用户持有的线路的最大值,当用户的线路数超过最大值时,就能再申请线路,此接口可释放用户持有的所有线路 | token[取值:用户的token] / 必须 | http://x.x.x.x:2002/release?token=xxxx; |
典型使用步骤及代码 数据示例如下(以下接口未经特别说明均为GET方法), 完整demo在tools/demo/python/sample目录下:
- Client获取所有可用的Service地址.如单个客户部署了多个Service,则会返回所有可用Service的列表.
Request : http://x.x.x.x:2002/services?token=xxxxx
Response:
{
"message": "success",
"services": [
{
"public": "X.XX.XX.XX:2003"
},
{
"public": "X.X.XX.XXX:2003"
}
]
}
说明
message: 用于返回错误提示
services: services列表, 其中每个元素代表一个service
public: service的公网地址
- Client获取可用区域及地区码
Request : http://127.0.0.1:2002/resources?token=xxxxxxxxxxx
{
"Message": "success",
"resources": [
{ "country": "Iraq", "code": "368" },
{ "country": "India", "code": "356" },
{ "country": "Egypt", "code": "818" },
{ "country": "Turkey", "code": "792" },
{ "country": "Spain", "code": "724" },
{ "country": "Oman", "code": "512" },
{ "country": "South Africa", "code": "710" }
]
}
说明
message: 用于返回错误提示
resources: 当前可用国家及其代码
- Client向任意Service调用request接口
Request : http://x.x.x.x:2002/request?token=xxxxx&number=5&expire=10®ion=368
Response:
{
"resources": [
{
"resource": "X.X.XX.XXX:2009"
},
{
"resource": "X.X.XX.XXX:2008"
},
{
"resource": "X.X.XX.XXX:2007"
},
{
"resource": "X.X.XX.XXX:2006"
},
{
"resource": "X.X.XX.XXX:2005"
}
],
"message": "success"
}
说明
message: 用于返回错误提示
resource: 申请到的线路地址
- Client(用户程序或浏览器)设置代理, 进行常规HTTP(S)数据通信
用户可在浏览器或自己的程序里用上一步骤里获取的resource设置好代理, 然后进行常规网络访问.例如 curl -x http://X.X.X.X:2009 -U : https://ifconfig.me - 如果用户持有线路数量已达上限而无法再申请, 则释放资源后再申请
Request : http://x.x.x.x:2002/release?token=xxxx
Response:
{
"message": "success"
}
说明:
message: 错误提示消息
关于资源端口的代理数据转发权限:
- 所有HTTP(S) 请求头里必须包含请求头 Proxy-Authorization: Basic <your token> 用于认证
FAQ
- 如果不调用/release接口释放资源,会产生什么情况？答:如果不调用release接口, service则认为线路资源在到期之前一直被占用, 如线路数超过限制(例如同时持有1000条线路)则无法再分配新线路,将造成资源利用率下降,总体可用带宽及有效数据总量降低.所以建议使用后正常调用,进行资源释放.
- 某些线路资源在使用过程中变得不可用,该怎么办？因为Pangolin的线路资源为动态分配,这是可能出现的正常情况.一旦发现此情况,可以调用/request接口重新获取和优化可用线路.
- 为什么/request接口会调用失败或未申请到足够的线路
分两种情况, 1 调用失败,一般是后端没有线路可分配 2 用户持有线路数已接近或超过限制, 此时需要调用/release接口
