NSIO 概览
面向”站点与用户对称”的覆盖网络生态：NS · NSD · NSGW 三组件、零信任接入平台，底层数据面为可独立复用的 nsplane。本站描述各仓库的已实现形态（
ns分支refactor/nsplanea9c6a090、nsd6bce2220、nsgwaa94aa5、nsplanev0.10.1、nssharedv0.6.0），并单独标注仍处于设计或规划中的能力。
组件与产品面
Section titled “组件与产品面”| 组件 | 仓库 | 产品面 | 一句话 |
|---|---|---|---|
| NS · 端侧节点 | ns | ns CLI、libns FFI、官方容器镜像 | 账户模式下每台 NS 既是”访问端”也是”发布端”：访问其他 Node 发布的 Service / 子网 / 出口，同时用 services.toml 发布本机 Service、用 ns subnet 发布本地 LAN；Quick 模式下设备凭短码两两直连 |
| NSD · 控制中心 | nsd | 单一静态二进制 + 内嵌 React 19 管理台 + nsdctl + SDK / Terraform provider；单实例或多实例部署 | 账户模式网络的权威：管理 Account / Organization / Network / Device / Node，编译 Access Grant，签发配置投影；从不承载业务流量 |
| nsplane · 数据面 | nsplane | Rust 库（nsplane-noise 核心、nsplane-packet、nsplane-core、nsplane 驱动、nsplane-tun）+ Linux / macOS 开发工具 | NS 节点的数据面：WireGuard 引擎、多传输与路径策略机制、报文过滤链、TUN 与用户态协议栈；每个节点一个引擎，其他应用也可直接嵌入 |
| NSGW · 数据网关 | nsgw | nsgw-server（+ 可选 Envoy sidecar）；独立的 nsgw-quick-relay | 账户模式的公网边缘：不解密 WireGuard 中继、WSS 中继、终结、公网 HTTP/L4 入口、Gateway Egress / Gateway Exit；Quick 模式的短码会合与密文中继 |
协议字段与 wire schema 中的 nsc / nsn 指一条链路的两端（访问端 / 发布端），不对应两个产品。
NS 的三个部分
Section titled “NS 的三个部分”| 部分 | 入口 | 主要用途 | 权威 | 状态 |
|---|---|---|---|---|
| 账户模式（NSD） | ns up --server <URL> 登记，之后 ns up / ns down | 团队、长期共享、策略与运维 | NSD：Account / Organization / Network / Device / Node 与 Access Grant | 已实现，默认 |
| Quick 模式 | ns quick up --relay <host:port>，ns quick invite / ns quick join <短码>，ns quick allow add <节点 ID> | 免账户的设备两两互联 | 每台设备自己：本地身份键、允许 / 移除记录 | ns 侧已实现 v2；relay 侧的 v2 服务端待 nsgw M2 |
| 应用模式 | ns send / ns receive <票据>；第三方应用 | 在节点的隧道之上运行的应用，首先是文件发送 | 由应用自己准入（文件发送用票据口令 PAKE），对端与路径来自节点当前模式 | 设计，未实现 |
- 账户模式：首次
ns up --server <URL>走浏览器 / 设备授权，由已登录 Account 批准；之后ns up/ns down/ns status作用于全部已连接的 membership（没有 active NSD），ns network join / leave增减 membership，未指定--server时使用默认 NSDhttps://nsd.dev.ns.io。NSD 投影 Service、子网、Gateway Exit 与 Short DNS，数据走 direct → wg-relay → wss-relay 链路阶梯。 - Quick 模式：无需账户或 NSD。A 运行
ns quick invite得到短码，B 运行ns quick join <短码>，双方经 relay 的会合信箱核对身份后配对并派生 PSK；也可以不会合，双方各自ns quick allow add <节点 ID>，记录从 relay 的登记表取得。配对只授权这一对设备：A–B 与 A–C 配对不让 B 与 C 互通。地址（N6/N4）与节点 ID 由身份键派生，一份签名的NodeRecord说明身份当前用哪把 WireGuard 键，relay 只在 WireGuard 之下转发密文；协议见 Quick 协议 v2。目前 relay 侧仍是 v1，v2 服务端是 nsgw 的迁移里程碑 M2。 - 应用模式：文件发送以及之后的功能、第三方应用都作为应用运行在节点之上，使用节点当前模式的对端与路径；没有现成对端时经会合信箱建立仅限本次会话的对端。目标设计中每个节点只有一个 nsplane 引擎，两种模式与所有应用都基于它。
- 账户模式与 Quick 模式由同一个二进制提供，运行在同一个 nsplane 引擎上。自 2026-10-12 起节点以 membership 模型运行：每个已连接的 NSD Network 与 Quick 各是引擎上的一个本地身份（由设备密钥链派生），平等、同时运行、互不影响；NSD 只提议，节点决定生效的配置。这一版 ns 的账户模式线上格式已变（身份对端，不再有 NSD 分配的 IPv4），NSD 与 nsgw 的配套在迁移计划的 M6。
跨组件的”角色 + 互联 + 时序”总体视图见 总体架构（拓扑、控制面下发、数据面链路阶梯、身份与授权模型、信任边界与失败域）。
每个组件有概览页（index.md）、架构与功能页和演进路线页（roadmap.md）；NS 的架构按三个部分分页。
- NS · 端侧节点 —— 账户模式、Quick 模式、应用模式；三种数据面（
tun/dns-vip/proxy）、链路阶梯、Service 发布、Short DNS、Gateway Exit、子网路由、libns。 - NSD · 控制中心 —— 身份与登记、Access Grant、配置投影、网关编排与中继放置、公网入口与 Edge Auth、管理台、Network 套餐与 SaaS 多租户。
- nsplane · 数据面 —— 定位与原则、crate 划分、无 I/O 引擎模型与驱动 trait、翻译与 MTU、安全基线、发布与路线图。
- NSGW · 数据网关 —— 五条数据面职责、Envoy 公网边缘、多 realm、fail-closed ACL 门、计量，以及 Quick relay。
协议角色关系矩阵
Section titled “协议角色关系矩阵”| 协议 / 机制 | NSD | NSGW | NS |
|---|---|---|---|
WebPKI 控制信任发现（GET /api/v1/info → control_trust.v1） | 发布方 | 消费方 | 消费方 |
| 控制传输 SSE / Noise IK / QUIC | server（Noise / QUIC 由 sidecar 终结为明文 HTTP） | client（按发现顺序探测） | client（auto 优先 SSE，运行时故障切换） |
Envelope v1（CBOR + Ed25519 签名，POST /api/v1/control） | 校验请求 / 签名响应 | 签名请求 | 签名请求 |
配置流事件（ControlMessage，逐事件 Ed25519 签名） | signer | verifier | verifier |
| WireGuard UDP | — | 不解密中继（:51821，含中继测量探测）/ 终结与 Exit 承载（:51820） | peer ↔ peer（direct / wg-relay）、Exit 客户端 |
中继位置测量（probe_roster / probe_set / gateway_rtt） | 下发名单、按 RTT 放置 | 应答测量探测 | 测量并在心跳中上报 |
WSS（/client、/wss-relay、/relay、/exit-wss/v1） | — | server | client |
| 公网 HTTPS / TCP / UDP 入口 | 编排（域名、路由、证书、Edge Auth） | Envoy sidecar + ext_authz + 入口 ACL | — |
| 本地 DNS（Short DNS v2 resolver） | authority / projection | — | server（127.53.53.53 / 169.254.53.53） |
| JWT（RS256） | issuer | verifier（WSS、Exit 承载） | 持有者 |
| ACL（仅允许语义） | 编译 acl_config | 执行（terminate / 公网入口 / Egress / Exit，全部 fail-closed） | 执行（Service PEP、Node L3、子网），fail-closed |
核心不变量：
- 节点私钥永不出节点 —— NSD 从不接收节点身份私钥或 WG 私钥；
WgConfig没有private_key字段。NSD 自有的签名密钥与集中管理的公网边缘证书密钥属于另外的信任域。 - 三种控制传输共用一份事件解析器 —— 传输只是外壳，事件签名独立于外壳。
- 账户模式配置来自 NSD 投影 —— 本地
services.toml与gateway_services.toml声明能力与执行下限。Quick 模式没有中心权威，每台设备只按自己的准入策略接纳配对。 - ACL 全链路 fail-closed —— 策略未到、显式为空、来源被撤销时一律拒绝；传输抓取失败只保留 last-known-good。
- 数据面对 NSD 无运行时依赖 —— NSD 不可达时既有链路继续工作，只失去变更与新登记能力。
不可放弃的差异化
Section titled “不可放弃的差异化”- 统一节点 —— 一个二进制、一个身份，同时访问与发布；同一 Account 下的 Node 之间默认全双向 L3 互通。
- 协议可插拔的控制面 + 零手工 pin —— 只配一个 HTTPS origin，Noise / QUIC / Envelope 信任材料由 WebPKI 认证的发现文档提供。
- 三种数据面同一份上层逻辑 ——
tun（默认，L3 + L4）、dns-vip（免 root 的 L4 兼容）、proxy（免 root 的 SOCKS5 / HTTP / PAC）。 - 链路阶梯 —— direct → wg-relay → wss-relay 逐级降级、可恢复；网关在 relay 模式下结构性看不到明文。
- 网关能力对称声明 —— NS 用
services.toml/ns subnet声明，NSGW 用gateway_services.toml声明，NSD 只做合成与裁剪，不能凭空生成节点没有声明的能力。 - 节点身份与 WG 私钥永不出节点 —— 这是协议约束，不是运维惯例。