自建 Headscale + DERP 全流程实战记录

记录一次完整、可上线、可长期运行的 Headscale + 自建 DERP 搭建过程。
本文不是“能跑就行”的教程，而是生产可用、已多客户端验证的配置方案。

简介#

Tailscale（Headscale）就是组建一个大的局域网，可以将你手里头的所有设备都拉到这个局域网内，进而使用局域网IP进行互联。
此外，Tailscale（Headscale）还有一个作用就是内网穿透，局域网内的设备之间的访问会通过穿透进行打洞（成功概率挺高），进而实现公网的点对点互联。而且就算打洞失败，也可以利用中转服务器进行互联。
应用场景举例：家里没有公网IP，但是可以通过Tailscale组网和穿透的方式实现在任意网络下对家里设备的访问。

整体架构说明#

使用 Headscale 作为 Tailscale 控制平面
自建 DERP Server，不依赖官方 DERP
使用 宝塔 / Nginx 统一终止 TLS
开启 DERP 防白嫖（verify-clients）
多客户端 tailscale netcheck 验证通过

最终架构如下：#

1
Tailscale Client
2
   ↓
3
Headscale（控制平面）
4
   ↓ 下发 DERP Map
5
https://derp.muxui.com/derp.json
6
   ↓
7
DERP Server（derper，HTTP 本地端口）
8
   ↓
9
宝塔 / Nginx（HTTPS 443）

DERP Server 搭建#

安装最新版GO#

更新软件包，安装依赖

1
apt update && apt upgrade
2
apt install -y wget git openssl curl

下载最新版GO

1
wget https://go.dev/dl/go1.25.5.linux-amd64.tar.gz
2
rm -rf /usr/local/go && tar -C /usr/local -xzf go1.25.5.linux-amd64.tar.gz

目前最新版为1.25.5，后续若有更新则可以去 https://go.dev/dl/ 查看最新版并替换下载即可，记得后面的版本号都要改

配置环境变量

1
export PATH=$PATH:/usr/local/go/bin
2
go version

1
echo "export PATH=$PATH:/usr/local/go/bin" >> /etc/profile
2
source /etc/profile

1
go env -w GO111MODULE=on
2
go env -w GOPROXY=https://goproxy.cn,direct

安装最新版Derper#

安装

1
go install tailscale.com/cmd/derper@latest

拷贝二进制文件

1
mkdir /etc/derp/
2
cp ~/go/bin/derper /etc/derp/

查看是否拷贝成功

1
ls /etc/derp

derper 域名部署（宝塔反代模式,国内服务器域名需要备案）#

⚠️ 关键原则：DERP 不自己处理 TLS

TLS 由宝塔 / Nginx 负责
derper 只监听本地 HTTP

正确启动参数（手动验证用）：#

1
/etc/derp/derper \
2
  -a :13445 \
3
  --hostname derp.muxui.com \
4
  --certmode=off \
5
  --stun \
6
  --stun-port 3478 \
7
  --verify-clients

看到以下日志即为成功：

1
STUN server listening on [::]:3478
2
derper: serving on :13445

systemd 服务（最终版）#

1
[Unit]
2
Description=Tailscale DERP Server
3
After=network-online.target
4
Wants=network-online.target
5

6
[Service]
7
Type=simple
8
User=root
9
ExecStart=/etc/derp/derper \
10
  -a :13445 \
11
  --hostname derp.muxui.com \
12
  --certmode=off \
13
  --stun \
14
  --stun-port 3478 \
15
  --verify-clients
16
Restart=always
17
RestartSec=5
18
LimitNOFILE=1048576
19

20
[Install]
21
WantedBy=multi-user.target

启用并启动：

1
systemctl daemon-reload
2
systemctl enable derp --now
3
systemctl status derp

Derper IP部署(123.123.123.123改成自己服务器的IP)#

1
DERP_IP="123.123.123.123"

1
openssl req -x509 -newkey rsa:4096 -sha256 -days 3650 -nodes -keyout ${DERP_IP}.key -out ${DERP_IP}.crt -subj "/CN=${DERP_IP}" -addext "subjectAltName=IP:${DERP_IP}"

这时候/root文件夹下会有两个证书文件：/root/123.123.123.123.crt和/root/123.123.123.123.key，拷贝到/etc/derp/:

1
mv /root/123.123.123.123.crt /etc/derp
2
mv /root/123.123.123.123.key /etc/derp

启动Derper服务器#

写入后台

新建文件derp.service

1
touch /etc/systemd/system/derp.service

写入以下内容

1
[Unit]
2
Description=TS Derper
3
After=network.target
4
Wants=network.target
5
[Service]
6
User=root
7
Restart=always
8
ExecStart=/etc/derp/derper -hostname 123.123.123.123 -a :13445 -http-port 13446 -certmode manual -certdir /etc/derp
9
RestartPreventExitStatus=1
10
[Install]
11
WantedBy=multi-user.target

启动

1
systemctl enable derp
2
systemctl restart derp
3
systemctl status derp

验证Derper是否搭建成功#

浏览器打开https://123.123.123.123:13445，忽略不安全，看看是不是显示下面的内容：

DERP
This is a Tailscale DERP server.
It provides STUN, interactive connectivity establishment, and relaying of end-to-end encrypted traffic for Tailscale clients.
Documentation:
About DERP
Protocol & Go docs
How to run a DERP server

DERP 防白嫖（verify-clients）#

为什么必须开启？#

不开启 --verify-clients：

任何人只要知道你的 DERP 地址
都可以把你当 TCP 中继刷流量

verify-clients 的工作方式#

DERP 通过 本机的 tailscaled
向 Headscale 校验客户端身份
只允许本 Tailnet 成员使用

搭建Headscale和Headscale-ui#

安装最新版Headscale#

下载

1
wget --output-document=headscale.deb \
2
  https://github.com/juanfont/headscale/releases/download/v0.27.1/headscale_0.27.1_linux_amd64.deb

目前最新版为0.27.1，后续若有更新则可以去 https://github.com/juanfont/headscale/releases 查看最新版并替换下载即可，记得后面的版本号都要改

安装

1
mv headscale_0.27.1_linux_amd64.deb headscale.deb
2
dpkg --install headscale.deb

修改配置文件（/etc/headscale/config.yaml）

仅列出需要修改的地方

1
server_url: https://headscale.muxui.com

1
listen_addr: 0.0.0.0:8080

1
metrics_listen_addr: ""

1
prefixes:
2
  v4: 100.64.0.0/10
3
#  v6: fd7a:115c:a1e0::/48

1
  # List of externally available DERP maps encoded in JSON
2
  urls:
3
    - https://derp.muxui.com/derp.json

1
  base_domain: tailnet.muxui.com

1
  # List of DNS servers to expose to clients.（建议改成国内适合自己的DNS）
2
  nameservers:
3
    global:
4
      - 114.114.114.114

启动

1
systemctl enable headscale
2
systemctl restart headscale
3
systemctl status headscale

3.3 安装最新版Headscale-ui#

下载

1
wget https://github.com/gurucomputing/headscale-ui/releases/download/2025.08.23/headscale-ui.zip

目前最新版为2025.08.23，后续若有更新则可以去 https://github.com/gurucomputing/headscale-ui 查看最新版并替换下载即可，记得后面的版本号都要改

安装

1
apt-get install unzip
2
unzip -d /var/www headscale-ui.zip

配置Derper服务器#

配置/etc/headscale/derp.json文件

新建

1
touch /etc/headscale/derp.json

写入以下内容

ip部署

1
{
2
  "Regions": {
3
    "901": {
4
      "RegionID":   901,
5
      "RegionCode": "Myself",
6
      "RegionName": "Myself Derper",
7
      "Nodes": [
8
          {
9
          "Name":             "901a",
10
          "RegionID":         901,
11
          "DERPPort":         13445,
12
          "IPv4":   "123.123.123.123",
13
          "InsecureForTests": true
14
        }
15
      ]
16
    }
17
  }
18
}

使用域名（推荐做法）#

1
{
2
  "Regions": {
3
    "901": {
4
      "RegionID": 901,
5
      "RegionCode": "MUXUI",
6
      "RegionName": "Muxui DERP",
7
      "Nodes": [
8
        {
9
          "Name": "901a",
10
          "RegionID": 901,
11
          "HostName": "derp.muxui.com",
12
          "DERPPort": 443,
13
          "InsecureForTests": true
14
        }
15
      ]
16
    }
17
  }
18
}

Nginx / 宝塔暴露 derp.json#

1
location /d/derp.json {
2
    alias /etc/headscale/derp.json;
3
    default_type application/json;
4
}

验证：

1
https://derp.muxui.com/derp.json

能直接返回 JSON。

如果不是宝塔,就下载安装并配置Nginx

下载

1
apt install -y nginx

打开/etc/nginx/sites-available/default并添加以下内容：

1
map $http_upgrade $connection_upgrade {
2
    default      upgrade;
3
    ''           close;
4
}
5
server {
6
    listen 80;
7
    listen [::]:80;
8
    listen 443      ssl http2;
9
    listen [::]:443 ssl http2;
10
    server_name headscale.example.com;
11
    ssl_certificate /root/cert.crt;
12
    ssl_certificate_key /root/private.key;
13
    ssl_protocols TLSv1.2 TLSv1.3;
14
    location / {
15
        proxy_pass http://127.0.0.1:8080;
16
        proxy_http_version 1.1;
17
        proxy_set_header Upgrade $http_upgrade;
18
        proxy_set_header Connection $connection_upgrade;
19
        proxy_set_header Host $server_name;
20
        proxy_redirect http:// https://;
21
        proxy_buffering off;
22
        proxy_set_header X-Real-IP $remote_addr;
23
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
24
        proxy_set_header X-Forwarded-Proto $scheme;
25
        add_header Strict-Transport-Security "max-age=15552000; includeSubDomains" always;
26
    }
27
    location /web {
28
    index  index.html;
29
          alias  /var/www/web;
30
  }
31
}
32
server {
33
  listen 80;
34
  listen [::]:80;
35

36
  server_name 127.0.0.1;
37

38
  root /var/www;
39
  index index.html index.htm index.nginx-debian.html;
40
  location /d {
41
    alias   /var/www;
42
    autoindex on;
43
  }
44
  location / {
45
    try_files $uri $uri/ =404;
46
  }
47
}

启动

1
systemctl enable nginx
2
systemctl restart nginx
3
systemctl status nginx

验证安装#

重启Derper，Headscale和Nginx服务

1
systemctl restart derp
2
systemctl status derp

1
systemctl restart headscale
2
systemctl status headscale

1
systemctl restart nginx
2
systemctl status nginx

打开网站

https://headscale.example.com/web

如无意外应该是三个服务的状态应该是全绿的，网页也能正常打开，有报错的话建议按教程自查或在帖子底下留言

配置Headscale-ui#

生成API Key

1
headscale apikeys create --expiration 9999d

并将其写入到https://headscale.muxui.com/web/settings.html的Headscale API Key里面，点击Save API Key提交，见到右侧有小对勾即可

新建用户Default

打开https://headscale.`muxui`.com/web/users.html，点击New User，输入Default并提交

最终验证（最关键）#

Windows 客户端 netcheck#

1
tailscale netcheck

结果示例：

1
Nearest DERP: Muxui DERP
2
DERP latency:
3
  - MUXUI: 6.9ms

下载最新客户端#

https://tailscale.com/download

启动指令解析#

—login-server: 指定使用的Headscale服务器地址，即https://headscale.example.com
—advertise-routes: 向Headscale服务器报告当前客户端处于哪个内网网段下, 便于Headscale服务器让同内网设备直接内网直连(可选的)或者将其他设备指定流量路由到当前内网(可选)，多条路由英文逗号隔开
—accept-routes: 是否接受Headscale服务器下发的用于路由到其他客户端内网的路由规则(可选)
—accept-dns: 是否使用Headscale服务器下发的 DNS 相关配置(可选, 推荐关闭)
—force-reauth：强制重新认证
—advertise-exit-node：作为出口节点

不同客户端的启动方法#

Windows

以管理员身份启动PowerShell，输入以下代码：

1
tailscale login --login-server https://headscale.example.com

用非国区Apple ID下载，配置V P N文件

点击右上角头像，点击Log In...，点击右上角三个点,点击Use a custom coordination server，输入https://headscale.example.com,点击Login in

Linux

安装

1
curl -fsSL https://tailscale.com/install.sh | sh

运行

1
tailscale up --reset --advertise-routes=192.168.x.0/24 --accept-routes=true --login-server=https://headscale.example.com

到Headscale-ui中允许设备加入局域网#

上面在客户端执行了tailscale up之后，在客户都会显示一个带Device Key的代码，格式类似于：

1
headscale nodes register --user USERNAME --key mkey:ed8f19e22f51c9c231c8bc8ccbxxxxxxxxxxxxxxf86c8211e4ad32b6c6e

拷贝mkey:ed8f19e22f51c9c231c8bc8ccbxxxxxxxxxxxxxxf86c8211e4ad32b6c6e，去 https://headscale.example.com/web/devices.html中导入Device Key

简介#