---
title: "常见问题"
description: "关于 TSLink 的常见问题解答"
url: "https://tslink.md/zh/docs/faq"
locale: "zh"
product_version: "0.1.1"
source: "https://github.com/anydoor7/tslink/blob/v0.1.1/README.md"
---

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

## 通用

### 为什么不直接用 `tailscale serve` 或 Tailscale Services？

[Tailscale Serve](https://tailscale.com/docs/features/tailscale-serve) 通过宿主机的 Tailscale client 发布 endpoint。[Tailscale Services](https://tailscale.com/docs/features/tailscale-services) 提供带独立 MagicDNS 名称的具名服务。配置需要官方列出的管理角色和带标签的宿主机；tailnet 有匹配的自动批准策略时，可以自动批准宿主机。

TSLink 提供本机多应用注册表、私有 HTTP/文件的人员期限授权、邀请 bundle、recipes、健康检查与 CLI/MCP 生命周期管理。每个服务使用内嵌的 [tsnet](https://tailscale.com/docs/features/tsnet) 节点，因此 TSLink 宿主机不需要系统级 Tailscale daemon。

默认 `tslink add myapp --proxy localhost:3000 --json` 会确保网关运行。没有存储凭据时，节点以用户拥有的无标签身份注册。首次注册可能返回 `needs_login` 和 `auth_url`：将该 URL 交给用户完成浏览器登录，以及 tailnet 策略要求的批准。然后运行 `tslink url myapp --wait --json`，使用它返回的实际地址。[快速开始](https://tslink.md/zh/docs/quickstart.md)说明了这一交接流程；注册成功本身不证明服务已就绪。

### TSLink 是免费的吗？

TSLink 采用 Apache-2.0 许可证，允许免费商用。可以通过 macOS 或 Linux 上的 Homebrew、发布归档、Linux 软件包或 Windows zip 安装。macOS 二进制已签名并经公证，Windows zip 没有 Authenticode 签名。验证和源码构建的步骤见[安装指南](https://tslink.md/zh/docs/installation.md)。Tailscale 账户条款单独适用。

### TSLink 支持哪些平台？

TSLink 使用 Go 编写，支持 **macOS**、**Linux** 和 **Windows**。三个平台都支持特定的自动启动方式：LaunchAgent（macOS）、systemd 用户服务（Linux）和 Task Scheduler 内建 supervisor（Windows）；`--startup` 选择无崩溃恢复的 fallback。

### TSLink 需要安装 Tailscale 应用吗？

**在运行 TSLink 的机器上：** 不需要。TSLink 嵌入了自己的 Tailscale 节点（通过 tsnet），独立于系统 Tailscale 守护进程运行。

**在访问你服务的设备上：** 对私有 tailnet 访问来说需要。这些设备需要 Tailscale 与网络权限，可以是你的 tailnet 成员，或已接受应用设备分享的外部账户。例外情况是通过 Funnel（`--funnel --public`）暴露的代理服务，它们会被显式公开到公共互联网，且不受 TSLink 身份执行保护。

### 什么是临时节点？

`--ephemeral` 为临时服务请求临时 tsnet 节点。Tailscale 控制面会[在一段不活跃时间后移除临时节点](https://tailscale.com/docs/features/ephemeral-nodes)；断开连接不证明远端已立即移除。本地服务注册仍会保留，直到你通过 `tslink remove` 移除它。

```bash
tslink add temp-service --proxy localhost:3000 --ephemeral
```

## 认证

### API 访问令牌和 OAuth 客户端密钥有什么区别？

|          | API 访问令牌                                | OAuth 客户端密钥                       |
| -------- | --------------------------------------- | --------------------------------- |
| **前缀**   | `tskey-api-*`                           | `tskey-client-*`                  |
| **过期**   | 定期过期                                    | 永不过期                              |
| **认证方式** | 当前对 Tailscale REST 标签/设备自动化和认证材料派生支持最完整 | 由 tsnet 直接用于认证；当前 REST 标签/设备自动化更窄 |
| **适用场景** | 自动化和标签/设备管理                             | 验证所需操作后的长期运行场景                    |

两者都在 `tslink login` 时输入。任一种都可用于服务认证，但在验证所需标签/设备操作前，不要把 OAuth client secret 写成 full automation 的通用推荐。

### 我的凭证存储在哪里？

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

tsnet 内部使用的认证密钥不会存储到磁盘。API-token 模式下，TSLink 会在每个服务启动时派生新的认证材料，并按该服务的标签、临时节点设置和服务级描述限定范围。

### TSLink 可以与 Headscale 一起使用吗？

TSLink 接受自定义控制 URL，但 Headscale 端到端注册和 HTTPS 验证仍待完成。使用时应不使用已存储的 Tailscale 凭据，或使用由所选服务器签发的用户自供认证密钥。对于其他控制服务器，TSLink 会以 `credential_control_url_mismatch` 拒绝使用从已存储 Tailscale 凭据派生的认证材料。修改 URL 前请阅读[配置：可用设置](https://tslink.md/zh/docs/configuration.md#%E5%8F%AF%E7%94%A8%E8%AE%BE%E7%BD%AE)。

全局设置自定义控制 URL：

```bash
tslink config set control-url https://headscale.example.com
```

也可以在 `registry.json` 中按服务设置。明确选择手动运行的网关可通过 `tslink serve --control-url <url>` 按会话覆盖。受管理网关已运行时，请遵循[配置变更后重启](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)，不要再启动第二个 `serve` 进程。

### `tslink config` 支持哪些配置项？

目前 `tslink config` 支持 `control-url`，用于将 TSLink 指向自定义协调服务器（如 Headscale）。使用 `tslink config set`、`tslink config get` 和 `tslink config list` 管理全局设置。全局配置存储在 `~/.config/tslink/config.json` 中。

## 安全

### 我的流量是加密的吗？

部分是。tailnet 段——设备与 TSLink 节点之间的流量——由 WireGuard 加密，即使底层网络被攻破也保持受保护。TSLink 还为 HTTP 代理与文件服务的 tailnet 监听器配置 HTTPS 证书。两点边界需注意：从 TSLink 节点到本地服务的后端跳转由你配置（通常为明文 HTTP 或明文 TCP，可能是明文），且原始 TCP 服务没有 TSLink TLS 终止。因此 tailnet 传输是加密的，但整条路径并非全程加密。

### tailnet 外的人能访问我的服务吗？

默认服务监听在私有 tailnet 内，并受其访问策略约束。

例外情况是 **Tailscale Funnel**（`--funnel --public`）。在代理服务上启用后，该服务可从公共互联网访问。只有在你确实需要公开访问时才启用 Funnel；公共 Funnel 流量不受 TSLink 身份执行保护。

### 我可以限制特定人员的访问吗？

可以。对代理/文件 HTTP 服务，使用 `--allow` 将访问限制为特定 Tailscale 身份：

```bash
tslink add internal --proxy localhost:9090 --allow user@example.com,tag:admin
```

这与标准 Tailscale ACL 配合使用。

### 什么是 ACL 标签，如何使用？

ACL 标签（如 `tag:admin`）标识带标签的 Tailscale 设备。代理/文件 HTTP `--allow` 可以匹配调用者的设备标签。服务 `--tags` 在有存储凭据的模式下配置 TSLink 节点标签；默认零凭据（Tier 1）节点保持用户拥有、无标签，即使 registry 中有标签。

普通远端 tag-owner 配置要求在 `login` 或 `serve` 上显式传入 `--manage-acl`，并使用拥有所需策略权限的凭据。API-token 模式当前支持最完整的 REST 标签/设备自动化；client-secret-only 操作更窄。已明确确认公开的 Funnel 有独立配置流程，见[标签配置](https://tslink.md/zh/docs/configuration.md#%E6%A0%87%E7%AD%BE%E9%85%8D%E7%BD%AE)。

### 使用 TSLink 前需要配置标签吗？

默认零凭据注册不需要标签。有存储凭据的服务使用配置的标签，未指定 `--tags` 时使用默认 `tag:tsmain`。设置本地标签不会创建远端策略：可以自行配置标签所有权，或使用权限足够的凭据显式选择普通 `--manage-acl` 配置。修改 Tier 1 服务的标签会保留其已有用户注册状态。

要自定义标签，使用 `tslink tags` 命令组：

```bash
# 查看当前标签
tslink tags list

# 更改未来有存储凭据服务的默认标签
tslink tags set-default tag:myteam

# 为特定服务添加自定义标签
tslink add api --proxy localhost:8080 --tags tag:api,tag:prod
```

## 技术边界

### agent 能使用 TSLink 吗？

可以。CLI `--json` 提供带版本的信封，owner 会话提供 44 个应用/访问管理 MCP 工具，精简角色看到更少工具。`tslink mcp` 把 stdout 保留给协议 frames，拒绝 `--json`。[MCP 参考](https://tslink.md/zh/docs/mcp-server.md)说明传输、参数、取消和日志脱敏的边界。

### 能分享 MCP 或本地 LLM server 吗？

用 `tslink add llm --proxy localhost:11434 --allow you@example.com` 注册已有 HTTP endpoint。接收 client 必须能访问 tailnet 地址。保留应用所需的自身授权；TSLink 不会把 stdio 转成 HTTP，也不代替 MCP OAuth。原始 TCP 没有 HTTP 身份头或 TSLink `--allow` 检查。

### 标准映射涵盖什么？

TSLink 没有安全标准认证。[标准对齐](https://tslink.md/zh/docs/standards-alignment.md)只是对 NIST SP 800-207 技术概念的教学性部分映射。独立节点提供服务网络身份，不提供进程或主机隔离。WireGuard 保护 tailnet 一段；后端一跳可能明文。HTTP 身份解析是 best-effort，缓存 60 秒，且只有配置 `--allow` 才由 TSLink 执行限制。

## 服务

### 我可以运行多少个服务？

TSLink 本身没有硬性限制。每个服务在 tailnet 上创建一个主机名。实际限制取决于你的 Tailscale 计划和系统资源。

### 支持哪些服务类型？

| 类型      | 标志        | 用途                    |
| ------- | --------- | --------------------- |
| **代理**  | `--proxy` | Web 应用、API、任何 HTTP 服务 |
| **文件**  | `--dir`   | 通过 HTTPS 提供目录服务       |
| **TCP** | `--tcp`   | 数据库、Redis、任何原始 TCP 协议 |

### TCP 服务如何工作？

TCP 服务逐字节转发原始 TCP 连接。这对于将数据库（PostgreSQL、MySQL）、Redis、消息代理或任何基于 TCP 的协议暴露到 tailnet 非常有用。与代理服务不同，TCP 服务不执行 HTTP 处理、HTTP `--allow`、middleware、TLS 终止或请求头注入。

```bash
tslink add mydb --tcp localhost:5432
```

注册并就绪后，用 `tslink url mydb --wait` 获取实际地址。从 tailnet 策略允许的设备访问，使用返回的主机名与记录的 TCP 端口，并保留数据库自身认证及所需的应用 TLS：

```bash
psql -h <tslink-url-返回的主机名> -p 5432
```

### 我可以暴露远程机器上的服务吗？

TSLink 代理到 `host:port`，因此目标服务必须从运行 TSLink 的机器可达。如果你可以通过 `curl http://host:port` 访问它，TSLink 就可以代理它。

### 我可以在非标准端口上暴露服务吗？

TSLink 代理和文件服务通过 HTTPS 的 443 端口访问。CLI 创建的 TCP 服务通过 `--tcp host:port` 记录的端口访问；如果手工编辑 registry 且省略 `port`，runtime 回退到 443。

### 添加服务时需要重启网关吗？

不需要。TSLink 支持热重载。当你运行 `tslink add` 或 `tslink remove` 时，网关会自动检测更改并更新，无需重启。

### 哪些更改会热重载，哪些需要节点重启？

Registry 中服务 type、target/path、port、标签、HTTP 访问列表、临时节点设置、Funnel 设置或实际 control URL 的更改会通过热重载重启受影响的 runtime。Tier 1 标签修改保留用户注册；有存储凭据时，实际节点标签变化可能重置节点身份。切换凭据模式或修改旧版 `authkey` 文件需要重启网关进程，请遵循对应平台的[守护进程管理](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)。可配置 middleware 属于 roadmap/experimental；已移除的 `middleware` registry 键即使为空也会被拒绝。

### 什么是身份头？

对于代理服务，Tailscale WhoIs 为转发到本地服务的请求解析出用户身份时，TSLink 才注入身份头：

* `X-Tailscale-User-Login` — 已认证用户的登录名
* `X-Tailscale-User-Name` — 用户的显示名称
* `X-Tailscale-User-Picture` — 用户头像的 URL（有该信息时）
* `X-Tailscale-Node` — 请求节点的 computed name（有该信息时）

TSLink 先移除传入的 `X-Tailscale-*` 头，再注入 WhoIs 解析出的值。解析是 best-effort：未配置 `--allow` 时，查询失败的请求仍可能转发且不带身份头；配置了 `--allow` 时，缺少身份会在到达后端前被拒绝。

只有在受控的 TSLink 到后端路径中，确保调用者不能绕过代理并伪造头时，才能信任这些值。应用若要求已识别用户，就应拒绝缺少身份的请求，并保留所需的认证与授权。身份头本身不认证每个请求。

### 身份头是否适用于文件和 TCP 服务？

不适用。身份头仅为代理服务注入，因为它们依赖于 HTTP 请求处理。文件服务直接提供静态文件，TCP 服务转发原始字节，不具备 HTTP 感知能力。

## Funnel

### 什么是 Tailscale Funnel？

Tailscale Funnel 允许你将服务公开暴露到互联网上，无需访问设备在你的 tailnet 上。服务仍然可通过相同的 `https://<服务名>.<tailnet名>.ts.net` URL 访问。

### 哪些服务类型支持 Funnel？

只有**代理**服务支持 Funnel（`--funnel --public`）。文件服务和 TCP 服务不支持 Funnel。

```bash
tslink add myapp --proxy localhost:3000 --funnel --public
```

### Funnel 安全吗？

Funnel 会将你的服务暴露到公共互联网。只有在你确实需要公开访问时才启用它。Launch candidate 中不要依赖 roadmap/experimental middleware 包保护 Funnel。注意身份头（`X-Tailscale-User-*`）对于公共 Funnel 请求不可用。

关于中间件、Docker 自动发现等实验性功能的问题，请参阅[实验性与路线图](https://tslink.md/zh/docs/experimental-roadmap.md)。

## 监控

### TSLink 暴露 Prometheus 指标吗？

Prometheus `/metrics` 属于 [roadmap/experimental](https://tslink.md/zh/docs/experimental-roadmap.md#prometheus-%E6%8C%87%E6%A0%87)。详细的可用指标请参阅实验性与路线图页面。

### 访问日志存储在哪里？

用 `tslink access log --app photos --since 24h` 查看保留的本地 HTTP/文件/TCP/guest 事件及权限变更 receipt。Daemon JSONL 在 `~/.config/tslink/access-log/`，变更 journal 是 `mcp-audit.json`。`tslink logs` 查看 logs/ 下的 daemon 诊断。[访问历史](https://tslink.md/zh/docs/access-history.md)说明路径隐私、独立容量与缺口。

### TSLink 使用什么日志格式？

历史使用带 schema-version-1 的类型事件，含 time、kind、app/service、decision、可选的 WhoIs 身份和 HTTP/TCP metadata 或 guest/MCP/lifecycle 详情。不保存 header、cookie、body 或秘密；路径默认是清理后的 prefix。事件及 intent/completion receipt 不是独立访问次数，也不证明操作完成。身份可能缺失、事件可能丢失或有崩溃缺口；status 和 doctor 报告当前历史健康。不保证完整审计或合规。Prometheus、flow analysis 与 cluster 遥测仍在规划中。

### 访问者能不安装 Tailscale 吗？

[访客链接](https://tslink.md/zh/docs/guest-links.md)通过明确公开的 Funnel，为单 HTTP proxy 应用提供强制 gate、可选 PIN 与有限期限。链接/PIN 可转发，不能证明人是谁，不支持 file/raw TCP。开放 Funnel 是另一种公网发布方式，请保留应用自身认证。

### 有自己的应用首页吗？

[私有 portal](https://tslink.md/zh/docs/portal-requests.md)列出一台主机上有权访问的应用，并为明确启用的私有 HTTP/文件提供请求入口。访问者仍需正确 Tailscale login、网络策略和节点分享；QR 不安装应用、不自动授权。多主机汇总和 admin 管理 dashboard/REST API 仍在规划中。

## 网络

### TSLink 需要端口转发吗？

通常不需要在路由器上配置入站端口转发。TSLink 宿主机仍须具备正常的 Tailscale 连通性，接收设备也需要可达的 tailnet 路径及其访问策略许可。

### 如果我的机器进入睡眠状态会怎样？

宿主机睡眠时网关无法提供服务。唤醒后的可用性取决于网关进程、网络连通性与节点认证仍然就绪；用 `tslink status --json` 和 `tslink url <name> --wait` 检查。需要持续可用性时，使用保持唤醒的宿主机或常开服务器。

### TSLink 可以与 Tailscale ACL 一起使用吗？

可以。Tailscale 访问控制列表（ACL）对 TSLink 服务的适用方式与 tailnet 上的其他设备相同。你可以限制哪些用户或设备可以访问特定服务。

关于自定义域名和 ACME 证书的问题，请参阅[实验性与路线图](https://tslink.md/zh/docs/experimental-roadmap.md#%E8%87%AA%E5%AE%9A%E4%B9%89%E5%9F%9F%E5%90%8D%E5%92%8C-acme)。

## 自动化

### 我可以通过编程方式管理服务吗？

可以。已交付的选择有两个，另有一个路线图项：

**1. 已发布 manifest 中的命令支持 `--json`** — 已发布 manifest 中的命令，除 stdio 的 `tslink mcp` 服务器外，都接受 `--json`，并返回一个带版本的信封。Cobra 的 `help` 和 `completion` 命令不在 manifest 中，只输出纯文本：

```bash
tslink list --json
tslink add myapp --proxy localhost:3000 --json
tslink remove myapp --json
tslink status --json
```

**2. MCP** — `tslink mcp` 通过 stdio 把同样的操作以 MCP 工具形式提供给本机上的 client；`tslink serve --mcp` 则在一个专用的 tailnet-only 节点上通过 HTTPS 提供给 tailnet 内其它机器上的 client。参见 [TSLink 作为 MCP 服务器](https://tslink.md/zh/docs/mcp-server.md)。

**3. 管理 REST API** — roadmap/experimental；当前 runtime 不会启动。

本地脚本和 CI/CD 管道使用带 `--json` 的 CLI，agent 使用 MCP，REST 管理仍属于 roadmap/experimental。

## 配置

### TSLink 将数据存储在哪里？

默认本地配置和运行时文件存储在 `~/.config/tslink/` 下（钥匙串凭据仍保留在系统钥匙串）：

| 路径              | 描述                |
| --------------- | ----------------- |
| `registry.json` | 服务注册表（所有已注册的服务）   |
| `config.json`   | 全局配置（控制 URL 等）    |
| `tslink.pid`    | 守护进程 PID 文件       |
| `apikey`        | API 访问令牌（文件回退）    |
| `clientsecret`  | OAuth 客户端密钥（文件回退） |
| `authkey`       | 旧版认证密钥（向后兼容）      |
| `nodes/`        | 按服务的 tsnet 节点状态   |
| `logs/`         | 守护进程和访问日志         |

### 我可以更改配置目录吗？

设置 `TSLINK_CONFIG_DIR` 可选择其它目录。CLI 与网关必须使用相同值，已安装的监督程序也需要匹配的环境。修改已有配置时遵循[守护进程管理](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)，不要操作一个目录而网关仍从另一个目录提供服务。

## 故障排除

### 我的服务之前可以工作但突然停止了

检查本地服务（`host:port` 目标）是否仍在运行。TSLink 代理流量但不管理你本地服务的生命周期。

### 我看到"地址已在使用中"错误

另一个网关或进程可能正在使用相同资源。先检查 `tslink status --json`，包括 `data.daemon_running` 和 `data.supervision`，再决定操作。macOS 受管理网关可能在 `stop` 后重启；手动和受管理网关需要不同处理。遵循[确认停机](https://tslink.md/zh/docs/daemon.md#%E7%A1%AE%E8%AE%A4%E5%81%9C%E6%9C%BA)或适用的[重启步骤](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)，识别实际冲突进程后再重试。

更多详细的故障排除信息，请参阅[故障排除](https://tslink.md/zh/docs/troubleshooting.md)指南。