NetSeed Docs

常用命令

左边看用途，右边看命令和结果。先连接，再按需管理。

邀请与加入 · 设备与配对 · 指定中继

将 <…> 替换为实际值，地址与设备信息以自己的终端为准。Windows 首次启动用管理员终端，macOS / Linux 加 sudo。已运行的本机实例可直接查询。

命令总览

连接与查询

命令用途修改状态
ns quick invite生成邀请，等待对方加入是
ns quick join输入邀请码，核对并确认连接是
ns quick up启动或恢复本机节点是
ns quick status查看身份、中继与当前连接数否
ns quick peers列出已保存的配对否
ns quick down停止连接，保留身份和配对是
ns quick --help查看帮助；也可用 help 子命令否

设备与高级管理

命令用途修改状态
ns quick peer show查看某个对端的地址与别名否
ns quick peer name设置本机显示名称是
ns quick peer remove移除对端并保留阻止记录是
ns quick allow list查看准入和移除记录否
ns quick allow remove撤销对端准入是
ns quick allow restore解除阻止，不自动重新配对是
ns quick policy set设置底层准入策略是
ns quick pending list查看底层待审批记录否
ns quick pending approve / deny批准或拒绝一条底层申请是

以上是命令索引；需要的参数与执行结果在对应演示中。高级准入管理不是短码配对的必做步骤。

01 / 启动

启动与恢复：up

后台启动节点，或恢复已有配对。首次邀请会自动启动，不用提前执行。

“运行中”代表本机已启动，不代表对端可达。

本机 · 启动交互示例
终端 · 输入后回车
sudo ns quick up
Quick: 运行中
节点 ID: <本机20字符节点ID>
已配置中继 (config): <中继地址>
查看实时连接：ns quick status

02 / 状态

查看连接：status

看本机身份、中继注册、连接数。这里已注册中继，但还没有连接对端。

“未知”是尚无观测，不等于零。中继配置和连接密钥有效期也在这里显示，不用再加参数。

本机 · 运行状态交互示例
终端 · 输入后回车
ns quick status
Quick: 运行中
节点 ID: <本机20字符节点ID>
已连接中继: <中继地址>
已连接节点: 0
已配置中继 (config): <中继地址>
连接密钥: 有效
续期时间: <自动续期时间> / 到期时间: <密钥到期时间>

03 / 对端

查看已配对设备：peers

还没配对时会提示发出邀请。配对后显示 ID、备注、IPv6 和日期，不是实时在线列表。

查看、命名、移除的完整示例。

本机 · 设备列表交互示例
终端 · 输入后回车
ns quick peers
还没有已配对节点。运行 ns quick invite 邀请对方。

04 / 停止

停止：down

停止本机 P2P，保留身份和配对。下次 up 恢复。

这不是删除设备，也不是退出账号。

本机 · 停止交互示例
终端 · 输入后回车
ns quick down
Quick 已停止，身份和已配对节点已保留。

05 / 命令索引

查看帮助

用 --help 查看可用命令。下面摘录常用部分；具体命令也能加 --help，例如 ns quick join --help。

ns quick help join 也可查看加入帮助。

NS Quick · 命令帮助交互示例
终端 · 输入后回车
ns quick --help
ns-quick
通过短邀请码，无需账号即可连接设备。

用法： ns quick [OPTIONS] <命令>

命令:
  up       启动或恢复本机 Quick 节点。
  down     停止 Quick 连接，保留身份和配对。
  status   查看本机节点和当前连接。
  invite   创建短邀请码，并核对确认申请连接的设备。
  join     使用对方的短邀请码连接设备。
  peers    列出节点 ID、备注、IPv6 和配对日期。
  peer     查看节点详情、设置本机备注或移除节点。
  policy   管理配对审批策略。
  pending  查看、批准或拒绝配对申请。
  allow    查看访问授权，移除或解除阻止节点。
  …（省略维护命令）
  help     显示帮助信息或指定命令的帮助

中继选项

日常不必填。需要指定、切换或恢复默认时，看连接与中继图解。up、invite、join 都支持 --relay、--reset-relays 和 --switch-relay。

--relay 只指定一个中继；不支持逗号列表或重复填写。--reset-relays 恢复内置多中继配置。

权限与可选配置

权限与可选配置

不用手写 keynet.toml。仅在高级配置时使用 --config FILE；文件必须存在且私有，Unix 通常为 600，Windows 使用受限 ACL。查询和停止要带相同文件：

自定义配置 · 停止交互示例
终端 · 输入后回车
ns quick --config /private/keynet.toml down
Quick 已停止，身份和已配对节点已保留。

不能接管其他用户实例；账号模式与 P2P 只能运行一个。重复 up 复用实例，编辑配置不会暗中重启。up --watch 就绪后 Ctrl-C 只退出观察，真正停止用 down。

自动化：从标准输入加入、JSON 结果

自动化：预先固定对方身份

先通过可信渠道取得对方完整 64 位身份指纹。不要用 --yes 代替身份核对，也不要把邀请码写入公共日志。

A · 固定接收方交互示例
终端 · 输入后回车
ns quick invite --recipient <B的完整身份指纹> --json
{"schema_version":1,"operation":"quick.pairing","stage":"complete","message":"配对成功。ns quick peers 查看节点，ns quick status 查看实时连接。","details":{}}

上面仅展示最终成功事件；程序先输出 invitation_created，随后才有配对阶段事件。

B · 从标准输入读取一行邀请码交互示例
终端 · 输入后回车
ns quick join --stdin --peer <A的完整身份指纹> --json
{"schema_version":1,"operation":"quick.pairing","stage":"complete","message":"配对成功。ns quick peers 查看节点，ns quick status 查看实时连接。","details":{}}

由可信秘密源提供一行邀请码并结束输入。检查 complete 和退出码；failed、cancelled 不是成功。首次启动仍需管理员权限。

invite/join 使用 schema 1 事件流；其他管理命令和参数解析错误可能是 schema 2，不要共用固定格式解析器。非交互切换中继另需 --switch-relay。

invite --ttl 15m 设有效期，--wait 120 设等待秒数，取更早截止时间；最长 15 分钟，等待范围 1–900 秒。