Headscale 节点连接不通时如何用 tailscale netcheck 与 debug 命令定位问题？-开发者社区

Headscale 节点连接不通时如何用 tailscale netcheck 与 debug 命令定位问题？

【免费下载链接】headscaleAn open source, self-hosted implementation of the Tailscale control server项目地址: https://gitcode.com/GitHub_Trending/he/headscale

当你自建的 Headscale 作为 Tailscale 控制服务器运行时，可能会遇到节点之间无法建立连接、流量无法直达或节点行为不符合预期的情况。Headscale 官方文档（docs/ref/debug.md、docs/ref/derp.md）提供了一条完整的定位路径：先在客户端用tailscale netcheck和tailscale debug系列命令检查本机网络状况、连接状态与 DERP 中继连通性，再回到 Headscale 服务端查看 debug 日志和 9090 端口的 metrics/debug 端点，确认节点连接与注册情况。本文按这条路径组织操作，帮助你区分问题出在客户端网络、DERP 中继链路还是 Headscale 服务端。

先理解 DERP：节点连不通时流量走哪里

根据 DERP 文档，DERP（Designated Encrypted Relay for Packets）服务器主要用在两个节点无法建立直连时中继流量。Headscale 内置了嵌入式 DERP 服务器，但它默认是关闭的，需要手动启用，并且文档建议同时配置服务器的公网 IPv4 与 IPv6 地址以获得更好的连接稳定性：

derp: server: enabled: true ipv4: 198.51.100.1 ipv6: 2001:db8::1

上面的ipv4/ipv6是文档示例值，请替换为你 Headscale 服务器的实际公网地址。启用嵌入式 DERP 还需要额外开放端口（见端口要求）：

tcp/443：HTTPS，嵌入式 DERP 启用时必需，需公网可达；
udp/3478：STUN，用于帮助客户端发现自己的公网地址并做 NAT 穿透，嵌入式 DERP 启用时必需。

如果你的 DERP 配置是“只用 Headscale 自己的中继”（即urls: []移除了 Tailscale 官方 DERP 服务器），要注意文档明确警告：这会让可用 DERP 只剩一个，成为单点故障，可能损害连通性。因此在移除 Tailscale 官方 DERP 服务器之前，先按下一节的命令验证嵌入式 DERP 的连通性。

客户端：用 netcheck 与 debug 命令检查本机网络

Troubleshooting 文档列出的 Tailscale 客户端命令可以在出问题的节点上执行，用于检查本机网络状况和客户端状态：

# 检查本机网络状况（STUN、UPnP 等网络条件） tailscale netcheck # 查看客户端状态（JSON 格式，便于检查节点在线情况） tailscale status --json # 查看 DNS 状态 tailscale dns status --all # 导出客户端日志 tailscale debug daemon-logs # 查看客户端收到的 netmap（Tailnet 状态快照） tailscale debug netmap

文档说明这些命令在对比 Headscale 与 Tailscale SaaS 行为差异时特别有用，更多内容可用tailscale debug --help查看。tailscale netcheck用于“检查本机网络条件”，如果它显示本机无法完成 STUN 打洞或 NAT 穿透，说明该节点的直连能力受限，连接是否可用就取决于 DERP 中继是否正常工作——这就进入下一步。

客户端：验证 DERP 中继链路

DERP 文档指出，任何 Tailscale 客户端都可以用来检查 DERP map 和 DERP 服务器的连通性：

# 查看客户端当前拿到的 DERP map tailscale debug derp-map # 与嵌入式 DERP 服务器做连通性检查 tailscale debug derp headscale

两个注意点：

tailscale debug derp headscale这个命令假设你使用的是配置文件中的默认 region code；如果你自定义了 region code，检查方式需要相应调整。
嵌入式 DERP 有一个明确限制：它不支持 Tailscale 的 captive portal 检查（没有 tcp/80 上的 HTTP/generate_204端点），且没有速度或吞吐优化，主要目的只是辅助节点连通。所以如果tailscale debug derp headscale正常但流量体验不佳，这属于文档已说明的特性边界，而不是配置错误。

服务端：把 Headscale 日志开到 debug 级别

确认客户端侧现象后，回到 Headscale 服务器端收集更多信息。Debug 文档说明可以把日志级别设为debug（或trace）来获取更详细的输出：

log: # Valid log levels: panic, fatal, error, warn, info, debug, trace level: debug

如果怀疑问题出在数据库交互上，还可以开启数据库 debug 模式，它会记录所有数据库查询；该设置同时要求log.level为debug或trace：

database: # Enable debug mode. This setting requires the log.level to be set to "debug" or "trace". debug: true log: level: debug

配置加载路径按文档默认假设是/etc/headscale/config.yaml。修改配置后重启 headscale 服务使其生效，然后在节点复现问题时观察日志。

服务端：用 9090 端口的 metrics/debug 端点查看节点连接状态

Headscale 提供 metrics 与 debug 端点，默认监听 localhost 的 9090 端口。通过它可以查看：

Go 运行时信息、内存使用与统计；
当前连接的节点和待处理的注册请求（判断节点是否真的连到了控制端）；
当前生效的策略、过滤器和 SSH 策略；
当前的 DERPMap；
Prometheus 指标。

在运行 Headscale 的服务器上直接访问：

curl http://localhost:9090/debug/

如果不在服务器上，文档给出两种方式：

# 方式一：SSH 端口转发，把服务端的 9090 转发到本机 ssh <HEADSCALE_SERVER> -L 9090:localhost:9090

然后在本机浏览器打开http://localhost:9090/debug/。<HEADSCALE_SERVER>替换为你的 Headscale 服务器地址。

# 方式二：通过 debug key 访问远程 debug 接口 openssl rand -hex 32 | tee debugkey.txt export TS_DEBUG_KEY_PATH=debugkey.txt headscale serve

之后在浏览器打开http://<IP_OF_HEADSCALE>:9090/debug/?debugkey=<DEBUG_KEY>，其中<IP_OF_HEADSCALE>和<DEBUG_KEY>分别替换为 Headscale 服务器 IP 和你生成的密钥值；debugkey参数必须在每个请求中携带。也可以用TS_ALLOW_DEBUG_IP环境变量允许指定 IP 访问 debug 接口（文档示例值192.168.0.10，替换为你的设备 IP），但注意当请求携带X-Forwarded-For头时该 IP 限制会被忽略：

export TS_ALLOW_DEBUG_IP=192.168.0.10 # IP address of your device headscale serve

文档同时强调：metrics 和 debug 端点应保持在内部网络，不要暴露到互联网；如需完全关闭，可在配置中设置metrics_listen_addr: null。在端口说明中，tcp/9090 也明确标注“不需要公网可达”。

如果怀疑注册环节本身有问题，headscale CLI 还提供了debug create-node测试命令，用于创建一个可用auth register命令注册的测试节点：

headscale debug create-node --name <NAME> --user <USER> --key <KEY>

<NAME>、<USER>、<KEY>为必填参数，<KEY>是注册 key（registration ID），可用重复的--route标志让该节点宣告指定路由。

边界与注意事项

节点能否直连取决于客户端网络条件（NAT、防火墙等），tailscale netcheck只能反映本机状况；中继是否可用要靠tailscale debug derp headscale单独验证。
嵌入式 DERP 不支持 tcp/80 上的/generate_204，因此无法用于 Tailscale 的 captive portal 检查；它也不做吞吐优化。
移除 Tailscale 官方 DERP 服务器（urls: []）前必须先验证嵌入式 DERP 连通性，否则全网只剩单台中继，是文档明确指出的单点故障。
Headscale 服务端建议通过 HTTPS 在 443 端口提供服务；Tailscale 客户端在特定情况下会假定 HTTPS 443，改用 HTTP 或其他端口虽可行但不推荐用于生产。
客户端侧更深入的排查可以参考文档中提到的 Tailscale 官方 Troubleshooting guide（docs/ref/debug.md 中有链接）。

完成以上检查后，问题通常可以归到三类之一：tailscale netcheck显示本机网络条件受限（客户端网络问题）、tailscale debug derp headscale失败（DERP 中继链路问题，回到 DERP 配置与 udp/3478、tcp/443 端口）、或 9090 debug 端点中节点未出现在连接列表（Headscale 服务端问题，结合 debug 日志继续定位）。

【免费下载链接】headscaleAn open source, self-hosted implementation of the Tailscale control server项目地址: https://gitcode.com/GitHub_Trending/he/headscale

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考