统一 NS

设备与节点共用 ns。下列步骤覆盖当前 12 个公开命令及关键子命令；参数始终以候选二进制 ns help 为准。

1. 安装、登记与信任（NS-01/NS-02/NS-03/NS-21/NS-24）

ns --version
sudo ns up \
  --server "$NSD_URL" \
  --nsd-noise-pubkey "$NSD_NOISE_PUBKEY" \
  --nsd-quic-pubkey "$NSD_QUIC_PUBKEY" \
  --nsd-envelope-key-pin "$NSD_ENVELOPE_KEY_PIN"
sudo ns up --server "$NSD_URL" --invite "$INVITE"
sudo ns up --server "$NSD_URL" --invite-file "$INVITE_FILE"
sudo ns up --transport-mode auto
sudo ns up --transport-mode wg
sudo ns up --transport-mode wss

• 安装来源和版本要与候选构建一致；覆盖安装不得顺带重置状态。
• URL 与 Noise 公钥、QUIC 公钥、Envelope key pin 必须从当前 NSD“快速开始”复制。任一 pin 错误时，对应受保护路径必须拒绝，不能 TOFU 或静默降级。
• --invite 与 --invite-file 互斥；文件必须安全读取，错误权限、链接、空值、过期或复用令牌都要明确失败。
• 浏览器批准后，ns info 必须显示批准账号和精确 Organization/Network/Profile；不能用旧浏览器账号或旧 profile 覆盖。
• 三种 transport mode 分别验证实际载体；网络不支持强制模式时明确失败，不能伪装连接。

2. 状态、节点与服务（NS-04/NS-05/NS-06/NS-07/NS-22）

ns status
ns status --json
ns status --all
ns status --probe
ns status --dns
ns info
ns info --json
sudo ns up --services-file "$SERVICES_FILE"

人类输出与 JSON 必须描述同一身份和同一运行时事实。--probe 只探测当前获准的 L3 节点；--dns 显示准确的非节点 DNS 记录；Short DNS 只解析当前网络获准服务。服务文件的有效配置要发布成功，无效结构、越权路径和不安全文件必须在启动前拒绝。

3. Organization 与 Network（NS-08/NS-09）

ns space list
ns space list --json
sudo ns space switch "$NETWORK_ID" --yes --json
sudo ns up

Network ID 是全局唯一选择键。切换成功后保持断开，再次 up 才启动新 Network。状态、服务、节点、出口与 DNS 只能来自新 profile；旧请求或缓存不得覆盖新 generation。

4. 出口（NS-10/NS-11/NS-12）

交互选择并立即启动

sudo ns exit

在 TTY 中选择获准 Gateway 后，应保存默认路由偏好并通过统一 TUN 运行时立即启动出口；取消不得改配置或启动。无候选、候选不支持默认路由、无 TTY 或无系统网络权限必须明确失败。

脚本配置与真实激活

ns exit set "$GATEWAY_ID" --default
ns exit set "$GATEWAY_ID" --cidr "203.0.113.0/24" \
  --transport auto \
  --private-network-routing local \
  --dns-routing local \
  --preserve-cidr "198.51.100.0/24"
sudo ns up --exit

exit set 只保存当前 profile 的本地出口偏好：不得发送远端选择，也不得声称运行时已就绪。只有 sudo ns up --exit 才按偏好激活数据面。分别以公网 IP、路由表、DNS 和私网访问验证 default/CIDR、DNS、私网保留与 transport，而不是只看命令成功。

清除边界

ns exit clear

clear 清除本地偏好，并在偏好存在时停止使用该状态目录的 NS CLI 运行时；远端选择可能仍保留。再次普通 sudo ns up 不得自动套用已清除偏好；远端对象不能被本地 clear 误删。

5. 子网发布（NS-13/NS-14/NS-15）

ns subnet add "$LAN_CIDR" --bind
ns subnet add "$LAN_CIDR" --join "$SUBNET_ID" --bind
ns subnet list
ns subnet bindings
ns subnet bind "$SUBNET_ID"
ns subnet unbind "$SUBNET_ID"
ns subnet remove "$SUBNET_ID"

--join 只用于明确加入同一物理 LAN 的 HA 映射，错误 LAN 要 fail closed。unbind 只移除本地投递绑定，不改变 NSD 映射；remove 只删除当前节点的发布，同映射的其它节点和 NSD 对象不得被误删。注意：这验证 ns 的节点发布能力，不等于当前 NSD UI 已开放 Subnet Access Grant；该授权入口当前按 ACL-06 做 Not Ready 负向验收。

6. 后台启动与就绪（NS-23）

sudo ns up --detach
sudo ns up --detach --wait-ready

普通 --detach 在 worker 生成后返回；带 --wait-ready 只有初始路由就绪才成功。超时、进程提前退出或取消必须停止本次 worker 并清理错误的运行时描述，不得留下第二实例。--wait-ready 单独使用或把 --detach 用于其它命令必须拒绝。

7. 诊断、停止、更新与重置（NS-16/NS-17/NS-18/NS-19/NS-20/NS-25）

ns doctor
ns report
sudo ns repair
sudo ns down
ns update --check
sudo ns update
sudo ns reset
sudo ns reset --all
sudo ns reset --all --yes

• doctor 与 update --check 只读；report 只打印预填环境信息的反馈链接且不得含凭据。
• repair 只处理当前登录用户默认状态目录的旧版权限，拒绝自定义错误目标、符号链接和不可确认路径。
• down 清理 TUN、路由、DNS 与本地实例；更新保留身份/Profile/authority，失败保留可运行旧二进制。
• 裸 reset 只清运行时/系统状态，保留设备身份、Space Profiles、单一 NSD authority 与凭据。
• reset --all 缺 --yes 必须拒绝；只有精确的 reset --all --yes 才能删除身份、全部 Profile、authority、凭据、VIP 映射与恢复状态，之后登记为全新设备和节点。

8. 旧状态迁移（NS-26/NS-27）

1. 准备仅含一个旧 source 的真实历史状态，运行候选 ns info/ns up：自动迁移为 singleton profile，身份不变且无需浏览器重新登记。
2. 准备含多个旧 source 的状态：启动必须 fail closed，不能任选其一或混合资源；提示明确要求人工全量重置，然后执行 sudo ns reset --all --yes 再重新登记。
3. 两类迁移后都检查文件权限、Profile/authority 唯一性和第二次启动幂等性。