NetBird 与 Headscale 连不上：管理端、预授权密钥和中继不是同一条路

想把家里和公司的机器组成一个私网，常见两条自建路线：NetBird 用自己的客户端连管理服务，Headscale 则是给 Tailscale 客户端用的自建协调服务。netbird up 停在连不上管理服务，或 headscale nodes list 里节点一直离线，看起来都像「组网失败」，其实请求打到了不同的主机。

这两套不能互相登录。NetBird 的设置密钥不能贴进 tailscale up，Headscale 的登录地址也不能填进 NetBird 的管理 URL。下面按产品分开写命令和报错。软件版本和默认端口会变，以你部署的版本文档为准。

两套控制面不要混用

点对点打洞成功时，流量不必经过中继。打洞失败才走中继。所以管理台在线、两边仍 ping 不通，要看的是中继和访问规则，不是再生成一把登录密钥。访问规则写错会表现为在线但端口拒绝。

从装不上到两边互通：分步操作

• 第一步：先把线路准备好，连上刺猬VPN。自定义用户名和密码即可匿名注册，不需要邮箱、也不需要手机号；免费节点永久免费、不限流量、不限速，注册即用。全程 HTTPS+AES 加密传输。自建控制面若在境外，人打开管理台和客户端注册都要先出得去；
• 第二步：分清你用的是哪一套。机器上有 netbird 命令就是 NetBird。只有 tailscale、并且登录地址指向你自己的域名，才是 Headscale；
• 第三步：NetBird 先打开管理台，确认能看到 Peers、Setup Keys 和访问控制。管理台打不开时不要先改客户端密钥；
• 第四步：在 Setup Keys 里新建一把密钥，记下是一次性还是可重复使用、何时过期。在客户端执行 netbird up，按提示填入。完成后 netbird status 应能看到管理服务已连接；
• 第五步：Headscale 在服务器上用 headscale preauthkeys create 生成密钥，再在客户端执行 tailscale up，登录地址写成你的 Headscale 域名，并带上预授权密钥。不要走公有协调服务的默认登录；
• 第六步：headscale nodes list 里应出现新节点。状态仍是离线，就先看客户端的 tailscale status，确认登录地址没有写错；
• 第七步：两边都在线后，用私网地址互访，不要用公网地址测试组网。访问被拒绝时打开访问控制或策略，看有没有放行对应端口；
• 第八步：需要远程桌面时，走已经通的私网地址。远程桌面工具本身的登录见 远程桌面工具，不要把组网密钥填进远程桌面的账号框；
• 第九步：密钥过期或泄露就作废并另建一把。旧密钥留在脚本里，会导致新机器注册失败或多余节点一直占着名字。

按现象排查：管理台、密钥、中继

先看管理台能不能开，再看节点是否在线，最后看私网能不能通。三步不要跳。

• NetBird 管理台打不开：人到管理域名的线路不通。换节点后再开，不要改 Setup key；
• netbird up 提示连不上管理服务：客户端到管理主机失败，或管理 URL 写错。核对配置里的管理地址是否是你的实例；
• Setup key 无效或过期：密钥用完了次数或到了过期时间。在管理台作废旧的，新建一把再执行 up；
• Peers 里在线，私网地址不通：访问控制没放行。检查规则里的组和端口，而不是重装客户端；
• Headscale 返回未授权：预授权密钥错误，或客户端仍在使用公有登录地址。把 login-server 指到你的域名；
• nodes list 有机器但一直离线：客户端没保持连接，或协调域名从客户端所在网络访问不到。在客户端看 status 里的协调地址；
• 两边在线但只有一边能连中继：中继或 DERP 的地址没有从该网络到达。先让管理连接稳定，再查中继主机；
• 改完策略立刻仍不通：节点还拿着旧策略。在客户端重连一次，让它重新拉取规则。

组网和上网线路不是一件事

刺猬VPN 负责把你送到境外的管理台和协调域名。机器之间的私网流量由 NetBird 或 Headscale 自己转发。不要把上网节点当成组网的中继。免费节点适合先完成一次注册。控制面要长期在线，用时长套餐按周期计费，期间不限流量、不限速。实际可用性取决于当前网络环境。

家里一台和云上一台要分开看

云服务器如果已经在境外，它访问 Headscale 或 NetBird 管理服务往往不需要你电脑上的这条线路。注册失败时，先在云上直接访问管理域名，确认是云的安全组拦了端口，还是你的电脑出不去。两边用同一把一次性密钥会有一边失败，一次性密钥用完即废。

家里的路由器如果开了双重地址转换，打洞更容易失败，流量会改走中继。中继能通就先用着，不要为了打洞把管理服务的密钥换掉。看 status 里当前是直连还是经中继，再决定要不要改路由器。

升级客户端后，旧的管理服务版本可能拒绝新客户端。报错会像密钥错误。先看管理服务和客户端的版本是否在发行说明里允许搭配，再作废密钥。Headscale 与 Tailscale 客户端的版本搭配同样以你所用版本的说明为准。

一台机器同时装了两套客户端时，路由会抢默认出口。先停掉不用的那一套再测试。用私网地址互访时，关掉测试机上无关的上网实验，避免把结果看成组网中断。

私网里的域名和公网 DNS 不是一回事。你在管理台给设备起了名字，并不表示家里的电脑能用这个名字解析。解析失败时先用私网地址直连，确认端口是通的，再查组网软件自己的域名功能有没有打开。不要把失败记成密钥无效。

Windows 上服务没有起来时，命令行的 status 会像没登录。先看服务是否在运行，再执行 up。只在终端里看到帮助文字，不代表后台服务已经连上管理端。macOS 的菜单栏状态和命令行不一致时，以命令行里打印的管理地址为准。

退出登录和卸载不是同一件事。logout 之后节点会从在线变成离线，管理台里的设备记录还在。要让名字让给新机器，就在管理台删除或停用该节点，再让新机器用新密钥注册。只卸载客户端，旧记录会一直占着名字。

访问规则改的是组和端口，不是密钥。你把某一组从允许改成拒绝之后，节点仍显示在线，只是端口不通。这时不要新建密钥。把规则改回并让客户端重连，私网地址应恢复。规则里的组名和设备实际所在的组不一致时，改了规则也看不到效果，先在设备详情里核对它属于哪一组。

手机客户端和电脑客户端加入的是同一个网，但手机系统可能在锁屏后把连接挂起。电脑上看到手机节点忽隐忽现，先看手机是否允许后台运行，不要在管理台把手机节点删掉重加。删掉再加等于用新密钥重新注册，名字和地址都可能变。

给同事的一次性密钥用聊天工具传送时，前后不要多出空格。多一个空格，管理台会报密钥无效，看起来像线路不通。把密钥重新生成，用纯文本贴进命令，再看 status。

和 Tailscale、远程桌面怎么分工

公有协调服务的 Tailscale 登录、设备和密钥见 Tailscale 异地组网。Headscale 是把协调服务换成你自己的，客户端仍是 Tailscale 那一套。NetBird 则是另一款客户端，不要把那篇里的登录地址抄进 netbird up。

私网通了之后要看对面的屏幕，用远程桌面连私网地址，工具本身的账号和画面设置见 远程桌面工具。组网密钥和远程桌面密码不是同一个。

三件事的顺序是：人能打开控制面，节点变成在线，最后才是远程桌面。控制面打不开时去调远程桌面的画质没有意义。

常见报错速查表

高频问答

• 问：NetBird 和 Headscale 能互相登录吗？答：不能。客户端、密钥和管理地址都是两套；
• 问：上网用的节点能代替中继吗？答：不能。中继是组网软件自己的转发，上网线路只帮助你到达控制面；
• 问：一次性密钥能装两台吗？答：不能。第二台要另建一把，或改用允许重复使用的密钥；
• 问：免费节点够不够？答：够完成一次注册。控制面长期在线用时长套餐，期间不限流量、不限速；
• 问：ping 通私网地址还要开远程桌面端口吗？答：要。组网通了不代表桌面端口已放行；
• 问：版本升级后像密钥错误？答：先对管理服务和客户端的版本说明，再更换密钥。

先分清你跑的是哪一套

NetBird 连不上管理服务、Setup key 无效，Headscale 节点离线、登录地址仍指向公有协调，这些都要先看命令是 netbird 还是 tailscale。密钥在各自的管理台里作废重发，私网不通再查访问规则和中继。不要把两套登录地址抄混。

刺猬VPN 采用 HTTPS+AES 加密传输，支持断线保护和按域名的智能分流。自定义用户名和密码即可匿名注册，不需要邮箱和手机号。免费节点永久免费、不限流量、不限速；时长套餐按周期计费，期间不限流量、不限速。一个账号支持多设备同时在线。部署细节以你使用的版本文档为准。实际可用性取决于当前网络环境。