---
title: "守护进程模式"
description: "将 TSLink 作为后台服务运行，支持跨平台自动启动"
url: "https://tslink.md/zh/docs/daemon"
locale: "zh"
product_version: "0.1.1"
source: "https://github.com/anydoor7/tslink/blob/v0.1.1/docs/daemon-lifecycle.md"
---

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

## 概述

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

## 作为守护进程运行

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

如果明确选择手动运行，先确认没有受管理安装，也没有运行中的网关。从已有安装切换时，先完成下方[确认停机](https://tslink.md/zh/docs/daemon.md#%E7%A1%AE%E8%AE%A4%E5%81%9C%E6%9C%BA)。注册服务时禁用守护进程安装，然后自行启动网关：

```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` 会在成功的优雅退出后保持停止。如需保持网关停止，请按下方[确认停机](https://tslink.md/zh/docs/daemon.md#%E7%A1%AE%E8%AE%A4%E5%81%9C%E6%9C%BA)操作。

## 信号处理

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

| 信号        | 平台                | 行为                               |
| --------- | ----------------- | -------------------------------- |
| `SIGTERM` | Unix（macOS、Linux） | 发起服务监听器和节点的关闭，然后退出               |
| `SIGINT`  | Unix（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
```

### Linux — systemd 用户服务

在 `~/.config/systemd/user/tslink.service` 创建 unit 文件。

* 作为用户服务运行（不需要 root）
* `Restart=on-failure`，`RestartSec=30`（重启尝试之间延迟 30 秒）
* `StartLimitIntervalSec=300` 和 `StartLimitBurst=5` 用于限制紧密失败循环
* 安装时通过 `systemctl --user` 自动启用并启动

未启用 lingering 时，用户服务随用户登录启动。`loginctl enable-linger "$USER"` 允许登出后继续运行，并在开机后无需登录即可启动。如果 lingering 只为 TSLink 启用，卸载后运行 `loginctl disable-linger "$USER"`。

安装后检查状态：

```bash
systemctl --user status tslink
journalctl --user -u tslink -f
```

### Windows — Task Scheduler

`tslink install` 注册交互用户 scheduled task，立即启动 TSLink，并在登录时再启动。任务运行内建 supervisor，以有界 backoff 恢复 daemon 崩溃。这是用户登录范围的运行方式，不是无需登录的开机服务。

查看实际监督信息：

```bash
tslink status --json
```

用 `data.supervision` 区分已验证的任务与 live supervisor，不能只看进程存活。Task Scheduler 不可用时，`tslink install --startup` 明确使用旧 Startup 脚本，没有崩溃恢复。迁移与失败恢复见 [TSLink Windows 监督说明](https://github.com/anydoor7/tslink/blob/v0.1.1/docs/daemon-lifecycle.md)。

### 移除自动启动

```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 时，才能继续维护。状态不确定时，先解决问题，再修改配置或启动另一个网关。

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

### 配置变更后重启

受管理运行时，先完成[确认停机](https://tslink.md/zh/docs/daemon.md#%E7%A1%AE%E8%AE%A4%E5%81%9C%E6%9C%BA)，再修改全局配置或凭据，最后带上之前选择的安装选项重新运行 `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 诊断。保留的请求与权限变更请用[访问历史](https://tslink.md/zh/docs/access-history.md)。

### 日志文件位置

| 文件                                     | 内容                                     |
| -------------------------------------- | -------------------------------------- |
| `~/.config/tslink/logs/tslink.out.log` | Daemon stdout                          |
| `~/.config/tslink/logs/tslink.err.log` | stderr 上的 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](https://tslink.md/zh/docs/experimental-roadmap.md#%E7%AE%A1%E7%90%86%E4%BB%AA%E8%A1%A8%E6%9D%BF%E5%92%8C-rest-api)。已交付自动化请使用带 `--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` 管理服务，注册表更改通过热重载生效，无需重启网关。