Headscale 自建组网部署笔记

# Headscale 自建组网部署笔记

自建 Headscale 控制面 + DERP 中转服务器，实现私有 Tailscale 组网。

# 架构概览

┌─────────────────────────────────────────────────────┐
│                  自建 Headscale 组网                  │
├─────────────────────────────────────────────────────┤
│                                                     │
│  ┌──────────────┐    ┌──────────────┐              │
│  │  Headscale   │    │ DERP Server  │              │
│  │  控制面      │◄──►│  数据中转    │              │
│  │  (Control)   │    │  (NAT穿透)   │              │
│  └──────┬───────┘    └──────┬───────┘              │
│         │                   │                      │
│    管理API/ACL          WireGuard隧道              │
│         │                   │                      │
├─────────┼───────────────────┼──────────────────────┤
│         ▼                   ▼                      │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐  │
│  │  节点 A    │  │  节点 B    │  │  节点 C    │  │
│  │ (服务器)   │  │ (手机)     │  │ (笔记本)   │  │
│  └────────────┘  └────────────┘  └────────────┘  │
└─────────────────────────────────────────────────────┘

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

# 端口规划

服务	端口	协议	说明
Headscale API	8080	TCP	控制面 API（仅本地监听）
DERP Server	443/8443	TCP	HTTPS 数据中转
STUN Server	3478	UDP	NAT 穿透探测

# 部署步骤

# 1. 安装 Headscale

# 下载最新版本（以 v0.29.1 为例）
cd /tmp
curl -sLO "https://github.com/juanfont/headscale/releases/download/v0.29.1/headscale_0.29.1_linux_amd64"
chmod +x headscale_0.29.1_linux_amd64
cp headscale_0.29.1_linux_amd64 /usr/local/bin/headscale

# 创建目录
mkdir -p /etc/headscale /var/lib/headscale

1
2
3
4
5
6
7
8

# 2. 生成密钥

# 生成私钥
headscale generate private-key > /var/lib/headscale/private.key
headscale generate private-key > /var/lib/headscale/noise_private.key
chmod 600 /var/lib/headscale/*.key

1
2
3
4

# 3. 配置文件

创建 /etc/headscale/config.yaml：

# 服务器地址（客户端连接地址）
server_url: http://<SERVER_IP>:8080

# 监听地址（仅本地访问）
listen_addr: 127.0.0.1:8080

# 密钥路径
private_key_path: /var/lib/headscale/private.key

# Noise 协议密钥（Tailscale v2）
noise:
  private_key_path: /var/lib/headscale/noise_private.key

# IP 前缀配置
prefixes:
  v4: 100.64.0.0/10
  v6: fd7a:115c:a1e0::/48
  allocation: random

# 数据库配置
database:
  type: sqlite
  sqlite:
    path: /var/lib/headscale/db.sqlite
    write_ahead_log: true

# DERP 中转服务器配置
derp:
  server:
    enabled: true
    region_id: 99
    region_code: "self"
    region_name: "自建 DERP"
    stun_listen_addr: "0.0.0.0:3478"
    private_key_path: /var/lib/headscale/derp_server_private.key
    automatically_add_embedded_derp_region: true
    ipv4: <SERVER_IP>
    verify_clients: false
  urls:
    - https://controlplane.tailscale.com/derpmap/default
  paths: []

# DNS 配置
dns:
  magic_dns: true
  base_domain: headscale.local
  nameservers:
    global:
      - 223.5.5.5
      - 8.8.8.8
  domains: []

# 日志配置
log_level: info
log:
  format: text

# API 配置
api:
  listen_addr: 127.0.0.1:8080

# TLS 配置（DERP 服务器使用）
tls_cert_path: /path/to/ssl/cert.pem
tls_key_path: /path/to/ssl/key.pem

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

# 4. 创建 systemd 服务

创建 /etc/systemd/system/headscale.service：

[Unit]
Description=headscale control server
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/headscale serve -c /etc/headscale/config.yaml
Restart=on-failure
RestartSec=5
User=root
RuntimeDirectory=headscale
RuntimeDirectoryMode=0755

[Install]
WantedBy=multi-user.target

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

# 5. 启动服务

systemctl daemon-reload
systemctl enable headscale
systemctl start headscale

# 检查状态
systemctl status headscale

1
2
3
4
5
6

# 6. 创建用户和 Pre-auth Key

# 创建用户
headscale users create default

# 生成 Pre-auth Key（有效期 30 天）
headscale preauthkeys create --user 1 --reusable --expiration 720h

1
2
3
4
5

# 7. 客户端连接

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

# 连接到自建 Headscale
tailscale up \
  --login-server http://127.0.0.1:8080 \
  --authkey <YOUR_PREAUTH_KEY> \
  --hostname <NODE_NAME> \
  --accept-routes

1
2
3
4
5
6
7
8
9

# 阿里云安全组配置

协议	端口	用途	方向
UDP	3478	STUN（NAT 探测）	入方向
TCP	443/8443	DERP（数据中转）	入方向

# 常用命令

# 查看节点列表
headscale nodes list

# 查看用户列表
headscale users list

# 生成新的 Pre-auth Key
headscale preauthkeys create --user 1 --reusable --expiration 720h

# 吊销设备
headscale nodes expire --all

# 删除设备
headscale nodes delete <node-id>

# 查看 Tailscale 状态
tailscale status

# 测试 DERP 连通性
tailscale ping <对端节点IP>

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

# 安全说明

# 传输加密

** DERP Server**: 使用 TLS 1.3 加密（端口 443/8443）
WireGuard 隧道: 节点间数据端到端加密（ChaCha20-Poly1305）
STUN: 仅用于 NAT 发现，不传输数据

# 认证机制

Pre-auth Key: 设备注册凭证（可设置过期时间）
Node Key: 每个节点的唯一密钥
Machine Key: 设备身份标识

# 访问控制

Headscale API 仅本地监听（127.0.0.1:8080）
节点间通信通过 Tailscale 隧道
可配置 ACL 策略控制节点间访问权限

# 注意事项

SSL 证书: DERP 服务器需要有效的 TLS 证书
防火墙: 确保放行 3478/UDP 和 443/TCP
Pre-auth Key: 建议设置较短的过期时间
备份: 定期备份 /var/lib/headscale/ 目录

# 参考链接

#VPN #Tailscale #Headscale #网络

上次更新: 2026/06/29, 09:48:40

← 初识CGroup C++编译优化选项→