1
2
3
4
5

# ZeroTier 的做法
$ ssh root@10.147.17.23    # 你得记住这个 IP

# Tailscale 的做法
$ ssh root@myserver.example.net    # 自动解析，不用记 IP

1
2
3
4
5

{
  "acls": [
    {"action": "accept", "src": ["tag:server"], "dst": ["tag:db:*"]}
  ]
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

公网 (xxx.xxx.xxx.xxx)
  │
  ├─ 10443/TCP  ── headscale API + DERP 中继
  ├─ 3478/UDP   ── STUN (NAT 穿透)
  │
  └─ Tailnet (100.80.0.0/16)   ← 自定义子网，方便记忆
       ├─ 100.80.0.1  iStoreOS (家)
       ├─ 100.80.0.4  云服务器-A
       └─ 100.80.0.5  云服务器-B
            │
            └─ 子网路由 192.168.1.0/24 → iStoreOS 家里的局域网

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

# docker-compose.yaml
services:
  headscale:
    image: headscale/headscale:latest
    container_name: headscale
    restart: unless-stopped
    volumes:
      - ./data/headscale:/var/lib/headscale
    ports:
      - "10443:10443"    # HTTPS API + DERP 中继
      - "3478:3478/udp"  # STUN
    command: serve

  headplane:
    image: ghcr.io/tale/headplane:latest
    container_name: headplane
    restart: unless-stopped
    volumes:
      - ./data/headplane:/etc/headplane
    ports:
      - "127.0.0.1:3000:3000"  # 仅本地访问，或通过 Tailscale 私网
    depends_on:
      - headscale

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

# 1. 创建目录结构
mkdir -p data/headscale/tls data/headplane

# 2. 编写 config.yaml（见第八节配置对比）并放到 data/headscale/config/

# 3. 放置 TLS 证书到 data/headscale/tls/

# 4. 启动
docker compose up -d

# 5. 创建用户
docker exec headscale headscale users create <username>

# 6. 生成 Headplane API key
docker exec headscale headscale apikeys create

# 7. 编写 data/headplane/config.yaml（见 Headplane 配置章节）

# 8. 重启 headplane
docker compose restart headplane

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

# Linux 客户端
tailscale up --login-server=https://headscale.example.com:10443

# 在 headscale 上注册（通过 Headplane 面板或 CLI）
# 方式一：Headplane Web 面板 → Devices → Approve
# 方式二：CLI
docker exec headscale headscale nodes list
docker exec headscale headscale nodes register --user <username> --key <nodekey>

# 使用预授权密钥（推荐，无需手动批准）
docker exec headscale headscale preauthkeys create --user <username> --reusable
# 客户端：
tailscale up --login-server=https://headscale.example.com:10443 --auth-key=<key>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# data/headplane/config.yaml
headscale:
  url: http://headscale:8080      # 容器内通过 Docker 网络访问
  api_key: <your-api-key>         # 由 headscale apikeys create 生成

server:
  host: 0.0.0.0
  port: 3000
  cookie_secret: <random-32-char>   # 随机字符串，openssl rand -hex 16

  disable_api_key_login: false      # 允许 API key 登录

1
2

docker exec headscale headscale apikeys create
# 输出类似: hskey-api-PR3zh3Os-Bm7-...

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

$ tailscale debug derp headscale
{
  "Info": [
    "Region 999 == \"headscale\"",
    "Successfully established a DERP connection",
    "STUN response: xxx.xxx.xxx.xxx:58024"
  ],
  "Errors": [
    "Error connecting over IPv6: no such host"   # 无 IPv6，不影响
  ]
}

1
2
3

# config.yaml
server_url: https://headscale.example.com:10443
listen_addr: 0.0.0.0:10443

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

# nginx stream 模块
stream {
    map $ssl_preread_server_name $backend {
        headscale.example.com headscale_backend;
        www.example.com      website_backend;
        default              website_backend;
    }

    upstream headscale_backend {
        server 127.0.0.1:10443;
    }
    upstream website_backend {
        server 127.0.0.1:8443;
    }

    server {
        listen 443;
        proxy_pass $backend;
        ssl_preread on;
    }
}

1
2
3
4
5
6

headscale.example.com {
    reverse_proxy 127.0.0.1:8080 {
        header_up True-Client-IP {remote_host}
        header_up X-Real-IP {remote_host}
    }
}

1
2
3
4

server_url: https://headscale.example.com
listen_addr: 127.0.0.1:8080      # 仅本地监听，TLS 由 Caddy 处理
tls_cert_path: ""
tls_key_path: ""

1
2
3

# config.yaml
tls_cert_path: /var/lib/headscale/tls/cert.pem    # 证书文件（含完整证书链）
tls_key_path: /var/lib/headscale/tls/cert.key      # 私钥文件

1
2
3
4
5
6

# docker-compose.yaml
services:
  headscale:
    volumes:
      - ./tls/cert.pem:/var/lib/headscale/tls/cert.pem:ro
      - ./tls/cert.key:/var/lib/headscale/tls/cert.key:ro

1
2
3
4
5

# config.yaml
tls_letsencrypt_hostname: "headscale.example.com"
tls_letsencrypt_cache_dir: /var/lib/headscale/cache
tls_letsencrypt_challenge_type: HTTP-01
tls_letsencrypt_listen: ":http"

1
2
3
4
5
6

$ openssl s_client -servername headscale.example.com \
    -connect headscale.example.com:10443 2>/dev/null \
    | openssl x509 -noout -dates

notBefore=Feb  8 09:48:26 2026 GMT
notAfter=May   8 09:48:25 2026 GMT

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# 每月 1 号凌晨 3 点更新证书
# crontab -e
0 3 1 * * /usr/local/bin/renew-headscale-cert.sh

# renew-headscale-cert.sh
#!/bin/bash
# 将新证书拷贝到 headscale 的证书目录
cp /path/to/new/fullchain.pem /opt/headscale/tls/cert.pem
cp /path/to/new/privkey.pem /opt/headscale/tls/cert.key
# 重启 headscale 容器
docker restart headscale

1
2

tailscale set --netfilter-mode=nodivert
tailscale up --login-server=https://headscale.example.com:10443

1
2
3
4

# config.yaml
prefixes:
  v4: 100.80.0.0/16    # 方便记忆
  v6: fd7a:115c:a1e0::/48

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84

# ============================================================
# ① server_url — 客户端连接地址
# 官方默认: http://127.0.0.1:8080
# 我的配置: https://headscale.example.com:10443
# 差异: 必须配置为公网可访问的 HTTPS 地址
# ============================================================
server_url: https://headscale.example.com:10443

# ============================================================
# ② listen_addr — 监听地址
# 官方默认: 127.0.0.1:8080
# 官方生产: 0.0.0.0:8080
# 我的配置: 0.0.0.0:10443
# 差异: 直接监听 10443 提供 HTTPS（非标准端口），不经过反代
# ============================================================
listen_addr: 0.0.0.0:10443

# ============================================================
# ③ metrics_listen_addr — 不变
# 官方默认: 127.0.0.1:9090
# 我的配置: 127.0.0.1:9090 (一致)
# ============================================================
metrics_listen_addr: 127.0.0.1:9090

# ============================================================
# ④ prefixes — IP 地址池
# 官方默认: v4: 100.64.0.0/10
# 我的配置: v4: 100.80.0.0/16
# 差异: 缩小到 /16 子网，方便记忆
# 备注: 官方支持缩小范围，但不能超出 CGNAT/ULA 范围
# ============================================================
prefixes:
  v4: 100.80.0.0/16          # 官方是 100.64.0.0/10
  v6: fd7a:115c:a1e0::/48
  allocation: sequential

# ============================================================
# ⑤ derp.server — 内嵌 DERP
# 官方默认: enabled: false
# 我的配置: enabled: true
# 差异: 启用自建 DERP 中继，减少对 Tailscale 官方 DERP 的依赖
# 注意: 启用后必须配置 stun_listen_addr 和 ipv4
# ============================================================
derp:
  server:
    enabled: true                         # 官方默认是 false
    region_id: 999
    region_code: "headscale"
    region_name: "Headscale Embedded DERP"
    stun_listen_addr: "0.0.0.0:3478"
    automatically_add_embedded_derp_region: true
    ipv4: xxx.xxx.xxx.xxx               # 填写你的公网 IP
    private_key_path: /var/lib/headscale/derp_server_private.key

# ============================================================
# ⑥ TLS 证书
# 官方默认: tls_cert_path: "" (不使用 TLS)
# 我的配置: 手动指定证书路径
# 差异: 自签/购买证书，而非 Let's Encrypt
# ============================================================
tls_cert_path: /var/lib/headscale/tls/cert.pem
tls_key_path: /var/lib/headscale/tls/cert.key

# ============================================================
# ⑦ DNS — MagicDNS
# 官方默认: base_domain: example.com
# 我的配置: 自定义域名
# 差异: 使用自己的域名，同时配置国内 DNS 上游
# ============================================================
dns:
  magic_dns: true
  base_domain: example.net               # 官方示例是 example.com
  nameservers:
    global:
      - 223.5.5.5                        # 官方示例是 1.1.1.1，国内用阿里 DNS 更快

# ============================================================
# ⑧ node.expiry — 节点过期
# 官方默认: 0 (永不过期)
# 我的配置: 0 (一致)
# 备注: Tailscale SaaS 默认 180 天，如果你想要类似行为，设为 180d
# ============================================================
node:
  expiry: 0

1
2
3
4
5

# 推荐方式：tailscale set 持久化（v1.46+）
tailscale set --accept-routes

# 或者 tailscale up 时带参数
tailscale up --login-server=https://headscale.example.com:10443 --accept-routes

1
2
3

$ tailscale up --login-server=https://headscale.example.com:10443 --accept-routes
Error: changing settings via 'tailscale up' requires mentioning all
non-default flags. Use --reset or explicitly mention all non-default settings.

1
2

tailscale set --accept-routes --netfilter-mode=nodivert
tailscale up --login-server=https://headscale.example.com:10443

1
2
3
4
5
6
7

# 错误
$ ip route show | grep 192.168.1
# (空)

# 正确
$ ip route show table 52
192.168.1.0/24 dev tailscale0    # ✅ 在这里

1
2
3
4
5
6
7

# 查看当前连接状态
tailscale status
# 如果显示 "relay" 而非 "direct"，说明在走 DERP 中继

# 检查是否直连
tailscale ping <node>
# 输出会显示是 direct 还是 relay

1
2

Error: initializing: loading configuration: server_url cannot use the same domain
as base_domain in a way that could make the DERP and headscale server unreachable

1
2
3
4

server_url: https://headscale.example.com:10443
# ...
dns:
  base_domain: example.net    # 不同于 server_url 的 example.com

1
2
3
4
5
6
7

# 确保证书包含完整链
openssl verify -CAfile /path/to/cert.pem /path/to/cert.pem

# 检查证书和私钥是否匹配
openssl x509 -noout -modulus -in /path/to/cert.pem | md5sum
openssl rsa -noout -modulus -in /path/to/cert.key | md5sum
# 两个 md5 值应该相同

1
2
3
4
5
6

# 正确
docker exec headscale headscale users list
docker exec headscale headscale nodes list

# 错误
headscale users list   # command not found

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

# === Headscale 管理 ===
docker exec headscale headscale nodes list              # 列出所有节点
docker exec headscale headscale nodes list-routes       # 列出所有路由
docker exec headscale headscale nodes approve-routes -i <ID> -r <CIDR>  # 批准路由
docker exec headscale headscale users list              # 列出用户
docker exec headscale headscale preauthkeys create -u <user> --reusable  # 创建预授权密钥

# === 客户端 ===
tailscale status                                       # 查看连接状态
tailscale set --accept-routes                          # 持久化接受路由
tailscale set --exit-node=<node>                       # 设置出口节点
tailscale debug derp-map                               # 查看 DERP 地图
tailscale debug derp headscale                         # 测试自建 DERP 连通性
tailscale ping <node>                                  # 测试节点直连延迟
ip route show table 52                                 # 查看 Tailscale 路由表

# === 端口检测 ===
nc -zv <IP> 10443                                      # 检查 TCP 端口
nc -zuv <IP> 3478                                      # 检查 UDP 端口

# === 证书检查 ===
openssl s_client -servername headscale.example.com \
  -connect headscale.example.com:10443 2>/dev/null \
  | openssl x509 -noout -dates                         # 检查证书到期时间