小岳
2026-11-15
点 赞
0
热 度
0
评 论
0

headscale:把异地机器连成局域网

  1. 首页
  2. 开源分享
  3. headscale:把异地机器连成局域网

文章摘要

摸鱼小助手

周五晚上在公司改代码,突然要用家里那台 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 打不通时还得靠中继,这部分体验和官方网络有差距。

headscale 组网结构:控制面自建,数据面直连

核心机制

  1. 控制服务器只做「介绍人」:交换各节点的 WireGuard 公钥、分配 100 开头的虚拟 IP,不转发业务流量。(推断:这也是它敢把控制面自建的原因——控制面泄露的只是拓扑信息,不是数据本身。)
  2. 节点注册靠预授权密钥:服务器生成一次性 key,客户端 tailscale up 时带上即可入网,默认一小时有效、只能用一次,避免长期密钥躺在命令历史里。
  3. 配置全部落在一个 YAML 文件:/etc/headscale/config.yaml,改完 systemctl restart headscale 生效,没有隐藏的数据库要单独初始化。
  4. 默认只监听 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

从零到能用

  1. 服务器上建一个用户:sudo headscale users create work。
  2. 生成预授权密钥:sudo headscale preauthkeys create --user 1,记下输出的 key,一小时后要重新生成。
  3. 客户端装好 Tailscale 后执行(分成三行更清楚):
tailscale up \
  --login-server http://服务器IP:8080 \
  --authkey 刚才生成的key
  1. 回服务器执行 sudo headscale nodes list,能看到新节点和它拿到的 100 开头 IP。
  2. 在两台客户端之间互相 ping 对方的 100 开头地址,通了就说明打洞成功,延迟通常和你直连公网差不多。
  3. 以后要加新机器,重复第 2 到第 4 步,每台一分钟;想删设备用 sudo headscale nodes delete,节点列表里能看到编号。

适合谁用 / 别用

适合:有一台公网 VPS,想把家里的 NAS、树莓派和公司的电脑连起来的个人开发者,或者三五人的小团队,愿意偶尔敲命令做管理,看重的点是把节点清单握在自己手里。

别用:想要图形控制台、单点登录和精细 ACL 面板的公司——headscale 至今没有官方 Web 界面(issue #234,59 条讨论,截至 2026-11-15 仍开放),所有管理靠命令行完成,成员多了会累。另外它只维护单个网络,官方文档也把定位写明是给个人和小型开源组织用的,别拿它当企业组网方案。

三个真实的坑

  1. 默认只监听本机回环地址,客户端一律连不上,现象是 health 页面能开、注册却超时。出处:v0.29.7 的 config-example.yaml 第 18 到 19 行,listen_addr 默认值是 127.0.0.1:8080,注释掉的示例才是 0.0.0.0。
  2. 客户端挂上 exit node(出口节点)之后,外网域名解析会失败:ping 公网 IP 正常,走 100.100.100.100 这个虚拟 DNS 解析不通,全网业务跟着断。出处:issue #2234,截至 2026-11-15 仍为开放状态。
  3. 节点数量上去之后,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

本站站长,主角光环,怎么滴,你还想攻击你的站长吗,真是好big的狗胆

小岳

intp 逻辑家

站长

不具版权性
不具时效性

文章内容不具时效性。若文章内容有错误之处,请您批评指正。

目录

欢迎来到摸鱼干货栈,这里为您提供开源与摸鱼源码

43 文章数
7 分类数
0 评论数
47标签数
最近评论