快速开始

工作原理介绍

  续断内网穿透(下简称 “续断”)提供一系列 RESTful API,让您可以快速管理续断客户端和隧道。您可以使用 cURL 或在您的程序里通过 HTTP Client 调用。我们在每一个 API 说明里均附有 cURL 调用的示例。

  首先以 http 隧道为例,简单介绍一下续断的工作原理,方便您更好地理解如何调用本 API。

续断

当外部应用(如浏览器)通过续断隧道访问您内网服务时:

  1. 请求先由续断的中转服务器转发到 绑定的客户端
  2. 转发时会根据 绑定的隧道授权 信息,调整转发速率(带宽值)和转发频率(并发连接数);
  3. 客户端把请求转发到本地服务,获取资源并原路返回;
  4. 浏览器显示出内容。

因此,在新建隧道时,需要先安装好续断客户端和拥有续断隧道授权。

哲西云:
安装客户端快速入口

哲西云测试平台:
安装客户端快速入口


API 使用方法

接下来,以一个常见的例子演示如何使用续断 API

手工安装完成客户端之后,使用接口购买 1Mbps,50 并发,7 天的授权。
新建隧道,映射安装客户端的电脑的远程桌面服务 3389 端口。(如果是 Linux 则映射 ssh 的 22 端口)

  我们提供的保姆级教程,会详细说明每一步的操作。教程中涉及购买授权等操作,需要从您的帐户余额中扣除一定的金额,请登录哲西云哲西云测试平台先行充值余额(测试平台中,您的订单系统会自动为您支付,不会产生任何真实费用)。为更方便理解,在快速入门的最后,能找到完整的示例代码

请注意:

API 文档中提供的例子,均是调用哲西云的接口。若您是正在使用测试平台,请自行替换例子的 API 入口。

哲西云 API 的入口:
https://cloud.zhexi.tech/api/v2/
哲西云测试平台 API 的入口:
https://demo.zhexi.tech/api/v2/

特别说明

本文档中提供的 cURL 示例仅保证能在 Linux/macOS 上运行,若您是在 Windows 下测试,请留意替换成 CMDPowerShell 的换行符和字符串标识 "

下面提供两个格式供您参考:

# CMD
curl.exe -XPOST "{{location}}/api/v2/mapping/tunnel?apikey=您的apikey" ^
-H "Content-Type: application/json" ^
-d "{\"ip\": \"127.0.0.1\"}"
# PowerShell
curl.exe -XPOST "{{location}}/api/v2/mapping/tunnel?apikey=您的apikey" `
-H "Content-Type: application/json" `
-d "{\`"ip\`": \`"127.0.0.1\`"}"

新建隧道需要经过以下步骤:

  1. 获取(生成)您的apikey,调用 API 时均需要使用;
  2. 调用获取客户端信息 API,传入内网 IP、MAC 地址和备注名等参数,拿到绑定隧道的 客户端ID
  3. 调用获取隧道授权 API,传入授权类型、带宽和有效期等参数,拿到可用的 隧道授权ID,没有可用授权则需要购买;
  4. 调用新建隧道 API,传入上面 2 个步骤得到的 ID,再加上隧道的其他像协议、内网 IP、内网端口等参数;
  5. 隧道创建成功。

1.获取(生成)您的 APIKEY

  调用 API 时,系统会通过 apikey 识别用户身份和权限。您需要先登录到哲西云哲西云测试平台,在右上角用户名处的弹出菜单,进入到 账户信息 页面,然后点击 API 配置中的 立即生成 按钮生成 apikey,如下图:

生成apikey

  apikey 是一种用户身份凭据,免去用户调用 API 时输入账号名和密码的麻烦。测试平台与正式环境相互独立,所生成的apikey并不通用,使用前请先确认。因拥有相同的用户权限,生成后,用户需谨慎使用,请勿外发!

特别说明

若您在调用 API 的过程中遇到这样的返回结果:
{"error":2,"info":"No privilege"}
通常情况下是因为您传入的 apikey 格式不正确,或使用了另外一个环境的 apikey。请检查您获取 apikey 的站点与调用 API 的入口是否一致。

2.获取客户端 ID

  续断内网穿透是通过用户本地安装的一个客户端进行数据转发,这里假设用户已经安装好续断客户端,并且该客户端处于正常运行状态。如未安装客户端,请参考 安装客户端预装客户端 进行安装。

  在终端*中输入以下命令,需要把命令中的 您的apikey 替换成第一步中获取到的 apikey

Windows:

通常指 cmdPowerShell,系统可能没有预装 cURL,请自行安装。

macOS:

通常指 终端(Terminal)zsh

Linux:

通常指 终端(Terminal)bash

curl -XGET '{{location}}/api/v2/machine/list?apikey=您的apikey'

返回结果:

{
    "error": 0,
    "data": [
        {
            "id": "客户端ID",
            "name": "DESKTOP-xxxxxx",
            "remark": "",
            "os": "Windows 10 Pro",
            ...
        }
    ]
}

  data 中的 id 就是我们需要客户端 ID,记下来备用。一般的使用场景data中只包含一个JSON对象,即只返回符合条件的第一个客户端的信息。

  如果用户在安装客户端时指定客户端备注,或在 Web 控制台上对该客户端进行备注,可使用 remark 参数指定要获取的客户端,如:

curl -XGET '{{location}}/api/v2/machine/list?apikey=您的apikey&remark=测试1'

返回结果:

{
    "error": 0,
    "data": [
        {
            "id": "客户端ID",
            "name": "DESKTOP-xxxxxx",
            "remark": "测试1",
            "os": "Windows 10 Pro",
            ...
        }
    ]
}

更多参数说明,请阅读 获取客户端信息

3.获取隧道授权 ID

获取 1Mbps,50 并发,7 天的授权。
(假设今天是 2021-09-01)

在终端中输入以下命令,需要把命令中的 您的apikey 替换成第一步中获取到的 apikey

curl -XGET '{{location}}/api/v2/mapping/valid?apikey=您的apikey&tunnelType=0&bandwidth=1&concurrency=50&expired_at=2021-09-08'

如果您是首次调用获取隧道授权API,会返回以下结果:

{
    "error": 0,
    "data": []
}

上面的 data 为空,表示您的帐户中没有符合条件的隧道授权,需要先调用购买隧道授权 API进行购买,购买示例如下:

(调用购买/升级接口所需金额将从帐户余额中扣除,请先充值,保证余额充足)

curl -XGET '{{location}}/api/v2/order/tunnel?apikey=您的apikey&bandwidth=1&concurrency=50&expired_at=2021-09-08'

返回结果:

{
    "error": 0,
    "data": {
        "id": "隧道授权ID",
        "cost": 183 // 本次消费1.83元
    }
}

若您已购买过隧道授权,且授权符合查询符合条件,上面调用 获取隧道授权API 时,会得到如下返回结果:

{
    "error": 0,
    "data": [
        {
            "id": "隧道授权ID",
            "type": 0,
            "bandwidth": 1,
            "concurrency": 50,
            "expiredAt": "2021-09-09T07:40:12.000Z",
            ...
        }
    ]
}

更多参数说明,请阅读 获取隧道授权

4.新建隧道

目前为止,我们已获得:

  1. 客户端 ID;
  2. 1Mbps,50 并发,7 天的隧道授权 ID;

接着调用新建隧道 API,映射内网 Windows 电脑 192.168.1.111 远程桌面服务 3389 端口。

特别说明

一个隧道授权只能用于创建一个隧道,且一对一绑定,不能重复使用。如您想释放某一个授权用于建立新的隧道,请先删除当前绑定的隧道,系统会自动释放该授权。

在终端中输入以下命令,需要把命令中的 您的apikey 替换成第一步中获取到的 apikey

curl -XPOST '{{location}}/api/v2/mapping/tunnel?apikey=您的apikey' \
    -H 'Content-Type: application/json' \
    -d '{
            "name": "隧道名称",
            "machineID": "步骤2得到的客户端ID",
            "templet": "步骤3得到的隧道授权ID",
            "type": "0",
            "ip": "192.168.1.111",
            "port": "3389"
    }'

返回结果:

{
    "error": 0,
    "data": {
        "id": "xxxxxxxx-0049-11ec-8549-85142dbb7e3e",
        "domain": "ihxxx.51xd.tech",
        "port": 46600
    }
}

返回值说明:

  • id
    新创建的隧道的 ID
  • domain
    系统随机分配的外网访问域名
  • port
    系统随机分配的外网访问端口

更多参数说明,请阅读 新建隧道

接下来,我们可以另一台装有 Windows 系统的电脑上,启动远程桌面程序(mstsc.exe),输入 domain:port,本例中是 ihxxx.51xd.tech:46600,如下图,即可发起远程控制:

Windows远程桌面

至此,隧道创建成功!

完整代码示例

手工安装完成客户端之后,使用接口购买 1Mbps,50 并发,7 天的授权。
新建隧道,映射内网 Windows 电脑 192.168.1.111 远程桌面服务 3389 端口。(如果是 Linux 则映射 ssh 的 22 端口)
(假设今天是 2021-09-01)

NodeJS - Axios

示例中忽略了错误处理,实际使用请自行处理

import axios from "axios";

const httpClient = axios.create({
    baseURL: "{{location}}",
    params: {
        apikey: "您的apikey",
    },
});

// 获取客户端信息
const { data: clientRes } = await httpClient("/api/v2/machine/list", {
    params: {
        remark: "",
    },
});

if (clientRes.current === 0) throw new Error("没有可用的客户端");

const clientID = clientRes.data[0].id;

console.log(`客户端ID:${clientID}`);

// 获取授权信息
const { data: templetRes } = await httpClient("/api/v2/mapping/valid", {
    params: {
        tunnelType: 0,
        bandwidth: 1,
        concurrency: 50,
        expired_at: "2021-09-08 00:00:00",
    },
});

let templetID = "";

if (templetRes.current === 0) {
    // 没有可用隧道授权,直接购买
    const { data: orderRes } = await httpClient("/api/v2/order/tunnel", {
        params: {
            bandwidth: 1,
            concurrency: 50,
            expired_at: "2021-09-08 00:00:00",
        },
    });

    if (orderRes.error === 0) templetID = orderRes.data.id;
} else templetID = templetRes.data[0].id;

if (templetID === "") throw new Error("没有可用的隧道授权");

console.log(`隧道授权ID:${templetID}`);

// 创建隧道
const { data } = await httpClient.post("/api/v2/mapping/tunnel", {
    name: "演示隧道",
    machineID: clientID,
    templet: templetID,
    type: 0,
    ip: "192.168.1.111",
    port: "3389",
});

console.log(data);

最后修改时间: