# Tailscale 集成

> 通过私有 Tailnet 接入 Agent、宿主机 tailscaled 状态观测、Tailscale 与 Headscale 控制面全局视图、回环身份认证以及 HTTPS Sidecar 部署。

URL: https://docs.serverbee.app/zh/docs/tailscale

ServerBee 在 Agent、Server、Web 控制台与 iOS 客户端中原生支持 [Tailscale](https://tailscale.com) 与自建 [Headscale](https://headscale.net) 网络。你可以让监控通信完全不暴露在公网之上，观测每台主机的 WireGuard 对端路径（`Direct` 直连与 `DERP` 中继），将 Tailnet 设备清单与已接入服务器自动关联，并通过 `*.ts.net` HTTPS 私密发布监控面板。

## 通过 Tailnet 连接 Agent [#通过-tailnet-连接-agent]

Agent 可以直接通过 Tailscale IPv4（`100.64.0.0/10`）、Tailscale IPv6（`fd7a:115c:a1e0::/48`）或 MagicDNS 域名（如 `https://serverbee.tailnet-name.ts.net`）完成首次注册并保持持久 WebSocket 连接，无需在公网暴露 `9527` 端口。

### 内置 CGNAT 与虚拟网卡保护机制 [#内置-cgnat-与虚拟网卡保护机制]

当主机同时运行 Tailscale 与 ServerBee 时，多项内置保护确保监控指标、GeoIP 和防火墙规则准确无误：

* **公网 IP 隔离**：Agent 与 Server 均将 RFC 6598 CGNAT（`100.64.0.0/10`）及 Tailscale ULA（`fd7a:115c:a1e0::/48`）视为非公网地址，`tailscale0` 地址不会覆盖服务器真实的公网 IPv4，也不会触发无效的 GeoIP 查询。
* **避免流量重复统计**：默认启用 `collector.exclude_tailscale_traffic = true`（`SERVERBEE_COLLECTOR__EXCLUDE_TAILSCALE_TRAFFIC=true`），在汇总主机实时速率与累计流量时跳过虚拟 `tailscale*` TUN 网卡，避免加密后的 WireGuard 流量与底层物理网卡重复计数。
* **防自锁护栏**：`100.64.0.0/10` 已纳入硬编码的 Tier-1 [防火墙黑名单](/zh/docs/firewall)保留段（`PROTECTED_CIDRS`）以及默认的 `server.trusted_proxies`，防止手动或自动封禁误断 Tailnet 管理连接。

### 「添加服务器」Tailnet URL 切换开关 [#添加服务器tailnet-url-切换开关]

当 Server 配置了 `preferred_server_url`（`SERVERBEE_TAILSCALE__PREFERRED_SERVER_URL`），或通过本地 `tailscaled` Unix Socket 自动识别出自身的 MagicDNS 域名 / `100.x` 地址时，`GET /api/tailscale/overview` 会返回 `server_tailnet_url`。

在 **服务器 → 添加服务器** 弹窗中，只要 `server_tailnet_url` 与当前浏览器访问地址不同，界面就会自动提供 **使用 Tailnet 地址** 切换开关，一键将一键安装命令中的 `--server-url` 切换为 Server 的 Tailnet 地址——即使你当前是通过公网域名或本地端口转发打开控制台，新接入的 Agent 也能直接走 Tailnet 私网连接：

```bash
curl -fsSL https://raw.githubusercontent.com/ZingerLittleBee/ServerBee/main/deploy/install.sh | sudo sh -s -- agent \
  --server-url https://serverbee.tailnet-name.ts.net \
  --enrollment-code YOUR_ONE_TIME_CODE
```

### 在 Docker 中运行 Agent [#在-docker-中运行-agent]

通过二进制 + systemd 安装的 Agent 可直接访问宿主机的 `tailscaled` Unix Socket。若采用 [Docker 方式运行 Agent](/zh/docs/agent#docker不推荐)，请将宿主机的 `tailscaled.sock` 以只读方式挂载进容器，以便 Agent 直接查询 LocalAPI 状态：

```bash
docker run -d \
  --name serverbee-agent \
  --privileged \
  --net=host \
  --pid=host \
  -v /proc:/host/proc:ro \
  -v /sys:/host/sys:ro \
  -v /etc/os-release:/host/etc/os-release:ro \
  -v /var/run/tailscale/tailscaled.sock:/var/run/tailscale/tailscaled.sock:ro \
  -v /opt/serverbee-agent:/etc/serverbee \
  --restart unless-stopped \
  ghcr.io/zingerlittlebee/serverbee-agent:1.0.0-beta.7
```

如果宿主机的 Socket 位于自定义路径，请挂载对应路径并设置 `SERVERBEE_TAILSCALE__SOCKET_PATH`（或在 `agent.toml` 中设置 `[tailscale] socket_path`）。

## 宿主机 `tailscaled` 状态观测 [#宿主机-tailscaled-状态观测]

当 **`tailscale`** 能力（`CAP_TAILSCALE`，位 11 / `2048`）处于生效状态时，每台 Agent 会自动探测并上报本机 `tailscaled` 守护进程状态。

* **能力归属 Agent 主机**：`tailscale` 属于**低风险**能力，**默认开启**（`CAP_DEFAULT = 3900`）。与所有[功能开关](/zh/docs/capabilities)一致，该能力完全由 Agent 主机本地控制——如需在某台机器上关闭 Tailscale 状态上报，可在 `agent.toml` 的 `[capabilities].deny` 中加入 `"tailscale"`，或传入 `--deny-cap tailscale`。
* **采集方式**：在 Unix 主机上，Agent 通过 Unix Domain Socket 请求 `tailscaled` LocalAPI 的 `GET /localapi/v0/status`（按顺序探测 `tailscale.socket_path`、`/var/run/tailscale/tailscaled.sock`、`/run/tailscale/tailscaled.sock`、`/var/run/tailscaled.socket`，超时时间 3 秒）。若 Socket 不可达、权限不足或运行在非 Unix 平台，则自动回退到执行 `tailscale status --json`。

### 观测指标与对端路径诊断 [#观测指标与对端路径诊断]

检测到可用的 `tailscaled` 后，Agent 会在 `SystemInfo.features` 中声明 `"tailscale"`，每 60 秒周期性同步快照，并响应 `GET /api/servers/{id}/tailscale/status` 的按需实时查询。Web 控制台的 **服务器详情 → Tailscale** 页面（`/servers/{id}/tailscale`）与 iOS 客户端的 **服务器详情 → Tailscale** 视图（`ServerTailscaleView`）均会展示：

* **节点概览**：后端运行状态（`Running`、`NeedsLogin`、`Stopped`）、主 Tailscale IPv4 与 IPv6、MagicDNS 域名、Tailnet 名称、客户端版本、DERP 主区域、Exit Node 状态（`exit_node` / `exit_node_option`）、通告的子网路由（Advertised Routes）、ACL 标签（Tags）以及健康告警（Health Warnings）。
* **密钥过期（Key Expiry）追踪**：展示节点密钥过期时间与剩余时长，便于在无人值守服务器因密钥过期掉线前及时续期或关闭密钥过期。
* **对端连接模式（Connection Mode）**：展示每个 Peer 的操作系统、Tailscale IP、收发字节数、最近一次 WireGuard 握手时间，以及实时连接路径分类：
  * **Direct（直连）** —— 已建立 UDP WireGuard 点对点直连隧道（存在活跃 `cur_addr`），具备最高吞吐与最低延迟。
  * **DERP（中继）** —— 流量正通过 Tailscale DERP 中继节点转发（如 `DERP (tok)`、`DERP (sfo)`）。若高流量节点长期处于 `DERP` 模式，通常意味着严格 NAT 或防火墙拦截了 UDP 打洞。
  * **Peer Relay（对端中继）** —— 通过对端中继节点转发。
  * **Idle（空闲）** —— 已知对端节点，当前无活跃隧道流量。

Server 同时会将每台主机的主 `tailscale_ipv4`、`tailscale_ipv6`、`tailscale_dns_name` 和 `tailscale_tailnet` 持久化在服务器记录中；即使 Agent 暂时离线，控制台依然可以展示并搜索最后已知的 Tailnet 地址（`cached: true`）。

## 控制面 API 集成与仪表盘组件 [#控制面-api-集成与仪表盘组件]

单机 `CAP_TAILSCALE` 反映每台 Agent 本地看到的 WireGuard 状态，而 Server 端可选的控制面集成则直接查询 **Tailscale 官方控制面**（API v2，`/api/v2/tailnet/{tailnet}/devices`）或自建 **Headscale**（API v1，`/api/v1/node`，兼容 Headscale v0.26+ 标签结构）的全局设备清单。

### 配置 Tailscale 或 Headscale [#配置-tailscale-或-headscale]

你可以通过 `server.toml` / `SERVERBEE_TAILSCALE__*` 环境变量静态配置（参见[配置参考](/zh/docs/configuration)），也可以在 Web 控制台的 **设置 → Tailscale**（或 iOS 客户端的 **设置 → 管理 → Tailscale**）中动态配置。UI 保存的运行时设置会覆盖配置文件与环境变量默认值。

| 提供方           | `provider`    | `api_base_url`                                       | `tailnet`                 | 凭据（`api_key`）                                 |
| ------------- | ------------- | ---------------------------------------------------- | ------------------------- | --------------------------------------------- |
| **Tailscale** | `"tailscale"` | `"https://api.tailscale.com"`                        | `"-"`（密钥所属默认 Tailnet）或组织名 | 只读 API Access Token（`tskey-api-...`）          |
| **Headscale** | `"headscale"` | 自建 Headscale 地址（如 `"https://headscale.example.com"`） | `"-"`（可选）                 | Headscale API Key（`headscale apikeys create`） |

控制面配置的安全边界：

* `api_key` 在管理接口中仅可写入不可读回：`GET /api/tailscale/config` 仅返回 `has_api_key: true | false`，绝不会在响应或日志中回显明文密钥。更新配置时将 API Key 留空即可保留已保存的密钥。
* 自定义 `api_base_url` 会经过 ServerBee 的 SSRF 安全校验：严格拦截回环地址（`127.0.0.0/8`、`::1`）与云厂商元数据地址（`169.254.169.254`），同时允许部署在内网 LAN 或 Tailnet 上的自建 Headscale 实例。
* 保存前可使用 **测试连接**（`POST /api/tailscale/test`）验证凭据有效性并查看发现的设备数量。

### 自动关联服务器与 `com.serverbee.tailscale-overview` 组件 [#自动关联服务器与-comserverbeetailscale-overview-组件]

`GET /api/tailscale/overview`（服务端内置 30 秒短期缓存，避免频繁请求上游 API）会按 Tailscale IPv4/IPv6、上报的 IPv4、MagicDNS 域名或主机名将每台 Tailnet 设备与已接入的 ServerBee 服务器自动匹配：

* **设置 → Tailscale** 汇总展示全局指标（**总设备数**、**在线设备**、**已关联 ServerBee 服务器**、**即将过期密钥**），已匹配设备可直接跳转到对应的 `/servers/{id}` 详情页。
* **内置仪表盘组件（`com.serverbee.tailscale-overview`）**：可在任意[自定义仪表盘](/zh/docs/dashboards)的组件选择器中添加 **Tailscale 概览（Tailscale Overview）** 组件，一屏查看 Tailnet 在线节点数、已关联监控主机数及临近过期的节点密钥数量。

## 原生 iOS 客户端支持 [#原生-ios-客户端支持]

[iOS 移动客户端](/zh/docs/mobile)提供完整的原生 SwiftUI 视图，覆盖单机 Tailscale 诊断与全局 Tailnet 管理：

* **服务器详情 → Tailscale（`ServerTailscaleView`）**：当服务器开启 `CAP_TAILSCALE` 并上报实时 `tailscaled` 状态或持久化 Tailnet 地址时，详情页会展示 Tailscale 导航卡片。点开可查看后端运行状态、支持一键复制的 Tailscale IPv4/IPv6 与 MagicDNS 行、DERP 主区域、密钥过期预警、Exit Node 与子网路由标签、ACL 标签、健康告警，以及带 `Direct`、`DERP`、`Peer Relay`、`Idle` 状态徽章的对端列表（含活跃端点、收发流量、最近握手时间及离线缓存快照提示）。
* **设置 → 管理 → Tailscale（`TailscaleAdminView`）**：管理员可配置 Tailscale 或 Headscale 控制面凭据、已保存的 API Key、首选 Server 地址及 Tailscale Serve 回环认证，执行 **测试连接**，并通过 `TailnetOverviewSection` 查看全局设备清单并直接跳转到已关联的服务器详情；只读成员亦可查看 Tailnet 概览与设备列表。
* **隐私模式 IP 打码**：开启 **设置 → 隐私模式** 后，所有卡片与列表中的 Tailscale IPv4/IPv6 地址、对端 Endpoint、子网路由、含 IP 的主机名及 Tailnet URL 均会自动隐藏后两段，而复制操作与编辑输入框仍保留真实完整地址。

## 身份认证方案 [#身份认证方案]

ServerBee 支持两种基于 Tailscale 身份的登录方式，可按部署架构择一或组合使用。

### 方案一：通过 `[oauth.oidc]` 接入 Tailscale OIDC（`tsidp`） [#方案一通过-oauthoidc-接入-tailscale-oidctsidp]

如果你在 Tailnet 内运行了 Tailscale 官方 OIDC Identity Provider（`tsidp`），或使用配合 Pocket ID、Authelia、Authentik 等外部 IdP 的 Headscale，可直接接入 ServerBee 标准的 OpenID Connect 配置：

```toml
[oauth]
base_url = "https://serverbee.tailnet-name.ts.net"
# 仅当你的 OIDC 提供方已通过 Tailnet ACL / 组织成员范围严格受控时才可开启：
allow_registration = false

[oauth.oidc]
issuer_url = "https://idp.tailnet-name.ts.net"
client_id = "your-tsidp-client-id"
client_secret = "your-tsidp-client-secret"
scopes = ["openid", "email", "profile"]
```

由于该方式走标准 OAuth2 授权码重定向流程而不依赖受信任请求头，因此无论 ServerBee 部署在反向代理后、另一台 Tailnet 节点还是云平台上均可安全工作。详见[安全设置 → OAuth 社交登录](/zh/docs/security#oauth-社交登录)。

### 方案二：Tailscale Serve 回环身份认证 [#方案二tailscale-serve-回环身份认证]

当 `tailscale serve` 与 `serverbee-server` 运行在**同一台宿主机或共享同一个容器网络命名空间**时，Tailscale 会在本地终止 Tailnet TLS，并在转发至回环地址的请求中注入 `Tailscale-User-Login` 请求头。开启 `SERVERBEE_TAILSCALE__AUTH_ENABLED=true`（`tailscale.auth_enabled = true`）后，浏览器访问 HTTP API 与升级实时 WebSocket 时均可免密登录。

<Callout type="warn">
  **回环安全边界（Loopback Security Boundary）：** 一旦从不可信网络对端或普通反向代理接受身份请求头，攻击者便可轻易伪造登录身份。因此 ServerBee 在信任 `Tailscale-User-Login` 前强制执行两条硬性边界：

  1. `tailscale.auth_enabled` **默认关闭（`false`）**。
  2. 即使显式开启，ServerBee 也**仅在同时满足以下两个条件时**才接受 `Tailscale-User-Login`：底层 TCP 连接对端（`ConnectInfo`）严格为回环地址（`127.0.0.1` 或 `::1`），**且**请求中不存在 `X-Forwarded-For` 或 `Forwarded` 转发头（若本地 `tailscaled` Unix Socket 可达，ServerBee 还会通过 `/localapi/v0/whois` 交叉核验对端身份）。

  任何来自非回环 IP、或携带 `X-Forwarded-For` / `Forwarded` 头的 `Tailscale-User-Login` 请求都会直接返回 `401 Unauthorized`。启用此模式时，请将 `server.listen` 绑定在 `127.0.0.1:9527`，确保所有外部与 Tailnet 流量都只能经由本机 `tailscale serve` 进入。
</Callout>

Tailscale Serve 认证下的账号映射与权限控制：

* ServerBee 将 `Tailscale-User-Login` 与现有用户匹配（完整邮箱匹配、唯一邮箱前缀匹配或已绑定的 OAuth 身份），并继续对首次启动生成的初始管理员账号执行 `must_change_password` 强制改密检查。
* 默认情况下（`auto_provision_role = ""`），未匹配的 Tailnet 用户会被拒绝访问，需由管理员预先创建账号。
* 将 `auto_provision_role` 设为 `"member"`（`SERVERBEE_TAILSCALE__AUTO_PROVISION_ROLE=member`）可在新 Tailnet 用户首次访问时自动创建只读 **Member** 账号。**系统绝不会自动创建 `admin` 管理员账号。**

## HTTPS Sidecar 部署（`*.ts.net`） [#https-sidecar-部署tsnet]

仓库内置的 `deploy/docker-compose.tailscale.yml` 提供了开箱即用的生产级 Docker Compose 模板，将 `tailscale/tailscale:latest` 与 `serverbee-server` 组合在共享网络命名空间中运行。

### 为什么 Web 与 iOS 客户端需要 `*.ts.net` HTTPS [#为什么-web-与-ios-客户端需要-tsnet-https]

* **Web 控制台**：ServerBee 默认对会话 Cookie 启用 `HttpOnly` + `Secure`（`auth.secure_cookie = true`）。通过 `https://<hostname>.<tailnet>.ts.net` 访问可在保持 Cookie 安全属性的前提下满足浏览器安全上下文、剪贴板复制及 `wss://` WebSocket 要求。
* **iOS 移动端客户端**：Apple App Transport Security（ATS）、二维码扫码配对、移动端 Access/Refresh Token 轮换以及[已验证移动推送注册](/zh/docs/mobile)均要求服务端具备受 iOS 系统信任的 HTTPS 证书。由于 Tailscale HTTPS 为 `*.ts.net` MagicDNS 域名自动签发公开受信任的 **Let's Encrypt** 证书，只要 iPhone 开启 Tailscale VPN 连接至同一 Tailnet，iOS 客户端即可直接安全接入，无需手动安装自签名根证书。（注：原生 iOS 客户端通过 `https://<hostname>.<tailnet>.ts.net` 使用移动端令牌认证，不使用仅面向浏览器的 `Tailscale-User-Login` 请求头。）

### 使用 `deploy/docker-compose.tailscale.yml` 快速部署 [#使用-deploydocker-composetailscaleyml-快速部署]

1. 在 Tailscale 管理控制台的 **DNS** 页面同时开启 **MagicDNS** 与 **HTTPS Certificates**，然后在 **Settings → Keys** 中生成 Auth Key（`tskey-auth-...`）。
2. 在部署目录创建 `config/ts-serve.json`，让 `tailscale serve` 将 `443` 端口 HTTPS 反向代理到容器共享回环上的 `http://127.0.0.1:9527`：

```bash
mkdir -p config
cat > config/ts-serve.json <<'EOF'
{
  "TCP": {
    "443": {
      "HTTPS": true
    }
  },
  "Web": {
    "${TS_CERT_DOMAIN}:443": {
      "Handlers": {
        "/": {
          "Proxy": "http://127.0.0.1:9527"
        }
      }
    }
  }
}
EOF
```

3. 使用 `deploy/docker-compose.tailscale.yml` 部署（下方示例固定为当前发布镜像版本）：

```yaml
services:
  tailscale:
    image: tailscale/tailscale:latest
    container_name: serverbee-tailscale
    hostname: serverbee
    restart: unless-stopped
    environment:
      - TS_AUTHKEY=${TS_AUTHKEY:-}
      - TS_STATE_DIR=/var/lib/tailscale
      - TS_SERVE_CONFIG=/config/ts-serve.json
      - TS_USERSPACE=false
    volumes:
      - tailscale-state:/var/lib/tailscale
      - tailscale-sock:/var/run/tailscale
      - ./config/ts-serve.json:/config/ts-serve.json:ro
    devices:
      - /dev/net/tun:/dev/net/tun
    cap_add:
      - NET_ADMIN
      - NET_RAW

  serverbee-server:
    image: ghcr.io/zingerlittlebee/serverbee-server:1.0.0-beta.7
    container_name: serverbee-server
    restart: unless-stopped
    network_mode: service:tailscale
    depends_on:
      - tailscale
    volumes:
      - serverbee-data:/data
      - tailscale-sock:/var/run/tailscale:ro
    environment:
      - SERVERBEE_SERVER__LISTEN=127.0.0.1:9527
      - SERVERBEE_SERVER__DATA_DIR=/data
      - SERVERBEE_AUTH__SECURE_COOKIE=true
      - SERVERBEE_TAILSCALE__SOCKET_PATH=/var/run/tailscale/tailscaled.sock
      - SERVERBEE_TAILSCALE__AUTH_ENABLED=false
    healthcheck:
      test: ["CMD", "wget", "--spider", "-q", "http://127.0.0.1:9527/healthz"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s

volumes:
  tailscale-state:
  tailscale-sock:
  serverbee-data:
```

4. 启动容器并从 Server 日志中获取首次启动生成的管理员随机密码：

```bash
TS_AUTHKEY=tskey-auth-YOUR_KEY docker compose -f deploy/docker-compose.tailscale.yml up -d
docker compose -f deploy/docker-compose.tailscale.yml logs serverbee-server
```

首次访问时 `tailscale` 会自动完成 Let's Encrypt 证书签发，随后即可在接入同一 Tailnet 的任意设备上打开 `https://serverbee.<tailnet>.ts.net`。

<Cards>
  <Card title="配置参考" href="/zh/docs/configuration" />

  <Card title="功能开关" href="/zh/docs/capabilities" />

  <Card title="部署指南" href="/zh/docs/deployment" />

  <Card title="iOS 移动端" href="/zh/docs/mobile" />
</Cards>
