Headscale 是 Tailscale 控制服务器的自托管实现。它交换公钥、地址和策略，数据面仍在客户端的 WireGuard 里。截至 2026-10-11，最新正式发布是 v0.29.4（2026-09-23）。本文说明边界和该版功能清单，不含安装步骤。

Headscale 是什么

一个可独立引用的定义句：Headscale 是 Tailscale 控制服务器的自托管实现，目标是为个人或小型开源组织提供单一 tailnet，而不是 Tailscale 公司的托管控制面。

v0.29.4 的 README 对 Tailscale 的转述是：它是建在 WireGuard 之上的覆盖网络；除专有系统上的图形客户端和控制服务器之外，其余部分开源。控制服务器的作用是交换节点的 WireGuard 公钥、分配客户端地址、划分用户边界、在用户之间共享机器，并公布节点宣告的路由。一个 tailnet 是 Tailscale 分配给个人或组织的私有网络。

Headscale 把这个控制面收成更窄的范围：一个 tailnet，面向自己托管的人和实验室。README 写明项目与 Tailscale Inc. 没有从属关系。

覆盖网络的另一种做法见 Nebula 是什么。WireGuard 本身的隧道模型见 WireGuard 与 OpenVPN。

沿革与维护者

仓库 juanfont/headscale 创建于 2020-06-21。LICENSE 的版权行是 Copyright (c) 2020, Juan Font。v0.29.4 文档首页写明，项目由 Kristoffer Dalby 与 Juan Font 维护。

本次读取的贡献计数中，kradalby 为 2492，juanfont 为 1011。计数会随新提交变化，不能单独证明职务。文档把二人写成维护者，这是职务表述；计数只是历史提交。

README 还有一句雇佣关系：一位活跃维护者受雇于 Tailscale，并被允许用工作时间向本项目贡献；这些贡献由其他维护者审核。句子没有点名。本文没有用 Tailscale 的页面核对是哪一位，因此不把雇佣关系写到某个具体账号上。

同一 README 列出 2023 年与 2026 年的两场 FOSDEM 演讲。本文没有核对演讲内容。

v0.29.4 的 go.mod 声明 go 1.26.5。2026-10-11 的默认分支 main 写的是 go 1.27.0。讨论语言版本时要带上标签。

许可证

LICENSE 是 BSD 3-Clause，GitHub 的 SPDX 标识是 BSD-3-Clause。文本允许以源码或二进制再分发，条件包括：保留版权声明和条件清单；二进制的配套材料里也要带上这段声明；未经事先书面许可，不得用版权持有人或贡献者的名字为衍生作品背书。

它不像 GPL 那样要求衍生作品以同一许可证提供源码。这是许可证文本的差别，不是对项目的评价。版权行只写了 2020 年的 Juan Font。此后提交是否在各自文件里另有版权声明，本文没有逐文件核对。

架构：控制面、客户端、中继

数据面不在 Headscale 进程里。节点跑的是 Tailscale 客户端，客户端之间的隧道是 WireGuard。Headscale 负责的是：谁可以加入这一张网、每个节点拿到哪个地址、公钥如何发给对端、哪些路由和策略生效。

v0.29.4 的客户端页写明，目标是支持 Tailscale 客户端最近 10 个版本，并列出 Linux、OpenBSD、FreeBSD、Windows、Android、macOS、iOS 与 tvOS 均为支持。部分系统指向额外说明。这是文档中的支持表，本文没有在这些系统上复测。

直连失败时的另一条路径写在 DERP 页。该页把 DERP（Designated Encrypted Relay for Packets）定义成：主要在两个节点无法建立直接连接时中继流量。Headscale 带有嵌入式 DERP，文档写明它默认关闭。同一页写明，除中继外它还用 STUN 帮助客户端发现公网地址并做 NAT 穿越。发现与打洞的概念见 VPN NAT 穿越与打洞。

因此「流量经过 Headscale」只在中继被用到时成立。文档没有把嵌入式 DERP 写成必经网关。Tailscale 公司提供的 DERP 地图也可以被加载；文档把「只留自己的 DERP」描述成单一故障点。这是该页的拓扑说明，不是部署步骤。

策略决定哪些节点可以互访。FAQ 写明：若策略只允许单向访问，两端仍会在 tailscale status 里看见对方，数据仍按策略过滤，但 tailscale ping 在两个方向都被允许。这是 FAQ 对 Tailscale 行为的转述，并指向 Tailscale 的设备可见性文档。

地址如何被放进隧道，属于客户端上的 WireGuard 配置。AllowedIPs 的含义见 WireGuard AllowedIPs 是什么。

v0.29.4 文档勾选了什么

功能页是一份与 Tailscale 控制服务器对照的清单。下面只记录勾选状态，不评价缺项是否重要。

文档标为已有的包括：节点注册（网页认证与预认证密钥）、MagicDNS、全局和受限域名服务器（分离 DNS）、搜索域、额外 DNS 记录（标明仅 Headscale）、Taildrop 与 Taildrive、标签、子网路由、出口节点、Via 路由过滤、IPv4/IPv6 双栈、临时节点、嵌入式 DERP、对等中继、ACL、Grants、一部分 Autogroup、子网路由和出口节点的自动批准、Tailscale SSH、节点属性，以及策略测试。OpenID Connect 注册和从身份提供者更新用户资料也被勾上。

分离 DNS 的一般概念见 VPN 分离 DNS 是什么。Headscale 的额外 DNS 记录是清单里标明「仅 Headscale」的一项，不能写成 Tailscale 托管服务的同名功能。

同一页明确未完成的有三项：Funnel、Serve、网络流日志。OIDC 组不能用于 ACL，这一条也被留空。Serve 一行的链接文字是 #1234，URL 指向 issue 1921。引用编号时打开该版 features.md 核对。

FAQ 另有几句项目自己的边界：

  • 部署上，官方支持的是他们发布的二进制和 DEB。社区包和容器镜像存在，但 FAQ 写明不正式支持用 Docker 部署。
  • 数据库方面，FAQ 推荐 SQLite，并把 PostgreSQL 写成仍受支持、处于维护模式。项目不提供从 PostgreSQL 迁到 SQLite 的工具。
  • 规模方面，FAQ 用「约 1000 台很少变动的服务器」和「约 80 台经常换网的终端」说明瓶颈在于每次变更都重算整张节点地图。它估计在变化很少时「也许能到数百台或更多」，并写明性能不是开发重点。这些是 FAQ 里的情景，不是本文做的压测。

FAQ 还写明，项目在逆向 Tailscale，以满足维护者自己的好奇。这是项目对自己方法的描述。本文不转述实现步骤，也不判断 Tailscale 协议是否另有公开规范。控制协议不是 IETF RFC。兼容范围以 v0.29.4 的功能清单为准。

文档中的典型用途

这些是设计目标里的角色，不是建议选它：

  • 自己运行控制服务器，让一批 Tailscale 客户端组成一个 tailnet，而不把协调交给 Tailscale 的托管服务。
  • 用策略表达哪些节点可以互访，用子网路由或出口节点公布一部分路由。站点到站点与远程接入的一般差别见 站点到站点与远程接入。
  • 在无法直连时，由 DERP 中继数据包。中继是否启用取决于路径，不是控制服务器这个名字自动决定的。

它不解析「浏览器走哪个 HTTP 代理」，也不实现 IKE。那些是另一类软件。

和相关项目差在哪

项目重心与 Headscale 的边界
Headscale单一 tailnet 的控制服务器不实现 WireGuard 数据面
Tailscale 控制服务器托管的协调服务README 把它写成闭源部分。Headscale 声明与该公司没有从属关系
WireGuard隧道协议客户端用它传数据。身份、地址和策略在控制面
Nebula自带证书和数据面的覆盖网络发现节点叫 lighthouse，不是 Tailscale 控制服务器
代理平台入站、路由、出站处理的是应用或透明代理的连接，不是一张给主机互访的 tailnet

引用清单时先分开的四件事

  1. 控制面和数据面：Headscale 协调，WireGuard 在客户端里传包。
  2. 版本：功能勾选来自 v0.29.4 文档。默认分支的 Go 版本已经不同。
  3. 未完成项：Funnel、Serve、网络流日志，以及 OIDC 组不能用于 ACL。
  4. 规模数字来自 FAQ 的情景说明，不是独立测试报告。

本文只整理公开资料。组网仍然要遵守网络所有者和当地法规的要求；这里不讨论绕过访问控制的做法。

主要资料