跳到内容
Localtonet Localtonet 控制台

在 Docker 中运行 Localtonet

获取本页帮助
本页内容 12 个章节
  1. 开始之前
  2. 步骤
  3. 拉取镜像
  4. 用你的令牌启动容器
  5. 创建并启动隧道
  6. 容器如何运行
  7. 在后台运行并自动重启
  8. 传入令牌的方式
  9. Docker Compose
  10. 从容器访问你的服务
  11. 查看日志
  12. 更新
  13. 适用于无法访问镜像仓库的主机的镜像归档
  14. 故障排查
  15. 相关页面

官方镜像 localtonet/localtonet 会在容器中运行 Localtonet 客户端。传入你的 AuthToken,然后像往常一样在控制台中创建并启动隧道。

开始之前 #

  • 64 位主机上的 Docker。镜像发布了 linux/amd64 和 linux/arm64 两个版本,Docker 会选择与你的主机匹配的那个。32 位 ARM 设备请改用 Linux 版本。
  • 来自我的令牌的 AuthToken。请为每个容器使用各自的令牌:当第二个客户端用同一个令牌连接时,第一个会被断开。

步骤 #

  1. 拉取镜像 #

    先拉取镜像,可以确保你运行的是当前版本,而不是主机上仍然存在的旧镜像。

    Bash
    docker pull localtonet/localtonet

    镜像位于 Docker Hub。除了 latest,如果你想固定某个版本,Docker Hub 上还列有每个版本对应的标签。

  2. 用你的令牌启动容器 #

    镜像名称之后的所有内容都会传给 Localtonet 客户端。请把 <YOUR_TOKEN> 替换为你的 AuthToken。

    Bash
    docker run localtonet/localtonet --authtoken <YOUR_TOKEN>

    容器会输出它的连接状态,并停留在前台。按 Ctrl + C 可以停止它。

  3. 创建并启动隧道 #

    打开控制台,用你交给容器的那个令牌创建隧道,然后选择启动。快速开始中有对应的表单。在填写本地 IP 地址之前,请先阅读从容器访问你的服务,因为 127.0.0.1 在容器内的含义不同。

容器如何运行 #

镜像以无界面模式启动客户端。与桌面上的客户端相比,这会带来三点变化:

  • 它从不提问。如果令牌缺失或格式不正确,容器会输出错误并以退出码 2 退出。
  • 它输出的是普通日志行,而不是实时状态表,即使你用 -it 启动也是如此。
  • 它不会保存令牌。镜像没有声明任何卷,所以每次创建容器时都要传入令牌:通过命令行、环境变量或文件。

隧道不在容器中配置。你在控制台中创建、启动和停止隧道,容器会通过它的连接获取这些隧道。

在后台运行并自动重启 #

使用 -d 让容器在后台运行,并设置重启策略,使 Docker 在重启或崩溃后再次启动容器:

Bash
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,你不需要再设置它。

使用令牌文件时,令牌不会出现在容器定义中,并以只读方式挂载它:

Bash
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. 然后退出。它不会向服务器查询令牌是否有效。

Bash
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-config

Docker Compose #

同样的配置写成 Compose 文件。把令牌放在与 compose.yaml 同目录、名为 auth-token 的文件中:

compose.yaml
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:ro
Bash
docker compose up -d
docker compose logs -f localtonet

当你要发布的服务位于同一个 Compose 项目中、且主机是 Linux 时,请在主机上发布它的端口,并让 Localtonet 容器使用主机网络。隧道的本地地址必须是 IP 地址,因此不能使用 web 这样的 Compose 服务名:

compose.yaml
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 主机上,Linux127.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无。
Linux,服务在主机上
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 未接受该令牌。

令牌本身绝不会写入日志。

更新 #

再次拉取镜像并重新创建容器:

Bash
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 归档,复制过去后再加载:

Bash
docker load --input localtonet-docker-amd64.tar

docker load 会输出它加载了什么。如果输出的是镜像 ID 而不是名称,请在运行之前为镜像命名:

Bash
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 这样的名称或其他容器的名称在这个字段中无效,详见从容器访问你的服务。

容器总是断开连接

请确认没有其他客户端使用同一个令牌。第二个用该令牌连接的客户端会断开第一个。请在我的令牌中为每个容器或设备各创建一个令牌。

支持