周五晚上在公司改代码,突然要用家里那台 NAS 上的数据集。传网盘太慢,开远程桌面又卡。如果三台机器在同一个局域网里,一条 scp 命令就完了。headscale 做的就是这件事:把散在异地的机器,重新连成一张属于你自己的私有局域网。
项目名片
| 项目 | 内容 |
|---|---|
| 仓库 | juanfont/headscale |
| 数据 | star 45,702 / fork 2,641(2026-11-15 抓取) |
| 技术栈 | Go |
| 许可证 | BSD-3-Clause(LICENSE 原文确认) |
| 最新版本 | v0.29.7(2026-10-30 发布) |
| 默认端口 | 8080(HTTP)/ 9090(指标) |
它解决什么问题
Tailscale 基于 WireGuard,能让设备之间打洞直连,但它的控制服务器(负责交换公钥、分配虚拟 IP)只跑在官方云上,免费版有设备数上限,节点清单也存在别人手里。headscale 把控制服务器这一环搬到你自己的 VPS 上:注册、发钥、记账都在自家完成,设备之间的流量仍然走 WireGuard 直连,不经过你的服务器,也就不占你那台小机器的带宽。
一句话说清边界:它替掉的是官方控制服务器这一环,替不掉的是 Windows、macOS、iOS 上的图形客户端——这些仍是闭源的,你装的 Tailscale 客户端还是官方那个,只是登录后指向你自己的服务器。另外两端能打洞直连的前提是网络环境不太极端,遇到对称型 NAT 打不通时还得靠中继,这部分体验和官方网络有差距。
核心机制
- 控制服务器只做「介绍人」:交换各节点的 WireGuard 公钥、分配 100 开头的虚拟 IP,不转发业务流量。(推断:这也是它敢把控制面自建的原因——控制面泄露的只是拓扑信息,不是数据本身。)
- 节点注册靠预授权密钥:服务器生成一次性 key,客户端
tailscale up时带上即可入网,默认一小时有效、只能用一次,避免长期密钥躺在命令历史里。 - 配置全部落在一个 YAML 文件:
/etc/headscale/config.yaml,改完systemctl restart headscale生效,没有隐藏的数据库要单独初始化。 - 默认只监听
127.0.0.1:8080(v0.29.7 示例配置第 19 行),公网可达必须手动改成0.0.0.0:8080,这是新装机最容易漏的一步。
跑起来
官方推荐 Debian/Ubuntu 用 DEB 包安装(以下命令 2026-11-15 按官方文档核对):
D="headscale_0.29.7_linux_amd64.deb"
B="https://github.com/juanfont/headscale"
wget "$B/releases/download/v0.29.7/$D"
sudo apt install ./$D
sudo nano /etc/headscale/config.yaml
sudo systemctl restart headscale
sudo systemctl status headscale
配置文件里至少改两处:
server_url: "http://203.0.113.10:8080"
listen_addr: "0.0.0.0:8080"
203.0.113.10 换成你服务器的公网 IP。改完先在浏览器开 http://服务器IP:8080/health,能看到 Healthy 再进下一步。
如果你已经有一套容器环境,也可以用 Docker 跑,但要注意官方 README 原文写了「不支持也不鼓励用容器和反向代理运行 headscale」,出了问题社区也偏向让你先换原生安装再排查:
docker run -d --name headscale \
-v /var/lib/headscale:/var/lib/headscale \
-v /etc/headscale:/etc/headscale \
-p 8080:8080 \
headscale/headscale:0.29.7 serve
从零到能用
- 服务器上建一个用户:
sudo headscale users create work。 - 生成预授权密钥:
sudo headscale preauthkeys create --user 1,记下输出的 key,一小时后要重新生成。 - 客户端装好 Tailscale 后执行(分成三行更清楚):
tailscale up \
--login-server http://服务器IP:8080 \
--authkey 刚才生成的key
- 回服务器执行
sudo headscale nodes list,能看到新节点和它拿到的 100 开头 IP。 - 在两台客户端之间互相 ping 对方的 100 开头地址,通了就说明打洞成功,延迟通常和你直连公网差不多。
- 以后要加新机器,重复第 2 到第 4 步,每台一分钟;想删设备用
sudo headscale nodes delete,节点列表里能看到编号。
适合谁用 / 别用
适合:有一台公网 VPS,想把家里的 NAS、树莓派和公司的电脑连起来的个人开发者,或者三五人的小团队,愿意偶尔敲命令做管理,看重的点是把节点清单握在自己手里。
别用:想要图形控制台、单点登录和精细 ACL 面板的公司——headscale 至今没有官方 Web 界面(issue #234,59 条讨论,截至 2026-11-15 仍开放),所有管理靠命令行完成,成员多了会累。另外它只维护单个网络,官方文档也把定位写明是给个人和小型开源组织用的,别拿它当企业组网方案。
三个真实的坑
- 默认只监听本机回环地址,客户端一律连不上,现象是 health 页面能开、注册却超时。出处:v0.29.7 的
config-example.yaml第 18 到 19 行,listen_addr默认值是127.0.0.1:8080,注释掉的示例才是0.0.0.0。 - 客户端挂上 exit node(出口节点)之后,外网域名解析会失败:ping 公网 IP 正常,走
100.100.100.100这个虚拟 DNS 解析不通,全网业务跟着断。出处:issue #2234,截至 2026-11-15 仍为开放状态。 - 节点数量上去之后,
headscale nodes list这类命令输出明显变慢,有用户报告 24 个节点要等 10 秒才出结果,日常巡检会很磨人。出处:issue #3119,报告于 2025 年,最近版本仍未彻底解决。
小结
回到周五晚上那个场景:装好 headscale 之后,公司电脑和家里 NAS 各执行一次 tailscale up,两台机器就都在同一张 100 开头的局域网里了,scp 直接可用,不用再往网盘里倒腾文件。控制面在你自己的服务器上,流量走 WireGuard 直连。代价是没有图形界面,且部署时务必记得改默认监听地址那一步。
参考资料
- 仓库:https://github.com/juanfont/headscale
- 官方文档:https://headscale.net/stable/
- 安装文档:https://headscale.net/stable/setup/install/official/
- v0.29.7 发布页:https://github.com/juanfont/headscale/releases/tag/v0.29.7
- issue #234:https://github.com/juanfont/headscale/issues/234
- issue #2234:https://github.com/juanfont/headscale/issues/2234
- issue #3119:https://github.com/juanfont/headscale/issues/3119
默认评论
Halo系统提供的评论