在 Docker 中运行 Localtonet
本页内容 12 个章节
官方镜像 localtonet/localtonet 会在容器中运行 Localtonet 客户端。传入你的 AuthToken,然后像往常一样在控制台中创建并启动隧道。
开始之前 #
- 64 位主机上的 Docker。镜像发布了
linux/amd64和linux/arm64两个版本,Docker 会选择与你的主机匹配的那个。32 位 ARM 设备请改用 Linux 版本。 - 来自我的令牌的 AuthToken。请为每个容器使用各自的令牌:当第二个客户端用同一个令牌连接时,第一个会被断开。
步骤 #
-
拉取镜像 #
先拉取镜像,可以确保你运行的是当前版本,而不是主机上仍然存在的旧镜像。
Bashdocker pull localtonet/localtonet镜像位于 Docker Hub。除了
latest,如果你想固定某个版本,Docker Hub 上还列有每个版本对应的标签。 -
用你的令牌启动容器 #
镜像名称之后的所有内容都会传给 Localtonet 客户端。请把
<YOUR_TOKEN>替换为你的 AuthToken。Bashdocker run localtonet/localtonet --authtoken <YOUR_TOKEN>容器会输出它的连接状态,并停留在前台。按 Ctrl + C 可以停止它。
-
创建并启动隧道 #
打开控制台,用你交给容器的那个令牌创建隧道,然后选择启动。快速开始中有对应的表单。在填写本地 IP 地址之前,请先阅读从容器访问你的服务,因为
127.0.0.1在容器内的含义不同。
容器如何运行 #
镜像以无界面模式启动客户端。与桌面上的客户端相比,这会带来三点变化:
- 它从不提问。如果令牌缺失或格式不正确,容器会输出错误并以退出码 2 退出。
- 它输出的是普通日志行,而不是实时状态表,即使你用
-it启动也是如此。 - 它不会保存令牌。镜像没有声明任何卷,所以每次创建容器时都要传入令牌:通过命令行、环境变量或文件。
隧道不在容器中配置。你在控制台中创建、启动和停止隧道,容器会通过它的连接获取这些隧道。
在后台运行并自动重启 #
使用 -d 让容器在后台运行,并设置重启策略,使 Docker 在重启或崩溃后再次启动容器:
docker run -d \
--name localtonet \
--restart unless-stopped \
localtonet/localtonet --authtoken <YOUR_TOKEN>使用常用的 Docker 命令来管理它:
| 命令 | 作用 |
|---|---|
docker ps | 列出正在运行的容器。 |
docker logs -f localtonet | 持续查看客户端的日志。 |
docker stop localtonet | 停止客户端。它的隧道会离线。 |
docker start localtonet | 用同一个令牌再次启动它。 |
docker rm -f localtonet | 删除容器。 |
传入令牌的方式 #
命令行中的令牌可以在 docker inspect 和主机的进程列表中看到。镜像也可以从环境变量或文件中读取令牌:
| 来源 | 使用方法 | 说明 |
|---|---|---|
--authtoken <YOUR_TOKEN> | 镜像名称之后的参数。 | 最简单。优先于 LOCALTONET_AUTH_TOKEN。 |
LOCALTONET_AUTH_TOKEN | 保存令牌的环境变量。 | 在没有给出 --authtoken 参数时使用。 |
LOCALTONET_AUTH_TOKEN_FILE | 保存文件路径(容器内路径)的环境变量,该文件只包含令牌。 | 令牌文件始终优先于直接传入的令牌。参数 --authtoken-file <PATH> 的作用相同。 |
镜像本身会设置 LOCALTONET_HEADLESS=1,你不需要再设置它。
使用令牌文件时,令牌不会出现在容器定义中,并以只读方式挂载它:
printf '%s' '<YOUR_TOKEN>' > auth-token
chmod 600 auth-token
docker run -d \
--name localtonet \
--restart unless-stopped \
-e LOCALTONET_AUTH_TOKEN_FILE=/run/secrets/localtonet_auth_token \
-v "$(pwd)/auth-token:/run/secrets/localtonet_auth_token:ro" \
localtonet/localtonet请在启动容器之前创建令牌文件。如果该文件不存在,Docker 会创建一个同名目录,客户端就无法从中读取令牌。
如果想在不连接的情况下检查令牌来源,请加上 --check-config。客户端会检查令牌是否存在且格式正确(33 个字符,无空格),输出 Localtonet headless configuration OK. 然后退出。它不会向服务器查询令牌是否有效。
docker run --rm \
-e LOCALTONET_AUTH_TOKEN_FILE=/run/secrets/localtonet_auth_token \
-v "$(pwd)/auth-token:/run/secrets/localtonet_auth_token:ro" \
localtonet/localtonet --check-configDocker Compose #
同样的配置写成 Compose 文件。把令牌放在与 compose.yaml 同目录、名为 auth-token 的文件中:
services:
localtonet:
image: localtonet/localtonet
restart: unless-stopped
environment:
LOCALTONET_AUTH_TOKEN_FILE: /run/secrets/localtonet_auth_token
volumes:
- ./auth-token:/run/secrets/localtonet_auth_token:rodocker compose up -d
docker compose logs -f localtonet当你要发布的服务位于同一个 Compose 项目中、且主机是 Linux 时,请在主机上发布它的端口,并让 Localtonet 容器使用主机网络。隧道的本地地址必须是 IP 地址,因此不能使用 web 这样的 Compose 服务名:
services:
web:
image: nginx
ports:
- "8080:80"
localtonet:
image: localtonet/localtonet
restart: unless-stopped
network_mode: host
environment:
LOCALTONET_AUTH_TOKEN_FILE: /run/secrets/localtonet_auth_token
volumes:
- ./auth-token:/run/secrets/localtonet_auth_token:ro对于这个示例,请把隧道的本地地址设为 127.0.0.1,本地端口设为 8080。
如果是 NAS 或 Home Assistant,现成的模板在 NAS 和 Home Assistant 页面。
从容器访问你的服务 #
隧道的本地 IP 地址和本地端口告诉客户端你的服务在哪里。客户端是从容器内部发起连接的,在容器内 127.0.0.1 指的是容器本身,而不是你的机器。请输入 IP 地址:客户端不会解析 host.docker.internal 这样的 Docker 名称、Compose 服务名或容器名。请使用与服务所在位置对应的值:
| 服务运行的位置 | 要输入的本地地址 | 还需要什么 |
|---|---|---|
| 在 Docker 主机上,Linux | 127.0.0.1 | 用 --network host 启动容器(Compose:network_mode: host)。这样容器就共享主机的网络。 |
| 在 Docker 主机上,不使用主机网络(包括 Windows 或 macOS 上的 Docker Desktop) | 主机的局域网 IP 地址,例如 192.168.1.10 | 服务必须监听容器可以访问的地址,而不能只监听 127.0.0.1,并且主机的防火墙必须允许该连接。 |
| 在另一个容器中 | 在 Linux 上使用 --network host 时填 127.0.0.1,否则填主机的局域网 IP 地址 | 在主机上发布该容器的端口(-p,Compose:ports),并把发布的端口用作隧道的本地端口。 |
| 在你网络中的另一台设备上 | 该设备的局域网 IP 地址,例如 192.168.1.20 | 无。 |
docker run -d \
--name localtonet \
--restart unless-stopped \
--network host \
localtonet/localtonet --authtoken <YOUR_TOKEN>你可以在现有隧道的设置中,通过本地地址更改它的地址。请参阅设置参考。
查看日志 #
docker logs -f localtonet 每发生一次变化就显示一行。第一行之后的每一行都以时间戳开头:
| 行 | 含义 |
|---|---|
Localtonet - headless log | 客户端已启动。 |
Connection: … | 与 Localtonet 的连接状态。状态变化时会出现新的一行。 |
AuthTokenName: … | 容器登录所用令牌的名称,与“我的令牌”中显示的一致。 |
OPEN …, ADDED … | 此令牌的一条隧道。OPEN 用于客户端启动时已存在的隧道,ADDED 用于之后出现的隧道。 |
STATUS … | 隧道的状态发生了变化。 |
CLOSED … | 一条隧道已从此客户端移除。 |
Authentication failed: AuthToken was rejected. | Localtonet 未接受该令牌。 |
令牌本身绝不会写入日志。
更新 #
再次拉取镜像并重新创建容器:
docker pull localtonet/localtonet
docker rm -f localtonet
docker run -d --name localtonet --restart unless-stopped localtonet/localtonet --authtoken <YOUR_TOKEN>使用 Compose 时,先运行 docker compose pull,再运行 docker compose up -d。如果想始终从最新镜像启动,请在 docker run 中加上 --pull always。
适用于无法访问镜像仓库的主机的镜像归档 #
如果主机无法访问 Docker Hub,请在另一台机器上把镜像下载为 TAR 归档,复制过去后再加载:
| 架构 | 归档 |
|---|---|
| AMD64 | localtonet-docker-amd64.tar |
| ARM64 | localtonet-docker-arm64.tar |
docker load --input localtonet-docker-amd64.tardocker load 会输出它加载了什么。如果输出的是镜像 ID 而不是名称,请在运行之前为镜像命名:
docker tag <IMAGE_ID> localtonet/localtonet
docker run -d --name localtonet --restart unless-stopped localtonet/localtonet --authtoken <YOUR_TOKEN>故障排查 #
容器立即退出,并提示“Invalid Localtonet headless configuration”
完整消息是 Invalid Localtonet headless configuration. Check the token file or environment settings. 客户端没有找到可用的令牌:没有传入任何内容、值不是 33 个字符、中间含有空格或换行,或者令牌文件的路径在容器中不存在。如果你挂载了令牌文件,请在主机上确认它是文件而不是目录。设置了重启策略时,容器会不断重启,直到你修复令牌,因此请查看 docker logs localtonet。
日志显示“Authentication failed: AuthToken was rejected.”
令牌格式正确,但 Localtonet 不接受它。请从我的令牌重新复制,并重新创建容器。
隧道已启动,但公网地址访问不到我的服务
请检查隧道的本地地址。127.0.0.1 只有在 Linux 上使用 --network host 时才有效,否则请使用主机的局域网 IP 地址。host.docker.internal 这样的名称或其他容器的名称在这个字段中无效,详见从容器访问你的服务。
容器总是断开连接
请确认没有其他客户端使用同一个令牌。第二个用该令牌连接的客户端会断开第一个。请在我的令牌中为每个容器或设备各创建一个令牌。