Tailscale续集-自建Headscale&Derp

上回折腾了自建 Derper，这回干脆把控制平面也一起迁出来：Headscale + Headplane + 自建 DERP。

简单来说：

Headscale：Tailscale 控制平面的开源实现，负责设备注册、密钥交换、ACL、DNS 等。
Headplane：Headscale 的 Web 管理面板，用起来更接近官方 Tailscale 控制台。
DERP/Derper：当 P2P 打洞失败时的中继保底，也可辅助 NAT 穿透。

需要先说明的是，DERP 并不是“明文代理”。Tailscale 的 DERP 只转发已经加密的 WireGuard 数据包，中继节点本身看不到业务流量内容；客户端会从控制平面拿到 DERP Map，再根据延迟等信息选择可用中继。

但是 DERP 也不是普通 Web 服务。derper 会在 TLS 内做协议切换，不兼容许多普通 HTTP 反代，所以不要把 DERP 直接丢到 Nginx/Caddy 这种七层 HTTP 反代后面。DERP 的 TCP 端口可以用 Docker 映射，STUN 的 UDP 3478 也必须单独放通。

0. Pre 检测#

先把几个鸡生蛋、蛋生鸡的问题排掉，不然后面会很痛苦。

0.1 域名与端口#

本文使用两个域名：

1
derp.example.net       # DERP 中继
2
tailscale.example.net  # Headscale + Headplane

公网侧需要放通：

1
8443/tcp   # DERP TLS 入口，Docker 映射到容器内 443
2
3478/udp   # STUN
3
443/tcp    # Headscale / Headplane，由 Caddy 反代

注意：DERPPort 可以非标端口，本文用 8443；STUNPort 是 UDP，不能靠普通 HTTP 反代解决。

0.2 创建 Docker 网络#

本文里 DERP 和 Headscale 分开网络，Headscale/Headplane 接到 Caddy 所在网络：

1
docker network create derper_network || true
2
docker network create caddy_network || true

0.3 证书文件准备#

derper -certmode manual 对证书文件名比较挑剔。建议证书目录里至少准备：

1
derp.example.net.crt
2
derp.example.net.key

如果用的acme.sh管理，用如下命令安装：

1
acme.sh --install-cert \
2
-d derp.example.net \
3
--fullchain-file /path/to/certs/derp.example.net/derp.example.net.crt \
4
--key-file /path/to/certs/derp.example.net/derp.example.net.key \
5
--reloadcmd "docker restart derp"
6
# 也可以使用docker compose -f "/path/to/compose.yml" restart

如果你的证书管理器导出的是 fullchain.pem 和 privkey.pem，可以软链接一份：

1
mkdir -p ./certs/derp.example.net
2

3
ln -sf /path/to/fullchain.pem ./certs/derp.example.net/derp.example.net.crt
4
ln -sf /path/to/privkey.pem   ./certs/derp.example.net/derp.example.net.key
5

6
chmod 600 ./certs/derp.example.net/derp.example.net.key

如果你直接挂 1Panel、宝塔、Certd 这类面板的证书目录，也请确认容器内看到的文件名符合这个规则。

0.4 文件服务器存 DERP Map#

我这里让 Headscale 从文件服务器拉 DERP Map。这样后续加节点、删节点，不需要每次进容器改配置。

这里有一个坑：

headscale.derp.urls 适合放外部 URL，内容是 JSON DERP Map。
headscale.derp.paths 适合放本地文件，内容是 YAML DERP Map。

所以如果你要放到文件服务器，建议使用 JSON：

1
{
2
  "Regions": {
3
    "901": {
4
      "RegionID": 901,
5
      "RegionCode": "derp",
6
      "RegionName": "MY DERP",
7
      "Nodes": [
8
        {
9
          "Name": "901a",
10
          "RegionID": 901,
11
          "HostName": "derp.example.net",
12
          "DERPPort": 8443,
13
          "STUNPort": 3478,
14
          "STUNOnly": false
15
        }
16
      ]
17
    }
18
  }
19
}

保存到文件服务器，比如：

1
https://assets.example.net/tailscale/derpmap.json

先在服务器上测一下能否访问：

1
curl -fsSL https://assets.example.net/tailscale/derpmap.json

如果这里访问失败，后面 Headscale 可能启动后没有可用 DERP，甚至直接报 initial DERPMap is empty 一类错误。

如果你不想依赖文件服务器，也可以用本地 YAML：

1
regions:
2
  901:
3
    regionid: 901
4
    regioncode: derp
5
    regionname: My DERP
6
    nodes:
7
      - name: 901a
8
        regionid: 901
9
        hostname: derp.example.net
10
        derpport: 8443
11
        stunport: 3478
12
        stunonly: false

然后在 Headscale 配置中使用：

1
derp:
2
  urls: []
3
  paths:
4
    - /etc/headscale/derp.yaml

0.5 确保能连回服务器#

自建控制平面最怕“服务在服务器上，但服务器自己访问不了自己的公网域名”。

后续至少要确认：

1
curl -I https://tailscale.example.net
2
openssl s_client -connect derp.example.net:8443 -servername derp.example.net </dev/null
3
curl -vk https://derp.example.net:8443/

如果服务器自身访问 tailscale.example.net 或 derp.example.net 会走错线路，建议先解决 DNS、回源、云防火墙、NAT 回环问题。

1. 启动 DERP#

docker-compose.yml：

1
services:
2
  derp:
3
    image: sparanoid/derp:edge
4
    container_name: derp
5
    restart: always
6
    init: true
7
    ports:
8
      - "8443:443"
9
      - "3478:3478/udp"
10
      # DERPPort 可以通过 Docker 端口映射改成非标端口
11
      # STUNPort 是 UDP，需要公网直接放通
12
    volumes:
13
      - ./certs/derp.example.net:/app/certs:ro
14
      # certdir 内建议包含：
15
      # derp.example.net.crt
16
      # derp.example.net.key
17

18
      - /var/run/tailscale/tailscaled.sock:/var/run/tailscale/tailscaled.sock
19
      # 后续开启 -verify-clients=true 时使用
20
      # 需要宿主机运行 tailscaled，并且已经加入对应 tailnet
21

22
  command: sh -c "
23
      derper \
24
        -hostname derp.example.net \
25
        -certdir /app/certs \
26
        -certmode manual \
27
        - verify-clients false \
28
        -home blank"
29

30
    # 一些可选启动参数：
31
    # -verify-clients true 启用客户端验证，防止DERP被偷，需要配合Tailscale使用，且需要挂载Tailscale的套接字文件
32
    # -home blank 访问DERP返回空白界面，简单防止DERP服务被扫。
33
    # -home https://xxx.com 访问DERP跳转指定URL
34

35
    networks:
36
      - derper_network
37

38
networks:
39
  derper_network:
40
    external: true

启动：

1
docker compose up -d
2
docker logs -f derp

测试：

1
curl -vk https://derp.example.net:8443/

如果 -home blank 生效，浏览器访问可能就是空白页，这不是坏事。主要看 TLS 是否正常、容器日志是否正常。

再次强调：本文没有把 DERP 走 Caddy HTTP 反代。DERP 不是普通 WebSocket/HTTP 服务，不建议这么玩。

2. 启动 Headscale + Headplane#

目录结构大概这样：

1
.
2
|-- compose.yml
3
|-- headplane-config
4
|   `-- config.yaml
5
|-- headplane-data
6
|-- headscale-config
7
|   |-- config.yaml
8
|   `-- dns_records.json
9
`-- headscale-data

先初始化 dns_records.json：

1
mkdir -p headscale-config headscale-data headplane-config headplane-data
2
echo "[]" > headscale-config/dns_records.json

后续如果需要添加自定义的dns records，可以在web console配置，但需要重启headscale才能生效，而新增主机的magic dns则不受影响容器内需要挂载docker socket才能重启，但出于安全考虑，不建议这种做法

2.1 Headscale 配置#

./headscale-config/config.yaml：

1
server_url: https://tailscale.example.net
2
listen_addr: 0.0.0.0:8080
3
metrics_listen_addr: 0.0.0.0:9090
4
grpc_listen_addr: 0.0.0.0:50443
5
grpc_allow_insecure: false
6

7
noise:
8
  private_key_path: /var/lib/headscale/noise_private.key
9

10
prefixes:
11
  v4: 100.64.0.0/10
12
  v6: fd7a:115c:a1e0::/48
13

14
allocation: sequential
15

16
derp:
17
  server:
18
    enabled: false
19
    region_id: 901
20
    region_code: "derp"
21
    region_name: "My DERP"
22
    verify_clients: true
23
    stun_listen_addr: "0.0.0.0:3478"
24
    private_key_path: /var/lib/headscale/derp_server_private.key
25

26
  urls:
27
    - https://assets.example.net/tailscale/derpmap.json
28

29
  paths: []
30
  auto_update_enabled: true
31
  update_frequency: 24h
32

33
disable_check_updates: false
34
ephemeral_node_inactivity_timeout: 30m
35

36
database:
37
  type: sqlite
38
  debug: false
39
  gorm:
40
    prepare_stmt: true
41
    parameterized_queries: true
42
    skip_err_record_not_found: true
43
    slow_threshold: 1000
44
  sqlite:
45
    path: /var/lib/headscale/db.sqlite
46
    write_ahead_log: true
47
    wal_autocheckpoint: 1000
48

49
acme_url: https://acme-v02.api.letsencrypt.org/directory
50
acme_email: ""
51
tls_letsencrypt_hostname: ""
52
tls_letsencrypt_cache_dir: /var/lib/headscale/cache
53
tls_letsencrypt_challenge_type: HTTP-01
54
tls_letsencrypt_listen: ":http"
55
tls_cert_path: ""
56
tls_key_path: ""
57

58
log:
59
  level: info
60
  format: text
61

62
policy:
63
  mode: database
64
  path: ""
65

66
dns:
67
  magic_dns: true
68
  base_domain: tailnet.example.net
69
  override_local_dns: true
70
  nameservers:
71
    global:
72
      - 1.1.1.1
73
      - 1.0.0.1
74
      - 2606:4700:4700::1111
75
      - 2606:4700:4700::1001
76
  split: {}
77
  search_domains: []
78
  extra_records: []
79
  extra_records_path: /etc/headscale/dns_records.json
80

81
unix_socket: /var/run/headscale/headscale.sock
82
unix_socket_permission: "0770"
83

84
logtail:
85
  enabled: false
86

87
randomize_client_port: false
88

89
taildrop:
90
  enabled: true

这里 server_url 必须是客户端能访问到的公网 HTTPS 地址。
base_domain 不要和 server_url 完全一样，MagicDNS 用它生成类似 hostname.tailnet.example.net 的域名。

2.2 Headplane 配置#

生成一个 32 字符的 cookie secret：

1
openssl rand -hex 16

./headplane-config/config.yaml：

1
host: "0.0.0.0"
2
port: 3000
3

4
# 不要带 /admin
5
base_url: "https://tailscale.example.net"
6

7
cookie_secret: "替换成 openssl rand -hex 16 生成的值"
8
cookie_secure: true
9
cookie_max_age: 86400
10

11
data_path: "/var/lib/headplane"
12

13
headscale:
14
  url: "http://headscale:8080"
15
  public_url: "https://tailscale.example.net"
16
  config_path: "/etc/headscale/config.yaml"
17
  config_strict: true
18
  dns_records_path: "/etc/headscale/dns_records.json"
19

20
integration:
21
  agent:
22
    enabled: false
23
    pre_authkey: ""
24

25
  docker:
26
    enabled: true
27
    container_label: "me.tale.headplane.target=headscale"
28
    socket: "unix:///var/run/docker.sock"
29

30
  kubernetes:
31
    enabled: false
32
    validate_manifest: true
33
    pod_name: "headscale"
34

35
  proc:
36
    enabled: false
37

38
# 不配置 OIDC 时，Headplane 登录依赖 Headscale API Key
39
# oidc:
40
#   enabled: true

Headplane 的 Docker 部署方式要求配置文件和数据目录持久化；如果要让它在 UI 里管理 DNS、ACL 等配置，还需要挂载 Headscale 配置文件和 Docker socket。官方文档也说明了 Docker 模式、/admin 访问路径和 API key 登录方式。(Headplane)

2.3 Docker Compose#

docker-compose.yml：

1
services:
2
  headplane:
3
    image: ghcr.io/tale/headplane:0.6.2
4
    container_name: headplane
5
    restart: unless-stopped
6
    volumes:
7
      - "./headplane-config/config.yaml:/etc/headplane/config.yaml"
8
      # This should match headscale.config_path in your config.yaml
9
      - "./headscale-config/config.yaml:/etc/headscale/config.yaml"
10

11
      # If using dns.extra_records in Headscale (recommended), this should
12
      # match the headscale.dns_records_path in your config.yaml
13
      - "./headscale-config/dns_records.json:/etc/headscale/dns_records.json"
14

15
      # Headplane stores its data in this directory
16
      - "./headplane-data:/var/lib/headplane"
17

18
      # If you are using the Docker integration, mount the Docker socket
19
      - "/var/run/docker.sock:/var/run/docker.sock:ro"
20
      - "/etc/localtime:/etc/localtime:ro"
21
    networks:
22
      - caddy_network
23

24
  headscale:
25
    image: headscale/headscale:0.28.0
26
    restart: unless-stopped
27
    container_name: headscale
28
    # 这里可以先映射端口，测试访问成功后再配置caddy路由
29
    # ports:
30
    #   - "127.0.0.1:8080:8080"
31
    #   - "127.0.0.1:9090:9090"
32
    volumes:
33
      - "./headscale-data:/var/lib/headscale"
34
      - "./headscale-config:/etc/headscale"
35
      - "/etc/localtime:/etc/localtime:ro"
36
    command: serve
37
    healthcheck:
38
      test: ["CMD", "headscale", "health"]
39
      interval: 30s
40
      timeout: 10s
41
      retries: 3
42
    networks:
43
      - caddy_network
44

45
networks:
46
  caddy_network:
47
    external: true

启动：

1
docker compose up -d
2
docker logs -f headscale
3
docker logs -f headplane

检查健康状态：

1
docker exec -it headscale headscale health

也可以从公网访问：

1
curl -I https://127.0.0.1:8080/health

Headscale 官方文档也建议先确认公网 health endpoint 可访问，再继续注册节点。(Headscale)

3. 配置 Caddy 路由#

我的 Caddy 是统一的 wildcard 入口，所以只加一个 matcher：

1
@tailscale {
2
  host tailscale.example.net
3
}
4

5
handle @tailscale {
6
  route {
7
    # Headplane 默认在 /admin
8
    @admin path /admin*
9
    handle @admin {
10
      reverse_proxy headplane:3000
11
      header {
12
        Access-Control-Allow-Origin  *
13
        Access-Control-Allow-Headers *
14
        Access-Control-Allow-Methods GET, POST, OPTIONS
15
      }
16
    }
17

18
    # 其余全部路由到 Headscale
19
    handle {
20
      reverse_proxy headscale:8080
21
    }
22
  }
23
}

如果你不是 wildcard Caddyfile，也可以单独写：

1
tailscale.example.net {
2
  encode zstd gzip
3

4
  @admin path /admin*
5
  handle @admin {
6
    reverse_proxy headplane:3000
7
  }
8

9
  handle {
10
    reverse_proxy headscale:8080
11
  }
12
}

注意：这里只代理 tailscale.example.net。
derp.example.net:8443 不要走这个 Caddy HTTP 反代。

重载 Caddy：

1
docker exec -it caddy caddy reload --config /etc/caddy/Caddyfile

也可以直接

1
docker compose down && docker compose up -d

4. 部署与接入客户端#

4.1 生成 Headplane 访问密钥#

进入 Headscale 容器，生成 API Key：

1
docker exec -it headscale headscale apikeys create --expiration 999d

然后打开：

1
https://tailscale.example.net/admin

粘贴 API Key 登录。

不配置 OIDC 的情况下，Headplane 不是传统“用户名 + 密码”的永久账户体系，而是靠 Headscale API Key 登录。想要更像正常后台账号，需要后续单独接 OIDC。

4.2 创建 Headscale 用户#

如果不想在 Web Console 里创建，也可以 CLI 创建：

1
docker exec -it headscale headscale users create username
2
docker exec -it headscale headscale users list

Headscale 0.28 以后不要再按老教程写 namespace 了，直接用 users。

4.3 Web Console 配置#

进入 Headplane 后，建议先做这些：

配置 Tailnet Name
打开 MagicDNS（可选）
确认 DNS Base Domain 不和 tailscale.example.net 冲突
确认 DERP Map 能看到 My DERP
创建 Pre-auth Key

如果你只是个人使用，Pre-auth Key 可以选：

1
Reusable:   按需开启
2
Ephemeral:  一般关闭
3
Expiration: 按需设置

4.4 命令行生成 Pre-auth Key#

也可以 CLI 生成。先看用户 ID：

1
docker exec -it headscale headscale users list

然后创建：

1
docker exec -it headscale headscale preauthkeys create --user <USER_ID>

如果需要复用、调整有效期等参数，先看当前版本帮助：

1
docker exec -it headscale headscale preauthkeys create --help

4.5 Linux 客户端加入#

1
sudo tailscale up \
2
  --login-server="https://tailscale.example.net" \
3
  --authkey="你的 preauthkey"

如果之前已经登录过官方 Tailscale 或其他 Headscale，建议加 --reset：

1
sudo tailscale up --reset \
2
  --login-server="https://tailscale.example.net" \
3
  --authkey="你的 preauthkey"

如果你不想让 Headscale 接管 DNS：

1
sudo tailscale up --reset \
2
  --login-server="https://tailscale.example.net" \
3
  --authkey="你的 preauthkey" \
4
  --accept-dns=false

如果你打开了 MagicDNS，就不要加 --accept-dns=false。

4.6 Windows 客户端加入#

管理员 PowerShell：

1
tailscale up --login-server="https://tailscale.example.net" --authkey="你的 preauthkey"

如果旧状态干扰：

1
tailscale up --reset --login-server="https://tailscale.example.net" --authkey="你的 preauthkey"

4.7 检查 DERP 是否生效#

客户端执行：

1
tailscale netcheck
2
tailscale debug derp-map

看输出里是否有类似：

1
My DERP
2
derp.example.net

再找另一个节点测试：

1
tailscale ping <对端节点名或 100.x 地址>

如果直连成功，会显示 direct；如果走中继，会显示 DERP。DERP 是保底，不是目标。能直连当然优先直连，不能直连时再走自建中继。

5. 开启防偷#

DERP 不开验证的话，只要别人拿到你的 DERP Map，就可能把你的中继当公共节点用。 ~~小机器带宽本来就贵，不能当赛博慈善家。~~

防偷有两种思路。

5.1 方案一：Headscale `/verify`#

这是我更推荐给 Headscale + Derper 的方式。Headscale 文档里提到，第三方 derper 可以通过 -verify-client-url 指向 Headscale 的 /verify 端点，由 Headscale 判断客户端是否属于本 Tailnet；-verify-client-url-fail-open 控制 Headscale 不可达时是放行还是拒绝，默认行为偏宽松，强迫症可以关掉。(Headscale)

~~当然我是懒狗，多derp单headscale，所有derp用一套配置CtrlCV更省事，我用的第二套，~~ 第一套我没测

修改 DERP 的启动参数：

1
command:
2
  - derper
3
  - -hostname
4
  - derp.example.net
5
  - -certdir
6
  - /app/certs
7
  - -certmode
8
  - manual
9
  - -verify-client-url
10
  - https://tailscale.example.net/verify
11
  - -verify-client-url-fail-open=false
12
  - -home
13
  - blank

然后重启：

1
docker compose up -d
2
docker logs -f derp

确保 derp 容器能访问：

1
docker exec -it derp wget -qO- https://tailscale.example.net/health

如果容器访问自己的公网域名不通，先修 DNS/NAT 回环/防火墙，不要急着怪 Headscale。

5.2 方案二：`-verify-clients=true` + 本机 tailscaled#

如果你想沿用传统方式，也可以让 derper 通过本机 tailscaled.sock 判断客户端身份。

前提：

DERP 宿主机安装并运行 Tailscale 客户端。
这个 Tailscale 客户端已经加入你的 Headscale tailnet。
derper 容器挂载 /var/run/tailscale/tailscaled.sock。
启动参数打开 -verify-clients=true。

修改：

1
volumes:
2
  - ./certs/derp.example.net:/app/certs:ro
3
  - /var/run/tailscale/tailscaled.sock:/var/run/tailscale/tailscaled.sock
4

5
command: sh -c "
6
  derper \
7
  -hostname derp.example.net \
8
  -certdir /app/certs \
9
  -certmode manual \
10
  - verify-clients true \
11
  -home blank"
12

13
# 一些可选启动参数：
14
# -verify-clients true 启用客户端验证，防止DERP被偷，需要配合Tailscale使用，且需要挂载Tailscale的套接字文件
15
# -home blank 访问DERP返回空白界面，简单防止DERP服务被扫。
16
# -home https://xxx.com 访问DERP跳转指定URL

Tailscale 官方 derper README 里也提醒了：如果使用 --verify-clients，同机需要运行 tailscaled，并且客户端需要对 derper 旁边的 tailscaled 可见。(GitHub)

重启后再次测试：

1
docker compose up -d
2
tailscale status
3
tailscale netcheck
4
tailscale debug derp-map
5
tailscale ping <对端节点>

常见坑#

1. Headscale 启动失败：DERPMap 为空#

检查：

1
curl -fsSL https://assets.example.net/tailscale/derpmap.json
2
docker logs headscale

如果使用 urls，外部 DERP Map 应为 JSON；如果使用 paths，本地 DERP Map 应为 YAML。不要混。

2. DERP 网页能打开，但客户端不用它#

检查 DERP Map 里的端口：

1
"DERPPort": 8443,
2
"STUNPort": 3478

再检查云防火墙、安全组、本机防火墙是否都放通了 8443/tcp 和 3478/udp。

3. `tailscale netcheck` 过了，但实际还是连不上#

netcheck 只能说明一部分网络状态正常，不代表所有路径都完全可用。继续看：

1
tailscale debug derp-map
2
tailscale ping <peer>
3
tailscale status

必要时看客户端日志。

4. Headplane 登录不了#

先重新生成 API Key：

1
docker exec -it headscale headscale apikeys create --expiration 999d

再确认 Headplane 配置中的：

1
headscale:
2
  url: "http://headscale:8080"
3
  public_url: "https://tailscale.example.net"

url 是容器内访问 Headscale 的地址；public_url 是浏览器和用户看到的公网地址。

5. MagicDNS 打开后系统 DNS 被改乱#

客户端加入时可以临时禁用：

1
tailscale up --reset \
2
  --login-server="https://tailscale.example.net" \
3
  --authkey="你的 preauthkey" \
4
  --accept-dns=false

等 Headscale 的 DNS 配置确认没问题后再打开。

总结#

至此，控制平面和中继平面都迁到了自己手里：

1
客户端
2
  ↓
3
tailscale.example.net
4
  ↓
5
Headscale 控制平面
6
  ↓
7
下发 DERP Map / DNS / ACL
8

9
客户端 A ←→ 客户端 B
10
  ↳ 能直连就直连
11
  ↳ 不能直连就走 derp.example.net:8443

这套方案的优点很明显：

不依赖 Tailscale 官方控制台
自己管理用户、设备、DNS、ACL
DERP 节点位置可控，延迟更低
开启 verify 后，不容易被人白嫖中继

缺点也同样明显：

证书、端口、DNS、配置都要自己维护
DERP/Headscale 都是关键基础设施，挂了就会影响新连接和中继
配置文件格式和版本变化比较快，升级前要看 release note

不过折腾嘛，本来就是这样：
先把能跑的跑起来，再把跑起来的修到好用。