Headscale 0.23.0 部署

背景

Headscale 升级了最新版(0.23)，相对于之前的版本做了许多改动，因此写下此文，重新部署一遍最新版本的 Headscale + Tailscale。

• 系统环境: 阿里云 Debian 12 （纯 IP）
• Headscale 版本: Headscale 0.23.0
• Tailscale 版本: Tailscale 1.76.0

在线链接

• Tailscale 官网: https://tailscale.com/
• Tailscale 仓库: https://github.com/tailscale/tailscale
• Headscale 官网: https://headscale.net/
• Headscale 仓库: https://github.com/juanfont/headscale

准备安装程序

按需下载以下程序:

• Headscale: headscale_0.23.0_linux_amd64.deb
• Tailscale Windows: tailscale-setup-1.76.0-amd64.msi
• Tailscale MacOS: Tailscale-1.76.0-macos.pkg
• Tailscale 群晖: https://pkgs.tailscale.com/stable/#spks

安装 Headscale 服务端

安装服务端

将 headscale_0.23.0_linux_amd64.deb 上传云服务器，执行安装命令:

dpkg --install ./headscale_0.23.0_linux_amd64.deb

通过 deb 文件安装的服务端会自动创建需要的目录和配置文件，我们只需要对配置文件做一些修改。

默认配置文件路径: /etc/headscale/config.yaml。要修改的内容如下:

server_url: http://127.0.0.1:8080 # 将 127.0.0.1 修改为服务器地址
listen_addr: 127.0.0.1:8080 # 修改为 0.0.0.0:8080
magic_dns: true # 修改为 magic_dns: false

当然如果要使用 Nginx 反代等服务，则视情况自行修改该配置文件。

配置 Headscale 服务自启动:

systemctl enable headscale
systemctl start headscale

查看服务状态:

systemctl status headscale

能够访问服务器的 /windows 端点，则说明正常启动。

初始化配置

在 Headscale 服务器上执行以下命令来创建命名空间（也称租户、用户）:

headscale namespace create master # 创建名为 master 的 namespace

安装 Tailscale 客户端

Windows 客户端

清理环境

如果之前安装过旧版本的 tailscale，建议清理一下。

首先从控制面板卸载已有的 tailscale，然后清理这里的注册表:

HKEY_LOCAL_MACHINE\SOFTWARE\Tailscale IPN

以及这里的文件:

C:\ProgramData\Tailscale
C:\Users\%USERNAME%\AppData\Local\Tailscale
C:\Windows\System32\config\systemprofile\AppData\Local\Tailscale

如果提示文件被占用，则检查是否后台还在运行 tailscale、tailscaled 或 tailscale-ipn 进程，以及是否在运行 tailscale 服务。

安装并登录客户端

配置方法可以参考: http://xxx.xxx.xxx.xxx:8080/windows, 将 url 中的地址改为自己 Headscale 服务器的地址。

安装前文提供的 msi 安装程序，然后执行以下命令以接入 Headscale:

tailscale login --login-server=http://xxx.xxx.xxx.xxx:8080/ --accept-routes=false --accept-dns=false

如果一切正常，应该如下显示:

对于 Windows 来说，可能会自动弹出浏览器访问该 url，如果没有弹出则手动访问。

在 Headscale 服务器上执行这段命令，即可注册 tailscale 客户端:

headscale nodes register --user master --key mkey:a658b2c3c0f26eb1100250da12c2661f9d300605eced18e29bdd23cf9836127b

注1: 我们之前创建的命名空间为 master，因此此处 --user 参数设为 master。

注2: 如果执行 tailscale login ... 命令后一直没有显示 To authenticate ... 这一段 url，则考虑执行以下 powershell 命令来清理缓存:

# 停止 tailscale-ipn.exe 进程
Stop-Process -Name "tailscale-ipn" -Force -ErrorAction SilentlyContinue
# 停止 tailscale 服务
Stop-Service -Name "tailscale" -Force
# 等待 tailscale 服务完全停止
$service = Get-Service -Name "tailscale"
while ($service.Status -ne 'Stopped') {
    Start-Sleep -Seconds 3
    $service.Refresh()
}
# 停止 tailscaled 进程
Stop-Process -Name "tailscaled" -Force -ErrorAction SilentlyContinue
# 删除文件夹
Remove-Item -Path "C:\ProgramData\Tailscale" -Recurse -Force
Remove-Item -Path "$env:LOCALAPPDATA\Tailscale" -Recurse -Force
# 启动 tailscale 服务
Start-Service -Name "tailscale"

清理后，重新双击 tailscale 图标以运行客户端，然后重新执行前文所述的 tailscale login .... 命令。

注3: 据称在 Windows 11 24H2 等版本上，重启 tailscale 后可能会出现无法重连、卡在 Starting 状态等问题。

参考: https://github.com/tailscale/tailscale/issues/13660

可以通过管理员权限执行以下 Powershell 命令解决:

Restart-Service -Name "tailscale"
tailscale up

执行后，重新打开 tailscale 客户端即可。

也可以创建一个快捷方式，将其 “目标” 字段修改为:

C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe -WindowStyle hidden -NoProfile -ExecutionPolicy Bypass -c "Restart-Service -Name "Tailscale" -Force;Start-Process \"C:\Program Files\Tailscale\tailscale-ipn.exe\""

同时设置快捷方式以管理员身份运行。

最后修改一下快捷方式的图标，就可以正常用了。

Linux 客户端

以 Ubuntu 为例:

# 添加 tailscale 仓库
mkdir -p --mode=0755 /usr/share/keyrings
curl -fsSL https://pkgs.tailscale.com/stable/debian/bookworm.noarmor.gpg | tee /usr/share/keyrings/tailscale-archive-keyring.gpg >/dev/null
curl -fsSL https://pkgs.tailscale.com/stable/debian/bookworm.tailscale-keyring.list | tee /etc/apt/sources.list.d/tailscale.list
# 安装 tailscale
apt-get update && apt-get install tailscale

接入 Headscale:

tailscale login --login-server=http://xxx.xxx.xxx.xxx:8080/ --accept-routes=false --accept-dns=false

同前文，访问该 url 并在 Headscale 服务器上执行所示命令即可。

MacOS 客户端

配置方法可以参考: http://xxx.xxx.xxx.xxx:8080/apple, 将 url 中的地址改为自己 Headscale 服务器的地址。

安装前文提供的 pkg 安装包，依照程序界面提示，允许配置系统 VPN 权限。

接入 Headscale:

按住 option (⌥) 键并点击菜单栏中的 tailscale 图标，点击 Debug - Add Account 按钮:

填写自己的 Headscale 服务器 url:

点击 Add Account 后，会弹出浏览器窗口。与前文相似，我们只需要在 Headscale 服务器上执行页面提示的命令即可。

群晖客户端

根据自己设备的系统版本和 CPU，选择对应的 spk 并安装，我使用的是 tailscale-x86_64-1.76.0-700076000-dsm7.spk:

启动 tailscale:

打开 SSH 并使用登录群晖 Web 界面的用户名和密码来登录群晖后台:

接入 Headscale:

tailscale login --login-server=http://xxx.xxx.xxx.xxx:8080/ --accept-routes=false --accept-dns=false

同前文，访问该 url 并在 Headscale 服务器上执行所示命令即可。

Headscale 基础维护命令

操作命名空间

headscale namespace list # 查看所有的namespace
headscale namespace create default # 创建namespace
headscale namespace destroy default # 删除namespace
headscale namespace rename default myspace # 重命名namespace

操作节点

headscale node list # 列出所有的节点
headscale node ls -t # 列出所有的节点,同时显示出tag信息
headscale -n default node ls # 只查看namespace为default下的节点
headscale node delete -i <ID> # 根据id删除指定的节点，这里面的id是node list查询出来的id
headscale node tag -i=2 -t=tag:test # 给id为2的node设置tag为tag:test
headscale node rename -i <ID> New_Name # 将指定node重命名

查看节点状态

服务端执行:

headscale node list | sed -r "s/\x1B\[([0-9]{1,2}(;[0-9]{1,2})?)?[m|K]//g"\
| sed "s/Namespace/Space/g" | sed "s/online/[+]ON/g" \
| sed "s/offline/[-]OFF/g" | grep "|" \
| awk -F "|" '{print $1"	|"$11"	|"$7"	|"$3}'

卸载 Headscale

dpkg -P headscale

如果提示有文件未删除，则手动删除即可。

Tailscale 基础维护命令

查看节点间连接状态

Windows / Linux 客户端执行:

tailscale status

MacOS 客户端执行:

/Applications/Tailscale.app/Contents/MacOS/Tailscale status 2>/dev/null

其中:

• active; relay: 表示本机到此节点间采用 derp 中转通信。
• active; direct: 表示本机到此节点间采用直连通信，是最理想的连接方式。
• idle: 表示该节点目前处于闲置状态。

查看节点间延迟

Windows/Linux 环境:

tailscale ping 100.64.0.5

MacOS 环境:

/Applications/Tailscale.app/Contents/MacOS/Tailscale ping 100.64.0.5

如下图可见，一开始两个节点之间通过东京的 DERP 服务进行中转，随后成功打洞，实现了低延迟直连。