NetSeed Docs

    NS 命令参考

    本文按当前 ns --help 的 12 个顶层命令维护。macOS/Linux 中修改 TUN、路由、DNS 或状态目录通常需要 sudo；Windows 请使用管理员 PowerShell。

    命令总览

    命令用途是否改变状态
    ns up启动已登记 NSD；首次登记、重新认证或确认后替换 NSD是
    ns status查看连接、来源、站点、节点与服务状态否
    ns info离线查看版本、Device、NSD 注册和运行持有者否
    ns exit选择或清除出口是
    ns subnet发布、绑定和检查 IPv4 LAN 映射是/读
    ns space列出或切换可访问的 Organization/Network是/读
    ns report输出带非敏感环境信息的反馈链接否
    ns doctor只读检查权限、DNS、实例和 NSD 连通性否
    ns down断开当前运行的 NS Node是
    ns repair修复默认状态目录的旧版权限是
    ns reset清理运行/系统状态，或明确完整删除身份是
    ns update检查或安装官方 CLI 更新是

    up

    sudo ns up --server https://nsd.haiyand.com
sudo ns up --detach --wait-ready

    首次使用 --server 打开浏览器登记；已有唯一 NSD Profile 时省略 --server 可直接启动。常用选项：--hostname 请求 Node DNS 标签；--services-file 指定服务定义（默认 /etc/nsio/services.toml）；--transport-mode auto|wg|wss；--control-mode auto|sse|noise|quic；--exit 在本次启动启用出口捕获；--metrics 开启仅本机指标。

    三类 NSD 信任 pin

    参数验证对象格式
    --nsd-noise-pubkeyNSD Noise 静态公钥64 位十六进制
    --nsd-quic-pubkeyNSD QUIC 证书 SHA-256 指纹64 位十六进制
    --nsd-envelope-key-pinNSD 响应信封 Ed25519 key 的 RFC 7638 JWK thumbprint43 字符、无填充 base64url

    它们是公开信任根，不是登录凭据。Noise/QUIC 各自验证服务器公钥或证书，二者都依赖 envelope signer pin 验证控制面响应。它们绑定某个 NSD 部署的 canonical HTTPS authority 与控制通道；在同一 NSD 中切换 Organization/Network/Space 不会改变 pin。NSD 替换、域名权威改变或服务端密钥轮换时才可能更新。auto 模式下 SSE 可用；Noise/QUIC 只有相应传输 pin 与 envelope pin 齐全时才进入候选。

    官方 App 首次启动使用受控发布配置；一旦已有可信持久 source/manifest authority，应优先沿用该权威。普通远程配置不得静默替换三项 pin 或重定向认证 authority；换权威/轮换必须经过显式、可验证的可信迁移。自定义 NSD 不继承官方 pin；不要从聊天、旧 Space 或未验证远端配置拼接。CLI 示例使用占位符：

    sudo ns up \
  --server https://nsd.example.com \
  --nsd-noise-pubkey '<64-hex-noise-key>' \
  --nsd-quic-pubkey '<64-hex-quic-fingerprint>' \
  --nsd-envelope-key-pin '<43-char-jwk-thumbprint>'

    status

    ns status
ns status --probe --dns
ns status --all
ns status --json

    --probe 对当前 L3 对等节点执行 ICMP 探测；--dns 显示非 Node DNS 记录；--all 包含默认隐藏条目。自动化应使用 --json，不要解析终端文案。

    info

    ns info
ns info --json

    无需连接即可核对版本、状态目录、Device、已登记 NSD、当前 Space 和运行持有者。排查 App/CLI 同时占用时优先执行。

    exit

    ns exit set --help
ns exit clear

    set 为当前 Space 选择已授权 Gateway Exit 与路由策略；clear 清除本地出口配置，不删除远端选择。未获授权或未选择出口时，不应打开出口捕获。

    subnet

    ns subnet add --help
ns subnet list
ns subnet bind --help
ns subnet bindings
ns subnet unbind --help
ns subnet remove --help

    子命令分别用于发布/加入 LAN 映射、查看本 Node 发布项、绑定本机 LAN 出口、查看本地 bindings、解绑和移除发布。每次操作都属于当前 Space；生产变更前用具体子命令 --help 核对 CIDR、映射 ID 与冗余网关参数。

    space

    ns space list
ns space switch <NETWORK_ID>

    list 同时显示 Organization 与 Network。switch 使用明确 Network ID；成功后保持未连接，防止在未确认新配置前自动产生流量。取消或失败时核对输出，再用 ns info 确认实际 Space。

    report 与 doctor

    ns report
ns doctor

    report 生成预填环境信息的反馈链接，不应包含凭据；提交前仍需人工检查。doctor 是只读检查，不会重置系统，适合第一步诊断。

    down、repair、reset

    sudo ns down
ns repair
sudo ns reset
sudo ns reset --all --yes

    down 正常断开并释放网络资源；repair 只修复当前用户默认状态目录的旧版权限；普通 reset 清理运行和系统网络状态，保留 Device、Space Profiles 与 NSD 权威。reset --all --yes 会完整删除身份、Profiles、权威、凭据、VIP 映射与恢复状态，之后必须作为新 Device 登记，只有明确需要时才执行。

    update

    ns update --check
sudo ns update --yes

    只更新命令行二进制；校验新发布物且保留可回退旧文件，永不主动修改身份与 Space 数据。