tailscale

Tailscale + Headscale 技能包

此整合技能涵盖使用 Headscale 作为开源控制服务的自托管 Tailscale 生态系统。它提供 7 个会根据上下文自动加载的子技能。

安全预检

在启用 SSH、Serve、Funnel、应用连接器、引导流程或更改控制平面暴露情况之前，请先阅读安全分流；遇到 Tailworm、疑似入侵或加固请求时，也请加载该文档。其通用客户端防护措施也适用于托管版 Tailscale；Headscale 操作仍仅适用于自托管环境。 不要仅仅因为此技能包的管理脚本面向 Headscale，就拒绝寻求这些防护措施的托管版用户。

采取行动前，请确认目标、范围和回滚方案。未经确认即可进行只读探查。 破坏性遏制措施（包括删除设备）必须得到用户的明确指示。 切勿为了方便而将 Tailscale SSH 设为默认启用。禁用之前，请保留并测试其他管理访问途径。 不要在用户的系统上运行公开的漏洞利用工具包。 结束时，请提供暴露面清单、受支持的缓解措施、已观察到的验证结果以及未解决的风险；如果进一步验证需要目前无法获取的证据或授权，请停止。

根据上下文自动加载

当用户的消息匹配触发关键词时，将加载对应子技能的 SKILL.md。 触发条件重叠时，可以同时加载多个子技能。

触发关键词	加载的子技能
"deploy headscale", "install headscale", "setup headscale server", "headscale config"	headscale-deploy
"ACL", "policy file", "tailnet policy", "access control", "grant", "tag owners"	tailnet-policy
"install tailscale", "connect to headscale", "tailscale client", "tailscale up", "tailscale status", "diagnose tailscale", "connectivity"	tailscale-client
"auth key", "preauthkey", "register node", "approve node", "tag node", "node list", "decommission node"	headscale-node-lifecycle
"subnet router", "exit node", "advertise route", "approve route"	headscale-routing
"DERP", "relay", "peer relay", "STUN"	headscale-derp
"backup headscale", "restore headscale", "migrate headscale", "headscale backup"	headscale-backup
"Tailscale", "Headscale", "tailnet", "mesh VPN", "WireGuard mesh", "self-hosted VPN"	加载此整合 SKILL.md 以进行导航

子技能顺序与依赖关系

headscale-deploy ─────┬──> tailnet-policy ───> headscale-routing
                       │
                       ├──> headscale-node-lifecycle
                       │
                       ├──> tailscale-client
                       │
                       ├──> headscale-derp
                       │
                       └──> headscale-backup (prerequisite: a running headscale instance)

• headscale-deploy 必须先完成——其他子技能都需要正在运行的 Headscale 服务
• tailnet-policy（配置 ACL）建议在向其他用户开放 tailnet 之前完成
• headscale-derp 是可选的，但建议启用以提高 NAT 环境下的可靠性
• 任何生产部署都应定期运行 headscale-backup

根目录脚本（共享工具）

这些脚本位于技能包根目录的 scripts/ 中，所有子技能均可使用。

可用脚本

脚本	用途	调用方式
scripts/headscale-health-check.sh	检查 Headscale 服务健康状况：版本、节点数量和数据库完整性。每次更改控制服务后运行；节点或客户端出现异常时，也应将其作为首个诊断步骤。	scripts/headscale-health-check.sh --json
scripts/headscale-backup.sh	根据已配置的 SQLite 和恢复路径，创建带校验和清单的 Headscale 归档。升级或迁移前运行；--dry-run 可预览而不写入。	scripts/headscale-backup.sh --dry-run --json
scripts/headscale-restore.sh	验证并恢复有清单支持的归档，并还原到归档中记录的目标路径。恢复期间运行；之后务必检查节点列表和策略。	scripts/headscale-restore.sh --backup headscale-backup-2026-01-01.tar.gz --dry-run --json
scripts/tailscale-status-json.sh	对 tailscale status --json 的结构化封装，并提供对等节点诊断信息。从任意客户端运行，即可检查连接、对等节点以及中继/直连路径的机器可读信息。	scripts/tailscale-status-json.sh
scripts/test-all.sh	对所有套件脚本进行冒烟测试（--help、语法、可执行性），无需运行中的 Headscale。修改套件中的任何脚本后运行；CI 会通过 scripts/check-skill-tests.py 运行此测试。	bash scripts/test-all.sh

模板

模板位于 templates/，涵盖常见的部署模式：

• templates/docker-compose-headscale.yaml — Headscale + 内置 DERP + Traefik TLS
• templates/headscale-config.yaml — 带注释的完整 Headscale 配置
• templates/policy-allow-all.json — 最简的允许所有策略
• templates/policy-deny-all.json — 锁定的拒绝所有策略
• templates/policy-tagged-segmented.json — 基于标签的访问模型
• templates/derp-map.json — 自定义 DERP 中继映射

环境变量

变量	使用者	用途
HEADSCALE_URL	全部	Headscale 服务 URL（例如 https://headscale.example.com）
HEADSCALE_API_KEY	全部	Headscale API 密钥（通过 headscale apikeys create 创建）
TAILSCALE_AUTHKEY	tailscale-client	用于非交互式客户端设置的预认证密钥

使用 CLI 工具

所有脚本都支持 --json、--dry-run，并提供详尽的 --help 输出。 相对于套件根目录的脚本路径：scripts/<tool> 或 skills/<sub-skill>/scripts/<tool>。

详细用法请参阅各子技能的 SKILL.md。

先决条件

• 运行脚本的主机上需安装 bash、Python 3.10+、jq 和 curl（参见 compatibility）。
• 服务器端操作需要运行中的 Headscale 服务，并设置 HEADSCALE_URL 和 HEADSCALE_API_KEY（通过 headscale apikeys create 创建 API 密钥）；非交互式客户端注册需要设置 TAILSCALE_AUTHKEY。
• 状态和路由子技能需要在目标机器上安装 tailscale 客户端；控制服务管理需要 headscale CLI（或 API 访问权限）。
• 对于 headscale-backup/restore：需要能够访问服务器上的 sqlite 数据库、配置、策略和证书路径，并准备好存储控制服务主机之外的归档。
• 对于迁移：在目标主机上与源辅助脚本的相同路径安装经过验证的恢复辅助脚本，或将 HEADSCALE_REMOTE_RESTORE_SCRIPT 设置为目标路径；恢复前准备好记录的归档路径和目录所有权。

限制

• 此工具包假设使用自托管的 Headscale 控制平面——它不会管理 Tailscale 托管的 SaaS（参见「何时不应使用」）。
• 脚本会在运行时检查环境变量；如果缺少变量，会提供明确的错误提示，但不会自行创建凭据。
• 备份/恢复操作针对控制服务器主机上现有的文件；无法恢复从未备份的数据，且恢复后应始终进行运行状况验证。
• 恢复操作接受清单版本为 1 的归档文件，并拒绝较旧的无清单 tarball。迁移要求在目标主机上安装经过验证的恢复助手，且不会回退到原始解包，也不会在未获得经过验证的恢复结果时报告成功。迁移前，请准备好归档路径和目标目录的所有权；在配置和服务路径分别更新并通过验证之前，会拒绝会移动文件的 root 覆盖操作。
• 子技能脚本位于 skills/<sub-skill>/scripts/ 下，并在各自的 SKILL.md 文件中说明，不在此处介绍。

何时不应使用

如果任务对应某个单一子技能，请勿加载此总览，而应直接加载匹配的子技能（例如 headscale-deploy、tailnet-policy、tailscale-client）。此总览假设使用自托管的 Headscale 控制服务器；对于托管控制平面的管理任务或非 Tailscale VPN 工具，请改用相应的网络技能。上述通用安全分类仍适用于托管版 Tailscale。