搭建自托管的单一 Tailscale 私有网络控制平面

方案简介

Headscale 是 Tailscale 控制服务器的开源、自托管实现，面向希望自行掌控网络控制平面的个人、自托管用户、爱好者和小型开源组织。它不是完整替代所有 Tailscale 产品能力的通用平台，而是围绕单一 Tailscale network（tailnet）提供较窄范围的控制服务。

这套方案将 Tailscale 的客户端网络模型与 WireGuard 的底层 VPN 能力结合起来：Headscale 作为控制服务器，负责节点之间的密钥交换、客户端地址分配、用户边界、机器共享以及节点通告路由。节点形成一个覆盖网络，并通过 NAT traversal 连接不同网络中的计算机。

亮点与能力

• 提供开源、自托管的 Tailscale 控制服务器实现。
• 基于 WireGuard 构建现代 VPN 网络。
• 让不同网络中的计算机形成 overlay network。
• 通过 NAT traversal 连接网络中的节点。
• 负责交换节点的 WireGuard 公钥。
• 为客户端分配 IP 地址，并建立用户之间的边界。
• 支持在用户之间共享机器。
• 暴露节点通告的路由。

这些能力共同构成一个适合个人使用或小型开源组织的私有 tailnet 控制平面。

组成与分工

• Headscale：自托管控制服务器，负责节点控制、地址分配、用户边界、机器共享和路由暴露。
• Tailscale：提供客户端网络模型和 tailnet 概念；Headscale实现的是其控制服务器的开源替代方案。
• WireGuard：提供 VPN 底层能力，并使用公钥完成节点间的控制面交换。
• overlay network：把不同网络中的计算机组织成逻辑上的覆盖网络。
• NAT traversal：帮助覆盖网络中的节点穿越网络地址转换环境。
• single Tailscale network (tailnet)：Headscale 的目标范围，适用于个人或小型开源组织。

实施步骤

1. 选择稳定版本

使用 Headscale 时，应选择与发布版本相同的 GitHub tag，并使用对应版本的示例配置。不要直接把 main 分支当作稳定配置来源，因为该分支可能包含尚未发布的变更。

2. 阅读对应版本文档

根据所选版本进入 stable 或 development 文档，按照文档完成 Headscale 服务端和 Tailscale 客户端的部署。仓库 README 没有在材料中给出服务端安装、初始化或启动命令，因此这里不补写命令。

3. 建立单一 tailnet

将 Headscale 作为控制服务器，接入 Tailscale 节点。节点加入后，由控制服务器交换 WireGuard 公钥、分配客户端 IP，并建立用户边界。

4. 配置节点能力

根据实际网络需要使用机器共享和节点通告路由，使节点能够访问目标网络。完成后通过客户端之间的连接以及通告路由验证覆盖网络是否工作。

使用与配置要点

运行后的核心使用方式是把 Headscale 当作控制平面，而不是普通的 Web 代理或应用网关。控制服务器负责节点关系和网络策略，Tailscale 节点负责加入该 tailnet 并参与覆盖网络。

日常配置和验证可以围绕以下内容展开：

• 确认服务端和示例配置来自同一个发布 tag。
• 确认节点能够获得由控制服务器分配的 IP 地址。
• 确认不同用户之间的边界符合预期。
• 按需启用机器共享。
• 对需要访问的网段使用节点通告路由，并检查这些路由是否被暴露。
• 在不同网络环境下验证 NAT traversal 后的节点连通性。

Headscale 的适用范围是一个私有 tailnet；如果目标是个人网络或小型开源组织，这一范围与项目设计目标一致。

注意事项与常见问题

• 项目明确不支持也不鼓励使用反向代理运行 Headscale。
• 项目明确不支持也不鼓励在容器中运行 Headscale。
• 应始终使用与发布版本一致的 GitHub tag；main 分支可能包含未发布变更。
• Headscale 的目标是单一 Tailscale network（tailnet），不是面向多租户的大规模控制平台。
• 项目与 Tailscale Inc. 没有关联。
• NixOS 用户可以使用仓库 nix/ 中提供的模块。
• 稳定版本和开发版本分别有对应文档，部署时应选择匹配的版本文档。

优缺点

• ✓ 开源且可自托管
• ✓ 适合个人或小型组织
• ✕ 仅支持单一 tailnet
• ✕ 不支持反向代理和容器运行

出处

本方案挖掘自开源项目 juanfont/headscale，方案内容与实施命令均来自其 README 原文。