【Headscale】自部署 Tailscale 服务端

创建于2022-04-27

2022年8月3日更新

预计阅读11分钟

全文约2.7k字

自部署开源 Tailscale 服务端 —— Headscale。

Headscale和Tailscale

Tailscale 是一个优秀的内网穿透和异地组网工具，基于 Wireguard ，配合 Tailscale 的穿透策略，基本上可以应用于大多数NAT场景。

Tailscale 是一款商用产品，对个人提供免费服务，就个人使用来说基本上是完全够用了（限制20台设备）。但是其后端服务器全都位于国外，在国内延迟实在有点高，而且完全依赖于第三方SSO认证，且官方支持的SSO平台也都在国外，在国内每况愈下的网络环境想快速的连接这些平台实在是有些困难，于是我们就需要自己部署后端了。

有人认为 Tailscale 后台不开源不够透明不够开放，于是自行开发了一套后端，命名为Headscale，很恶趣味的名字，这套后端完全开源，可自行部署，最重要的是比 Netmaker 部署要容易得多，而且打洞失败可以自动转中继，比较智能。

配置服务端

基础配置

下载 Headscale 的服务端二进制文件：Github Release 。

目前官方支持arm架构（意味着可以部署在路由器和其他嵌入式设备上）和x86架构，原则上来说可以部署在任一节点上，但这里建议部署在具有公网IP的、没有NAT的服务器上以确保服务的稳定性。

将下载好的二进制文件移动到/usr/local/bin/目录下并改名headscale，然后进行部署准备：

# 附加可运行属性
chmod +x /usr/local/bin/headscale
# 创建配置目录
mkdir -p /etc/headscale
# 创建证书和数据目录
mkdir -p /var/lib/headscale
# 创建空数据库
touch /var/lib/headscale/db.sqlite

下载示例配置文件存放到/etc/headscale/目录下并改名config.yaml，需要修改的配置项如下：

# 将<server_Address>替换为你自己的IP或域名
server_url: http://<server_Address>:8080
# 修改你自己的IP段，可以自定义；如果不需要IPv6可以将IPv6那行注释掉
ip_prefixes:
  - fd7a:115c:a1e0::/48
  - 10.249.249.0/16
# 修改对自己来说方便的DNS，可以保持默认
dns_config:
  nameservers:
    - 114.114.114.114
# 建议关闭Magic DNS，否则有可能造成客户端无法正常上网
magic_dns: false
# 修改Socket存储位置
unix_socket: /var/run/headscale/headscale.sock

接着再创建 gRPC socket ：

1 2	mkdir /var/run/headscale touch /var/run/headscale/headscale.sock

权限和安全配置（可选）：

# 创建 Headscale 用户
adduser --no-create-home --disabled-login --shell /sbin/nologin --disabled-password headscale
# 修改数据库的Owner
chown -R headscale:headscale /var/lib/headscale

此时就可以试运行一下 Headscale 了：

1	headscale serve

如果没有报错就可以进入下一步了。

后台和开机自启

新建Service文件：/etc/systemd/system/headscale.service

[Unit]
Description=headscale controller
After=syslog.target
After=network.target

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

# 可选的权限和安全配置
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

随后启动即可：

# 启动服务
systemctl start headscale
# 开机自启
systemctl enable headscale
# 查看状态
systemctl status headscle

新建命名空间（Tailnet）

Tailscale 中有一个概念叫 tailnet，你可以理解成租户，租户与租户之间是相互隔离的，具体看参考 Tailscale 的官方文档： What is a tailnet 。Headscale 也有类似的实现叫 namespace，即命名空间。我们需要先创建一个 namespace，以便后续客户端接入。

创建命名空间：

1 2	# <namespace>替换为你自定义的租户名称 headscale namespaces create <namespace>

查看命名空间：

1	headscale namespaces list

配置客户端

支持的客户端

并非全部客户端都支持（或全部支持）将 Headscale 作为后端，目前适配情况如下：

操作系统	支持情况	解决方案
Linux	✅	原生支持
Windows	✅	修改注册表
macOS	✅	需要添加描述文件
Android	⭕	需要自编译APK
iOS	❌	目前不支持

查询已注册的节点

在经过下面的步骤注册完客户端后可通过这条命令查询已注册的节点：

1	headscale nodes list

输出：

ID | Name                      | NodeKey | Namespace | IP addresses  | Ephemeral | Last seen           | Online  | Expired
1  | lxn-testbench-ubuntu-v34  | [0]     | main      | 192.168.5.1   | false     | 2022-04-27 00:59:57 | offline | no     
2  | lxn-testbench-windows-v35 | [0]     | main      | 192.168.5.2   | false     | 2022-04-27 06:04:50 | online  | no    
3  | lxn-testbench-macos-v37   | [0]     | main      | 192.168.5.3   | false     | 2022-04-27 08:33:23 | offline | no    
4  | lxn-testbench-ubuntu-v36  | [0]     | main      | 192.168.5.4   | false     | 2022-04-27 09:22:11 | online  | no     
5  | lxn-testbench-mia5-v11    | [0]     | main      | 192.168.5.6   | false     | 2022-04-27 11:49:33 | online  | no

Linux

这一小节操作基于 Ubuntu 20.04(Focal) LTS Desktop Edition。

先下载Linux的Tailscale客户端，可以使用官方的一键脚本：

1	curl -fsSL https://tailscale.com/install.sh \| sh

其他的安装说明和安装包下载可以在 Tailscale Packages - stable track 找到。

安装完成后可以执行如下命令将 Tailscale 加入 Headscale 网络：

1 2	# <server_Address>替换为你Headscale服务器的IP地址 tailscale up --login-server=http://<server_Address>:8080 --accept-routes=true --accept-dns=false

如果连接成功会有如下输出：

root@lxn-testbench-v35:~# tailscale up --login-server=http://0.0.0.0:8080 --accept-routes=true --accept-dns=false

To authenticate, visit:

        http://0.0.0.0:8080/register?key=0

把这段网址复制到浏览器打开，会返回如下输出：

headscale
Machine registration
Run the command below in the headscale server to add this machine to your network:

headscale -n NAMESPACE nodes register --key 0

把最后一行的命令复制到 headscale 服务器上并将NAMESPACE替换为刚才创建的命名空间后执行，执行成功后会返回Machine register，同时在客户机上也应该有返回输出Success.，之后再按照上面查看已连接客户端的方法在服务端查询确认设备在线就可以了。

Windows

这一小节操作基于 Windows 11 Dev。

先下载 Windows 的 Tailscale 客户端，下载地址，下载后正常安装即可，不必登录。找到状态栏右下角的Tailscale图标，右键退出。

然后在客户端浏览器上打开http://<server_Address>:8080/windows，并按照屏幕提示添加对应的注册表项或下载导入由服务器提供的注册表文件，随后再重新打开 Tailscale 客户端。

由于众所周知的原因，国内可能无法正常连接到Github，某些必要的文件也就无法从Github下载。如果此时无法正常打开http://<server_Address>:8080/windows请按照如下方法添加注册表项。

打开命令提示符（管理员），输入以下命令：

1
2
3

REG ADD "HKLM\Software\Tailscale IPN" /v UnattendedMode /t REG_SZ /d always
# 将<server_Address>替换为你服务器的地址
REG ADD "HKLM\Software\Tailscale IPN" /v LoginURL /t REG_SZ /d "http://<server_Address>:8080"

此时右键Tailscale的托盘图标，点击登录（Log in…），会返回如下输出：

headscale
Machine registration
Run the command below in the headscale server to add this machine to your network:

headscale -n NAMESPACE nodes register --key 0

把最后一行的命令复制到 headscale 服务器上并将NAMESPACE替换为刚才创建的命名空间后执行，执行成功后会返回Machine register，同时在客户机上Tailscale的托盘图标也会发生变化，右键可以看到Connected字样，之后再按照上面查看已连接客户端的方法在服务端查询确认设备在线就可以了。

macOS

这一小节的操作基于 macOS 12.5.7。

macOS加入Headscale网络的方式可能略显麻烦，因为需要一个美区的Apple ID，据说国区是没有 Tailscale 这个软件的。

直接在App Store下载 Tailscale ，下载后正常安装即可，不必登录，也先不要打开 Tailscale 。

在客户端的浏览器上打开http://<server_Address>:8080/apple，并按照屏幕提示在 Terminal 做相应的操作或直接下载导入由服务器提供的描述文件，随后打开 Tailscale 客户端。

由于众所周知的原因，国内可能无法正常连接到Github，某些必要的文件也就无法从Github下载。如果此时无法正常打开http://<server_Address>:8080/apple请按照如下方法添加注册表项。

打开 Terminal （终端），输入以下命令：

1	defaults write io.tailscale.ipn.macos ControlURL http://<server_Address>:8080

然后打开 Tailscale ，点击Get Start，Allow VPN Configurations，Sign in to your network，然后会自动打开Safari，把最后一行的命令复制到 headscale 服务器上并将NAMESPACE替换为刚才创建的命名空间后执行，执行成功后会返回Machine register，同时在客户机上Tailscale的托盘图标上的感叹号会消失，右键可以看到Connected字样，之后再按照上面查看已连接客户端的方法在服务端查询确认设备在线就可以了。

如果打开 Tailscale 后仍然是 Tailscale 官方的登录界面，则重启一下mac就可以了。

Android

这一小节的操作配置如下：
编译系统：Ubuntu 20.04 LTS Server Edition；
客户端运行环境：Android 5.1.1/MIUI 10 稳定版。

编译需要较强的性能，否则可能会被卡CPU检测Kill掉。

Android 的 Tailscale 客户端需要自行编译，方法如下：

安装依赖：

安装GoLang的步骤请看 Ubuntu 安装 Golang 最新版本。
安装Git：apt update&&apt install git。

首先将 Tailscale 的客户端 clone 到本地：

1	git clone https://github.com/tailscale/tailscale-android.git

（可选）预编译和运行确保没有数据错误：

1	make tailscale-debug.apk

修改后端地址。找到文件/tailscale-android/cmd/tailscale/backend.go，查找如下代码段：

func (b *backend) Start(notify func(n ipn.Notify)) error {
	b.backend.SetNotifyCallback(notify)
	return b.backend.Start(ipn.Options{
		StateKey: "ipn-android",
	})
}

修改为：

func (b *backend) Start(notify func(n ipn.Notify)) error {
    b.backend.SetNotifyCallback(notify)
    prefs := ipn.NewPrefs()
    prefs.ControlURL = "http://<server_Address>:8080"
    opts := ipn.Options{
    StateKey: "ipn-android",
        UpdatePrefs: prefs,
    }
    return b.backend.Start(opts)
}

其中<server_Address>修改为Headscale服务器的地址。

编译：

1	make tailscale-debug.apk

安装：

1	adb install tailscale-debug.apk

安装后在手机上打开，点击Get start，登录时选择Sign in with others，会自动跳转到浏览器，把最后一行的命令复制到 headscale 服务器上并将NAMESPACE替换为刚才创建的命名空间后执行，执行成功后会返回Machine register，同时在客户机上会自动跳转到主界面，将主界面上方的开关打开后，再按照上面查看已连接客户端的方法在服务端查询确认设备在线就可以了。

iOS

iOS暂不支持使用Headscale作为后端，因为Tailscale的iOS客户端没有开源，而且官方的解决方案经过尝试也是不可用的（在iOS上安装由服务端提供的描述文件），所以只能等官方适配了。

总结

Headscale 的部署方式实在是简单多了，~~建议大力推广~~。

参考资料

排名不分先后

Tailscale 基础教程：Headscale 的部署方法和使用教程

Lxn-Chan!

【Headscale】自部署 Tailscale 服务端

Headscale和Tailscale

配置服务端

基础配置

后台和开机自启

新建命名空间（Tailnet）

配置客户端

支持的客户端

查询已注册的节点

Linux

Windows

macOS

Android

iOS

总结

参考资料

上一篇

Ubuntu 安装 Transmission 和 WebUI

Linux

下一篇

将云服务器的镜像备份到其他地方

Linux

简单说两句