用途:部署自托管 Headscale 控制服务器(Tailscale 控制端的开源实现),适用于在 Linux 或 Docker 环境从零搭建新实例、配置服务器参数、管理 DERP 中继基础设施以及诊断部署问题。
主要能力:提供 Docker Compose 与二进制两种部署方式;Docker Compose 可用 install-headscale.sh 配合 --docker 生成 compose 文件与 systemd drop-in,也可手动创建(镜像 headscale/headscale:latest,端口 8080 与 3478/udp,命令 headscale serve)。二进制安装脚本负责识别平台、下载 GitHub 发布包、安装至 /usr/local/bin、创建 headscale 系统用户、编写 systemd 单元以及生成 /etc/headscale/config.yaml。支持配置 server_url、listen_addr、metrics_listen_addr、dns_config、derp.server、derp.urls、db_type(sqlite3 或 postgres)及 TLS 相关选项。
验证方式:curl -s https://headscale.example.com/health 做健康检查;headscale-health-check.sh --json 做综合诊断;headscale nodes list 查看已注册节点;headscale apikeys list 验证 API 访问。
前提:Linux(x86_64 或 aarch64)或支持 compose 的 Docker 主机、指向服务器的 DNS 记录、可用的 80/443 端口、可选的 3478/udp(STUN)及 root 或 sudo 权限。
限制与注意事项:SQLite 适合小于 100 节点的小型 tailnet,更大或高可用场景应选 PostgreSQL,且迁移不易;Let's Encrypt 自动签发需要 80 端口可访问,也可用反向代理;端口冲突需改 listen_addr;嵌入式 DERP 适合小型部署,生产建议专用 DERP 节点;Headscale 不支持热重载配置,修改后需 systemctl restart headscale 或 docker compose restart;应定期备份数据库。该技能只覆盖初始部署与服务器配置,不涉及客户端设置、ACL/策略编写或已运行服务器的日常管理。