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 文档DERPDesignated 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/443HTTPS嵌入式 DERP 启用时必需需公网可达udp/3478STUN用于帮助客户端发现自己的公网地址并做 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 # 查看客户端收到的 netmapTailnet 状态快照 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或tracedatabase: # 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 策略当前的 DERPMapPrometheus 指标。在运行 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_PATHdebugkey.txt headscale serve之后在浏览器打开http://IP_OF_HEADSCALE:9090/debug/?debugkeyDEBUG_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_IP192.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 KEYNAME、USER、KEY为必填参数KEY是注册 keyregistration 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 guidedocs/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），仅供参考