跳到内容
Localtonet Localtonet 控制台

命令行参考

获取本页帮助
本页内容 14 个章节
  1. 开始之前
  2. 语法
  3. 快速概览
  4. 身份验证
  5. --authtoken
  6. --ephemeral-token
  7. 服务管理
  8. 无头模式
  9. --headless
  10. --authtoken-file
  11. --check-config
  12. 无头日志
  13. 网络选择
  14. --network
  15. --net 和 --ip
  16. 出站代理
  17. --proxy
  18. --proxy-user
  19. 代理环境变量
  20. --http-transport
  21. 设备终端
  22. --terminal
  23. --terminal-user
  24. --pairing-key
  25. localtonet ssh
  26. 诊断与信息
  27. --debug
  28. --version
  29. --help
  30. 环境变量
  31. 退出码
  32. 示例
  33. 相关页面

localtonet 控制台客户端的全部选项:用令牌登录、作为服务运行、无提示运行、选择网络或出站代理,以及设备终端命令。

开始之前 #

本页介绍适用于 Windows、macOS 和 Linux 的控制台客户端,包括 Docker 镜像和 Linux 软件包中的客户端。请从安装概览安装它。隧道不在命令行中创建:你可以在控制台中、通过 API 或 MCP 服务器创建、启动和停止隧道。客户端负责把设备连接到你的账户并承载流量。

语法 #

Bash
localtonet [options]
localtonet ssh <DEVICE> [--key <KEY>] [--stdio] [-- <COMMAND>]
  • 选项可以按任意顺序给出。选项名称不区分大小写,localtonet ssh 的选项除外。
  • 值写在选项之后,用空格或等号分隔:--authtoken <YOUR_TOKEN> 与 --authtoken=<YOUR_TOKEN> 等价。
  • 需要值的选项在缺少值时会失败,并提示 <option> requires a value.
  • --proxy、--proxy-user 和 --http-transport 只能给出一次。
  • <YOUR_TOKEN> 之类的占位符代表你自己的值。输入时不要带尖括号。

不带任何选项时,客户端以交互方式启动:使用已保存的令牌或要求你输入令牌,然后连接并显示实时状态表。

Bash
localtonet

快速概览 #

选项用途
--authtoken <TOKEN>用 AuthToken 登录。
--ephemeral-token不在此设备上保存令牌。
--install-service, --start-service, --stop-service, --status-service, --remove-service管理后台服务。
--headless无提示运行,并输出纯文本日志行。
--authtoken-file <PATH>从文件读取令牌(无头模式)。
--check-config检查令牌来源后退出(无头模式)。
--network列出设备的网络接口。
--net <NAME> --ip <ADDRESS>让客户端的所有流量都经由同一个网络接口。
--proxy <none|env|URL>, --proxy-user <USER>通过出站代理连接到 Localtonet。
--http-transport <auto|https|raw>选择服务器连接经代理承载的方式。
--terminal <enable|disable|status>, --terminal-user <ACCOUNT>, --pairing-key <KEY>为此设备开启或关闭设备终端。
ssh <DEVICE>在你的某台设备上打开 shell 或运行命令。
--debug输出连接诊断信息。
--version输出版本号。
--help, -h输出内置帮助。

身份验证 #

--authtoken #

Bash
localtonet --authtoken <YOUR_TOKEN>

用来自我的令牌的 AuthToken 让设备登录。令牌长 33 个字符。客户端会把它保存在当前用户的配置文件中,因此下次直接运行 localtonet 即可。

  • 如果没有 --authtoken 也没有已保存的令牌,客户端会询问 Please Enter AuthToken or PIN。你可以输入令牌,也可以输入控制台为某个令牌显示的六位 PIN。
  • 输入的值不是有效令牌时,客户端会回应 Wrong Token!,并再次询问。
  • 客户端运行期间,按 F12 会删除已保存的令牌并退出。按 Ctrl + C 会退出并保留令牌。
  • 不带短横线的旧写法 authtoken <YOUR_TOKEN> 仍然可用。

请保管好你的令牌。它允许 Localtonet 客户端以此设备的身份连接。每台设备使用一个令牌:用同一令牌连接的第二个客户端会把第一个断开。

--ephemeral-token #

Bash
localtonet --authtoken <YOUR_TOKEN> --ephemeral-token

令牌仅用于本次运行。客户端不会把令牌写入已保存的设置,也不会更改已保存的令牌。适用于自动化和临时会话。

服务管理 #

这些选项会把客户端注册到 Windows 服务、macOS 的 launchd 或 Linux 的 systemd。它们需要管理员权限(macOS 和 Linux 上用 sudo),并且每个选项都需要令牌,因为服务是以令牌命名的。完整指南见作为服务运行。

选项作用示例
--install-service把客户端安装为开机启动的服务并启动它。命令行上的其他选项会存入该服务。localtonet --install-service --authtoken <YOUR_TOKEN>
--start-service启动已安装的服务。localtonet --start-service --authtoken <YOUR_TOKEN>
--stop-service停止服务。localtonet --stop-service --authtoken <YOUR_TOKEN>
--status-service输出服务的状态,例如 Running、Stopped 或 NotFound。localtonet --status-service --authtoken <YOUR_TOKEN>
--remove-service停止服务并将其删除。localtonet --remove-service --authtoken <YOUR_TOKEN>

服务选项在无头模式下不使用。

无头模式 #

无头模式适用于容器、init 系统和脚本。客户端从不提问,不响应按键,不保存令牌,并且每次变化只写一行纯文本日志,而不是状态表。Docker 镜像以及 Linux 和 OpenWrt 软件包都以这种方式运行客户端。

--headless #

Bash
localtonet --headless --authtoken-file /etc/localtonet/auth-token

以无头模式启动客户端。设置环境变量 LOCALTONET_HEADLESS=1 效果相同。收到终止信号时,客户端会正常停止。

令牌来自以下来源之一:

来源说明
--authtoken-file <PATH>只包含令牌的文件。令牌前后的空格和换行会被忽略。
LOCALTONET_AUTH_TOKEN_FILE保存此类文件路径的环境变量。未给出 --authtoken-file 时使用。
--authtoken <TOKEN>直接写在命令行上的令牌。
LOCALTONET_AUTH_TOKEN保存令牌的环境变量。未给出 --authtoken 时使用。

令牌文件始终优先于直接传入的令牌。如果指定了令牌文件但无法读取,客户端会停止,不会回退到其他来源。

找不到可用令牌时,客户端会输出 Invalid Localtonet headless configuration. Check the token file or environment settings. 并以退出码 2 退出。可用的令牌长 33 个字符,且不含空格。

--authtoken-file #

Bash
localtonet --headless --authtoken-file <PATH>

从文件而不是命令行读取令牌,这样它不会出现在进程列表或 shell 历史记录中。请保护好该文件,例如使用 chmod 600。此选项仅在无头模式下读取。

--check-config #

Bash
localtonet --headless --authtoken-file /etc/localtonet/auth-token --check-config

检查令牌来源并退出,不进行连接。找到格式正确的令牌时,它会输出 Localtonet headless configuration OK. 并以退出码 0 退出,否则输出上面的错误并以退出码 2 退出。检查仅在本地进行:它不会告诉你 Localtonet 是否接受该令牌。请始终与 --headless(或 LOCALTONET_HEADLESS=1)一起使用;单独使用时会被忽略。

无头日志 #

行含义
Localtonet - headless log客户端已启动。
Connection: …连接状态发生了变化。
AuthTokenName: …设备登录所用令牌的名称。
OPEN …, ADDED …启动时已存在的隧道,或之后新增的隧道。
STATUS …某个隧道的状态发生了变化。
CLOSED …某个隧道已从此客户端移除。
Authentication failed: AuthToken was rejected.Localtonet 没有接受该令牌。

除第一行之外,每一行都以时间戳开头。令牌绝不会写入日志。

网络选择 #

在拥有多个互联网连接的设备上(例如以太网和移动调制解调器),你可以选择客户端使用哪一个。网络选择页面介绍了该功能以及每个隧道的设置。

--network #

Bash
localtonet --network

列出每个活动的网络接口及其地址,检查每个 IPv4 地址能否访问互联网,然后退出。每一行都已写成你可以直接传入的选项:

输出
NetworkName: Ethernet
--net Ethernet --ip 192.168.1.20   --> Internet available (public IP 203.0.113.10)
--------------------------------------------------
NetworkName: Mobile
--net Mobile --ip 10.20.30.40   --> No internet access
--------------------------------------------------

IPv6 地址会以 IPv6, internet check not available 列出。

--net 和 --ip #

Bash
localtonet --authtoken <YOUR_TOKEN> --net Ethernet --ip 192.168.1.20

把整个客户端固定到一个网络接口。--net 是接口名称,--ip 是该接口的一个地址,与 --network 输出的完全一致。两者必须同时给出。含空格的接口名称可以直接写,也可以加引号。

  • 如果无法应用这一对参数,客户端最多会等待 30 秒让接口就绪(开机启动时这很有帮助),然后停止,并给出原因和退出码 2。它不会继续使用其他网络。
  • 如果只给出两个选项中的一个,客户端会输出 --net and --ip must be given together; the default network is used. 并在不固定网络的情况下继续运行。
  • 在 Linux 上,客户端会为固定的地址添加路由规则。这需要 root 权限,或者对 ip 命令免密码使用 sudo。
消息含义
Network interface '…' was not found. Run 'localtonet --network' to list the interfaces.--net 之后的名称与任何接口都不匹配。
Network interface '…' is Down.该接口存在,但未启用。
'…' is not an address of network interface '…'.--ip 之后的地址不属于该接口。
'…' is not an IP address.--ip 之后的值不是 IP 地址。

如果只想为单个隧道而不是整个客户端使用不同的连接,请在该隧道的参数设置中设置同样的一对参数。

出站代理 #

当设备只能通过代理访问互联网时,请使用这些选项。它们作用于客户端到 Localtonet 的自身连接,不会改变客户端访问你本地服务的方式。

--proxy #

值作用
未给出,或 none直接连接。代理环境变量会被忽略。
env使用下面介绍的代理环境变量。如果一个都没有设置,或其中一个无效,客户端会报错并停止,而不是直接连接。
代理 URL所有连接都使用该代理。支持的协议方案:http://、https://、socks5:// 和 socks5h://。
Bash
localtonet --authtoken <YOUR_TOKEN> --proxy http://proxy.example.com:3128
localtonet --authtoken <YOUR_TOKEN> --proxy socks5h://proxy.example.com:1080
localtonet --authtoken <YOUR_TOKEN> --proxy env
协议方案行为默认端口身份验证
http://HTTP 代理,使用 CONNECT。80无或 Basic
https://先与代理建立经过验证的 TLS 连接,然后使用 CONNECT。443无或 Basic
socks5://SOCKS5,TCP 和 UDP。主机名在你的设备上解析。1080无,或用户名和密码
socks5h://SOCKS5,TCP 和 UDP。主机名由代理解析。1080无,或用户名和密码

代理主机可以是 IPv4 地址、主机名,或放在方括号中的 IPv6 地址。凭据可以作为 user:password@host:port 写在 URL 中,其中的特殊字符需要做 URL 编码。调试输出从不包含凭据。

--proxy-user #

Bash
localtonet --authtoken <YOUR_TOKEN> --proxy socks5h://proxy.example.com:1080 --proxy-user <PROXY_USER>

设置代理用户名,并通过隐藏输入的提示(Proxy password:)询问密码,这样密码就不会出现在命令行上。密码不会被保存。

  • 它需要 --proxy env 或代理 URL,并且不能与 URL 中的凭据同时使用。
  • 它只能在交互式终端中使用。无头模式和服务从不提示:请把凭据放进代理 URL,或者使用 --proxy env 并提供包含凭据的代理 URL。
  • --install-service 会拒绝 --proxy-user 和带密码的代理 URL,因为服务无法保存它们。请使用 --proxy env 安装服务,并在服务的环境中提供这些变量。

代理环境变量 #

只有使用 --proxy env 时才会读取这些变量。对于每一种连接,使用第一个已设置的变量:

连接变量(按顺序)
HTTP 和 WebSockethttp_proxy, HTTP_PROXY, all_proxy, ALL_PROXY
HTTPS 和安全 WebSockethttps_proxy, HTTPS_PROXY, all_proxy, ALL_PROXY
原始 TCP 和 UDPall_proxy, ALL_PROXY, https_proxy, HTTPS_PROXY, http_proxy, HTTP_PROXY

no_proxy(如果未设置小写形式,则为 NO_PROXY)列出直接访问的主机:

  • 各条目用逗号分隔。主机或域名匹配其自身及其子域名。匹配时忽略大小写和开头的点。
  • IP 地址按完全相同匹配;IPv6 地址可以放在方括号中。* 会让所有主机都绕过代理。
  • 不支持地址范围(CIDR)、带端口的条目和部分通配符,它们会被报告为配置错误。
  • 当你传入代理 URL 或直接连接时,no_proxy 不起作用。

--http-transport #

Bash
localtonet --authtoken <YOUR_TOKEN> --proxy http://proxy.example.com:3128 --http-transport https

控制当代理只放行普通网页流量时,客户端如何承载其服务器连接。使用 HTTPS 传输时,客户端会把这些流量作为普通 HTTPS 请求发送到 Localtonet 网关,而不是通过代理打开长时间存在的原始连接。

值作用
auto(默认)在 HTTP 或 HTTPS 代理之后,如果服务器提供 HTTPS 传输,客户端会优先使用,否则使用 CONNECT。在 SOCKS5 代理之后,它先使用原生 TCP 和 UDP,并可以回退到经由同一代理的 HTTPS 传输。
https服务器连接必须使用 HTTPS 传输。
raw从不使用 HTTPS 传输:只使用 CONNECT 或 SOCKS。

其他任何值都会让客户端停止,并提示 LOCALTONET_HTTP_TRANSPORT_MODE must be auto, https or raw.

设备终端 #

设备终端让你可以从控制台或通过 SSH 在自己的设备上使用 shell。它可在 Windows、Linux 和 macOS 上运行,需要 Localtonet Desktop v8.6 或更高版本。设备终端页面介绍了该功能,下面是它的命令行部分。

--terminal #

Bash
localtonet --terminal enable --authtoken <YOUR_TOKEN>
localtonet --terminal status --authtoken <YOUR_TOKEN>
localtonet --terminal disable --authtoken <YOUR_TOKEN>
值作用
enable把此设备与你的账户配对。命令会输出一个批准码并等待;打开我的设备,选择添加设备并输入该代码。代码有效期为 15 分钟。批准后,命令会输出 Terminal enabled. Shells will run as <account>.
disable在此设备上关闭终端,并把设备从你的账户中移除。如果无法连接到控制台,终端仍会在本地关闭,并且命令会提示你同时在控制台中移除该设备。
status输出终端是否已启用,以及 shell 以哪个账户运行。

这三种形式都需要令牌,与正常启动一样:传入 --authtoken,或者省略它以使用已保存的令牌。如果 Localtonet 在该设备上作为服务运行,请从管理员终端运行命令,或使用 sudo。在交互式终端中,enable 之后客户端会继续作为普通客户端运行,除非该设备上已经有使用此令牌的 Localtonet 在运行。

--terminal-user #

Bash
sudo localtonet --terminal enable --authtoken <YOUR_TOKEN> --terminal-user <ACCOUNT>

当你以 root 或管理员身份启用终端时,用它选择 shell 以哪个账户运行。如果没有它,提权后的 enable 会询问 Run shells as user:;在无法提问的脚本中,它会停止并提示 Choose the account for shells with --terminal-user. 没有 --terminal-user 时,未提权的命令使用当前用户。

--pairing-key #

Bash
localtonet --terminal enable --authtoken <YOUR_TOKEN> --terminal-user <ACCOUNT> --pairing-key <PAIRING_KEY>

用于配对无人能读取批准码的设备,例如用脚本配置的服务器。请在我的设备中的添加设备下,用创建一次性密钥来创建密钥。它有效期为一小时,且只能使用一次。使用配对密钥时,命令不会输出代码,也不会等待批准。

localtonet ssh #

Bash
localtonet ssh <DEVICE>
localtonet ssh <DEVICE> -- uptime
localtonet ssh <DEVICE> --key <ACCESS_KEY> -- uptime

在你的某台设备上打开 shell,或在其上运行一条命令并返回其退出码。<DEVICE> 是我的设备中显示的设备名称。ssh 必须是 localtonet 之后的第一个词。

部分作用
-- <COMMAND>运行该命令,而不是打开 shell。-- 之后的所有内容都是命令。
--key <ACCESS_KEY>设备的访问密钥,在我的设备的密钥下创建。使用密钥时,无需在浏览器中批准。
--stdio不打开 shell。它只通过标准输入和输出把原始连接传到设备,用作 SSH 客户端的 ProxyCommand。

没有密钥时,命令会输出 Approve this connection in your browser: 和一个链接,并最多等待五分钟让你批准。如果连接未获批准,它会以 The connection was not approved. 结束。

诊断与信息 #

--debug #

Bash
localtonet --debug --proxy env --authtoken <YOUR_TOKEN>

在标准错误上开启连接诊断:正在使用的代理路由及其所属设置、DNS 模式、握手结果和 UDP 状态。凭据和请求正文不包含在内。--debug 还会让客户端切换到无头模式,因此不会提示。它是一个标志,不带值。

--version #

Bash
localtonet --version

输出客户端版本,例如 v8.6,然后退出。

--help #

Bash
localtonet --help

输出内置帮助并退出。-h 的作用相同。

环境变量 #

变量效果
LOCALTONET_HEADLESS1 开启无头模式。
LOCALTONET_AUTH_TOKEN令牌,用于无头模式。
LOCALTONET_AUTH_TOKEN_FILE令牌文件的路径,用于无头模式。
http_proxy、https_proxy、all_proxy、no_proxy 及其大写形式代理设置,仅在使用 --proxy env 时有效。

退出码 #

代码含义
0命令正常完成。
1设备终端命令失败,例如批准码已过期或无法连接到设备。
2选项错误或缺少值、无头模式的令牌不可用,或 --net 与 --ip 这一对参数无法应用。

localtonet ssh <DEVICE> -- <COMMAND> 返回远程命令的退出码。

示例 #

在桌面上首次启动
localtonet --authtoken <YOUR_TOKEN>
Linux 上的后台服务
sudo localtonet --install-service --authtoken <YOUR_TOKEN>
sudo localtonet --status-service --authtoken <YOUR_TOKEN>
Docker,令牌来自环境变量
docker run -d --restart unless-stopped -e LOCALTONET_AUTH_TOKEN=<YOUR_TOKEN> localtonet/localtonet
所有流量都使用移动调制解调器
localtonet --network
localtonet --authtoken <YOUR_TOKEN> --net Mobile --ip 10.20.30.40
位于企业代理之后
export all_proxy=http://proxy.example.com:3128
localtonet --authtoken <YOUR_TOKEN> --proxy env
支持