【2026.10】headscale_v0.29.5+derp+tailscale自建部署教程
一.前言
这套方案大概稳定使用3年时间，10月份由于之前部署headscale服务器到期想更换，所以产生了重新部署最新版的念头，这份文档是几年前写在飞书里面，这次更新之后发到L站供佬友们参考。先叠个甲本文大部分都是自己重新编辑排版，不属于AI生成转发到论坛，且部署教程还是以文字发布较为友好，故只使用少量图片请各位佬手下留情。
然后说下自己对内网搭建的体验和经验，其实论坛的佬友对于tailscale/WireGuard/netbird/easytier/Zerotier等等内网穿透的方案都有不同的理解，我觉得原因在于每个人用的网络运营商，包括每台设备的运营商，还有服务器的服务商和所在区域等等属性都完全不一样，众说纷纭有的好用有的不好用都是正常的。所以并没有一个固定答案哪个方案最好，自己实际部署使用下来没问题就行，至于丝滑还是卡的一批，那纯粹是选方案时的直觉或者说运气问题了。当然也有可能是本人网络相关经验和认知不足（是的就是很菜），所以本次文档中有什么纰漏和错误，还请各位佬友指出多多交流。
网络及设备
本人的设备几乎所有系统都包含了，几台linux\win\mac\ios\android\nas组件的内网，然后网络的话也是电信移动联通都有，headscale是搭建在一台龟上面（自带derp），一个derp节点是放在腾子的国内服务器上。
域名及证书
公网ip是必要的（虽然easytier是去中心化的但好像还是有个公网服务器比较好？这个没有搭建过所以先容我提个问题），然后最好是用域名来指向headscale服务（因为如果用是公网ip，迁移headscale服务器的时候，tailscale客户端全都得用新的地址来重新连接，如果用域名的话后续迁移就省下客户端重连这一步）。关于域名备案的问题，我是国内注册的域名都备案了，国外注册的都托管在小黄云上，所以本次教程没遇到拦截问题。
证书的话其实用Caddy来反代+申续签是比较好的，headscale的官方也有推荐这个方式，但是多年前并没有这个选项，以及因为我的证书全都是在1panel上管理，所以本次教程中也以自己手动上传证书为主。
二.Headscale服务端部署
这次部署有个很大的区别，是官方安装包自带derp服务好使了（不是用hs官方derp节点来中转意思，这个很慢不稳定），几年前的版本好像还有很多不完善才没用，好像是不能验证客户端还是什么问题忘了，所以最后又用docker部署2个derp节点，现在是一个hs服务自带一个derp节点，再另外部署一个derp节点就搞定了。
1.适用环境
- 设备：公网服务器 Ubuntu 24.04；
- 版本：Headscale 0.29.5 官方 DEB；
- 域名：hs.openai.com(hah记得用自己的域名)；
- 端口：服务器安全列表及实例防火墙（ufw）开放 TCP 443、UDP 3478
2.Headscale部署
2.1 官方教程
官方的教程地址：
https://headscale.net/stable/setup/install/official/
安装deb脚本
sudo apt update
sudo apt install -y curl ca-certificates
VERSION=0.29.5
ARCH=$(dpkg --print-architecture)
curl -fL -o headscale.deb "https://github.com/juanfont/headscale/releases/download/v${VERSION}/headscale_${VERSION}_linux_${ARCH}.deb"
sudo apt install -y ./headscale.deb
headscale version
sudo systemctl status headscale --no-pager
APT 若显示“Download is performed unsandboxed as root”，但同时有 Setting up headscale 和 systemd 服务链接，则 DEB 已安装成功；这条 N: 只是本地 DEB 所在目录不允许 apt 用户读取的提示，不应再叠加安装独立二进制。
上传并部署证书
1Panel 产出的 fullchain.pem、privkey.pem 如果上传到 /home/ubuntu/headscale/certs/。官方 DEB 的 systemd 单元设置 ProtectHome=true，因此服务不能直接读取 /home/ubuntu 下的文件；该目录只作为上传源，需复制到 /etc/headscale/tls/。证书必须覆盖 hs.openai.com，fullchain 必须包含完整证书链。
sudo install -d -o root -g headscale -m 0750 /etc/headscale/tls
sudo install -o root -g headscale -m 0640 /home/ubuntu/headscale/certs/fullchain.pem /etc/headscale/tls/fullchain.pem
sudo install -o root -g headscale -m 0640 /home/ubuntu/headscale/certs/privkey.pem /etc/headscale/tls/privkey.pem
sudo -u headscale test -r /etc/headscale/tls/fullchain.pem
sudo -u headscale test -r /etc/headscale/tls/privkey.pem
修改配置并启动
编辑 /etc/headscale/config.yaml 中已存在的字段，不要在末尾重复追加第二个 derp: 或 dns: 段。以下只展示目标字段，其他版本对应的默认项保持不变；SQLite、Noise 私钥、prefixes 等沿用包内默认配置。
sudo cp /etc/headscale/config.yaml /etc/headscale/config.yaml.bak
sudo vim /etc/headscale/config.yaml
在现有文件中找到并修改对应字段，不要在文件末尾追加第二份同名 YAML 字段：
- server_url: https://hs.openai.com 一定得是https，对应443端口
- listen_addr: 0.0.0.0:443
- tls_cert_path: “”、tls_key_path: “”：这里填上一步上传的证书的位置，如果你是用 caddy 就留空，https 由 Caddy 处理。
- dns.magic_dns: false、dns.override_local_dns: false：沿用之前不接管客户端 DNS 的习惯。
- derp.server.enabled: true、derp.server.verify_clients: true、derp.server.ipv4: 188.8.8.88。注释掉示例中的 derp.server.ipv6，除非你确有公网 IPv6。
- 可以暂时保留 derp.urls 中官方默认 DERP 地址作为迁移期间的备用中继。内置 DERP 测试通过后，如希望仅使用自建中继，再改为 urls: 。
- 保留包内默认的 SQLite 路径、Noise 私钥路径和 prefixes。公网没有 IPv6，也不要求删除 Tailscale 的内网 IPv6 前缀。
示例：
# /etc/headscale/config.yaml
server_url: https://hs.openai.com
listen_addr: 0.0.0.0:443
tls_letsencrypt_hostname: ""
tls_cert_path: /etc/headscale/tls/fullchain.pem
tls_key_path: /etc/headscale/tls/privkey.pem
derp:
server:
enabled: true
region_id: 999
region_code: "headscale"
region_name: "Headscale Embedded DERP"
verify_clients: true
stun_listen_addr: "0.0.0.0:3478"
automatically_add_embedded_derp_region: true
ipv4: 188.8.8.88
# 没有真实公网 IPv6 时，注释示例 ipv6: 2001:db8::1
urls: []
paths: []
保存后测试配置通过后重启服务：
sudo -u headscale headscale configtest
sudo systemctl restart headscale
sudo systemctl status headscale --no-pager
sudo journalctl -u headscale -n 80 --no-pager -l
2.2 使用独立二进制文件部署（可忽略）
之前用的是二进制文件部署，那个时候好像因为用deb安装包之后，会有很多用户权限的问题，导致很多bug才没用。但这次问了AI之后不再推荐独立部署，所以直接用的2.1安装deb包，如有这方面需求的佬友，可以找找其他的帖子，我记得是有的。
2.3 创建headscale用户
这里生成的authkey，可以方便tailscale客户端直接同一行命令连接上来。而不用一个个客户端发起请求，然后到hs端批准，这样就太麻烦了。
# 名字自己取
sudo headscale user create yourname
# 生成一个过期时间 24h 且可以重复使用的 authkey ,<用户ID> 创建了一个 yourname 就填 1 ,是的就是填索引值
sudo headscale preauthkeys create --user <用户ID> --reusable --expiration 24h # 365d
# 查看下创建的authkey
sudo headscale preauthkeys --user yourname list
三.Tailscale客户端
1.安装
只推荐官方给的客户端安装教程:
https://tailscale.com/download/linux/ubuntu-2204
里面可以选择各个不同平台的安装方式，非常简单，不在此赘述。
2.连接使用
2.1 windows
安装完成后打开cmd后者powershell，软件安装后自动配置了环境变量。
tailscale up --login-server https://hs.openai.com --hostname <自己取名> --accept-routes=true --accept-dns=false --authkey <2.3生成的 authkey>
# 例如： tailscale up --login-server https://hs.openai.com --hostname windows-1 --accept-routes=true --accept-dns=false --authkey dsadsdsadsadasdasdsadsad
遇到解决不了的问题，直接卸载重装再运行一遍(老版本就是有很多bug，新版本感觉bug少了很多，可以忽略)，卸载时重装前需要删除以下两个文件夹：
C:\ProgramData\Tailscale
# user换成你的电脑账户名
C:\Users\user\AppData\Local\Tailscale
2.2 linux/macos
官方给的命令都是要 root 权限的，所以要加 sudo
sudo tailscale up --login-server https://hs.openai.com --hostname <自己取名> --accept-routes=true --accept-dns=false --authkey <2.3生成的 authkey>
同样遇到奇葩问题，比如连接不上，就卸载重装吧，省时间，下面给出一个快速删除重新安装的脚本：
Ubuntu 清理:
sudo apt purge tailscale -y
sudo rm -rf /etc/default/tailscaled /etc/systemd/system/tailscaled.service.d
apt-cache policy tailscale
sudo apt-get install -y tailscale
Centos 清理：
#!/bin/bash
# Stop the Tailscale service
sudo systemctl stop tailscaled
# Remove Tailscale package
sudo yum remove -y tailscale
# Clean up Tailscale directories and files
sudo rm -rf /var/lib/tailscale
sudo rm -rf /etc/systemd/system/tailscaled.service.d
sudo rm -rf /etc/default/tailscaled
sudo rm -rf /usr/lib/systemd/system/tailscaled.service
sudo rm -rf /var/run/tailscale
sudo rm -rf /var/log/tailscale*
# Reload systemd
sudo systemctl daemon-reload
# Install yum-utils if not already installed
sudo yum install -y yum-utils
# Add Tailscale repository
sudo yum-config-manager --add-repo https://pkgs.tailscale.com/stable/centos/7/tailscale.repo
# Install Tailscale
sudo yum install -y tailscale
# Enable and start Tailscale service
sudo systemctl enable --now tailscaled
echo "Tailscale installation and setup complete."
# 创建一个bahs.sh复制粘贴以上内容进去
# chmod +x bash.sh
# ./bash.sh 即可
2.3 IOS
在 appstore 下载 tailscale 程序，估计需要美区账号，直接在 app 里设置headscale server url，设置步骤：
-
打开app正常安装vpn，但先别打开。
-
然后点击右上角小人图标
-
再点击右上角圆圈三个点
-
把https://hs.openai.com的url填进去，注意要先关闭vpn才能跳转。
-
复制它给出的连接，到headscale服务端去运行一下即可，其中USERNAME要替换成刚刚 2.3 中 headscale 生成的账户名称 ‘yourname’。
3.阿里云服务器（旧）
这里单独开一个小节是因为有个大bug，阿里云和apt的内网dns都是在100网段，和 tailscale 的默认网段冲突了，会导致阿里云一旦开启 tailscale 后就无法正常解析域名，也无法更新gpt，所以在 tailscale 客户端启动前的时候要加个参数：
# 全局设置netfilter模式为nodivert，将创建和管理Tailscale子链，但将这些链的调用留给管理员。
# 全局设置Tailscale客户端接受Tailscale admin设置的dns
sudo tailscale set --netfilter-mode=nodivert --accept-dns=true
这是几年前遇到的bug，不知道现在有没有这个问题，先保留在这里。
四.Derp中继服务部署
因为普通部署的derp服务，暴露在公网被扫一下端口很容易发现，且headscale配置derp节点的时候只需要域名和ip，并没有验证所以很容易被白嫖。一定记得在部署derp的时候添加DERP_VERIFY_CLIENTS参数来限制，而这个前提是要先搭建tailscale客户端并登录，也就是说前面所有的步骤都得先行完成（当然部署完了再来改也是可以的）。
1.使用域名部署
这种方案需要满足以下几个条件：
-
要有自己的域名，并且申请了 SSL 证书（使用1panel生成的证书，且有自动续签的功能，较为方便）
-
需要准备一台云主机（阿里云实测不行，最好是腾讯云）
-
如果服务器在国内，域名需要备案。
如果以上条件都具备，就可以按照下面的步骤开始部署了。
1.1 docker部署
26年7月份实测通过的部署命令，之前使用的yangchuansheng的derp镜像已经失效了。
sudo docker run -d \
--restart always \
--name derper \
--network host \
-v /home/ubuntu/softs/certs/:/app/certs \
-v /run/tailscale:/var/run/tailscale \
-e TZ=Asia/Shanghai \
-e DERP_CERT_MODE=manual \
-e DERP_CERT_DIR=/app/certs \
-e DERP_ADDR=:12345 \
-e DERP_DOMAIN=derp.openai.com \
-e DERP_HTTP_PORT=-1 \
-e DERP_STUN_PORT=3478 \
-e DERP_VERIFY_CLIENTS=true \
fredliang/derper:latest
注意点：
-
服务器的端口记得放开，ipv4的 tcp 12345和3478端口，以及ipv4的 udp 3478端口。
-
ssl证书有要求，/home/ubuntu/softs/certs文件夹下包含两个文件，crt和key文件。假设你的域名是 derp.openai.com，那么证书的名称必须是 derp.openai.com.crt，一个字符都不能错！同理，私钥名称必须是 derp.openai.com.key，一个字符都不能错！
-
域名记得换成你的 derp.openai.com。
-
-e DERP_VERIFY_CLIENTS=true一定要先安装登录tailscale客户端，然后和-v /var/run/tailscale:/var/run/tailscale配套一起启动。
1.2 官方部署
这里我没有尝试，因为要开的端口更多
https://tailscale.com/docs/reference/derp-servers/custom-derp-servers
2.Headscale配置Derp
部署好 derper 之后，就可以修改 Headscale 的配置来使用自定义的 DERP 服务器了。Headscale 可以通过两种形式的配置来使用自定义 DERP：
-
一种是在线 URL，格式是
JSON，与 Tailscale 官方控制服务器使用的格式和语法相同。 -
另一种是本地文件，格式是
YAML。
# sudo vim /etc/headscale/derp.yaml
regions:
901:
regionid: 901
regioncode: BJ
regionname: beijing
nodes:
- name: 901a
regionid: 901
hostname: <就是上面的域名> # derp.openai.com 必须与远端证书匹配
ipv4: <公网ip> # 如果域名有正确的公网 A 记录，不用写 ipv4；若要写，必须填远端服务器的真实 IPv4，不能填域名
stunport: 3478
stunonly: false
derpport: 12345
配置说明：
-
regions是 YAML 中的对象，下面的每一个对象表示一个可用区，每个可用区里面可设置多个 DERP 节点，即nodes。 -
每个可用区的
regionid不能重复。 -
每个
node的name不能重复。 -
regionname一般用来描述可用区，regioncode一般设置成可用区的缩写。 -
ipv4字段不是必须的，如果你的域名可以通过公网解析到你的 DERP 服务器地址，这里可以不填。 如果你使用了一个二级域名，而这个域名你并没有在公共 DNS server 中添加相关的解析记录，那么这里就需要指定 IP（前提是你的证书包含了这个二级域名，这个很好支持，搞个泛域名证书就行了）。 -
stunonly: false表示除了使用 STUN 服务，还可以使用 DERP 服务。
保存后让 Headscale 用户可读：
sudo chown root:headscale /etc/headscale/derp.yaml
sudo chmod 640 /etc/headscale/derp.yaml
接下来还需要修改 Headscale 的配置文件，编辑 /etc/headscale/config.yaml，引用上面的自定义 DERP 配置文件（把现有的 paths: 改为 /etc/headscale/derp.yaml）。
需要修改的配置项如下（只粘贴了需要修改的地方！！！）：
# sudo vim /etc/headscale/config.yaml
derp:
server:
enabled: true
# 这里保留你现有的区域 999 等配置
urls: []
# - https://controlplane.tailscale.com/derpmap/defaul
paths:
- /etc/headscale/derp.yaml
# paths: []
上面只是需要改动的结构示意，不要复制后生成第二个 derp: 段。urls: 可以继续保持，表示不加入 Tailscale 官方的中继地图。修改完这两份配置后 需要重启headscale服务
sudo -u headscale headscale configtest
sudo systemctl restart headscale
sudo systemctl status headscale --no-pager
检测最简单的办法是直接打开 DERP 服务器的 URL：https://xxxx:12345，如果看到如下页面，且地址栏的 SSL 证书标签显示正常可用，那才是真没问题了。
3.从客户端验证两个区域
到任意一台刚刚部署了tailscale客户端上运行：
tailscale debug derp-map
地图应同时出现 999／headscale／443 和 901／BJ／12345。
4.证书过期
由于我的derp的证书是手动复制到服务器上的，所以1panel的自动续签无法直接更改（只对1panel上的应用生效），所以需要手动复制新的证书内容到服务器上（每三个月一次）：
先去1panel找到域名证书，然后去derp服务器上改证书
cd /home/ubuntu/softs/certs
# 复制粘贴证书内容
sudo systemctl restart tailscaled
sudo docker restart derp容器id
hs的证书也同理上传修改，然后重启hs服务
sudo vim /etc/headscale/tls/fullchain.pem
sudo vim /etc/headscale/tls/privkey.pem
sudo -u headscale test -r /etc/headscale/tls/fullchain.pem
sudo -u headscale test -r /etc/headscale/tls/privkey.pem
sudo systemctl restart headscale
五.常用命令
1.tailscale 客户端命令
# 检查网络和状态
tailscale netcheck
tailscale status
# macos
/Applications/Tailscale.app/Contents/MacOS/Tailscale status
2.headscale 服务端命令
基本上都要加 sudo
# 查所有的
sudo headscale nodes list
# 删除某个id的node
sudo headscale nodes delete --identifier 1
# 修改某个node的name，但不是hostname
sudo headscale nodes rename NEWNAME --identifier 1
# 查看认证key
sudo headscale preauthkeys --user yourname list
手动修改客户端的ipv4的内网地址，目前没有官方命令，只能改数据库hah：
# 估计都得先安装sqlite3
sudo apt update
sudo apt install sqlite3
# 然后再修改
sudo -u headscale sqlite3 /var/lib/headscale/db.sqlite \
"BEGIN IMMEDIATE;
UPDATE nodes SET ipv4='100.64.0.100'
WHERE id=88
AND NOT EXISTS (
SELECT 1 FROM nodes WHERE ipv4='100.64.0.100' AND id<>88
);
SELECT changes();
COMMIT;"
sudo systemctl restart headscale
这里面 ipv4 就是你想改的ip地址（记得100.64.0不能变，最后一位不要超过255），id就是‘sudo headscale nodes list’显示的客户端的索引
六.记录一些问题解决
1.如果遇到错误，要多看看tailscale和derp的日志，自己看不懂发给AI，能发现核心问题并解决，处理起来也简单。
2.有时候会遇到relay server unavailable这个问题，不是客户端版本的问题，而是加了客户端验证之后，derp节点的tailscale客户端要先重启一遍，才能把derp的verify client更新（sudo systemctl restart tailscaled）。
3.本文签证手动上传频率大概3个月一次，其实可以让AI写一个自动化脚本来解决的，毕竟全部搭建成功之后大家都在一个内网里，所以一个定时任务就可以搞定。