云原生

Headscale 自建异地组网完全指南

Headscale 自建异地组网完全指南 本文详细介绍如何使用 Headscale 自建 Tailscale 控制服务器，实现跨云、跨地域的异地组网，并配合自建 DERP 中继服务器优化国内访问体验。 什么是 Headscale Headscale 是 Tailscale 控制服务器的开源替代方案，

Headscale 自建异地组网完全指南

本文详细介绍如何使用 Headscale 自建 Tailscale 控制服务器，实现跨云、跨地域的异地组网，并配合自建 DERP 中继服务器优化国内访问体验。

什么是 Headscale

Headscale 是 Tailscale 控制服务器的开源替代方案，使用相同的 WireGuard 协议，可以实现：

  • 异地组网：打通家庭、公司、云服务器等多个网络
  • 内网穿透：无需公网 IP 即可访问内网服务
  • 安全传输：基于 WireGuard 的端到端加密
  • 零配置：自动 NAT 穿透，无需手动配置端口映射

相比 Tailscale 官方服务，Headscale 的优势：

  • 数据自主可控
  • 支持多用户/多团队管理
  • 可自建 DERP 中继，优化国内访问

服务端部署

环境准备

# 系统要求：Ubuntu 22.04 LTS
# 内存：建议 1GB 以上
# 带宽：根据节点数量调整

# 设置主机名
hostname="headscale-server"
hostnamectl set-hostname ${hostname}

# 配置国内镜像源
cat <<'EOF' > /etc/apt/sources.list
deb https://mirrors.cernet.edu.cn/ubuntu/ jammy main restricted universe multiverse
deb https://mirrors.cernet.edu.cn/ubuntu/ jammy-updates main restricted universe multiverse
deb https://mirrors.cernet.edu.cn/ubuntu/ jammy-backports main restricted universe multiverse
deb https://mirrors.cernet.edu.cn/ubuntu/ jammy-security main restricted universe multiverse
EOF

apt update -y

安装依赖

# 安装 WireGuard 工具
apt install wireguard-tools -y

# 启用 IP 转发
echo "net.ipv4.ip_forward = 1" >> /etc/sysctl.conf
echo "net.ipv4.conf.all.proxy_arp = 1" >> /etc/sysctl.conf
sysctl -p /etc/sysctl.conf

安装 Headscale

# 配置变量
HEADSCALE_VERSION="0.22.3"
HEADSCALE_ARCH="amd64"
HEADSCALE_HOST="0.0.0.0"

# 下载安装包
wget --output-document=headscale.deb \
  "https://github.com/juanfont/headscale/releases/download/v${HEADSCALE_VERSION}/headscale_${HEADSCALE_VERSION}_linux_${HEADSCALE_ARCH}.deb"

# 安装
apt install ./headscale.deb -y

配置文件

创建 /etc/headscale/config.yaml：

---
server_url: http://${HEADSCALE_HOST}:8080
listen_addr: 0.0.0.0:8080
metrics_listen_addr: 0.0.0.0:9090
grpc_listen_addr: 0.0.0.0:50443
grpc_allow_insecure: false
private_key_path: /var/lib/headscale/private.key

noise:
  private_key_path: /var/lib/headscale/noise_private.key

# IP 分配范围
ip_prefixes:
  - 100.64.0.0/10

# DERP 配置（使用官方）
derp:
  server:
    enabled: false
  urls:
    - https://controlplane.tailscale.com/derpmap/default
  auto_update_enabled: true
  update_frequency: 24h

# 数据库
db_type: sqlite3
db_path: /var/lib/headscale/db.sqlite

# 禁用检查更新
disable_check_updates: false
ephemeral_node_inactivity_timeout: 30m
node_update_check_interval: 10s

# TLS 配置（如需使用 HTTPS）
tls_letsencrypt_hostname: ""
tls_cert_path: ""
tls_key_path: ""

# DNS 配置
dns_config:
  override_local_dns: true
  nameservers:
    - 223.5.5.5
    - 8.8.8.8
  magic_dns: false
  base_domain: example.com

# Unix Socket
unix_socket: /var/run/headscale/headscale.sock
unix_socket_permission: "0770"

# 禁用日志上报
logtail:
  enabled: false

启动服务

# 启动并设置自启
systemctl start headscale
systemctl enable headscale
systemctl status headscale

# 创建 API Key
headscale apikeys create

# 创建用户
headscale users create team1
headscale users create team2

# 查看状态
headscale user list
headscale nodes list

客户端接入

Linux 客户端

# 安装 Tailscale
curl -fsSL https://tailscale.com/install.sh | sh

# 连接到自建 Headscale 服务器
HEADSCALE_URL="http://your-server-ip:8080"
tailscale up --login-server=${HEADSCALE_URL} \
  --accept-routes=true \
  --accept-dns=false

# 服务端批准节点
headscale nodes register --user team1 --key nodekey:xxxxx

Windows/macOS 客户端

  1. 安装 Tailscale 客户端
  2. 命令行执行：
tailscale up --login-server=http://your-server-ip:8080
  1. 在服务端执行注册命令

预授权密钥（免审批）

# 创建 24 小时有效期的预授权密钥
headscale preauthkeys create -e 24h --user team1

# 查看密钥列表
headscale --user team1 preauthkeys list

# 客户端使用密钥连接
KEY="your-preauth-key"
tailscale up --login-server=${HEADSCALE_URL} \
  --accept-routes=true \
  --authkey $KEY

路由与子网宣告

服务端开启路由转发

# 开启 IPv4/IPv6 转发
echo 'net.ipv4.ip_forward = 1' | tee /etc/sysctl.d/ipforwarding.conf
echo 'net.ipv6.conf.all.forwarding = 1' | tee -a /etc/sysctl.d/ipforwarding.conf
sysctl -p /etc/sysctl.d/ipforwarding.conf

客户端宣告子网

# 例如：客户端内网为 192.168.1.0/24
tailscale up --login-server=${HEADSCALE_URL} \
  --accept-routes=true \
  --advertise-routes=192.168.1.0/24

# 多个子网用逗号分隔
# --advertise-routes=192.168.1.0/24,10.0.0.0/24

服务端批准路由

# 查看待批准的路由
headscale routes list

# 开启指定路由
headscale routes enable -r 1
headscale routes enable -r 2

# 批量开启某节点的所有路由
headscale routes enable -i 1

自建 DERP 中继服务器

为什么需要自建 DERP

  • 国内访问官方 DERP 延迟高（300ms-2s）
  • 自建 DERP 可以实现：
    • 更低的延迟
    • 更好的稳定性
    • 数据自主可控

Docker 部署 DERP

# docker-compose.yml
version: '3.5'
services:
  derper:
    container_name: derper
    image: fredliang/derper
    restart: always
    volumes:
      - ./cert:/cert
      - /var/run/tailscale/tailscaled.sock:/var/run/tailscale/tailscaled.sock
    ports:
      - 3478:3478/udp
      - 12345:23479
    environment:
      DERP_DOMAIN: derp.yourdomain.com
      DERP_ADDR: ":23479"
      DERP_VERIFY_CLIENTS: "true"

Nginx 反向代理

server {
    listen 443 ssl http2;
    server_name derp.yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:12345;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Headscale 配置自建 DERP

编辑 /etc/headscale/config.yaml：

derp:
  server:
    enabled: false
  urls: []  # 禁用官方 DERP
  paths:
    - /etc/headscale/derp.yaml  # 本地 DERP 配置

创建 /etc/headscale/derp.yaml：

regions:
  900:
    regionid: 900
    regioncode: custom
    regionname: Custom DERP
    nodes:
      - name: 900a
        regionid: 900
        hostname: derp.yourdomain.com
        ipv4: your-server-ip
        stunport: 3478
        stunonly: false
        derpport: 443

重启 Headscale：

systemctl restart headscale

使用 IP 的简化方案

如果没有域名，可以直接使用 IP：

# 运行 DERP 容器
docker run --restart always \
  --net host \
  --name derper \
  -d yangchuansheng/ip_derper

# 或指定端口
docker run --restart always \
  -p 4443:443 \
  -p 3478:3478/udp \
  --name derper \
  -d yangchuansheng/ip_derper

访问地址：https://your-server-ip:4443/

防火墙配置

需要开放的端口：

端口 协议 用途
8080 TCP Headscale HTTP API
3478 UDP STUN/TURN
41641 UDP WireGuard
443 TCP DERP HTTPS 
# UFW 配置
ufw allow 8080/tcp
ufw allow 3478/udp
ufw allow 41641/udp
ufw allow 443/tcp

常见问题

节点无法连接

  1. 检查防火墙端口是否开放
  2. 检查 Headscale 服务是否运行
  3. 查看日志：journalctl -u headscale -f

打洞失败，一直走 DERP

  1. 检查 NAT 类型（对称型 NAT 难以打洞）
  2. 确保 UDP 3478 和 41641 端口开放
  3. 尝试使用自建 DERP

路由不生效

  1. 确认服务端已批准路由：headscale routes list
  2. 客户端需要 --accept-routes=true
  3. 检查客户端的 iptables/nftables 规则

小结

Headscale + Tailscale 是一套强大的异地组网方案：

  1. 服务端：Headscale 提供控制平面
  2. 客户端：Tailscale 提供数据平面
  3. DERP：自建中继优化国内访问

适用场景：

  • 家庭 NAS 远程访问
  • 跨云服务器组网
  • 团队远程办公
  • IoT 设备管理

参考资料：

Comment