Tailscale 集成
通过私有 Tailnet 接入 Agent、宿主机 tailscaled 状态观测、Tailscale 与 Headscale 控制面全局视图、回环身份认证以及 HTTPS Sidecar 部署。
ServerBee 在 Agent、Server、Web 控制台与 iOS 客户端中原生支持 Tailscale 与自建 Headscale 网络。你可以让监控通信完全不暴露在公网之上,观测每台主机的 WireGuard 对端路径(Direct 直连与 DERP 中继),将 Tailnet 设备清单与已接入服务器自动关联,并通过 *.ts.net HTTPS 私密发布监控面板。
通过 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 与虚拟网卡保护机制
当主机同时运行 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 防火墙黑名单保留段(PROTECTED_CIDRS)以及默认的server.trusted_proxies,防止手动或自动封禁误断 Tailnet 管理连接。
「添加服务器」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 私网连接:
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
通过二进制 + systemd 安装的 Agent 可直接访问宿主机的 tailscaled Unix Socket。若采用 Docker 方式运行 Agent,请将宿主机的 tailscaled.sock 以只读方式挂载进容器,以便 Agent 直接查询 LocalAPI 状态:
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 状态观测
当 tailscale 能力(CAP_TAILSCALE,位 11 / 2048)处于生效状态时,每台 Agent 会自动探测并上报本机 tailscaled 守护进程状态。
- 能力归属 Agent 主机:
tailscale属于低风险能力,默认开启(CAP_DEFAULT = 3900)。与所有功能开关一致,该能力完全由 Agent 主机本地控制——如需在某台机器上关闭 Tailscale 状态上报,可在agent.toml的[capabilities].deny中加入"tailscale",或传入--deny-cap tailscale。 - 采集方式:在 Unix 主机上,Agent 通过 Unix Domain Socket 请求
tailscaledLocalAPI 的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(空闲) —— 已知对端节点,当前无活跃隧道流量。
- Direct(直连) —— 已建立 UDP WireGuard 点对点直连隧道(存在活跃
Server 同时会将每台主机的主 tailscale_ipv4、tailscale_ipv6、tailscale_dns_name 和 tailscale_tailnet 持久化在服务器记录中;即使 Agent 暂时离线,控制台依然可以展示并搜索最后已知的 Tailnet 地址(cached: true)。
控制面 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
你可以通过 server.toml / SERVERBEE_TAILSCALE__* 环境变量静态配置(参见配置参考),也可以在 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 组件
GET /api/tailscale/overview(服务端内置 30 秒短期缓存,避免频繁请求上游 API)会按 Tailscale IPv4/IPv6、上报的 IPv4、MagicDNS 域名或主机名将每台 Tailnet 设备与已接入的 ServerBee 服务器自动匹配:
- 设置 → Tailscale 汇总展示全局指标(总设备数、在线设备、已关联 ServerBee 服务器、即将过期密钥),已匹配设备可直接跳转到对应的
/servers/{id}详情页。 - 内置仪表盘组件(
com.serverbee.tailscale-overview):可在任意自定义仪表盘的组件选择器中添加 Tailscale 概览(Tailscale Overview) 组件,一屏查看 Tailnet 在线节点数、已关联监控主机数及临近过期的节点密钥数量。
原生 iOS 客户端支持
iOS 移动客户端提供完整的原生 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)
如果你在 Tailnet 内运行了 Tailscale 官方 OIDC Identity Provider(tsidp),或使用配合 Pocket ID、Authelia、Authentik 等外部 IdP 的 Headscale,可直接接入 ServerBee 标准的 OpenID Connect 配置:
[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 社交登录。
方案二:Tailscale Serve 回环身份认证
当 tailscale serve 与 serverbee-server 运行在同一台宿主机或共享同一个容器网络命名空间时,Tailscale 会在本地终止 Tailnet TLS,并在转发至回环地址的请求中注入 Tailscale-User-Login 请求头。开启 SERVERBEE_TAILSCALE__AUTH_ENABLED=true(tailscale.auth_enabled = true)后,浏览器访问 HTTP API 与升级实时 WebSocket 时均可免密登录。
回环安全边界(Loopback Security Boundary): 一旦从不可信网络对端或普通反向代理接受身份请求头,攻击者便可轻易伪造登录身份。因此 ServerBee 在信任 Tailscale-User-Login 前强制执行两条硬性边界:
tailscale.auth_enabled默认关闭(false)。- 即使显式开启,ServerBee 也仅在同时满足以下两个条件时才接受
Tailscale-User-Login:底层 TCP 连接对端(ConnectInfo)严格为回环地址(127.0.0.1或::1),且请求中不存在X-Forwarded-For或Forwarded转发头(若本地tailscaledUnix 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 进入。
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)
仓库内置的 deploy/docker-compose.tailscale.yml 提供了开箱即用的生产级 Docker Compose 模板,将 tailscale/tailscale:latest 与 serverbee-server 组合在共享网络命名空间中运行。
为什么 Web 与 iOS 客户端需要 *.ts.net 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 轮换以及已验证移动推送注册均要求服务端具备受 iOS 系统信任的 HTTPS 证书。由于 Tailscale HTTPS 为
*.ts.netMagicDNS 域名自动签发公开受信任的 Let's Encrypt 证书,只要 iPhone 开启 Tailscale VPN 连接至同一 Tailnet,iOS 客户端即可直接安全接入,无需手动安装自签名根证书。(注:原生 iOS 客户端通过https://<hostname>.<tailnet>.ts.net使用移动端令牌认证,不使用仅面向浏览器的Tailscale-User-Login请求头。)
使用 deploy/docker-compose.tailscale.yml 快速部署
- 在 Tailscale 管理控制台的 DNS 页面同时开启 MagicDNS 与 HTTPS Certificates,然后在 Settings → Keys 中生成 Auth Key(
tskey-auth-...)。 - 在部署目录创建
config/ts-serve.json,让tailscale serve将443端口 HTTPS 反向代理到容器共享回环上的http://127.0.0.1:9527:
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- 使用
deploy/docker-compose.tailscale.yml部署(下方示例固定为当前发布镜像版本):
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:- 启动容器并从 Server 日志中获取首次启动生成的管理员随机密码:
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。