TSLinkTSLink 文档

守护进程模式

将 TSLink 作为后台服务运行，支持跨平台自动启动

查看 Markdown

概述

TSLink 可以作为后台守护进程运行，这样你就不需要保持终端窗口打开。它支持在 macOS、Linux 和 Windows 上自动启动。

作为守护进程运行

默认 tslink add 和 tslink share 已会确保后台网关运行。完成可能出现的 needs_login / auth_url 入网授权，再用 tslink status --json 检查状态、用 tslink url <name> --wait 等待服务就绪。网关已运行时再次执行 serve 会返回冲突。

如果明确选择手动运行，先确认没有受管理安装，也没有运行中的网关。从已有安装切换时，先完成下方确认停机。注册服务时禁用守护进程安装，然后自行启动网关：

bash
tslink add app --proxy localhost:3000 --no-daemon-install
tslink serve --daemon

手动网关在后台运行，将 stdout/stderr 重定向到日志文件，关闭终端后仍继续运行。这个流程不登记登录自启动或崩溃监督。使用服务前仍需完成入网授权并等待就绪。

检查状态

查看守护进程是否正在运行、认证状态和服务数量：

bash
tslink status

输出示例：

代码
→ tslink: running (pid 12345)
→ tailnet: authenticated
→ services: 3 registered

停止守护进程

停止后台网关：

bash
tslink stop

macOS/Linux 上会发送 SIGTERM，最多等待五秒确认进程退出。超时只返回错误，不会强制终止，进程可能仍在运行。Windows 上会请求操作系统立即终止进程，再等待退出确认，不会优雅排空请求。维护前请检查命令结果和 tslink status --json。

stop 不移除自启动。已安装的 macOS LaunchAgent 可在停止后重新拉起进程；Linux 用户 unit 的 Restart=on-failure 会在成功的优雅退出后保持停止。如需保持网关停止，请按下方确认停机操作。

信号处理

TSLink 监听操作系统信号以协调干净的关闭过程：

信号平台行为
SIGTERMUnix（macOS、Linux）发起服务监听器和节点的关闭，然后退出
SIGINTUnix（macOS、Linux）与 SIGTERM 相同（允许前台模式下使用 Ctrl+C）
进程终止Windows通过操作系统进程终止立即终止

Unix 优雅关闭时，TSLink 先关闭控制平面，再逐个关闭服务节点：

  1. 取消节点的工作，停止接收新的 HTTP 请求。
  2. 每个代理/文件 HTTP 服务器最多有五秒排空进行中的请求；该服务器关闭失败或超时后会直接关闭它。
  3. 关闭节点的监听器、tsnet 节点和处理器资源。原始 TCP 不使用 HTTP 排空步骤。
  4. 保留服务状态供下次运行，移除运行时/PID 记录并退出。

HTTP 排空预算按服务节点计算，与 CLI 的五秒进程退出等待不同。关闭多个节点可能花费更久；CLI 超时不能证明所有连接或进程已停止。

登录时自动启动

TSLink 可以注册为登录时自动启动：

bash
tslink install

macOS — LaunchAgent

在 ~/Library/LaunchAgents/com.tslink.daemon.plist 创建 plist 文件。

  • 登录时启动 TSLink
  • KeepAlive=true — 进程崩溃时自动重启；LaunchAgent 仍安装时，tslink stop 后也会被重新拉起
  • ThrottleInterval=30 — 将重启循环节流到 30 秒
  • 管理 stdout/stderr 日志
  • 通过 launchctl 加载和管理

如果目的是禁用自启动，先运行 tslink uninstall，再运行 tslink stop，避免 launchd 立即重启 TSLink。

安装后检查状态：

bash
launchctl list | grep tslink

移除自动启动

bash
tslink uninstall

这会移除平台特定的自启动配置。macOS/Linux 还会尝试停止受管理任务；拒绝、错误或警告需先解决，才能视为移除完成。Windows 先禁用 owned scheduled task，停止 supervisor 与 child，确认无运行实例，再删除任务。只有 Startup fallback 才仅移除脚本而不接管当前进程。手动启动的进程也需另行停止。如目的是停止共享，请按以下顺序操作。

确认停机

逐步执行并检查结果，确认后再继续：

  1. 运行 tslink uninstall --json，先移除受管理自启动，避免 macOS KeepAlive 重新拉起网关。遇到错误或无法确认移除的警告时停止操作。
  2. 运行 tslink stop --json，停止可能剩余的进程。遇到错误时停止操作；Unix 超时后进程可能仍在运行。
  3. 运行 tslink status --json。只有 ok 为 true、data.daemon_running 为 false，且 data.supervision.installed、autostart、restart_on_exit 全为 false 时，才能继续维护。状态不确定时，先解决问题，再修改配置或启动另一个网关。

移除自启动和停止进程不会删除已注册服务或凭据。

配置变更后重启

受管理运行时，先完成确认停机，再修改全局配置或凭据，最后带上之前选择的安装选项重新运行 tslink install。macOS/Linux 的 install 会启动受管理任务。Windows 的 install 只登记下次登录；如需在已确认停机后恢复当前会话，请用匹配的运行选项执行 tslink serve --daemon，或等待下次登录。随后检查 tslink status --json、完成可能的入网授权，再用 tslink url <name> --wait 等待就绪。

没有自启动登记的手动运行环境，应先停止并确认 data.daemon_running: false，再修改设置，最后用 tslink serve（前台）或 tslink serve --daemon（后台）恢复运行。新增注册继续使用 --no-daemon-install，以保持手动运行。

进程生命周期

TSLink 使用基于 PID 的生命周期管理：

  1. 当 tslink serve --daemon 启动时，它会 fork 进程并将 PID 写入 ~/.config/tslink/tslink.pid。
  2. tslink status 读取 PID 文件来检查进程是否仍在运行。
  3. tslink stop 读取 PID 并发送终止信号。

这确保同一时间只有一个网关实例在运行。如果你尝试启动第二个实例，TSLink 会检测到现有 PID 并警告你网关已在运行。

结构化日志

tslink logs 查看结构化 gateway 诊断。保留的请求与权限变更请用访问历史。

日志文件位置

文件内容
~/.config/tslink/logs/tslink.out.logDaemon stdout
~/.config/tslink/logs/tslink.err.logstderr 上的 gateway 生命周期、warning/error
~/.config/tslink/access-log/有界异步 HTTP/文件/TCP/guest JSONL 事件
~/.config/tslink/mcp-audit.json独立有界变更 intent/completion 与生命周期 journal

访问日志格式

Schema-version-1 事件有类型化 time、kind、app/service、identity、decision；HTTP 加 method/status/bytes/duration 与清理的路径。公共 Funnel 不确定人的身份。查询合并保留的 daemon 片段与 journal。缺 completion 表示结果未知；drops 和崩溃缺口使它无法保证完整审计。Status/doctor 查看当前 access-log health。

查看日志

bash
tslink logs --source err --last 100
tail -f ~/.config/tslink/logs/tslink.err.log
tslink access log --app photos --since 24h --json

管理 API 和仪表板

管理仪表板和 REST API 属于 roadmap/experimental。已交付自动化请使用带 --json 的 CLI。

推荐设置

默认后台运行流程：

bash
# 逐个注册服务；普通 add 会确保网关运行
tslink add app --proxy localhost:3000 --json
tslink add files --dir ~/shared --json
tslink add mydb --tcp localhost:5432 --json

检查每次 add 的结果。如返回 needs_login，打开它的 auth_url，完成 tailnet 要求的注册/审批后再继续。随后对每个服务运行 tslink url <name> --wait，并检查 tslink status --json；守护进程存活本身不代表服务就绪。默认 add 成功后，无需再执行 serve 或 install。

自启动可用性遵循上方平台登录/lingering 规则；status --json 的 data.supervision.autostart_scope 显示实际观察到的启动范围。使用 tslink add 和 tslink remove 管理服务，注册表更改通过热重载生效，无需重启网关。

配置

TSLink 配置文件、全局设置、当前字段和状态管理

故障排查

常见 TSLink 问题的解决方案

目录

概述作为守护进程运行检查状态停止守护进程信号处理登录时自动启动macOS — LaunchAgentLinux — systemd 用户服务Windows — Task Scheduler移除自动启动确认停机配置变更后重启进程生命周期结构化日志日志文件位置访问日志格式查看日志管理 API 和仪表板推荐设置