Headscale 如何用自定义 derp.yaml 向节点提供自己的 DERP 中继服务器区域？
当你希望 Tailscale 客户端之间无法直连时走自己部署的 DERP 中继，而不是 Tailscale Inc. 提供的默认 DERP 地图时，可以通过给 Headscale 指定一个自定义的 derp.yaml 文件来实现。Headscale 的 DERP 相关设置位于配置文件的 derp 段（配置说明），其中 derp.paths 指向本地 YAML 文件，用于修改通过 URL 加载的已有 DERP 地图，或直接向节点提供自定义 DERP 服务器（DERP 参考文档）。
本文的目标：写出一份 derp.yaml，声明自己的 DERP 区域与节点，让 Headscale 只向客户端下发这份自定义 DERP 地图，并在客户端上验证结果。
前提条件
- 一个可公网访问的 DERP 服务器（或几台），按 DERP 文档示例 的说明，典型的自定义 DERP 服务器提供：
- DERP 中继：HTTPS，tcp/443；
- 可选的 captive portal 检查：HTTP，tcp/80（配合 canport80: true）；
- 可选的 STUN：udp/3478。
- Headscale 已部署并可运行，配置默认从 /etc/headscale/config.yaml 加载（部署前提）。
- 一个已连接该 Tailnet 的 Tailscale 客户端，用于最后验证 DERP 地图。
仓库根目录自带一份 derp-example.yaml 可作为起点参考。
第一步：编写 derp.yaml
derp.yaml 的结构对应 DERPMap/DERPRegion/DERPNode 的定义。DERP 文档给出的示例声明了两个自定义区域 custom-east（ID 900）和 custom-west（ID 901），每个区域一台 DERP 服务器：
regions:
900:
regionid: 900
regioncode: custom-east
regionname: My region (east)
nodes:
– name: 900a
regionid: 900
regioncode: custom-east
hostname: derp900a.example.com
ipv4: 198.51.100.1
ipv6: 2001:db8::1
canport80: true
901:
regionid: 901
regioncode: custom-west
regionname: My Region (west)
nodes:
– name: 901a
regionid: 901
regioncode: custom-west
hostname: derp901a.example.com
ipv4: 198.51.100.2
ipv6: 2001:db8::2
canport80: true
上面的 hostname、ipv4、ipv6 均为文档示例值，需要替换为你自己 DERP 服务器的实际主机名和 IP。regionid 建议避开 Tailscale 默认地图使用的小数字区域 ID（示例中使用 900、901）；regioncode/regionname 会在 Tailscale 客户端 UI 中显示，用来标识这个区域。仓库自带的 derp-example.yaml 还展示了 stunport、stunonly、derpport 等可选字段，以及通过 1: null 禁用某个默认区域的写法。
注意：如果你的 DERP 服务器不支持 HTTP tcp/80 上的 /generate_204，就不要依赖 canport80 做 captive portal 检查；文档同时指出嵌入式 DERP 服务器本身就不支持该端点。
第二步：在 config.yaml 中指向自定义地图
要让节点只看到 derp.yaml 中的两台服务器，需要关闭默认地图加载，并把 paths 指向你的文件：
derp:
server:
enabled: false
urls: []
paths:
– /etc/headscale/derp.yaml
两个要点：
- urls: [] 表示不从 Tailscale 的默认地址加载 DERP 地图，节点只会获得 paths 中文件的内容；
- server.enabled: false 表示不使用 Headscale 的嵌入式 DERP 服务器。即使你同时想保留嵌入式 DERP，也可以把它与自定义地图一起用：启用 server.enabled: true 后，它会按 config-example.yaml 中 automatically_add_embedded_derp_region: true 的默认行为自动并入 DERP 地图（若设为 false，则需要自己在 derp.yaml 中写明它的条目）。
可选分支：保留 Tailscale 默认地图并只删掉个别区域。 如果只想在默认地图基础上禁用某个区域（例如纽约区域，region ID 1），可以保留 urls 并在 derp.yaml 中用 null 禁用该区域：
# derp.yaml：禁用区域 ID 1
regions:
1: null
# config.yaml：默认地图 + 本地覆盖文件
derp:
server:
enabled: false
urls:
– https://controlplane.tailscale.com/derpmap/default
paths:
– /etc/headscale/derp.yaml
文档明确警告：把 Tailscale 的 DERP 服务器全部移除后，客户端只剩一个 DERP 服务器可用，这是单点故障，可能影响连通性；在这样做之前，应先确认自己的 DERP 服务器连通性正常。
第三步：校验配置并生效
修改完 config.yaml 后，用 headscale configtest 校验配置文件是否合法：
headscale configtest
配置无误后重启 headscale 服务，让新的 DERP 设置随服务启动加载（文档假设 headscale 以系统服务方式运行，见部署前提）。
验证：客户端侧检查 DERP 地图与连通性
在任意一个 Tailscale 客户端上执行：
-
查看客户端实际收到的 DERP 地图：
tailscale debug derp-map
输出中应出现你在 derp.yaml 里声明的区域（示例配置下即 region ID 900、901，区域名如 My region (east)）；如果设置了 urls: []，则不应再看到 Tailscale 默认地图中的区域。
-
如果你同时启用了嵌入式 DERP，可以用 tailscale debug derp headscale 检查与它的连通性（文档说明这依赖配置文件中默认的 region code）。
此外，Headscale 的 metrics 与 debug 端点也提供额外的 DERP 相关信息，详见调试文档。
限制与注意事项
- 嵌入式 DERP 服务器不支持 /generate_204 端点，无法用于 Tailscale 的 captive portal 检查；DERP 的定位是辅助连通性，没有速度或吞吐量优化。
- 第三方 DERP 服务器（如 Tailscale 的 derper）可以通过 -verify-client-url 参数指向 Headscale 的 /verify 端点（例如 https://headscale.example.com/verify）来限制只有本 Tailnet 节点才能使用中继；-verify-client-url-fail-open 控制 Headscale 不可达时的行为，默认放行。嵌入式 DERP 的客户端校验（verify_clients: true）默认开启。
- 只使用自己的 DERP 时存在单点故障风险，这是文档明确的取舍，上线前先用 tailscale debug derp-map 确认地图符合预期。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
