在 NAS 或 Home Assistant 上运行 Localtonet
安装模板 AMD64 和 ARM64
本页内容 7 个章节
Localtonet 提供部署模板,可在支持 Docker 的 NAS 和 Home Assistant 上以容器方式运行 Localtonet 客户端。你只需添加自己的 AuthToken,启动容器,然后在控制台中管理隧道。
这些模板是什么 #
下载内容是一个小型 ZIP 压缩包,包含两个模板,共五个文件:
| 模板 | 适用于 | 文件 | 需要修改的内容 |
|---|---|---|---|
NAS / Docker Compose(文件夹 nas) | Synology Container Manager、QNAP Container Station、任何其他运行 Docker 的 NAS,以及 Home Assistant Container 或 Core 主机 | nas/compose.yaml 和 nas/auth-token.example | 只需修改令牌:把 auth-token.example 复制为 auth-token,并把 DUMMY_AUTH_TOKEN 替换为你的 AuthToken。compose.yaml 保持原样。 |
Home Assistant 应用(文件夹 home-assistant) | Home Assistant OS 和 Home Assistant Supervised | home-assistant/localtonet/config.json(本地应用的定义,以前称为加载项)和 home-assistant/repository.json | 文件中无需修改任何内容。安装应用后,你在 Home Assistant 中输入令牌。本地安装不使用 repository.json。 |
第五个文件 README.txt 是本页步骤的简短文本版本。
两个模板都按 Docker 页面介绍的方式,在容器中无提示地运行 Localtonet 客户端。它们适用于 AMD64(Intel 和 AMD 处理器)和 ARM64。开始之前请确认你的 NAS 使用的处理器;32 位 ARM 的 NAS 无法运行。
它们不是什么 #
- 它们不是 Synology SPK 或 QNAP QPKG 软件包。Synology 的套件中心和 QNAP 的 App Center 中不会出现任何内容。
- Home Assistant 模板并不是官方 Home Assistant 商店中的条目。你需要把它作为本地应用安装。
- 它们不包含容器镜像。你的设备会拉取模板中指定的镜像
docker.io/localtonet/localtonet,也就是 Docker 页面所述、位于 Docker Hub 上的镜像。 - 它们不会给容器 VPN 接口所需的权限。这些模板用于隧道;VPN 功能不属于其中。
开始之前 #
- 支持 Docker 和 Docker Compose 的 NAS,或 Home Assistant OS / Supervised。
- 来自我的令牌的 AuthToken。请使用没有其他设备使用的令牌:当第二个客户端用同一令牌连接时,第一个会被断开。
- 模板 ZIP。下载链接位于本页末尾的列表中,也在下载页面。
使用 Docker Compose 设置 NAS #
-
解压 ZIP 并把 nas 文件夹复制到 NAS #
在你的电脑上解压压缩包。把
nas文件夹复制到 NAS 上容器管理器可以使用的共享文件夹中。 -
创建令牌文件 #
在
nas文件夹中,把auth-token.example复制为auth-token。打开auth-token,把DUMMY_AUTH_TOKEN替换为你的 AuthToken,写在单独一行,文件中不要有其他内容。请妥善保管令牌文件。把它的访问权限限制为你在 NAS 上的账户,不要放在其他人可以读取的共享文件夹或同步文件夹中。该令牌允许 Localtonet 客户端以此设备的身份连接。
该文件必须在容器启动之前就存在。如果缺失,Docker 会改为创建一个名为
auth-token的目录,容器就无法从中读取令牌。 -
保持 compose.yaml 原样 #
你不需要编辑
compose.yaml。它的image:行指定了 Localtonet 镜像以及此 ZIP 对应的版本,例如docker.io/localtonet/localtonet:8.6.0。其余各行在Compose 模板的作用中说明。 -
启动项目 #
在容器管理器中把
compose.yaml导入为项目并启动:- Synology:在 Container Manager 中,基于
nas文件夹及其中的compose.yaml创建项目。 - QNAP:在 Container Station 中,基于
compose.yaml创建应用。该文件按相对于 Compose 文件的路径挂载./auth-token,因此令牌文件必须能在该路径下访问到。 - 任何带 shell 的 Docker 主机:在
nas目录中运行下面的命令。
Bashdocker compose up -d具体界面因 NAS 型号和版本而异。请按厂商的文档,基于 Compose 文件创建项目。
- Synology:在 Container Manager 中,基于
-
创建并启动隧道 #
容器运行后,打开控制台,用你写入文件的令牌创建隧道并选择启动,与快速入门中一样。
Compose 模板的作用 #
这就是整个文件。image: 行末尾的标签是你的 ZIP 对应的 Localtonet 版本;8.6.0 只是示例。
services:
localtonet:
image: "docker.io/localtonet/localtonet:8.6.0"
restart: unless-stopped
network_mode: host
environment:
LOCALTONET_HEADLESS: "1"
LOCALTONET_AUTH_TOKEN_FILE: /run/secrets/localtonet_auth_token
volumes:
- ./auth-token:/run/secrets/localtonet_auth_token:ro| 设置 | 作用 |
|---|---|
image | Localtonet 镜像 docker.io/localtonet/localtonet 及要运行的版本。只有在迁移到其他版本时才修改标签,参见日志与更新。 |
restart: unless-stopped | 重启或崩溃后,Docker 会再次启动容器,除非你自己停止了它。 |
network_mode: host | 容器与 NAS 共用网络。这样隧道就能通过 127.0.0.1 访问 NAS 本身的服务,并通过局域网地址访问局域网中的其他设备。这需要 Linux 主机网络。 |
LOCALTONET_HEADLESS | 无提示运行客户端,并输出纯文本日志行。 |
LOCALTONET_AUTH_TOKEN_FILE | 客户端读取令牌的文件在容器内的路径。 |
volumes | 把你的 auth-token 文件以只读方式挂载到该路径。 |
设置 Home Assistant OS 或 Supervised #
Home Assistant OS 和 Supervised 通过 Supervisor 运行应用。该模板是一个本地应用,你需要把它复制到设备上。
-
复制应用文件夹 #
解压 ZIP。把文件夹
home-assistant/localtonet复制到 Home Assistant 的本地应用目录,使其成为/addons/localtonet。该文件夹只有一个文件config.json。请不要编辑它:它指定了应用名称 Localtonet、镜像docker.io/localtonet/localtonet以及此 ZIP 对应的版本,并把authtoken选项留空,供你之后填写。 -
重新加载应用商店并安装 Localtonet #
在 Home Assistant 中重新加载应用商店,使其找到该本地应用,然后安装 Localtonet。
-
输入令牌并启动应用 #
打开应用的 Configuration 页面,在
authtoken选项中输入你的 AuthToken,然后启动应用。Home Assistant 会像密码一样隐藏该值。此后应用会随 Home Assistant 自动启动。 -
创建并启动隧道 #
在控制台中用该令牌创建隧道并选择启动。要发布 Home Assistant 本身,请创建一个指向
127.0.0.1以及 Home Assistant 所监听端口的 HTTP 隧道。Home Assistant 的默认端口是8123。Home Assistant 对经由代理到达的请求有自己的设置;如果它拒绝这些请求,请参阅 Home Assistant HTTP 文档。
该应用使用主机网络,因此可以直接访问 Home Assistant 和你网络中的其他设备。它支持 Home Assistant 的 amd64 和 aarch64 架构。
Home Assistant Container 和 Core 没有 Supervisor,因此无法安装应用。在这些安装方式上,请改在 Docker 主机上使用 NAS / Docker Compose 模板。
文件 home-assistant/repository.json 位于你要复制的文件夹之外,不属于本地安装的一部分。它包含仓库 URL 和维护者的占位值(DUMMY),请忽略它。
访问你的服务 #
两个模板都使用主机网络。在隧道的本地 IP 地址字段中:
127.0.0.1就是 NAS 或 Home Assistant 主机本身。用它来访问 NAS 的网页界面、Home Assistant 或该设备上的任何其他服务,并配上该服务所监听的端口。- 像
192.168.1.20这样的局域网地址可以访问你网络中的另一台设备。
已启动的隧道可从互联网访问。在发布 NAS 登录页面或 Home Assistant 之前,请在服务本身设置强密码和两步验证,并考虑访问控制页面中的选项。
日志与更新 #
容器会写出纯文本日志行:连接状态、登录所用令牌的名称,以及每当有隧道被添加、状态变化或被移除时的一行。你可以在容器管理器的日志视图中、Home Assistant 中应用的 Log 标签页里,或用下面的命令查看:
docker compose logs -f localtonet出现 Invalid Localtonet headless configuration. Check the token file or environment settings. 表示客户端没有找到可用的令牌:令牌文件缺失或为空、仍包含 DUMMY_AUTH_TOKEN,或令牌长度不是 33 个字符。出现 Authentication failed: AuthToken was rejected. 表示令牌格式正确,但 Localtonet 不接受它。
每个模板 ZIP 对应一个 Localtonet 版本:Compose 文件把它固定在 image: 行的标签中,Home Assistant 应用则固定在 config.json 的 version 字段中。要把 NAS 升级到更新的版本,请把标签改为 Docker Hub 上该镜像列出的某个版本(参见 Docker),然后再次运行 docker compose up -d(或在容器管理器中更新项目)。你的 auth-token 文件保持不变。
相关页面 #
NAS 与 Home Assistant
适用于 Synology Container Manager、QNAP Container Station 及其他支持 Docker 的 NAS 设备的 Docker Compose 模板,另附适用于 OS / Supervised 的 Home Assistant 应用模板。支持 AMD64 和 ARM64。
这些是部署模板,不是 SPK / QPKG 安装包,也不是 Home Assistant 官方商店中上架的应用。镜像仓库中必须有匹配的 Docker 镜像。Home Assistant Container / Core 用户可以使用 Compose 模板。
配置你的 NAS 或 Home Assistant
- 解压 ZIP 文件并阅读
README.txt。 - 对于 NAS,将
nas/auth-token.example复制为nas/auth-token,并填入你的 AuthToken。请妥善保管此文件。 - 检查
nas/compose.yaml中的镜像标签,然后将其导入为项目,或在nas目录中运行docker compose up -d。 - 对于 Home Assistant OS / Supervised,请按照 README 中的本地应用安装说明操作,并在应用配置中填入令牌。
模板使用 Linux 主机网络以访问局域网,不会启用 VPN 权限。