Headscale自部署指南：用Docker搭建Tailscale开源替代方案

痛点：免费的Tailscale只有3个用户#

用 Tailscale 组网非常爽——装个客户端，登录账号，所有设备就在一个虚拟局域网里了。问题是：免费版最多 3 个用户。

当你的设备超过 3 台——笔记本、台式机、两台服务器、手机——免费版直接不够用。付费版 $6/月起，一年下来也小几百块。而且数据经过 Tailscale 的中继服务器，虽然加密了，但总有那么点不放心。

Headscale 就是答案。

Headscale 是 Tailscale 控制服务器的开源实现，完全兼容 Tailscale 客户端。你只需要一台有公网 IP 的 VPS，就能自建一套功能完整的 Tailscale 组网服务。没有用户数限制，数据不经第三方，连 DERP 中继服务器也能自建。

本文用 Docker Compose 完成全套部署：Headscale 控制服务 + Caddy HTTPS 反向代理 + headscale-ui 管理面板 + 自建 DERP 中继。

Headscale ≠ VPN：理解 P2P Mesh 组网#

在动手部署之前，先搞清楚 Headscale 在整个组网中扮演的角色。

Tailscale/Headscale 不是传统的 VPN（Virtual Private Network），而是一种 P2P Mesh 网络。两者的核心区别：

Headscale 的工作机制用一个简单的流程就能说明：

1
设备A ──注册到──▶ Headscale 控制服务器
2
设备B ──注册到──▶ Headscale 控制服务器
3

4
控制服务器告诉 A："B 的公网 IP 是 x.x.x.x:3478"
5
控制服务器告诉 B："A 的公网 IP 是 y.y.y.y:3478"
6

7
设备A ◀───直接 UDP 连接───▶ 设备B
8
       ↕ NAT 穿透失败时走 DERP 中继

关键点：Headscale 只负责控制面——处理注册、分配 IP、交换节点信息。真正的数据传输是设备之间的直连 UDP（STUN 打洞），流量完全不经过 Headscale 服务器。只有 NAT 穿透失败时，才回退到 DERP 中继。

部署架构#

我们用 Docker Compose 部署三个服务：

1
┌─────────────────────────────────────┐
2
│              VPS（公网）              │
3
│                                     │
4
│  ┌──────────┐  ┌──────────┐        │
5
│  │ Headscale │  │  Caddy   │        │
6
│  │ :8080     │◀─│ HTTPS    │────8080│
7
│  │ :9090     │  │ :443     │        │
8
│  └─────┬────┘  └──────────┘        │
9
│        │                           │
10
│  ┌─────┴────┐                      │
11
│  │ headscale │                      │
12
│  │  -ui      │                      │
13
│  └──────────┘                      │
14
│                                     │
15
│  端口：443(HTTPS) 3478(STUN/DTLS)   │
16
└─────────────────────────────────────┘

• Headscale：核心控制服务，监听 8080（HTTP API）
• Caddy：自动 HTTPS 反向代理，将域名流量转发给 Headscale
• headscale-ui：Web 管理面板，方便管理节点和用户

环境要求#

• 一台有公网 IP 的 VPS（1 核 1GB 内存足够）
• 一个域名（例如 hs.example.com），解析到 VPS 的 IP
• 安装 Docker 和 Docker Compose

Docker Compose 部署#

1
mkdir -p /opt/headscale/{config,data,ui} && cd /opt/headscale

1
version: "3.9"
2

3
services:
4
  headscale:
5
    image: headscale/headscale:0.29.1
6
    container_name: headscale
7
    restart: unless-stopped
8
    volumes:
9
      - ./config:/etc/headscale
10
      - ./data:/var/lib/headscale
11
    ports:
12
      - "3478:3478/udp"   # STUN/DERP over DTLS
13
    command: serve
14
    networks:
15
      - headnet
16

17
  headscale-ui:
18
    image: ghcr.io/gurucomputing/headscale-ui:latest
19
    container_name: headscale-ui
20
    restart: unless-stopped
21
    networks:
22
      - headnet
23

24
  caddy:
25
    image: caddy:2-alpine
26
    container_name: caddy
27
    restart: unless-stopped
28
    ports:
29
      - "80:80"
30
      - "443:443"
31
    volumes:
32
      - ./Caddyfile:/etc/caddy/Caddyfile
33
      - ./data/caddy:/data
34
    networks:
35
      - headnet
36

37
networks:
38
  headnet:
39
    driver: bridge

1
docker run --rm headscale/headscale:0.29.1 headscale config > config/config.yaml

1
# 你的域名
2
server_url: https://hs.example.com:443
3
# Headscale 内部监听地址
4
listen_addr: 0.0.0.0:8080
5
# 内部 gRPC（UI 使用）
6
metrics_listen_addr: 0.0.0.0:9090
7
# IP 分配范围
8
ip_prefixes:
9
  - 100.64.0.0/10
10
# DERP 配置
11
derp:
12
  server:
13
    enabled: true
14
    region_id: 999
15
    region_code: "selfhost"
16
    region_name: "Self-hosted DERP"
17
    stun_listen_addr: "0.0.0.0:3478"
18
    private_key_path: /var/lib/headscale/derp_server_key
19
  urls: []
20
  auto_update_enabled: false
21
# 随机化节点端口（提高 STUN 打洞成功率）
22
randomize_client_port: true

1
hs.example.com {
2
    reverse_proxy headscale:8080
3
}
4

5
ui.hs.example.com {
6
    reverse_proxy headscale-ui:80
7
}

1
docker compose up -d

1
docker compose ps
2
docker compose logs -f headscale

创建用户并接入客户端#

1
# 在 headscale 容器中执行
2
docker compose exec headscale headscale users create myhome
3

4
# 创建预授权密钥（有效期24小时）
5
docker compose exec headscale headscale preauthkeys create --user myhome --expiration 24h

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

4
# 连接到自建 Headscale
5
sudo tailscale up --login-server=https://hs.example.com --authkey=<上一步生成的密钥>

1
tailscale up --login-server=https://hs.example.com --authkey=<密钥>

1
tailscale status

1
100.64.0.1  headscale         john@        linux   -
2
100.64.0.2  laptop            john@        macOS   active; direct x.x.x.x:3478
3
100.64.0.3  server-prod       john@        linux   active; relay "selfhost"

DERP 中继部署与配置#

DERP（Detoured Encrypted Relay Protocol）是 Tailscale/Headscale 的保底机制——当两个设备之间的 NAT 穿透失败时（比如双方都在对称 NAT 后面），流量会通过 DERP 中继服务器转发。

1
# 在 docker-compose.yml 中添加
2
services:
3
  derper:
4
    image: headscale/headscale:0.29.1
5
    container_name: derper
6
    restart: unless-stopped
7
    entrypoint: ["derper"]
8
    command: ["--hostname=hs.example.com", "--verify-clients=true"]
9
    ports:
10
      - "3478:3478/udp"
11
    volumes:
12
      - ./data/derper:/var/lib/headscale/derper
13
    networks:
14
      - headnet

1
docker compose exec headscale headscale debug derp

1
Regions:
2
  999 (selfhost):
3
    - node: selfhost-derp (STUN: 0.0.0.0:3478)
4
      IPv4: hs.example.com
5
      can dial: ✅ Home: 200ms

1
# 在客户端上查看 DERP 延迟
2
tailscale status --json | jq '.Peer | to_entries[] | {name: .value.DNSName, relay: .value.Relay}'

1
# 在不同 VPS 上部署独立的 DERP 实例，然后在 Headscale 配置中注册
2
derp:
3
  server:
4
    enabled: true
5
    region_id: 999
6
    region_code: "selfhost"
7
    region_name: "Self-hosted DERP"
8
    stun_listen_addr: "0.0.0.0:3478"
9
  # 手动添加其他 DERP 节点
10
  urls: []
11
  auto_update_enabled: false
12
  nodes:
13
    - region_id: 999
14
      region_code: "selfhost"
15
      region_name: "Self-hosted DERP"
16
      # 可以添加多个节点
17
      nodes:
18
        - name: "derp-asia"
19
          region_id: 999
20
          hostname: "hs.example.com"
21
          stun_port: 3478
22
          stun_only: false
23
        - name: "derp-eu"
24
          region_id: 1000
25
          hostname: "eu.hs.example.com"
26
          stun_port: 3478
27
          stun_only: false

1
# config.yaml 中的 derp 配置
2
derp:
3
  server:
4
    enabled: true
5
    region_id: 999
6
    region_code: "selfhost"
7
    region_name: "Self-hosted DERP"
8
    stun_listen_addr: "0.0.0.0:3478"
9
  # 用官方的 DERP 列表作为 fallback
10
  urls:
11
    - https://controlplane.tailscale.com/derpmap/default
12
  auto_update_enabled: true

使用 headscale-ui 管理#

浏览器打开 https://ui.hs.example.com，输入 Headscale API 地址：

1
API URL: https://hs.example.com

在 Headscale 中生成 API Key：

1
docker compose exec headscale headscale apikeys create

把生成的 Key 粘贴到 UI 中，就能可视化地管理所有节点了：

• 查看在线/离线设备
• 路由配置
• 用户管理
• 节点过期时间

运维技巧#

1
# 每小时清理过期节点
2
docker compose exec headscale headscale nodes expire --all

1
0 * * * * docker compose exec -T headscale headscale nodes expire --all

1
# 查看实时日志
2
docker compose logs -f headscale
3

4
# 查看已注册节点
5
docker compose exec headscale headscale nodes list
6

7
# 查看路由状态
8
docker compose exec headscale headscale routes list
9

10
# 查看用户列表
11
docker compose exec headscale headscale users list

1
cd /opt/headscale
2

3
# 拉取最新镜像
4
docker compose pull headscale
5

6
# 重新创建容器
7
docker compose up -d --force-recreate headscale
8

9
# 检查版本和迁移状态
10
docker compose logs headscale | grep -i "migration\|version"

1
tar -czf backup-$(date +%Y%m%d).tar.gz data/

1
acl_policy_path: /etc/headscale/acl.hujson

1
{
2
  "groups": {
3
    "group:admin": ["tag:admin"],
4
    "group:dev": ["tag:dev"]
5
  },
6
  "acls": [
7
    {"action": "accept", "src": ["tag:admin"], "dst": ["*:*"]},
8
    {"action": "accept", "src": ["tag:dev"], "dst": ["tag:dev:*"]}
9
  ]
10
}

1
# 备份整个 headscale 数据目录
2
tar -czf headscale-backup-$(date +%Y%m%d).tar.gz /opt/headscale/data

Headscale vs Tailscale 对比#

常见问题 FAQ#

Q：为什么我用 tailscale status 看到是 relay 而不是 direct？

A：说明 NAT 穿透没成功，流量走了 DERP 中继。首先确认设备的 UDP 端口（3478）能被双方访问。如果双方都在严格 NAT 后面（如公司网络 + 手机热点），基本只能走 relay，但延迟通常也在可接受范围内。

Q：Headscale 的 IP 段为什么要用 100.64.0.0/10？

A：这是 IANA 预留的运营商级 NAT（CGNAT）地址段，与内网地址（192.168.x.x/10.x.x.x）不冲突，也不会和公网 IP 冲突，是 Tailscale/Headscale 的默认分配段。

Q：迁移已有的 Tailscale 设备到 Headscale 需要重装吗？

A：不需要重装。直接在设备上执行 sudo tailscale logout 退出官方网络，然后 sudo tailscale up --login-server=https://hs.example.com 重新登录即可。

Q：Headscale 支持 MagicDNS 吗？

A：支持。在 config.yaml 中启用 dns.magic_dns: true，然后在客户端 tailscale up --accept-dns 即可通过设备名互相访问（例如 ping laptop 而不是 ping 100.64.0.2）。

Q：能否把已有的 WireGuard 配置导入 Headscale？

A：不能直接导入。Headscale 的节点管理完全通过控制平面进行，需要每台设备用 Tailscale 客户端重新注册。不过你可以在 Headscale 中手动添加子网路由，让 Headscale 网络访问现有 WireGuard 子网。

Q：Headscale 支持 exit node（出口节点）吗？

A：支持。在要作为 exit node 的设备上执行 sudo tailscale up --login-server=https://hs.example.com --advertise-routes=0.0.0.0/0,::/0，然后在 Headscale 中启用路由即可。这样所有设备可以经过该节点访问公网，适合用来做科学上网或远程办公网络出口。

Q：我用的是 frp/Cloudflare Tunnel 暴露内网服务，和 Headscale 比哪个好？

A：场景不同。frp 和 Cloudflare Tunnel 适合暴露单个端口给公网（如把内网的 Web 服务发布出去）。Headscale 适合设备互联——让你的所有设备在一个虚拟局域网里互相访问。如果只是发布一个 Web 服务，frp 更简单；如果你需要 SSH 到任意设备、传输文件、访问内网资源，Headscale 更合适。

Q：Headscale 控制服务器宕机了，现有连接会断吗？

A：不会。Headscale 控制服务器只负责注册和信令交换（handshake），设备之间的 P2P 连接一旦建立，就不依赖控制服务器。即使控制服务器宕机了，已有连接照常工作。只是新设备无法注册加入网络，已有连接的保活机制会继续运行。

总结#

Headscale 让你在 VPS 上自建一套完整的 P2P Mesh 组网服务，摆脱 Tailscale 免费版的 3 用户限制，同时数据完全由自己掌控。Docker Compose 部署方式让整个过程足够丝滑——从零到上线，半小时就能搞定。

有了 Headscale，你的所有设备——笔记本、服务器、树莓派、手机——都在一张网里。SSH 不用再开公网端口，文件传输用内网速度，数据库直连走加密通道。

部署清单回顾：

1. ✅ 准备一台公网 VPS + 域名
2. ✅ Docker Compose 部署 Headscale + Caddy + headscale-ui
3. ✅ 创建用户和预授权密钥
4. ✅ 客户端接入验证
5. ✅ 可选：自建 DERP 中继 + ACL 策略

如果你在部署中遇到问题，欢迎评论区留言。

延伸阅读#

• Docker 换源避坑指南 — 部署前的必备准备
• Nginx Proxy Manager 反代面板 — 统一管理所有服务的访问入口
• Uptime Kuma 自建服务监控 — 所有服务状态一目了然