排错指南
看提示定位问题，不把删除状态或重新安装作为第一步。
先运行 ns quick status 和 ns quick peers，再按终端提示查找下面的处理方法。输出示例见常用命令。请保留现有身份与配置，不要通过删除文件或系统路由绕过检查。
命令不存在
终端显示：
如果提示不认识 quick 或 join，先用 ns --version 查看当前命令行版本，再从命令行下载页确认并安装支持该命令的版本。更新 App 不会同时更新单独安装的 NS 命令行。
邀请码输入错误
终端显示：
使用默认中继时，复制完整的两字母加八数字短码。指定中继时执行 ns quick join 58307264 --relay quick.haiyand.com，中继必须与邀请方一致。
不想在命令中显示 PIN，可执行 ns quick join --relay quick.haiyand.com，回车后私密输入；输入不回显是正常的。手动指定中继时只支持一个地址；带前缀的短码与 --relay 不一致会报错，请复制邀请方提供的完整命令。
一直等确认、过期或取消
申请已发送、已确认、正在建立连接 都不是最终成功。A 和 B 都要保持终端打开，通过可信渠道核对完整的 20 字符节点 ID 并确认。
配对失败的通用提示为：
终端随后可能显示具体原因，例如等待超时。过期、关闭窗口或取消后，让 A 重新生成邀请。按 Ctrl-C 主动取消时：
已有配对不会删除。异常断网时远端取消可能未立即送达，临时会话会到期清理；不要把取消和移除永久配对混为一谈。
如果成功后出现以下提示，表示配对已完成，只是临时回执未送达：
此时先验证连接，不要重复删除并配对。
中继还没升级，或安全连接失败
终端提示可能包含：
短码配对需要客户端与中继同时支持，不能只升级客户端。第一条也可能由网络或证书问题引起：先检查域名、端口和系统时间，再联系中继管理员确认是否支持短码配对；不要关闭证书验证。quick.haiyand.com 的完整命令见指定中继。
非交互环境缺少身份确认
无人值守邀请没有固定接收方时，提示：
无人值守加入没有固定邀请方时，提示：
真人 SSH 操作请分配 PTY；自动化通过可信渠道预先核对完整身份，再按自动化示例填写，不用通用 --yes 绕过身份校验。
权限不足或账号模式仍在运行
- Linux/macOS：从状态所属用户的普通终端执行
sudo ns quick invite、sudo ns quick join或sudo ns quick up。 - Windows：用同一账号打开管理员终端；程序不会额外弹 UAC。驱动缺失或校验失败时，使用可信、架构匹配的 Wintun，不从不明网站下载 DLL。
- Linux 容器：root 身份本身不等于具备 TUN、
iproute2和网络管理权限。 - 账号模式还在连接：先在原 App 或 CLI 正常断开。不要改状态目录或删所有权文件绕过冲突。
同用户的已启动实例可在普通终端查询和停止；使用自定义配置时始终带同一 --config FILE。
本机 ready，却访问不了对方
例如运行实例报告尚无中继注册、无已连接对端时：
Quick: 运行中 只表示本机就绪。peers 列表仅表示保存了对端；unknown 是没有观测而不是零连接。检查双方是否运行、中继是否可用，再双向测试实际 IP 和应用端口。
域名解析失败先检查网络和 DNS；证书错误检查时间与信任配置；不同自定义中继需有可用共同路径，不保证中继间转发。切换中继需另行确认重启，详见连接与中继。
地址能通，应用或名称不通
用 peer show 的实际地址；IPv4 别名仅在本机有效，并需为 active。suspended 表示别名暂停，检查冲突，不删除其他 VPN 配置。应用要检查监听地址、地址族、端口和防火墙，不建议关闭整机防火墙。
Linux 默认不接入系统 DNS；macOS/Windows 需分域配置成功，其他 VPN、企业策略或应用自带 DNS 可能影响解析。详见地址与 DNS。
停止失败、清理未完成
正常停止成功应显示：
终端显示：
报错就不能视为成功。保留终端的错误提示，再执行 ns quick status 检查状态；仍无法停止时，按下方说明联系支持，不要自行删除状态文件或系统路由。
求助时提供什么
提供系统版本、ns --version、脱敏命令、完整错误文字和两端 status 的相关结果。日志在状态目录的 keynet-runtime.log，只摘录失败时间附近的必要内容。
不要提交邀请码、私钥、完整状态目录或未检查的配置。截图遮盖邀请码；身份核验通过可信私下渠道完成。