ByteNoteByteNote
字

字节笔记本

2026年2月23日

Headscale 部署与使用指南：自建 Tailscale 控制服务器

#开源工具

Headscale 是一个开源的 Tailscale 控制服务器替代方案，让你可以完全掌控自己的 VPN 网络，没有设备数量限制，也无需支付订阅费用。本文将详细介绍 Headscale 的部署方法和各平台客户端的连接配置。

什么是 Tailscale

Tailscale 是基于 WireGuard 构建的 VPN 工具，与其他 Mesh VPN 工具（如 Netmaker）类似。Tailscale 在用户空间运行 WireGuard，而 Netmaker 使用内核空间 WireGuard，因此 Tailscale 的性能略低于内核空间解决方案，但仍比 OpenVPN 快得多，且更易于使用。

Tailscale 的主要特点：

  • 简单设置：无需防火墙配置，网络设置简单
  • 安全性：自动密钥轮换，默认端到端加密，可查看访问日志
  • NAT 穿透：当 UDP 无法工作时，使用 DERP（Detoured Encrypted Routing Protocol）通过 TCP 中继，帮助连接即使在复杂防火墙后也能工作
  • 集中控制：从一个地方向所有设备推送访问规则和设置
  • 便捷认证：支持 Google、Microsoft、GitHub 等登录提供商

Tailscale 有免费套餐，适合个人使用或小团队（约 20 台设备限制）。如果需要更多功能，有付费套餐可选。但如果你想要完全控制、无限设备、无需订阅费用，Headscale 是更好的选择。

什么是 Headscale

Tailscale 的控制服务器是专有的，免费用户有设备限制。开源社区构建了 Headscale 作为替代方案，它是自托管 Tailscale 的主要开源选择。

Headscale 由欧洲航天局的 Juan Font 创建，使用 Go 语言编写，采用 BSD 许可证发布。Headscale 复制了 Tailscale 控制服务器的大部分功能，你可以自己运行整个协调服务器，完全控制网络流量，没有设备数量限制。

Headscale 部署方法

快速部署（Sealos 应用商店）

Sealos 应用商店提供一键部署 Headscale，几乎无需配置：

  • SQLite 版本
  • PostgreSQL 版本

点击"部署到 Sealos"，登录 Sealos 账户后点击"部署应用"。部署完成后，点击 Headscale 应用的"详情"查看访问方式。Headscale 服务会有一个映射到内部 8080 端口的公共域名。

Linux 服务器手动部署

Headscale 只需要互联网访问即可工作，但为了获得最佳 NAT 穿透性能，建议使用具有公网 IP 的云服务器。

1. 下载 Headscale 二进制文件

bash
# 替换 <HEADSCALE_VERSION> 和 <ARCH> 为你的版本和架构（如 v0.22.3, amd64）
wget --output-document=/usr/local/bin/headscale \
  https://github.com/juanfont/headscale/releases/download/v<HEADSCALE_VERSION>/headscale_<HEADSCALE_VERSION>_linux_<ARCH>
chmod +x /usr/local/bin/headscale

2. 创建配置目录和数据目录

bash
mkdir -p /etc/headscale
mkdir -p /var/lib/headscale
touch /var/lib/headscale/db.sqlite

3. 下载并编辑配置文件

bash
wget https://github.com/juanfont/headscale/raw/main/config-example.yaml -O /etc/headscale/config.yaml

编辑 /etc/headscale/config.yaml：

  • 设置 server_url 为你的公网 IP 或域名（如 http://<YOUR_PUBLIC_IP_OR_DOMAIN>:8080）
  • 如果暂时不需要 MagicDNS，设置 dns_config.magic_dns 为 false
  • 设置 randomize_client_port 为 true 以获得更好的 NAT 穿透效果
  • 自定义私有网络 IP 范围（默认使用 100.64.0.0/10）

4. 创建 SystemD 服务

创建 /etc/systemd/system/headscale.service：

ini
[Unit]
Description=Headscale Controller - Self-hosted Tailscale coordination server
After=syslog.target
After=network.target

[Service]
Type=simple
User=headscale
Group=headscale
ExecStart=/usr/local/bin/headscale serve
Restart=always
RestartSec=5

# Security settings
NoNewPrivileges=yes
PrivateTmp=yes
ProtectSystem=strict
ProtectHome=yes
ReadWritePaths=/var/lib/headscale /var/run/headscale
AmbientCapabilities=CAP_NET_BIND_SERVICE
RuntimeDirectory=headscale

[Install]
WantedBy=multi-user.target

5. 创建用户并启动服务

bash
useradd headscale -d /home/headscale -m -s /bin/false
chown -R headscale:headscale /var/lib/headscale
systemctl daemon-reload
systemctl enable --now headscale
systemctl status headscale

管理 Headscale 用户

在连接设备之前，需要创建至少一个用户：

bash
# 创建名为 default 的用户
headscale users create default

# 查看用户列表
headscale users list

连接 Tailscale 客户端

Linux 客户端

下载并安装 Tailscale：

bash
# 下载静态版本（替换版本号）
wget https://pkgs.tailscale.com/stable/tailscale_1.XX.Y_amd64.tgz
tar zxvf tailscale_1.XX.Y_amd64.tgz

# 安装二进制文件
sudo cp tailscale_1.XX.Y_amd64/tailscaled /usr/sbin/tailscaled
sudo cp tailscale_1.XX.Y_amd64/tailscale /usr/bin/tailscale

# 复制 SystemD 服务文件
sudo cp tailscale_1.XX.Y_amd64/systemd/tailscaled.service /lib/systemd/system/
sudo cp tailscale_1.XX.Y_amd64/systemd/tailscaled.defaults /etc/default/tailscaled

# 启动服务
sudo systemctl enable --now tailscaled

连接到 Headscale：

bash
sudo tailscale up --login-server=http://<HEADSCALE_PUB_ENDPOINT>:8080 \
  --accept-routes=true --accept-dns=false

运行后会显示注册链接，复制节点密钥到 Headscale 服务器或 Headplane Web 界面完成注册。

macOS 客户端

有三种安装方式：

  • App Store：从 Mac App Store 获取
  • 直接下载：从 Tailscale 官网下载 .pkg 或 .zip
  • 命令行：安装 CLI 工具

配置自定义服务器（Tailscale 1.34.0+）：

  1. 按住 Option (⌥) 键点击菜单栏的 Tailscale 图标
  2. 悬停在 Debug 菜单上
  3. 选择 "Custom Login Server..." 然后 "Add Account..."
  4. 输入 Headscale URL（如 https://<YOUR_HEADSCALE_DOMAIN>）
  5. 浏览器会打开注册页面，按前述方式完成注册

Android 客户端

Android Tailscale 从 1.30.0 版本开始支持自定义服务器：

  1. 从 Google Play 或 F-Droid 下载 Tailscale
  2. 打开应用，点击右上角的三点菜单 (⋮)
  3. 快速点击打开和关闭菜单约 5-7 次，解锁 "Change server" 选项
  4. 点击 "Change server" 输入 Headscale URL
  5. 点击 "Sign in with other" 完成浏览器注册

Windows 客户端

访问 https://<HEADSCALE_PUB_ENDPOINT>/windows 查看具体配置说明，通常需要编辑注册表或使用命令行参数设置 ControlURL。

iOS 客户端

  1. 从 App Store 下载 Tailscale
  2. 打开应用，点击右上角账户图标，选择 "Log in..."
  3. 点击选项菜单（三个点或齿轮），选择 "Use custom coordination server"
  4. 输入 Headscale URL 并点击 "Log in"
  5. 在浏览器中完成注册

自动注册设备（Pre-Auth Keys）

Headscale 支持预授权密钥，让设备自动加入无需手动批准：

bash
# 创建 24 小时有效的密钥
headscale preauthkeys create --user default --expiration 24h

# 使用密钥连接设备
sudo tailscale up --login-server=http://<HEADSCALE_PUB_ENDPOINT>:8080 \
  --accept-routes=true --accept-dns=false --authkey=$AUTH_KEY

设置子网路由

子网路由允许 Tailscale 设备访问其他设备后面的整个本地网络。

在路由器上启用 IP 转发：

bash
echo 'net.ipv4.ip_forward = 1' | sudo tee /etc/sysctl.d/ipforwarding.conf
sudo sysctl -p /etc/sysctl.d/ipforwarding.conf

宣告路由：

bash
sudo tailscale up --login-server=http://<HEADSCALE_PUB_ENDPOINT>:8080 \
  --accept-routes=true --accept-dns=false \
  --advertise-routes=192.168.100.0/24 --reset

在 Headscale 上启用路由：

bash
# 查看节点 ID
headscale nodes list

# 启用路由
headscale routes enable --node-id <NODE_ID> --route "192.168.100.0/24"

客户端需要使用 --accept-routes=true 参数来接收路由。

总结

Headscale 让你可以完全掌控自己的 VPN 网络，没有设备限制，无需订阅费用。配合 Tailscale 客户端，你可以在各种平台上轻松建立安全的私有网络连接。

对于需要完全控制基础设施的用户，Headscale 是 Tailscale 商业服务的理想开源替代方案。

开源工具
上一篇

sysin - SYStem INside | 软件与技术分享

下一篇

Headscale 部署与使用指南：自建 Tailscale 控制服务器

分享: