跳到内容
Localtonet Localtonet 控制台

Localtonet REST API

获取本页帮助
本页内容 8 个章节
  1. 交互式参考
  2. 开始之前
  3. 基础 URL 与认证
  4. 约定
  5. 错误
  6. 速率限制
  7. 示例
  8. 列出你的隧道
  9. 用随机子域名创建 HTTP 隧道
  10. 启动隧道
  11. 端点分组
  12. 隧道
  13. 批量隧道操作
  14. 隧道配置
  15. AuthToken
  16. 令牌组
  17. 服务器
  18. SSO 提供商
  19. VPN 访问
  20. 故障排查
  21. 相关页面

REST API v2 可以完成控制台对隧道所做的事情:创建、启动、停止、删除和配置隧道,以及管理 AuthToken、令牌组和 SSO 提供商。每个请求都用你的 API 密钥进行认证。

交互式参考 #

每个端点及其请求和响应模型,以及可用来试用的表单,都在交互式参考中:

本页介绍通用约定和各端点分组的概览。请求的确切字段,请在参考中打开对应的端点查看。

开始之前 #

  • 你的 API 密钥。打开控制台,在 API 密钥卡片中使用复制。请参阅账户与安全。
  • 创建隧道时:需要运行该隧道的设备的 AuthToken,以及用该令牌连接的 Localtonet 客户端。请参阅 AuthToken。

请妥善保管你的 API 密钥。任何拥有它的人都可以创建、更改和删除你的隧道和令牌。API 密钥卡片中的更换会创建新密钥,并使旧密钥失效。

基础 URL 与认证 #

所有 v2 端点都以下面的地址开头:

基础 URL
https://localtonet.com/api/v2

在每个请求的 Authorization 请求头中,以 Bearer 令牌的形式发送 API 密钥:

HTTP
GET /api/v2/tunnels HTTP/1.1
Host: localtonet.com
Authorization: Bearer <YOUR_API_KEY>

在团队控制台中复制的 API 密钥,会列出该团队中的 AuthToken 和隧道;你自己账户的密钥则列出不属于任何团队的 AuthToken。

约定 #

主题API 的行为
格式请求体和响应体均为 JSON。带请求体时请发送 Content-Type: application/json。
隧道 ID路径中的 tunnelId 是隧道的数字 id,由列表和创建端点返回。
路径中的 AuthToken{token} 就是 AuthToken 字符串本身。
成功状态码读取返回带响应体的 200,大多数创建操作返回 201(隧道创建端点会返回新建的隧道),大多数操作和更新返回不带响应体的 204。各端点的响应见参考。
批量端点路径中包含 /bulk/ 的端点接受 JSON 数组,每次请求最多 100 项(/tunnels/bulk/protocol-type:最多 500 项)。
新建的隧道你创建的隧道尚未运行,需要用启动操作来启动它。只有 proxy/with-detail 端点可以通过 isStartAfterCreate 在同一次调用中启动隧道。

错误 #

状态含义响应体
400请求体无效,或操作被拒绝,例如因为超出了你的套餐限制。大多数端点返回 JSON 格式的问题对象;title 中是消息。验证错误和批量端点的错误列在 errors 下。
401API 密钥缺失或无效。没有具体消息
403, 409当更改不被允许,或与当前配置冲突时,部分隧道配置和 VPN 访问端点会返回此状态。问题对象,消息在 title 中。
404未找到该隧道或对象,或它不属于你。空,或问题对象
429请求过多。见下面的速率限制。

速率限制 #

请求有速率限制。超出限制的请求会收到 429 Too Many Requests。请等待后重新发送;请使用批量端点,而不要进行大量单个调用。

示例 #

请把 <YOUR_API_KEY> 替换为你的 API 密钥,把 <YOUR_TOKEN> 替换为设备的 AuthToken。

列出你的隧道 #

Bash
curl https://localtonet.com/api/v2/tunnels \
  -H "Authorization: Bearer <YOUR_API_KEY>"

响应是一个 JSON 数组,每条隧道对应一个对象。其字段包括 id、title、url(公网地址)、protocolType、authToken、serverId、clientIp 和 clientPort(本地目标)、status 和 connectionStatus。如果你还没有任何隧道,响应是 404,而不是空数组。

用随机子域名创建 HTTP 隧道 #

先获取你要使用的服务器的代码:

Bash
curl https://localtonet.com/api/v2/servers \
  -H "Authorization: Bearer <YOUR_API_KEY>"

每个条目都有 serverCode、serverName 和 serverDomain。然后创建隧道。下面的示例会转发到设备 3000 端口上的 Web 应用:

Bash
curl -X POST https://localtonet.com/api/v2/tunnels/http/random-subdomain \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "authToken": "<YOUR_TOKEN>",
    "serverCode": "<SERVER_CODE>",
    "protocolType": 1,
    "ip": "127.0.0.1",
    "port": 3000
  }'
字段含义取值
authToken运行该隧道的设备的 AuthToken。必填
serverCode服务器,来自 GET /servers。必填
protocolType隧道类型。1 HTTP, 5 File Server, 24 MCP Gateway
ip隧道转发到的本地 IP 地址。有效的 IP 地址,例如 127.0.0.1
port本地端口。1 到 65534
path要共享的本地文件夹。仅文件服务器必填

响应是 201 Created,并附带新建的隧道。请记下它的 id 和 url。

启动隧道 #

Bash
curl -X POST https://localtonet.com/api/v2/tunnels/<TUNNEL_ID>/actions/start \
  -H "Authorization: Bearer <YOUR_API_KEY>"

响应是 204 No Content。设备的客户端连接后,隧道即可通过它的 url 访问。用 /actions/stop 可以再次停止它。

端点分组 #

下面所有路径都相对于 https://localtonet.com/api/v2。

隧道 #

方法路径用途
GET/tunnels列出你的所有隧道。
GET/tunnels/{tunnelId}获取一条隧道。
POST/tunnels/http/random-subdomain用随机子域名创建 HTTP、文件服务器或 MCP 网关隧道。
POST/tunnels/http/custom-subdomain用你选择的子域名创建。
POST/tunnels/http/custom-domain在你自己的域名上创建。
POST/tunnels/tcp-udp创建 TCP、UDP 或 TCP 与 UDP 混合隧道。
POST/tunnels/proxy创建 HTTP、SOCKS5、Shadowsocks 或 VLESS 代理隧道。
POST/tunnels/proxy/with-detail创建代理隧道,并返回完整的连接详情。
POST/tunnels/shared-proxy创建共享(轮换)代理隧道。
POST/tunnels/{tunnelId}/actions/start启动隧道。
POST/tunnels/{tunnelId}/actions/stop停止隧道。
DELETE/tunnels/{tunnelId}永久删除隧道。
PATCH/tunnels/{tunnelId}/title更改标题。
PATCH/tunnels/{tunnelId}/local-ip更改本地 IP 地址。
PATCH/tunnels/{tunnelId}/local-port更改本地端口。
PATCH/tunnels/{tunnelId}/port-reserved开启或关闭 TCP/UDP 隧道的端口保留。
PATCH/tunnels/{tunnelId}/legacy-connect开启或关闭旧版连接模式。
PATCH/tunnels/{tunnelId}/protocol-type更改代理隧道的代理协议。
GET/tunnels/{tunnelId}/request-logsHTTP 或文件服务器隧道最近的 HTTP 请求日志。

批量隧道操作 #

方法路径用途
POST/tunnels/bulk/http/random-subdomain用随机子域名创建多条 HTTP 隧道。
POST/tunnels/bulk/http/custom-subdomain用自定义子域名创建多条。
POST/tunnels/bulk/http/custom-domain在自定义域名上创建多条。
POST/tunnels/bulk/tcp-udp创建多条 TCP/UDP 隧道。
POST/tunnels/bulk/proxy创建多条代理隧道。
POST/tunnels/bulk/proxy/with-detail创建多条代理隧道,并返回它们的连接详情。
POST/tunnels/bulk/shared-proxy创建多条共享(轮换)代理隧道。
POST/tunnels/bulk/actions/start启动多条隧道。请求体:隧道 ID 数组,例如 [123, 456]。
POST/tunnels/bulk/actions/stop停止多条隧道。请求体:隧道 ID 数组。
DELETE/tunnels/bulk删除多条隧道。请求体:隧道 ID 数组。
PATCH/tunnels/bulk/protocol-type更改多条代理隧道的代理协议。

隧道配置 #

这些端点用于更改一条隧道的设置,路径都以 /tunnels/{tunnelId} 开头。各项设置的作用见设置参考。

方法/tunnels/{tunnelId} 之后的路径用途
GET, POST, PATCH, DELETE/ip-restrictions列出、添加、设置允许或拒绝模式,或删除所有 IP 限制。用 /ip-restrictions/{restrictionId} 删除单条。
GET, POST, PATCH, DELETE/access-controlsURL 路径访问控制的同样操作。用 /access-controls/{controlId} 删除单条。
GET, PATCH/headers自定义 HTTP 请求头。
GET, PATCH/authenticationHTTP 基本认证。
GET, PATCH/expiration隧道的到期日期。
GET, PATCH/server-portTCP/UDP 隧道的服务器端端口。
GET, PATCH/http-timeoutHTTP 请求超时。
GET, PATCH/rate-limit速度限制。
GET, PATCH/bandwidth-limit数据传输总量限制。
GET/bandwidth-usage当前带宽用量。用 POST /bandwidth-usage/reset 重置计数器。
GET, PATCH/arguments隧道的自定义命令行参数。
GET, POST/shared-proxy-clients列出或添加共享(轮换)代理隧道的客户端。用 PATCH 或 DELETE /shared-proxy-clients/{clientId} 更新或删除单个客户端。
GET/advanced-settings在一次响应中返回隧道的所有高级设置。
GET, PATCH/ipv4-only, /wifi-split, /proxy-protocol, /pass-through, /https-only, /http3读取或切换一项高级设置。
PATCH/ssl-stream切换 SSL 流设置。
GET, PATCH/file-path, /host-header, /path-rewrite, /upstream-proxy, /note, /vless读取或更改一个值。
GET, PUT/token-groups分配给该隧道的令牌组。
GET, PATCH/server该隧道所在的服务器。

AuthToken #

方法路径用途
GET/auth-tokens列出你的 AuthToken。
GET/auth-tokens/detail列出你的 AuthToken 及其详情。
GET/auth-tokens/{token}一个 AuthToken 的详情。
POST/auth-tokens创建 AuthToken。
DELETE/auth-tokens/{token}删除 AuthToken。
GET/auth-tokens/{token}/tunnels某个 AuthToken 的隧道。
GET/auth-tokens/{token}/ip-history设备的公网 IP 地址更换历史。
GET, PATCH/auth-tokens/{token}/airplane-mode-settings飞行模式自动化设置。
POST/auth-tokens/{token}/change-ip-links/{airplaneModeSettingId}添加更换 IP 链接。
DELETE/auth-tokens/{token}/change-ip-links/{id}删除更换 IP 链接。
POST/auth-tokens/{token}/restart-device-links/{airplaneModeSettingId}添加重启设备链接。
DELETE/auth-tokens/{token}/restart-device-links/{id}删除重启设备链接。
GET, PATCH/auth-tokens/{token}/arguments保存在该 AuthToken 上的客户端参数。

令牌组 #

方法路径用途
GET/token-groups列出你的令牌组。
GET/token-groups/{id}获取一个令牌组。
POST/token-groups创建令牌组。
DELETE/token-groups/{id}删除令牌组。
POST/token-groups/{id}/auth-tokens把 AuthToken 添加到组中。
DELETE/token-groups/{id}/auth-tokens/{tokenId}把 AuthToken 从组中移除。

服务器 #

方法路径用途
GET/servers列出你可以在其上创建隧道的服务器,以及创建请求中要使用的 serverCode。

SSO 提供商 #

方法路径用途
GET/sso-providers列出你的 SSO 提供商。
GET/sso-providers/default-endpoints某种 SSO 提供商类型的默认端点。
POST/sso-providers创建或更新 SSO 提供商。
DELETE/sso-providers/{id}删除 SSO 提供商。
GET/sso-providers/tunnel/{tunnelId}为一条隧道配置的 SSO 提供商。这里的 tunnelId 是隧道的 GUID(guidId)。
PUT/sso-providers/tunnel/{tunnelId}保存一条隧道的 SSO 提供商。

提供商的作用见单点登录。

VPN 访问 #

VPN 访问会在代理隧道上提供 WireGuard 或 OpenVPN 设备配置文件;该设备的全部流量都通过代理发出。这些端点以 /tunnels/{tunnelId}/vpn-access 开头。

方法/tunnels/{tunnelId}/vpn-access 之后的路径用途
GET(无)列出该隧道的 VPN 设备。
POST(无)创建 VPN 设备。
DELETE/{peerId}删除(吊销)VPN 设备。
POST/{peerId}/regenerate重新生成 VPN 设备的密钥。
GET/{peerId}/config下载 VPN 设备的配置文件。
GET/{peerId}/qrWireGuard 设备配置的二维码。
GET/{peerId}/credentialsOpenVPN 设备的用户名和密码。

故障排查 #

每个请求都返回 401

请检查请求头:必须是 Authorization: Bearer,后面跟一个空格和密钥,密钥两边不要加引号。如果你在 API 密钥卡片中选择过更换,旧密钥就不再有效,请复制新密钥。

我看不到团队的 AuthToken

你使用的是自己账户的 API 密钥。请切换到团队控制台,并在那里复制 API 密钥。

隧道已创建,但它的地址没有响应

新建的隧道处于停止状态。请调用 POST /tunnels/{tunnelId}/actions/start,并确认设备上的 Localtonet 客户端正在使用你所用的 AuthToken 运行。

我收到 429 Too Many Requests

请求有速率限制。请等待后重新发送请求,并用一次批量请求代替单个调用的循环。

支持