---
title: "安装"
description: "在 macOS、Linux 和 Windows 上安装 TSLink，并验证发布产物。"
url: "https://tslink.md/zh/docs/installation"
locale: "zh"
product_version: "0.1.1"
source: "https://github.com/anydoor7/tslink/blob/v0.1.1/docs/getting-started.md"
---

> Documentation index: https://tslink.md/zh/llms.txt · Installed binary is authoritative: `tslink manifest`.

## 前置要求

你需要一个 **Tailscale 账户**，并启用 [MagicDNS 和 HTTPS](https://tailscale.com/docs/how-to/set-up-https-certificates)。私有访问的接收设备需要 [Tailscale](https://tailscale.com/download) 和相应策略权限。应用主机使用 TSLink 内嵌的 Tailscale 节点，无需另装 Tailscale daemon。首次私有分享不必存储 API 令牌或 OAuth 客户端凭据。macOS 主机需要 macOS 13 Ventura 或更高版本：自 v0.1.1 起使用 Go 1.27 构建，已不再支持 macOS 12 Monterey 及更早版本（见[平台指南](https://github.com/anydoor7/tslink/blob/v0.1.1/docs/platforms.md)）。

## 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 发布页](https://github.com/anydoor7/tslink/releases/tag/v0.1.1)选择适合 `amd64` 或 `arm64` 的 `.deb`、`.rpm` 或 `tslink_0.1.1_linux_<arch>.tar.gz`。软件包通过系统包管理器安装；归档解压后，将 `tslink` 放入 `PATH` 包含的目录。

## Windows

从 [v0.1.1 发布页](https://github.com/anydoor7/tslink/releases/tag/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 的步骤见[平台指南](https://github.com/anydoor7/tslink/blob/v0.1.1/docs/platforms.md)。

```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`。

## 验证发布产物

按[发布验证命令](https://github.com/anydoor7/tslink/blob/v0.1.1/docs/verify-release.md)操作，将 `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 策略约束；策略使密钥过期时可能需要重新授权。授权交接及就绪步骤见[快速开始](https://tslink.md/zh/docs/quickstart.md)。

### Tier 2 — 存储凭据（可选）

存储凭据支持带标签的节点认证，但标签所有权和策略权限仍需满足，普通 ACL 自动化要求显式 `--manage-acl`。远端陈旧设备清理要求精确所有权证明及设备权限。带标签身份的节点密钥过期行为与 API-token 过期不同，见[标签配置](https://tslink.md/zh/docs/configuration.md#%E6%A0%87%E7%AD%BE%E9%85%8D%E7%BD%AE)；存储凭据本身不证明配置成功。

```bash
tslink login
```

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

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

### 选择哪种密钥类型？

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

API 访问令牌在 [管理后台 → Keys](https://login.tailscale.com/admin/settings/keys) 生成。OAuth 客户端密钥在 [管理后台 → OAuth](https://login.tailscale.com/admin/settings/oauth) 生成 — 点击 "+ credential" → "OAuth client" → 按所需 API 操作配置 scopes → 复制下方的 **client secret**（不是上方较短的 client ID）。

### 凭证存储

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

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

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

| 文件             | 内容          |
| -------------- | ----------- |
| `apikey`       | API 访问令牌    |
| `clientsecret` | OAuth 客户端密钥 |
| `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
```

### macOS

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

### Linux

在 `~/.config/systemd/user/tslink.service` 创建 **systemd 用户服务**，支持失败后自动重启，安装时自动启用并启动。未启用 lingering 时随用户登录启动；`loginctl enable-linger "$USER"` 允许开机后无需登录运行，并在登出后继续运行。如果 lingering 只为 TSLink 启用，卸载后应禁用。

### Windows

注册 Task Scheduler 任务并立即启动内建 supervisor，支持 daemon 崩溃恢复与后续登录自启动。`tslink install --startup` 为明确的 Startup fallback，没有崩溃恢复。这是用户登录范围，不是无需登录的开机服务。

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

移除自启动：

```bash
tslink uninstall
```

Windows uninstall 先禁用并停止其 owned task/supervisor，再删除任务；Startup-only fallback 留下的当前进程需另行执行 `tslink stop`。macOS/Linux 会尝试停止受管理任务，但错误或无法确认移除的警告需先解决。停止共享或维护前，按[确认停机](https://tslink.md/zh/docs/daemon.md#%E7%A1%AE%E8%AE%A4%E5%81%9C%E6%9C%BA)检查状态再继续。

## 自定义控制服务器（Headscale）

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

如果你使用 [Headscale](https://headscale.net/) 或其他自定义控制服务器：

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

此设置持久化在 `~/.config/tslink/config.json` 中，适用于所有服务。如果网关已在运行，全局设置变更需按[重启流程](https://tslink.md/zh/docs/daemon.md#%E9%85%8D%E7%BD%AE%E5%8F%98%E6%9B%B4%E5%90%8E%E9%87%8D%E5%90%AF)恢复运行后生效。

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

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

## Docker 集成

Docker 标签发现属于 [roadmap/experimental](https://tslink.md/zh/docs/experimental-roadmap.md#docker-%E8%87%AA%E5%8A%A8%E5%8F%91%E7%8E%B0)。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 可执行文件可用后，按[快速开始](https://tslink.md/zh/docs/quickstart.md)注册首个服务、完成可能的入网授权并等待就绪。存储凭据是可选项。