headscale 是 Tailscale 控制服务器的开源自托管实现，目标是为自托管爱好者提供一个开源、可自建的 Tailscale 控制面。它实现一个独立的 tailnet，适合个人或小团队使用。
一、项目官方信息
| 项目 | 信息 |
|---|---|
| GitHub 仓库 | https://github.com/juanfont/headscale |
| 官方文档 | https://headscale.net/stable/ |
| 开源协议 | BSD-3-Clause |
| 主要语言 | Go（约 98.8%） |
| Star 数 | 约 45.0k |
注意：headscale 与 Tailscale Inc 无官方关系，但有一名活跃维护者受雇于 Tailscale。
二、官方图片
headscale 官方 Logo：
三、环境要求
- Linux 服务器（官方推荐直接跑二进制，不鼓励反代/容器）。
- 公开域名（用于 TLS 与客户端发现）。
- 反向代理（可选，但官方不鼓励）。
- SQLite/PostgreSQL（默认 SQLite）。
四、完整部署步骤
1. 下载二进制
到 https://github.com/juanfont/headscale/releases 下载对应版本：
wget https://github.com/juanfont/headscale/releases/download/v0.24.0/headscale_0.24.0_linux_amd64.deb
sudo dpkg -i headscale_0.24.0_linux_amd64.deb
或用 tar.gz。
2. 配置
编辑 /etc/headscale/config.yaml（或 config-example.yaml）：
server_url: https://hs.example.com:8443
listen_addr: 0.0.0.0:8443
metrics_listen_addr: 127.0.0.1:9090
db_type: sqlite3
db_path: /var/lib/headscale/db.sqlite
base_domain: example.com
3. 启动
sudo headscale serve
systemd：
sudo systemctl enable --now headscale
4. 创建用户（tailnet）
sudo headscale users create myuser
5. 注册节点
在客户端生成注册命令：
sudo headscale nodes register --user myuser --key <client-key>
或在客户端用 --login-server 启动后授权：
tailscale up --login-server https://hs.example.com:8443
6. 查看节点
sudo headscale nodes list
五、使用方法
常用命令
headscale users list
headscale nodes list
headscale nodes expire <id>
headscale nodes delete <id>
headscale preauthkeys create --user myuser
预授权密钥
为自动注册生成一次性密钥：
headscale preauthkeys create --user myuser --expiration 1h
客户端：
tailscale up --login-server https://hs.example.com:8443 --authkey <key>
路由与出口节点
在 headscale 中批准路由：
headscale nodes routes list <id>
headscale nodes routes approve <id> <route>
客户端支持
Linux/macOS/Windows/iOS/Android 客户端均可对接，详见 https://headscale.net/stable/about/clients/ 。
六、常见问题 FAQ
1. 官方不推荐 Docker？ README 明确说不支持/不鼓励反代与容器方式，建议直接跑二进制。
2. 客户端连不上？
确认 server_url 可达；TLS 证书有效；客户端 --login-server 地址正确。
3. 如何升级？ 下载新版本二进制替换，重启服务；数据库自动迁移。
4. 支持多 tailnet 吗？ 设计上是单 tailnet（多 user），适合个人/小团队。
5. 与官方 Tailscale 兼容吗？ 客户端协议兼容，但控制面功能可能滞后于官方。
6. 如何开发？
需 Go 最新版 + Buf；用 nix develop 准备环境。