一键命令部署 Tailscale 异地组网：Headscale + Headplane 快速上手

一、Tailscale 与 Headscale 简介

Tailscale 是一款基于 WireGuard 的零配置 VPN 组网工具，它能让你在全球各地的设备之间建立起一条加密的直接隧道，无需复杂的端口映射和证书配置。但 Tailscale 官方服务器在海外，数据需要经过第三方，对于隐私敏感或网络受限的用户来说存在一定顾虑。

Headscale 是 Tailscale 控制服务器的开源实现，你可以完全自托管在自己的服务器上，数据完全自主可控。配合 Headplane Web 管理面板，通过一条简单的命令就能完成部署，实现可视化管理用户、节点和访问策略。

二、一键部署 Headscale + Web 管理面板

准备工作：一台具有公网 IP 的 Linux 服务器（推荐 1核1G 以上），已安装 Docker 和 Docker Compose。

2.1 执行一键安装命令

运行以下命令，脚本会自动完成 Headscale 服务端和 Headplane 管理面板的部署：

bash <(curl -sL kejilion.sh) app headscale

安装过程中会自动完成以下操作：

• 自动检测服务器公网 IP
• 下载并配置 Headscale 配置文件
• 生成 API Key 并自动配对 Web 面板
• 启动双容器：Headscale 服务端 + Headplane 管理面板

2.2 安装完成输出

安装成功后会显示类似以下信息：

========================================
  Headscale + Headplane 安装完成
========================================

  Web 管理面板: http://你的服务器IP:8081/admin
  Headscale API: http://你的服务器IP:8080

  登录 API Key（已自动配对，请保存）:
  hskey-api-xxxxxxxxxxxxx

  打开面板后输入上方 API Key 即可登录
  服务端已自动配对，无需手动填写 URL
========================================

重要提示：请保存好输出的 API Key，这是登录 Web 面板的唯一凭证。

三、访问 Web 管理面板

打开浏览器访问 http://你的服务器IP:8081/admin，进入 Headplane 登录页面。

在输入框中粘贴安装时生成的 API Key，点击 Sign In 即可登录管理面板。

登录后可以看到：

• Users - 用户管理，创建不同的用户命名空间
• Machines - 节点管理，查看已接入的设备
• Routes - 子网路由，配置局域网互通
• ACL - 访问控制策略（需开启数据库模式）

四、客户端设备接入

4.1 安装 Tailscale 客户端

在需要组网的设备上安装 Tailscale 客户端：

# Linux 一键安装
curl -fsSL https://tailscale.com/install.sh | sh

Windows、macOS、iOS、Android 用户可前往官网下载对应客户端。

4.2 指定自建服务器连接

关键步骤：使用 --login-server 参数指定你的 Headscale 服务器地址，而不是连接 Tailscale 官方服务器。

tailscale up --login-server=http://你的服务器IP:8080

执行后会输出类似以下信息：

To authenticate, visit:

	http://你的服务器IP:8080/register?key=nodekey:xxxxxxxx

4.3 服务端注册节点

方法一：命令行注册

# 先创建用户
docker exec headscale headscale users create myuser

# 注册节点（复制客户端输出的完整 nodekey）
docker exec headscale headscale nodes register --user myuser --key nodekey:完整key

方法二：使用 PreAuth Key（推荐）

先生成预认证密钥：

# 创建用户
docker exec headscale headscale users create myuser

# 查看用户ID
docker exec headscale headscale users list

# 生成预认证密钥（用户ID为1）
docker exec headscale headscale preauthkeys create --user 1

然后客户端一条命令直接加入：

tailscale up --login-server=http://你的服务器IP:8080 --authkey=生成的预认证密钥

五、验证组网连通

在已注册的设备上执行：

# 查看组网状态
tailscale status

# Ping 其他设备（使用 Tailscale 分配的 IP）
tailscale ping 100.64.0.x

如果能看到其他设备并且能 Ping 通，说明组网成功！此时所有设备之间已经通过 WireGuard 加密隧道直连。

六、进阶：局域网互通（子网路由）

如果想让组网设备访问彼此所在的局域网，可以配置子网路由。

6.1 在局域网网关设备上开启路由

# 开启 IP 转发
echo 'net.ipv4.ip_forward = 1' | tee -a /etc/sysctl.conf
sysctl -p

# 广播局域网网段
tailscale up --login-server=http://你的服务器IP:8080 --advertise-routes=192.168.1.0/24

6.2 服务端批准路由

# 查看待审批路由
docker exec headscale headscale routes list

# 批准路由
docker exec headscale headscale routes enable --route 1

6.3 其他设备接受子网路由

tailscale up --login-server=http://你的服务器IP:8080 --accept-routes

配置完成后，你就可以在任何已组网的设备上直接访问 192.168.1.x 局域网地址了！

七、常见问题

Q1：为什么客户端显示连接到官方服务器？

确保使用 --login-server 参数指定你的自建服务器地址。如果之前连接过官方服务器，使用 --reset 参数重置：

tailscale up --login-server=http://你的服务器IP:8080 --reset

Q2：如何开启 ACL 访问控制？

编辑 Headscale 配置文件，添加：

policy:
  mode: database

然后重启服务。默认情况下所有设备之间完全互通。

Q3：支持 P2P 直连吗？

是的！Tailscale/Headscale 默认使用 WireGuard 协议尝试 P2P 直连。约 92% 的连接能成功打洞直连，少数极端 NAT 环境会走 DERP 中继。你可以在配置中启用自建 DERP 服务器来优化中继性能。

Q4：生产环境如何配置 HTTPS？

建议使用 Nginx 反向代理 + Let's Encrypt 证书，配置域名访问。HTTP 模式仅适用于测试环境或内网使用。

八、总结

通过一条命令部署 Headscale + Headplane，你可以快速搭建属于自己的 Tailscale 控制服务器，实现：

• 完全自主可控的异地组网解决方案
• Web 可视化管理用户和节点
• WireGuard 加密的 P2P 直连
• 局域网互通、子网路由
• 跨平台支持（Linux/Windows/macOS/iOS/Android）

相比 Tailscale 官方服务，自建 Headscale 让你在享受便捷组网的同时，完全掌控自己的数据和网络拓扑。赶快试试吧！