如何基于 Headscale 和 Tailscale 实现跨地域组网

在万物互联的数字化时代，网络边界正以前所未有的速度消融。当远程办公成为常态、跨地域协作成为标配，Tailscale以其零配置、跨平台、点对点直连的特性，正在重塑现代网络连接的范式。本文通过开源项目Headscale自建控制平面，实现跨端、跨地域私有化组网。

基础条件

• 1台带公网IP的服务器
• Linux 基础 及 Shell 操作经验
• Docker、Nginx 配置及操作经验
• 域名解析配置能力

Nginx 配置文件

• 使用 nginx 反向代理 API 和 UI
• 注意修改域名 scale.example.org

server {
    listen 80;
    server_name scale.example.org;

    location /admin {
        proxy_pass http://127.0.0.1:8090;
        proxy_http_version 1.1;
        proxy_request_buffering off;
        proxy_buffering off;
    }

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header REMOTE-HOST $remote_addr;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_http_version 1.1;
        proxy_request_buffering off;
        proxy_buffering off;
    }
}

Headscale 配置文件

• 保存为 /srv/headscale/etc/config.yaml
• 注意修改参数 server_url、ipv4、ipv6

# 访问域名
server_url: http://scale.example.org

# HTTP 监听配置
listen_addr: 0.0.0.0:8080

# METRICS 监听配置
metrics_listen_addr: 0.0.0.0:9090

# GRPC 监听配置
grpc_listen_addr: 0.0.0.0:50443
grpc_allow_insecure: false

# 主服务 TS2021 Noise 协议
noise:
  private_key_path: /var/lib/headscale/noise_private.key

# 内网 IP 段，建议在以下受支持的 CGNAT 段内
prefixes:
  v4: 100.64.0.0/10
  v6: fd7a:115c:a1e0::/48
  # IP 分配模式，sequential | random
  allocation: sequential

# DERP 服务配置
derp:
  server:
    enabled: true
    region_id: 999
    region_code: "headscale"
    region_name: "Headscale Embedded DERP"
    # STUN 服务端口，修改为非标端口
    stun_listen_addr: "0.0.0.0:4567"
    private_key_path: /var/lib/headscale/derp_server_private.key
    # 自动添加内置 DERP 至列表
    automatically_add_embedded_derp_region: true
    # 服务器外网 IP，修改为实际值
    ipv4: 123.45.67.1
    #ipv6: 2001:db8::1
  # 从URL引入 DERP 服务器
  urls:
    - https://controlplane.tailscale.com/derpmap/default
  # 从本地引入 DERP 服务器
  paths: []
  # 自动更新引入的 DERP 服务器
  auto_update_enabled: true
  update_frequency: 24h

# 禁止检查更新
disable_check_updates: true

# 不活跃临时节点删除时间
ephemeral_node_inactivity_timeout: 30m

# 数据库配置
database:
  type: sqlite
  debug: false
  gorm:
    prepare_stmt: true
    parameterized_queries: true
    skip_err_record_not_found: true
    slow_threshold: 1000
  sqlite:
    path: /var/lib/headscale/db.sqlite
    write_ahead_log: true
    wal_autocheckpoint: 1000

# SSL 证书配置
tls_cert_path: ""
tls_key_path: ""

# ACL 参数设置
policy:
  mode: database

# DNS 参数配置
dns:
  magic_dns: true
  base_domain: example.com
  nameservers:
    global:
      - 223.5.5.5
      - 223.6.6.6
    split:
      {}
  search_domains: []
  extra_records: []

# Unix 嵌套字
unix_socket: /var/run/headscale/headscale.sock
unix_socket_permission: "0770"

# 日志服务配置
logtail:
  enabled: false

# 随机客户端端口
randomize_client_port: true

Headscale 服务管理

• 保存为 /srv/headscale/docker，给予可执行权限
• 使用 /srv/headscale/docker install 启动服务端
• 使用 docker exec headscale headscale api create 创建 API 密钥
• 访问 http://scale.example.org，使用上一步的密钥登陆

#!/bin/sh
#
# @Author  Rehiy <wang@rehiy.com>
# @Website http://www.rehiy.com
#

APP_NAME=headscale

APP_SERV=headscale/headscale
APP_DASH=goodieshq/headscale-admin

APP_PATH=$(cd `dirname $0`; pwd)

#####################################################################################

if [ "$1" = "install" ] || [ "$1" = "update" ]; then
    docker pull $APP_SERV
    docker pull $APP_DASH
fi

if [ "$1" = "remove" ] || [ "$1" = "update" ]; then
    docker rm -f $APP_NAME-ui
    docker rm -f $APP_NAME
fi

if [ "$1" = "install" ] || [ "$1" = "update" ]; then
    docker run --name $APP_NAME -d \
        --restart unless-stopped \
        --publish 8080:8080 \
        --publish 4567:4567/udp \
        --volume $APP_PATH/etc:/etc/headscale \
        --volume $APP_PATH/var:/var/lib/headscale \
        $APP_SERV serve
    docker run --name $APP_NAME-ui -d \
        --restart unless-stopped \
        --publish 8090:80 \
        $APP_DASH
fi

Tailscale 注册节点

• 在需要注册的节点执行下面的脚本
• 注意修改域名scale.example.org

#!/bin/sh
#

OS_LSB=$(lsb_release -cs)
TS_GPG=/usr/share/keyrings/tailscale-archive-keyring.gpg

curl -fsSL https://pkgs.tailscale.com/stable/debian/$OS_LSB.noarmor.gpg | tee $TS_GPG >/dev/null
echo "deb [signed-by=$TS_GPG] https://pkgs.tailscale.com/stable/debian $OS_LSB main" | tee /etc/apt/sources.list.d/tailscale.list

apt update
apt install -y tailscale

tailscale up --login-server=http://scale.example.org --accept-dns=false --accept-routes