欢迎使用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&region=155;
/release	释放用户自己持有的线路资源,我们会限制单用户持有的线路的最大值,当用户的线路数超过最大值时,就能再申请线路,此接口可释放用户持有的所有线路	token[取值:用户的token] / 必须	http://x.x.x.x:2002/release?token=xxxx;

典型使用步骤及代码 数据示例如下(以下接口未经特别说明均为GET方法), 完整demo在tools/demo/python/sample目录下:

1. 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的公网地址

2. 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: 当前可用国家及其代码

3. Client向任意Service调用request接口

Request : http://x.x.x.x:2002/request?token=xxxxx&number=5&expire=10&region=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: 申请到的线路地址

3. Client(用户程序或浏览器)设置代理, 进行常规HTTP(S)数据通信
   用户可在浏览器或自己的程序里用上一步骤里获取的resource设置好代理, 然后进行常规网络访问.例如 curl -x http://X.X.X.X:2009 -U : https://ifconfig.me
4. 如果用户持有线路数量已达上限而无法再申请, 则释放资源后再申请

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接口