简体中文
故障排查
一个症状一节：先看现象，再跑几条检查，最后一句话说怎么修。八节覆盖的是真的会坏的那些地方。
面板走 HTTP，https:// 连不上，那不是故障。离线的机器是被拒绝，不是被排队，它回来之后也没有什么在等着发生。这一页上没有一步是去手改 /etc 的，事实源是 config/，让它成真的是 nhub apply。核心单元不能从面板上停掉，缺了 dnsmasq 的网关不是关掉了一个功能，而是坏了。有两个已知的毛病这一页修不了：被控端在一轮处理中途收到停止时会先把退避等完，以及同一个主机名后面的两台中枢会互相把对方踢下线。
面板连不上
bash
# 1. 单元起来了吗。应该是 active (running)。
systemctl status neutrino_hub_web
# 2. 它在你以为的那个端口上吗。没搬过的话是 8080。
ss -lntp | grep neutrino
# 3. 这个网络它应答吗。开放范围里应该列着这个网络。
sudo nhub apply --only router --dry-run端口在「网络」页的面板端口里改，应答哪些网络在同一页的开放范围里定。面板是 HTTP，地址栏里写 https:// 永远连不上。
WARNING
同一个主机名后面挂两台中枢，会互相把对方踢下线。会话 cookie 只认主机名不认端口，所以登进第二台就等于从第一台上被登出。
两台就给两个主机名，或者一次只开一台的页面。
被锁在外面
登录页写着「多次失败后已锁定。」时：
bash
# 1. 重新放开登录，顺带清掉 fail2ban 上所有 SSH 封禁。
sudo nhub unlock密码本身忘了：
bash
# 2. 设一个新的面板密码，所有会话都会被登出。
sudo nhub reset password保险库主口令是另一把秘密，这里重置不到它，那件事在《备份与恢复》里。
设备离线
抽屉里的操作被拒绝，写着「这台机器没有响应，没有在它上面启动任何操作。」
bash
# 1. 在那台机器上：被控端起来了吗。应该是 active (running)。
systemctl status neutrino_agent
# 2. 它绑在谁上。应该是这台中枢的地址。
sudo nagent status
# 3. 别等它自己来，立刻要一次状态。
sudo nagent sync| 界面上写着 | 怎么修 |
|---|---|
| 那个被控端说的通道协议比这台 hub 旧，请升级它 | 在抽屉里「重新安装被控端」 |
| 那个被控端的版本比这台 hub 新，请升级 hub | 先把中枢升上去 |
| hub 没有出示这台机器所固定的证书 | 中枢被重置或者重装过，用新链接重新接入 |
| 什么都没绑 | 生成一条新链接，在机器上跑 sudo nagent connect '<链接>' |
TIP
在一轮处理中途发出的停止，要等退避走完才生效。那是被控端自己的已知毛病，不是机器卡住了。
客户端连不上
先看窗口里那句拒绝，再对下面这张表。
| 拒绝 | 怎么修 |
|---|---|
| 连接不上 hub | 从这里连不上中枢的通道端口 8443 |
| hub 拒绝了这个链接，它可能已过期，请重新生成一个 | 链接只有五分钟，重新生成一条 |
| 这不是加入链接，请从 hub 复制整行 | 粘贴时被截断了 |
| 此链接是给设备 agent 的，不是给客户端的 | 到「客户端」页生成，不是设备页 |
| 此链接不带 hub 地址和令牌 | 同样是复制不全 |
| 应答的不是此链接固定的 hub | 中枢被重置或者重装过 |
| hub 已关闭此客户端 | 在客户端页把它启用 |
| 此客户端比 hub 新，请先升级 hub | 先升级中枢，再粘一条新链接 |
| 窗口需要 WebKitGTK 或者某个运行时 | 按它给的包名装上，再启动客户端 |
共享挂不上
| 拒绝 | 怎么修 |
|---|---|
| 请填家目录下的文件夹，例如 ~/nas/share | 路径在家目录之外 |
| 请填一个空闲盘符，例如 N: | Windows 上要的是盘符，不是路径 |
| 那个文件夹不是空的 | 换一个空的 |
| 这台机器上的挂载未获授权 | polkit 的弹窗被关掉了，再点一次挂载 |
| 这台机器上缺少挂载工具 | 装上 cifs 那套工具 |
| 保存的登录信息已丢失，请用配置重新填写 | 点「配置」把共享的用户名和密码重填一遍 |
| 那一行是灰的，写着当前无法访问 | 提供共享的机器关着，或者开放范围里没有这个网络 |
客户端唯一一次提权就是那个挂载用的 polkit 助手，除此之外它从不是 root。
AI 工具不走网关
bash
# 1. 这个人的工具指向哪里。应该是中枢的端点。
nclient service ai show
# 2. 网关应答吗。应该回一个模型列表，而不是一句拒绝。
curl -s http://<hub>:8317/v1/models -H 'Authorization: Bearer PLACEHOLDER_CLIENT_KEY'| 症状 | 怎么修 |
|---|---|
| hub 还没有给你密钥 | 在 AI 页的接入里生成一把，或者把客户端重新接一次 |
| 面板写「网关没有应答，无法向它查询。」 | 在中枢上看 systemctl status neutrino_hub_cliproxyapi |
| 工具还在用它们自己的配置 | 配置框里的保存只是暂存，要按「应用」 |
| 某台机器指着旧端口 | 网关端口改过，每个端点都要跟着改 |
虚拟网里少一个节点
| 引擎 | 检查 | 怎么修 |
|---|---|---|
| NetBird | 标记写着管理面不可达 | 在代理页打开让这台机器自己的流量走代理 |
| NetBird | 节点表是空的 | 在另一台设备上用 NetBird 应用登录 |
| NetBird | 路由通告了但访问不到 | 那个网段在控制台里还缺一条访问控制策略 |
| EasyTier | 写着还没有机器加入 | 另一台机器的网络名字和密码必须完全一致 |
| EasyTier | 加进来了但路由不通 | 把网段加进导出的局域网再应用一次 |
| 两者 | 这台机器在虚拟网上哪儿都不应答 | 「网络」页的开放范围 |
换一把密码就是换了一张网。引擎不会有任何提示，节点表就是一直空着。
日志
| 要看什么 | 在哪 |
|---|---|
| 初始化那一次的过程 | /var/log/neutrino/setup.log |
| 中枢自己的日志 | /var/log/neutrino/ |
| 某个单元 | journalctl -u neutrino_hub_web -n 200 |
| 某台机器上的被控端 | journalctl -u neutrino_agent -n 200 |
| AI 网关，在面板里 | AI 页的日志一栏 |
| 渲染出来会是什么样 | sudo nhub apply --dry-run |
面板上的单元名依次是 neutrino_hub_xray、neutrino_hub_router、neutrino_hub_dnsmasq、neutrino_hub_web、neutrino_hub_cliproxyapi 这五个核心单元，加上可选的 neutrino_hub_netbird 和 neutrino_hub_easytier，机器上的被控端是 neutrino_agent。按接口起的那几个是模板单元，写成 neutrino_hub_dhcpcd@<网口>.service 这样。
至此，八种症状就都介绍完了。