命令行参考
本页内容 14 个章节
localtonet 控制台客户端的全部选项:用令牌登录、作为服务运行、无提示运行、选择网络或出站代理,以及设备终端命令。
开始之前 #
本页介绍适用于 Windows、macOS 和 Linux 的控制台客户端,包括 Docker 镜像和 Linux 软件包中的客户端。请从安装概览安装它。隧道不在命令行中创建:你可以在控制台中、通过 API 或 MCP 服务器创建、启动和停止隧道。客户端负责把设备连接到你的账户并承载流量。
语法 #
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>之类的占位符代表你自己的值。输入时不要带尖括号。
不带任何选项时,客户端以交互方式启动:使用已保存的令牌或要求你输入令牌,然后连接并显示实时状态表。
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 #
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 #
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 #
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 #
localtonet --headless --authtoken-file <PATH>从文件而不是命令行读取令牌,这样它不会出现在进程列表或 shell 历史记录中。请保护好该文件,例如使用 chmod 600。此选项仅在无头模式下读取。
--check-config #
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 #
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 #
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://。 |
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 #
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 和 WebSocket | http_proxy, HTTP_PROXY, all_proxy, ALL_PROXY |
| HTTPS 和安全 WebSocket | https_proxy, HTTPS_PROXY, all_proxy, ALL_PROXY |
| 原始 TCP 和 UDP | all_proxy, ALL_PROXY, https_proxy, HTTPS_PROXY, http_proxy, HTTP_PROXY |
no_proxy(如果未设置小写形式,则为 NO_PROXY)列出直接访问的主机:
- 各条目用逗号分隔。主机或域名匹配其自身及其子域名。匹配时忽略大小写和开头的点。
- IP 地址按完全相同匹配;IPv6 地址可以放在方括号中。
*会让所有主机都绕过代理。 - 不支持地址范围(CIDR)、带端口的条目和部分通配符,它们会被报告为配置错误。
- 当你传入代理 URL 或直接连接时,
no_proxy不起作用。
--http-transport #
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 #
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 #
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 #
localtonet --terminal enable --authtoken <YOUR_TOKEN> --terminal-user <ACCOUNT> --pairing-key <PAIRING_KEY>用于配对无人能读取批准码的设备,例如用脚本配置的服务器。请在我的设备中的添加设备下,用创建一次性密钥来创建密钥。它有效期为一小时,且只能使用一次。使用配对密钥时,命令不会输出代码,也不会等待批准。
localtonet ssh #
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 #
localtonet --debug --proxy env --authtoken <YOUR_TOKEN>在标准错误上开启连接诊断:正在使用的代理路由及其所属设置、DNS 模式、握手结果和 UDP 状态。凭据和请求正文不包含在内。--debug 还会让客户端切换到无头模式,因此不会提示。它是一个标志,不带值。
--version #
localtonet --version输出客户端版本,例如 v8.6,然后退出。
--help #
localtonet --help输出内置帮助并退出。-h 的作用相同。
环境变量 #
| 变量 | 效果 |
|---|---|
LOCALTONET_HEADLESS | 1 开启无头模式。 |
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>sudo localtonet --install-service --authtoken <YOUR_TOKEN>
sudo localtonet --status-service --authtoken <YOUR_TOKEN>docker run -d --restart unless-stopped -e LOCALTONET_AUTH_TOKEN=<YOUR_TOKEN> localtonet/localtonetlocaltonet --network
localtonet --authtoken <YOUR_TOKEN> --net Mobile --ip 10.20.30.40export all_proxy=http://proxy.example.com:3128
localtonet --authtoken <YOUR_TOKEN> --proxy env