常见问题
关于 TSLink 的常见问题解答
通用
为什么不直接用 tailscale serve 或 Tailscale Services？#
Tailscale Serve 通过宿主机的 Tailscale client 发布 endpoint。Tailscale Services 提供带独立 MagicDNS 名称的具名服务。配置需要官方列出的管理角色和带标签的宿主机；tailnet 有匹配的自动批准策略时，可以自动批准宿主机。
TSLink 提供本机多应用注册表、私有 HTTP/文件的人员期限授权、邀请 bundle、recipes、健康检查与 CLI/MCP 生命周期管理。每个服务使用内嵌的 tsnet 节点，因此 TSLink 宿主机不需要系统级 Tailscale daemon。
默认 tslink add myapp --proxy localhost:3000 --json 会确保网关运行。没有存储凭据时，节点以用户拥有的无标签身份注册。首次注册可能返回 needs_login 和 auth_url：将该 URL 交给用户完成浏览器登录，以及 tailnet 策略要求的批准。然后运行 tslink url myapp --wait --json，使用它返回的实际地址。快速开始说明了这一交接流程；注册成功本身不证明服务已就绪。
TSLink 是免费的吗？
TSLink 采用 Apache-2.0 许可证，允许免费商用。可以通过 macOS 或 Linux 上的 Homebrew、发布归档、Linux 软件包或 Windows zip 安装。macOS 二进制已签名并经公证，Windows zip 没有 Authenticode 签名。验证和源码构建的步骤见安装指南。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 控制面会在一段不活跃时间后移除临时节点；断开连接不证明远端已立即移除。本地服务注册仍会保留，直到你通过 tslink remove 移除它。
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 前请阅读配置：可用设置。
全局设置自定义控制 URL：
tslink config set control-url https://headscale.example.com也可以在 registry.json 中按服务设置。明确选择手动运行的网关可通过 tslink serve --control-url <url> 按会话覆盖。受管理网关已运行时，请遵循配置变更后重启，不要再启动第二个 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 身份：
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 有独立配置流程，见标签配置。
使用 TSLink 前需要配置标签吗？
默认零凭据注册不需要标签。有存储凭据的服务使用配置的标签，未指定 --tags 时使用默认 tag:tsmain。设置本地标签不会创建远端策略：可以自行配置标签所有权，或使用权限足够的凭据显式选择普通 --manage-acl 配置。修改 Tier 1 服务的标签会保留其已有用户注册状态。
要自定义标签，使用 tslink tags 命令组：
# 查看当前标签
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 参考说明传输、参数、取消和日志脱敏的边界。
能分享 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 没有安全标准认证。标准对齐只是对 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 终止或请求头注入。
tslink add mydb --tcp localhost:5432注册并就绪后，用 tslink url mydb --wait 获取实际地址。从 tailnet 策略允许的设备访问，使用返回的主机名与记录的 TCP 端口，并保留数据库自身认证及所需的应用 TLS：
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 文件需要重启网关进程，请遵循对应平台的守护进程管理。可配置 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。
tslink add myapp --proxy localhost:3000 --funnel --publicFunnel 安全吗？
Funnel 会将你的服务暴露到公共互联网。只有在你确实需要公开访问时才启用它。Launch candidate 中不要依赖 roadmap/experimental middleware 包保护 Funnel。注意身份头（X-Tailscale-User-*）对于公共 Funnel 请求不可用。
关于中间件、Docker 自动发现等实验性功能的问题，请参阅实验性与路线图。
监控
TSLink 暴露 Prometheus 指标吗？
Prometheus /metrics 属于 roadmap/experimental。详细的可用指标请参阅实验性与路线图页面。
访问日志存储在哪里？
用 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 诊断。访问历史说明路径隐私、独立容量与缺口。
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 吗？
访客链接通过明确公开的 Funnel，为单 HTTP proxy 应用提供强制 gate、可选 PIN 与有限期限。链接/PIN 可转发，不能证明人是谁，不支持 file/raw TCP。开放 Funnel 是另一种公网发布方式，请保留应用自身认证。
有自己的应用首页吗？
私有 portal列出一台主机上有权访问的应用，并为明确启用的私有 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 证书的问题，请参阅实验性与路线图。
自动化
我可以通过编程方式管理服务吗？
可以。已交付的选择有两个，另有一个路线图项：
1. 已发布 manifest 中的命令支持 --json — 已发布 manifest 中的命令，除 stdio 的 tslink mcp 服务器外，都接受 --json，并返回一个带版本的信封。Cobra 的 help 和 completion 命令不在 manifest 中，只输出纯文本：
tslink list --json
tslink add myapp --proxy localhost:3000 --json
tslink remove myapp --json
tslink status --json2. MCP — tslink mcp 通过 stdio 把同样的操作以 MCP 工具形式提供给本机上的 client；tslink serve --mcp 则在一个专用的 tailnet-only 节点上通过 HTTPS 提供给 tailnet 内其它机器上的 client。参见 TSLink 作为 MCP 服务器。
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 与网关必须使用相同值，已安装的监督程序也需要匹配的环境。修改已有配置时遵循守护进程管理，不要操作一个目录而网关仍从另一个目录提供服务。
故障排除
我的服务之前可以工作但突然停止了
检查本地服务（host:port 目标）是否仍在运行。TSLink 代理流量但不管理你本地服务的生命周期。
我看到"地址已在使用中"错误
另一个网关或进程可能正在使用相同资源。先检查 tslink status --json，包括 data.daemon_running 和 data.supervision，再决定操作。macOS 受管理网关可能在 stop 后重启；手动和受管理网关需要不同处理。遵循确认停机或适用的重启步骤，识别实际冲突进程后再重试。
更多详细的故障排除信息，请参阅故障排除指南。