故障排查

排障的顺序是固定的：先看本机状态，再看路径，最后看策略。

bash
celium status        # 本机在什么状态、对端可不可见
celium netcheck      # 本机网络环境如何
celium ping <对端>    # 到某台对端走什么路径

节点一直起不来#

celium status 的 backend state 会告诉你卡在哪一步：

状态含义怎么办
Stopped没在运行celium up
NeedsLogin服务器要求这台机器先被授权按 celium up 打印的链接在浏览器里批准
NeedsMachineAuth服务器要求管理员批准这台机器让管理员在后台批准，或给节点密钥加 preauthorized
Starting正在注册或等待网络地图看 health 一行的提示；长时间不动多半是连通性问题

health 一行是节点自己报告的问题，先读它。

bash
celium status --json | jq .Health

对端显示 online 但连不上#

看 PATH 列：

  • relay：能通，只是走中继。这不是故障，只是慢一点。想拿到直连，见下一节。
  • -：还没有建立任何路径。通常是对端刚上线，或双方都在严格 NAT 后面且中继不可用。
bash
celium ping db-1        # 看看到底走哪条路、延迟多少
celium netcheck         # 看本机是否根本无法直连

一直走中继，拿不到直连#

直连需要双方的网络允许 UDP 双向通行。以下情况拿不到直连，属于正常：

  • 一方在对称 NAT（celium netcheck 会写"映射随目标变化"）后面；
  • 网络只允许 TCP 出网（酒店、机场、部分企业网）；
  • 双方都在 CGNAT 后面且运营商不做锥形映射。

排查顺序：

  1. celium netcheck —— 出方向 UDP 是否可用？NAT 类型是什么？
  2. 两端各自的防火墙是否放行 UDP（默认端口 41641，可以 --port 指定）；
  3. 路由器是否开启了会破坏打洞的"对称 NAT"或 SIP ALG。

即使一直走中继，安全性和功能都不受影响——中继只转发密文。

名字解析不了#

bash
celium status | grep magicdns     # 确认内网域名后缀
  • TUN 模式：节点会接管宿主机解析；如果宿主机自己配了别的解析器并把它锁住（例如企业 MDM），

内网域名可能解析不到。可以临时用虚拟地址访问（celium status 里能看到）。

  • 用户态模式：宿主机上的程序不能用内网域名，因为宿主机根本没有这条路由。请通过

celium proxy 给出的本地代理访问，代理会自己解析。

内网域名永远不会被发到公共 DNS——这是有意的隐私设计，因此"公共 DNS 查不到"是正常的。

访问被拒绝（能 ping 通，但连不上端口）#

几乎总是策略问题。记住三条：

  1. 默认拒绝：没有任何规则覆盖的流量不放行；
  2. 规则是单向的：A → B:22 不等于 B → A:22，需要就写两条；
  3. 两端各自执行：两端都要有规则覆盖。

在管理后台的"访问策略"里检查当前策略，改完即时生效，不需要重启。

权限问题#

现象原因
cannot create a TUN device建真实接口需要 root。用 sudo，或改用 --tun=userspace
用户态模式下宿主机程序访问不了内网这是用户态模式的固有边界，见上

服务器侧#

bash
celium-control … --verbose        # 前台运行看日志
curl -s http://127.0.0.1:8080/health
curl -s http://127.0.0.1:8080/       # 会打印控制公钥，用于和节点上 pin 的核对

节点报"服务器的公钥与预期不符"：说明节点 pin 的控制公钥与服务器当前的不一致。只有两种可能：服务器换了密钥（重新生成了 control.key），或者有人在冒充服务器。前者需要把新的公钥重新下发给所有节点，后者说明 pin 正在保护你——不要绕过它。

收集信息#

bash
celium bug-report        # 汇总状态、netcheck、版本与状态目录清单

报告里不会包含私钥或会话令牌，可以直接贴出来求助。