Localtonet REST API
本页内容 8 个章节
REST API v2 可以完成控制台对隧道所做的事情:创建、启动、停止、删除和配置隧道,以及管理 AuthToken、令牌组和 SSO 提供商。每个请求都用你的 API 密钥进行认证。
交互式参考 #
每个端点及其请求和响应模型,以及可用来试用的表单,都在交互式参考中:
- localtonet.com/api:API v2,当前版本。你也可以通过控制台上的 API 界面按钮进入。
- localtonet.com/api/v1:API v1,为现有集成保留。新的开发请使用 v2。
本页介绍通用约定和各端点分组的概览。请求的确切字段,请在参考中打开对应的端点查看。
开始之前 #
- 你的 API 密钥。打开控制台,在 API 密钥卡片中使用复制。请参阅账户与安全。
- 创建隧道时:需要运行该隧道的设备的 AuthToken,以及用该令牌连接的 Localtonet 客户端。请参阅 AuthToken。
请妥善保管你的 API 密钥。任何拥有它的人都可以创建、更改和删除你的隧道和令牌。API 密钥卡片中的更换会创建新密钥,并使旧密钥失效。
基础 URL 与认证 #
所有 v2 端点都以下面的地址开头:
https://localtonet.com/api/v2在每个请求的 Authorization 请求头中,以 Bearer 令牌的形式发送 API 密钥:
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 下。 |
401 | API 密钥缺失或无效。 | 没有具体消息 |
403, 409 | 当更改不被允许,或与当前配置冲突时,部分隧道配置和 VPN 访问端点会返回此状态。 | 问题对象,消息在 title 中。 |
404 | 未找到该隧道或对象,或它不属于你。 | 空,或问题对象 |
429 | 请求过多。 | 见下面的速率限制。 |
速率限制 #
请求有速率限制。超出限制的请求会收到 429 Too Many Requests。请等待后重新发送;请使用批量端点,而不要进行大量单个调用。
示例 #
请把 <YOUR_API_KEY> 替换为你的 API 密钥,把 <YOUR_TOKEN> 替换为设备的 AuthToken。
列出你的隧道 #
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 隧道 #
先获取你要使用的服务器的代码:
curl https://localtonet.com/api/v2/servers \
-H "Authorization: Bearer <YOUR_API_KEY>"每个条目都有 serverCode、serverName 和 serverDomain。然后创建隧道。下面的示例会转发到设备 3000 端口上的 Web 应用:
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。
启动隧道 #
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-logs | HTTP 或文件服务器隧道最近的 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-controls | URL 路径访问控制的同样操作。用 /access-controls/{controlId} 删除单条。 |
| GET, PATCH | /headers | 自定义 HTTP 请求头。 |
| GET, PATCH | /authentication | HTTP 基本认证。 |
| GET, PATCH | /expiration | 隧道的到期日期。 |
| GET, PATCH | /server-port | TCP/UDP 隧道的服务器端端口。 |
| GET, PATCH | /http-timeout | HTTP 请求超时。 |
| 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}/qr | WireGuard 设备配置的二维码。 |
| GET | /{peerId}/credentials | OpenVPN 设备的用户名和密码。 |
故障排查 #
每个请求都返回 401
请检查请求头:必须是 Authorization: Bearer,后面跟一个空格和密钥,密钥两边不要加引号。如果你在 API 密钥卡片中选择过更换,旧密钥就不再有效,请复制新密钥。
我看不到团队的 AuthToken
你使用的是自己账户的 API 密钥。请切换到团队控制台,并在那里复制 API 密钥。
隧道已创建,但它的地址没有响应
新建的隧道处于停止状态。请调用 POST /tunnels/{tunnelId}/actions/start,并确认设备上的 Localtonet 客户端正在使用你所用的 AuthToken 运行。
我收到 429 Too Many Requests
请求有速率限制。请等待后重新发送请求,并用一次批量请求代替单个调用的循环。