TSLinkTSLink 文档

安装

在 macOS、Linux 和 Windows 上安装 TSLink，并验证发布产物。

查看 Markdown

前置要求

你需要一个 Tailscale 账户，并启用 MagicDNS 和 HTTPS。私有访问的接收设备需要 Tailscale 和相应策略权限。应用主机使用 TSLink 内嵌的 Tailscale 节点，无需另装 Tailscale daemon。首次私有分享不必存储 API 令牌或 OAuth 客户端凭据。macOS 主机需要 macOS 13 Ventura 或更高版本：自 v0.1.1 起使用 Go 1.27 构建，已不再支持 macOS 12 Monterey 及更早版本（见平台指南）。

macOS（Homebrew）

bash
brew install --cask anydoor7/tap/tslink

macOS 二进制使用 Developer ID 证书签名，并经 Apple 公证。首次运行需要联网查询公证凭证。

Linux

Linux 上的 Homebrew 使用同一条命令：

bash
brew install --cask anydoor7/tap/tslink

也可以从 v0.1.1 发布页选择适合 amd64 或 arm64 的 .deb、.rpm 或 tslink_0.1.1_linux_<arch>.tar.gz。软件包通过系统包管理器安装；归档解压后，将 tslink 放入 PATH 包含的目录。

Windows

从 v0.1.1 发布页下载 tslink_0.1.1_windows_amd64.zip 或 tslink_0.1.1_windows_arm64.zip。解压后，将 tslink.exe 所在目录加入用户 PATH，然后运行：

powershell
tslink install

TSLink 随用户登录启动。zip 没有 Authenticode 签名，请按下方步骤通过已签名的校验和与 attestations 验证。

从源码构建

源码构建需要 Git 和 Go 1.27.1+。下方命令适用于 bash/zsh；各平台 shell 的步骤见平台指南。

bash
git clone https://github.com/anydoor7/tslink.git
cd tslink
go install .
export PATH="$PATH:$(go env GOPATH)/bin"

使用 PowerShell 时，在系统设置中将 $(go env GOPATH)\bin 加入用户 PATH。

验证发布产物

按发布验证命令操作，将 version 设为 v0.1.1，并填写所下载产物的准确文件名。需要支持 gh attestation verify 的 gh 2.49+、支持 verify-blob --bundle 的 cosign，以及 sha256sum 或 shasum。

下载所选产物、checksums.txt 和 checksums.txt.sigstore.json。先将产物的 SHA-256 与 checksums.txt 中对应项比较，再验证该校验和文件的 Sigstore bundle，最后验证产物的 GitHub attestation。验证固定以下四个值：

  • OIDC issuer：https://token.actions.githubusercontent.com
  • Workflow 身份：https://github.com/anydoor7/tslink/.github/workflows/release.yml@refs/tags/v0.1.1
  • 源码 ref：refs/tags/v0.1.1
  • Signer workflow：github.com/anydoor7/tslink/.github/workflows/release.yml

归档的 SBOM sidecar 有独立的校验和、bundle 和 attestation，需要按同一指南单独验证。

验证安装

bash
tslink --version
tslink --help

第一条命令显示已安装版本，第二条列出命令帮助。

升级

使用 Homebrew 时，先升级 cask：

bash
brew upgrade --cask tslink

如果 TSLink 作为后台服务运行：

bash
tslink install

这会把服务的可执行文件路径更新到新版本。归档、Windows zip 或 Linux 软件包也应先替换或升级二进制，再按需运行 tslink install 更新后台服务。随后检查 tslink --version 和 tslink status --json。

认证

TSLink 有两档凭据。Tier 1 是默认档，不需要存储 API 凭据；注册与审批仍受 tailnet 策略约束。

Tier 1 — 交互式入网（默认）

无需执行存储凭据的 tslink login 命令即可分享；首次节点注册仍须完成浏览器登录。

bash
tslink share ./build

节点第一次需要加入 tailnet 时，TSLink 打印一个 Tailscale 授权 URL 然后退出。打开它、批准这个节点，再执行 tslink url <name> --wait 取实际可用的 URL。在 --json 模式下同样的信息以一条结构化记录返回，脚本或 agent 读一个字段就行，不用解析散文：

json
{"type":"tslink.result","ok":true,"schema_version":1,"command":"share","code":0,"data":{"status":"needs_login","auth_url":"https://login.tailscale.com/a/..."}}

这样入网的节点归你所有、不打标签。注册、审批、访问及节点密钥过期受 tailnet 策略约束；策略使密钥过期时可能需要重新授权。授权交接及就绪步骤见快速开始。

Tier 2 — 存储凭据（可选）

存储凭据支持带标签的节点认证，但标签所有权和策略权限仍需满足，普通 ACL 自动化要求显式 --manage-acl。远端陈旧设备清理要求精确所有权证明及设备权限。带标签身份的节点密钥过期行为与 API-token 过期不同，见标签配置；存储凭据本身不证明配置成功。

bash
tslink login

它会显示一个选择菜单 — 选择 [1] API 访问令牌 或 [2] OAuth 客户端密钥，并提供分步引导。

普通 tskey-api-* API 访问令牌具有完整的 Tailscale API 权限；包括 OAuth client 在内的 trust credentials 支持按 scope 授权。2026 年 10 月 6 日根据 Tailscale API 官方文档核实。除非你确实需要 Tier 2 提供的能力，否则优先用 Tier 1。

选择哪种密钥类型？

密钥类型前缀有效期工作方式适用场景
API 访问令牌tskey-api-*会周期性过期派生短期、单次使用的认证密钥；节点是否临时取决于服务的 --ephemeral 标志验证权限后的所需 REST 自动化
OAuth 客户端密钥tskey-client-*不会周期性过期tsnet 直接使用；当前 REST 标签/设备自动化更窄验证所需操作后的长期运行场景

API 访问令牌在 管理后台 → Keys 生成。OAuth 客户端密钥在 管理后台 → OAuth 生成 — 点击 "+ credential" → "OAuth client" → 按所需 API 操作配置 scopes → 复制下方的 client secret（不是上方较短的 client ID）。

凭证存储

TSLink 使用系统钥匙串安全存储你的凭证：

平台后端
macOS钥匙串（Keychain）
LinuxSecret Service（GNOME Keyring / KWallet）
Windows凭据管理器（Credential Manager）

凭据优先使用系统钥匙串（macOS Keychain、Linux Secret Service、Windows Credential Manager）。明文 0600 文件回退仅在 macOS/Linux 证明旧钥匙串值不存在或已删除后允许；钥匙串不可达或状态不确定时拒绝写入，应恢复访问后重试。Windows 不允许凭据文件回退。无头运行本身不保证可以回退。

文件内容
apikeyAPI 访问令牌
clientsecretOAuth 客户端密钥
authkey旧版认证密钥

非交互式设置

如果无法打开浏览器（如无头服务器），请从 secret manager 注入凭证到 stdin 或环境变量：

bash
printf %s "$TSLINK_API_KEY" | tslink login --api-key-stdin
printf %s "$TSLINK_CLIENT_SECRET" | tslink login --client-secret-stdin

也可以使用由 secret manager 注入的环境变量：

bash
TSLINK_API_KEY="$TSLINK_API_KEY" tslink login
TSLINK_CLIENT_SECRET="$TSLINK_CLIENT_SECRET" tslink login

兼容性 argv flags 和旧版凭证文件仍可能被 TSLink 读取，但官方自动化说明不应把 secret 放进 argv、shell history 或手动写入的 credential files。

登录时自动启动

默认 add/share 会处理后台运行设置。如需显式登记或更新登录自启动，运行：

bash
tslink install

在 ~/Library/LaunchAgents/com.tslink.daemon.plist 创建 LaunchAgent，启用 KeepAlive。TSLink 在用户登录时启动，停在开机登录窗口时不会启动；agent 仍安装时，崩溃或手动停止后都会重新拉起。

检查 tslink status --json 的 data.supervision.autostart_scope，以实际观察到的登录/开机范围为准；unknown 不能证明无需登录即可开机运行。入网/审批和服务就绪与自启动是不同状态。

移除自启动：

bash
tslink uninstall

Windows uninstall 先禁用并停止其 owned task/supervisor，再删除任务；Startup-only fallback 留下的当前进程需另行执行 tslink stop。macOS/Linux 会尝试停止受管理任务，但错误或无法确认移除的警告需先解决。停止共享或维护前，按确认停机检查状态再继续。

自定义控制服务器（Headscale）

Tailscale API 派生的节点 auth key 不能发给非 Tailscale control server，会以 credential_control_url_mismatch 拒绝。自定义控制服务器的入网及 HTTPS 支持须另行验证；端到端 Headscale 验证仍待完成。

如果你使用 Headscale 或其他自定义控制服务器：

bash
# 全局设置，适用于所有服务
tslink config set control-url https://headscale.example.com

此设置持久化在 ~/.config/tslink/config.json 中，适用于所有服务。如果网关已在运行，全局设置变更需按重启流程恢复运行后生效。

你也可以为单个服务覆盖控制服务器：

bash
# 按服务覆盖
tslink add my-service --proxy localhost:3000 --control-url https://headscale.example.com

Docker 集成

Docker 标签发现属于 roadmap/experimental。Launch-candidate 流程请用 tslink add 显式注册容器背后的服务。

配置目录

默认本地配置和运行时文件位于 ~/.config/tslink/，主要存储凭据位于系统钥匙串。TSLINK_CONFIG_DIR 可选择其它本地目录，须与网关/监督程序环境一致。

代码
~/.config/tslink/
  ├── registry.json       # 服务注册表
  ├── config.json          # 全局配置（control-url）
  ├── tslink.pid           # 守护进程 PID
  ├── apikey               # API 密钥（文件回退）
  ├── clientsecret         # OAuth 密钥（文件回退）
  ├── authkey              # 旧版认证密钥
  ├── nodes/               # 每个服务的 tsnet 状态
  └── logs/                # 守护进程和访问日志

下一步

TSLink 可执行文件可用后，按快速开始注册首个服务、完成可能的入网授权并等待就绪。存储凭据是可选项。

简介

访问与管理电脑或云主机上的应用，保持私有或按自己的条件分享。

快速入门

把本地文件、目录或 HTTP 服务分享给另一台 tailnet 设备

目录

前置要求macOS（Homebrew）LinuxWindows从源码构建验证发布产物验证安装升级认证Tier 1 — 交互式入网（默认）Tier 2 — 存储凭据（可选）选择哪种密钥类型？凭证存储非交互式设置登录时自动启动自定义控制服务器（Headscale）Docker 集成配置目录下一步