NSIO Docs
NSIO Docs
首页

NSIO Next · 当前开发基线

统一 L3 + L4 架构
产品能力目录与实现闭环
功能闭环总账
产品闭环与功能实现
实施蓝图与交付契约
发行、升级与卸载
跨组件共享契约
控制资源生命周期
控制投影与 Runtime Protocol
数据面协议
Grant 与策略编译

组件实现规格

ns · 统一节点运行时
Client · App、CLI 与门户
NSD · 身份与控制面
NSGW · 增值数据面
身份、登录与会话
注册、准入与配额协议
商业模型与 Entitlement
采购、计费与发票
服务运营与 SLA
备份与灾难恢复
信任、合规与数据权利

Last Updated: 2026/8/9 11:10:38

Previous Page功能闭环总账
Next Page实施蓝图与交付契约

#NSIO Next · 产品闭环与功能实现规格

状态:产品、交互与跨组件实现基线。本文回答“用户如何一步步完成任务,以及系统每一层如何闭环”。系统对象与安全边界以统一 L3 + L4 架构为准;全部能力、组件责任、状态与角色预演见产品能力目录与实现闭环;控制对象状态/API 见控制资源生命周期,运行投影见Runtime Protocol,建流与传输见数据面协议,注册状态、API 与事务以注册、准入与配额协议为权威。

#0. 什么叫“功能闭环”

一个功能只有覆盖七个必需阶段,才算可以进入实现:

  1. 创建:入口、前置条件、用户动作、权威对象和初始状态;
  2. 投影:谁验证、编译、签名并向哪些执行者下发哪个 revision;
  3. 执行:数据/控制路径如何建立,哪一端做最终校验;
  4. 失败:等待、不可用、读取失败、冲突和不兼容如何区分与恢复;
  5. 撤销:谁可撤销、新连接和在途连接多久停止;
  6. 清理:路由、DNS、凭据、租约、配额和本地状态如何有序释放;
  7. 审计:actor、对象、revision、provenance、结果和 request ID 如何留证。

需要人工或策略批准的功能再增加审批阶段;会占用配额、计费或计量的功能再增加计量阶段。没有这些条件的功能不强行写“无审批/无计量”占位,但不得漏掉适用阶段。

后文所有功能都按这个标准描述。只画 UI、只定义 API、只跑通 happy path 都不算完成。

#1. 产品中的人、空间与入口

#1.1 四类使用者

使用者首次入口主要目标认证方式
个人用户NS App两台自己的设备互联邮箱密码、Google 或 GitHub
组织创建者NS App 或 Web创建团队、邀请成员、管理网络人类登录 + MFA
企业员工企业邀请、SSO 或 MDM访问被授权节点和应用企业 OIDC,目录生命周期可接 SCIM
无人值守节点CLI、镜像或自动化服务器、路由器、连接器、CI 加入Enrollment Key,只用于注册

#1.2 人类用户先登录,再决定进入哪里

人类设备不先要求用户理解 Organization、Network ID 或 Auth Key。统一流程是:

  1. 安装并打开 NS App;
  2. 点击“登录并连接”,App 打开系统浏览器;用户直接选择邮箱密码、Google、GitHub 或企业 SSO,不要求先统一填写邮箱;
  3. Directory API 返回该身份可进入的邀请、Organization 和 Network;
  4. 首次登录自动创建一个真实但在 UI 中称为“个人空间”的 Organization、Personal Network 和个人安全模板;
  5. 有待接受邀请时同时展示邀请,用户可以加入已有 Organization,个人空间仍然保留;
  6. Personal 配额内邀请成员不改变套餐;用户明确启用试用、主动升级或使用当前 entitlement 不包含的企业能力时,个人空间可以原地升级为团队/企业 Organization;
  7. 登录不是网络授权。只有 Device 注册、Network Membership 生效且 Grant 编译成功后,设备才获得数据面能力。

登录入口、账号绑定、会话和身份撤销的权威规则见身份、登录与会话实现基线。App 不显示密码字段,也不根据邮箱自行合并账号;邮箱只在邮箱密码或用户主动选择的企业 SSO 发现流程中使用。

不在首次连接之前强迫个人用户选套餐、配置 ACL 或进入管理控制台。先让两台设备连通,再展示升级价值。

这里的 Organization 是后台稳定租户边界,不是要求个人用户手工“创建公司”。个人 UI 只称“我的空间”。个人空间升级团队时仍使用同一个 Organization,不重建任何资源;只有用户明确要求另一个独立账单/安全边界时,才创建新的 Organization ID。

个人空间使用和企业相同的 Grant 引擎。个人用户可以创建节点端口规则、服务 ACL、发布 Service、使用 Route/Exit 等基础能力;默认界面用“谁可以访问”而不是“ACL/GrantRule”降低门槛。套餐限制应落在设备数量、托管流量、审计保留、SSO/SCIM、专属 NSGW 和 SLA,不通过取消个人用户的安全控制来制造升级理由。

#1.3 全局产品导航

NS App 面向使用和本机发布:

首页
├── 连接状态 / 当前 Network / Node IP
├── 设备
├── 服务
├── 发布服务
└── 设置
    ├── 连接与数据面
    ├── 互联网出口
    ├── DNS / 高级网络
    └── 诊断与更新

管理控制台面向组织治理:

Organization Switcher
├── Overview
├── Networks
│   ├── Nodes / Routes / DNS
│   ├── Services / Applications
│   ├── Access / Grants
│   ├── Capabilities / Activations
│   ├── Public Applications / Edge Auth
│   └── Gateways
├── People & Groups
├── Devices
├── Security & Posture
├── Audit
├── Integrations / API
└── Billing & Entitlements

账号可以属于多个 Organization/Network,但首版运行时只激活一个控制 Profile;切换入口放在账号与 Network 选择器中。

#1.4 易用性原则

  1. 先完成价值,再解释架构。 个人用户不看到 Organization、Realm、Profile ID、CIDR、GrantRule 等内部词;企业管理员需要时再展开;
  2. 一个动作只有一个主要结果。 “连接”负责建立当前 Network;“发布服务”负责创建本地声明;“允许访问”负责创建 Grant,不把三件事塞进一个表单;
  3. 默认值来自使用场景。 个人空间默认自己的设备互通;企业升级时预览并收紧,不要求用户从空白 ACL 开始;
  4. 状态说事实,不说推断。 “读取失败”“尚未授权”“节点离线”“服务无健康后端”分别显示,绝不都变成空列表;
  5. 错误必须带下一步。 权限不足指向管理员,系统权限缺失打开设置,网络冲突指出具体路由,服务失效提供编辑/停用/重试;
  6. 高级能力渐进展示。 普通员工首页只看连接、设备和服务;路由、Gateway、SCIM、策略版本只在相应角色的控制台出现;
  7. 可撤销且不丢配置。 断开不删除选择,停用不等于删除,删除前显示影响并提供恢复窗口;
  8. 首次成功目标不超过三分钟。 已安装 App 的前提下,登录、授权 TUN、连接、看到本机 Node IP 应在一个连续流程内完成。

NSIO Next 用户首次成功闭环

#2. 首次使用闭环

#2.1 个人用户

用户操作

  1. 登录后自动进入个人空间,不要求先选择产品版本;
  2. 确认设备显示名,例如 clark-mac;
  3. App 创建可恢复的 Enrollment Request,Personal Policy 自动批准后惰性取得短期 Grant;
  4. Grant commit 原子创建 Device 与 Node Membership;
  5. App 请求系统 VPN/TUN 权限;
  6. 点击“连接”;
  7. 在第二台设备用同一账号重复登录;
  8. 设备列表出现两台设备,用户点击“测试连接”或使用 ping clark-pc。

系统实现

  • NSD 事务性创建 Personal Organization、默认 Network、用户 Membership 和 user:self → nodes:owned 的个人模板;Device/Node Membership 只在 Enrollment Grant commit 事务中创建;
  • App 为 Request 生成 Staging Device Key;commit 后晋升为 Organization 专属 Device Key,并生成 Network 专属 Node/WireGuard key,私钥不离开设备;
  • NSD 分配 Node IP 和 Node DNS,编译最小 peer map 与双端 Grants;
  • App 启动 ns 的 L3 TUN,安装 Node 路由与 split DNS;
  • 两节点先探测直连,失败则自动使用基础 Relay。

成功状态

已连接 · Personal
此设备:clark-mac · 100.80.12.34
设备:2 台 · 1 台可达

失败与收尾

  • VPN 权限被拒绝:停在“需要系统网络权限”,提供重新授权,不创建假的已连接状态;
  • 第二台设备离线:显示“离线”,不显示“无权限”;
  • peer map 读取失败:保留最后未过期配置并显示控制面错误,不返回空设备列表;
  • 用户退出登录:先断开并撤销本机控制会话;是否删除 Device 由用户明确选择。

#2.2 从个人空间原地升级为团队或企业

个人与企业不是两套数据模型,也不要求用户把设备搬到另一个空间。Personal 配额内邀请成员是正常协作流程,不会自动启用付费试用或改变 entitlement。只有用户主动点击“升级团队”、明确确认试用,或尝试启用当前 entitlement 不包含的 SSO/SCIM 等企业能力时,才进入升级向导。

批量导入用户、绑定企业域名等动作应先按当前 entitlement 预检:当前能力和配额足够时直接完成;不足时展示缺少的能力、预计影响和试用期限,由用户明确确认后再启用试用。推荐升级可以提示,但不能因为邀请第一个成员或填写企业域名而静默改变商业状态。

向导只收集新增的组织信息:

  1. 组织展示:把“我的空间”改为公司/团队名称;
  2. 管理边界:确认 Owner、账单联系人和恢复管理员;
  3. 安全模板:保留个人互通模板、切换小团队协作,或启用企业默认拒绝;
  4. 成员加入:发邀请、批量导入或配置 SSO;
  5. 套餐:展示价格、配额、到期行为和影响预览;用户明确确认后才启用有期限的团队/企业试用 entitlement;
  6. 确认影响:列出哪些现有个人 Grants 会保留、收紧或需要确认。

升级保持同一个 Organization ID、默认 Network ID、Device、Node Membership、Node IP、Service ID、域名和审计历史。安全模板切换使用版本化 Grant 变更并先预览影响,不能因为“升级企业版”自动扩大或突然切断已有访问。

用户仍可从空间选择器“新建独立 Organization”,但它只用于确实需要账单、法律实体或安全边界隔离的场景,不是个人转企业的必经路径。

#2.3 接受邀请或企业 SSO

邀请方式

  • 邮箱邀请包含一次性、短期 invite token;
  • 用户登录后看到组织名称、将加入的 Network、角色和到期时间;
  • 接受后创建 Organization User 和 Network Principal Membership;
  • 拒绝或过期不泄漏其他成员、节点和服务。

企业 SSO

  1. 管理员验证企业域名并配置企业 OIDC;上游若使用 SAML,由客户 Identity Authority 负责桥接,不进入 NS App 或 Enrollment 协议;
  2. 员工点击“使用企业 SSO”后才输入企业邮箱或组织域名;Directory API 只返回“继续使用企业登录”、未配置或可重试故障,不公开组织内部信息;
  3. IdP 登录完成后,NSD 根据 SCIM/组映射创建或更新 User、Group 和 Membership;
  4. Device 仍需注册、审批或满足 MDM/posture,登录成功不等于设备自动可信;
  5. 普通退出登录只撤会话;SCIM deprovision 或管理员确认离职才撤销该 Organization Membership,并在默认 5 分钟 SLA 内让 peer 授权收敛;
  6. 公司资产 Device 保留并等待重新指派,不因员工离职被删除。

#2.4 无人值守服务器

管理员在目标 Network 创建 Enrollment Key,必须限定:到期、使用次数、标签、允许能力和是否需要审批。

ns up --enrollment-key nsk_... \
  --name prod-api-01 \
  --tags server,prod \
  --capabilities endpoint,service-host

节点生成自己的长期 key,用 Enrollment Key 只完成一次注册。服务器不能通过命令行增加 key 未允许的 tag、route、service_host 或 exit_provider 能力。注册后 key 可立即删除,节点不受影响;节点撤销后不能靠旧 key 恢复身份。

#3. Node IP、Service VIP 与域名闭环

#3.1 两套名称解决两个不同问题

对象目标地址默认名称适用场景
NodeNode IP<node>.<network>.<org>.node.ns.ioPing、SSH、RDP、文件共享、任意被授权端口
ServiceService VIP<service>.<network>.<org>.svc.ns.io稳定业务身份、服务级 ACL、HA、多后端

例子:

clark-pc.personal.clark.node.ns.io  → 100.80.12.35
git.dev.acme.svc.ns.io              → 100.112.8.9

.node.ns.io 和 .svc.ns.io 是目标逻辑命名空间,由 NS App 的 split DNS 解析,不要求公开互联网 DNS 暴露内部地址。私有部署可以使用客户自己的受控后缀;协议携带的是稳定对象 ID 和完整域名,不把 ns.io 硬编码成唯一可能后缀。

#3.2 短名称

  • 当前主 Network 内可直接使用 clark-pc、git;
  • Node 与 Service 同名时,短名记录必须 withheld,DNS 不得随机解析到其中一个对象;UI 同时显示类型并提供各自完整 FQDN,命令行必须使用 FQDN 消歧;
  • 目标 Network 内出现同名时不随机选择,短名记录 withheld,并提示使用完整 FQDN;
  • 改名后旧名称保留有限期 alias,alias 到期前在控制台显示影响范围;
  • 未获得资源 Grant 的用户不收到该 DNS 记录,不能靠 DNS 枚举目录。

#3.3 自定义域名

自定义域名有两种完全不同的模式:

  1. 内部访问域名:例如 git.acme.com。已连接且获授权的设备通过 split DNS 得到 Service VIP;未连接设备继续使用公共 DNS 或解析失败;
  2. 公网入口域名:公共 DNS 指向 NSGW Public Ingress,由 NSGW 终结 TLS/OIDC/WAF 后转到被授权 Service。

TUN 模式不要求 HTTP Proxy 才能支持内部自定义域名。split DNS 返回 Service VIP,原始 TCP/TLS 流量经 TUN 到 Service Endpoint,SNI 和 Host 保持不变。Next 在明确支持的平台也可以提供本地 L4 Proxy 模式,由 PAC 把匹配域名送到本机代理。

当访问域名与远端 backend 域名相同,连接器解析 backend 时必须使用未被 NS split DNS 覆盖的 origin resolver 或固定 origin 记录,避免把请求再次解析回 Service VIP 形成环路。

#3.4 地址和名称的权威

  • NSD 是 Next Node IP、Service VIP、canonical Node/Service name 的分配权威;
  • 节点本地 manifest 是“这个后端是否允许被发布”的权威;
  • 客户端只缓存 DNS/VIP 投影,不自行选择一个地址上传为全局事实;
  • Next 首次创建 Service 时由 NSD 分配 canonical name 和 Service VIP;客户端不得上传自选 VIP 作为全局权威。

#4. 访问节点的完整闭环

#4.1 用户看到什么

设备页只展示用户有权知道的节点:名称、所有者、OS、在线状态、Node IP、Node DNS 和允许的常用动作。未授权节点不显示为灰色诱饵。

clark-pc
在线 · Windows · 100.80.12.35
可用:Ping · 远程桌面 · SSH

常用动作不是根据端口扫描猜出来的,而是由 Node Grant、目标节点声明的能力和实时状态共同决定。用户仍可在终端直接访问被授权端口。

#4.2 用户操作

  1. App 首页点击“连接”;
  2. 在“设备”选择目标,点击 Ping/SSH/RDP,或复制 Node 名称;
  3. 终端也可执行 ping clark-pc、ssh clark-pc;
  4. 若一个短名在多 Network 冲突,App 自动使用完整 Node FQDN,终端提示可复制的完整名称。

#4.3 控制与数据实现

用户输入 Node 名称
  → 本机 split DNS 查询
  → 只在授权 netmap 中查到 Node IP
  → OS 路由把目标 Node IP 送入 NS TUN
  → 源节点执行出站 GrantRule
  → 直连 WireGuard;失败则 Relay
  → 目标节点验证 peer、epoch、目的端口和入站 GrantRule
  → 包注入目标 TUN / 本机协议栈
  → 目标应用收到原始 L3/L4 连接

NSD 下发 netmap + grants + dns snapshot/delta(各自 schema_version=1),但不承载包。源端允许不是最终许可,目标端仍执行入站规则,防止过期配置或修改过的客户端绕过。

#4.4 Node Grant 的产品表达

管理员不需要手写 JSON。创建规则使用一句可读表单:

允许 [开发组] 访问 [标签:开发服务器]
协议 [TCP] 端口 [22, 3389]
条件 [受管设备]

个人模板等价于“允许 user:self 访问 nodes:owned 的任意端口”,但底层仍是 Grant。个人用户可以在“访问权限”高级设置中把它收紧到节点、协议和端口,也能为分享对象创建最小授权。企业默认不创建横向 Node Grant,员工只看到服务目录。

#4.5 状态、失败与关闭

状态用户文案可执行动作
authorized + online在线,可连接打开/复制名称/诊断
authorized + offline节点离线查看上次在线、通知所有者
no Grant不出现在普通列表管理员策略模拟可看到拒绝原因
control read failed暂时无法刷新设备重试;保留最后未过期数据
route conflict无法安装到该节点的路由查看冲突 Network/CIDR
handshake failed无法建立安全通道网络诊断、Relay 状态、重试

断开 NS 只移除本机临时路由、DNS 和会话,不删除 Device、Membership 或 Node IP。管理员撤销 Membership 后,DNS、peer map 和入站许可在撤销 SLA 内同时消失,并写审计事件。

Node 与 Service 两条完整访问闭环

#5. 发布服务的完整闭环

#5.1 谁是发布权威

服务发布采用两层权威的交集:

  • 节点本地 ns 决定“这台机器允许暴露哪个本地/远程后端”;
  • NSD 决定“这个声明是否进入目录、叫什么、谁能访问、向谁投影”。

服务由 ns 上报。NS App、CLI 和原生 services.toml 都编辑同一份 Next Service Manifest,再由 ns 签名上报。NSD 不能单方面把员工笔记本任意端口变成服务。

#5.2 App 发布向导

用户进入“发布服务”后按三步完成,不展示协议内部字段:

第一步:选择来源

  • 本机端口,例如 127.0.0.1:8080;
  • 本机可达地址,例如 192.168.1.20:22;
  • 远程域名/URL,例如 https://xsaz.s8nw56.com;
  • 从本机 Next services.toml 选择已声明的后端。

App 可以在用户点击“发现本机服务”后扫描监听端口,但首版不后台自动扫描,更不自动发布。

第二步:定义服务

  • 显示名,例如“研发 Git”;
  • 服务短名,例如 git;
  • 协议 TCP/UDP/HTTP/HTTPS;
  • 外部访问端口;
  • 健康检查和可选自定义域名;
  • 是否申请进入 Organization 服务目录。

第三步:确认边界

明确展示“哪些 Network、哪个本机后端、NSD 管理员是否需要审批”。点击发布后先写本地 manifest,再上报;本地写入失败时不在 NSD 留下 active Service。

#5.3 上报与审批状态机

local_draft
  → local_validated
  → reported
  → pending_approval | active
  → degraded
  → disabled | retired
  1. ns 验证后端格式、协议、端口、禁止范围和本地 publish capability;
  2. ns 用 Node key 上报 service.declare 命令,包含本地 manifest revision 和健康材料;
  3. NSD 校验 Node Membership、service_host capability、名称冲突和 entitlement;
  4. 按 Network 策略自动批准或进入 pending;
  5. NSD 创建稳定 Service ID,集中分配 Service VIP 和 canonical name;
  6. 管理员添加或选择 Grant;
  7. NSD 只向获授权消费者下发 services + dns + grants snapshot/delta;
  8. 发布节点收到 acceptance/rejection,App 显示准确状态和原因。

#5.4 NSD 能不能下发服务映射

可以下发发布请求或受管期望配置,但不能无条件强制发布:

节点类型NSD 下发行为节点处理
用户设备publication.requestApp 弹出请求,用户接受后写本地 manifest;拒绝/过期可审计
普通服务器请求待本地 CLI/Admin 接受ns service request list/accept/reject
受管服务器下发 scoped desired manifest仅在注册时派生、节点本地仍有效的 ManagedConfigAuthorization 范围内自动接受
超出预授权范围拒绝不创建 endpoint,返回 local_policy_denied

Enrollment Key 只在注册时证明一次性加入权限。受管服务器会把其允许范围派生为节点本地的 ManagedConfigAuthorization,记录 Organization/Network、管理签名方、允许资源类型与范围、revision 和撤销状态;desired manifest 每次到达都必须重新校验这份本地授权,不能继续拿已消费或已过期的 Enrollment Key 当永久授权。

节点所有者可以执行“停止受管配置”:

  1. 本地撤销 ManagedConfigAuthorization 并写入不可回退的 revision;
  2. 已经接受的本地 manifest 默认冻结为当前版本,不因撤销管理权被远程静默删除;
  3. 后续 desired manifest 回落为普通 publication.request,必须由 App/CLI 明确接受;
  4. 用户可另选“停止受管配置并停用受管服务”,该动作先展示受影响 Service/Route,再本地停用;
  5. NSD 收到撤销证明后更新节点状态并记录 actor、scope、旧/新 revision 和结果,管理员不能用旧 revision 恢复管理权。

管理员可以随时在 NSD 禁用 Service 或撤销 Grant,因为这是远端可达性;但删除节点本地 manifest 需要节点所有者或当前有效的受管配置权限。远端授权永远不能超过本地同意。

#5.5 远程 URL 和 IP 白名单服务

节点可以作为连接器发布它能够访问的远程后端,例如 https://xsaz.s8nw56.com:

  1. 在靠近目标、且公网 IP 已加入目标白名单的服务器上运行 ns;
  2. 本地 manifest 声明 HTTPS backend 和 origin resolver;
  3. NSD 把它创建为普通 Service/Endpoint,并按 Grant 授权;
  4. 用户访问 Service 域名或内部自定义域名;
  5. 流量先到连接器节点,再由该节点以自己的网络出口访问目标;
  6. 目标网站看到的是连接器服务器公网 IP,不是用户笔记本公网 IP。

这不要求额外 NSGW。需要高可用、固定企业出口、托管 IP 或审计 SLA 时,才使用 Gateway Egress/App Connector 增值能力。

#5.6 服务修改、停用和删除

  • 修改 backend:先创建新 local revision、健康通过,再让 NSD 切换 Endpoint;失败保留旧 revision;
  • 暂停发布:本地 endpoint 变 disabled,Service 可以保留名称和 Grant,消费者看到“当前无可用后端”;
  • 管理员禁用:停止投影,不删除本地 manifest;
  • 删除 Service:先显示自定义域名、Grants、Ingress、消费者和审计影响;默认进入 retired 保留期,再释放名称/VIP;
  • 删除节点:Service 有其他 Endpoint 时继续;最后一个 Endpoint 删除后 Service 进入 degraded,不伪装成读取失败。

#6. 访问服务的完整闭环

#6.1 用户体验

服务页是被授权的应用目录,不是全 Organization 服务清单:

研发 Git                         在线
Web · 内部 · git.dev.acme.svc.ns.io
                                        [打开]

生产 SSH                        在线
TCP :22 · ssh-prod.dev.acme.svc.ns.io
                                        [复制地址]

Web 服务点击“打开”;TCP/UDP 服务显示适合的命令或一键动作。Gateway Egress 服务用明显的“网关出网”标签,但仍保持相同 item 布局和筛选逻辑。筛选使用单选菜单:协议、服务类型、状态;选择后筛选值直接显示在控件上。

#6.2 数据路径

应用访问 Service 名称 / 自定义域名
  → split DNS 返回 Service VIP
  → TUN 根据 Service VIP + protocol + port 命中服务路由
  → 本机验证 Service Grant 与 projection revision
  → 选择健康 Service Endpoint
  → 直连或 Relay 到发布节点 / NSGW
  → 发布节点再次验证 Service ID、消费者主体和端口
  → 转发到本地或远程 backend

Service Grant 与 Node Grant 独立。用户可以访问 git Service,但没有权利访问承载节点的其他端口;管理员也可以完全关闭横向 L3,只保留服务目录。

#6.3 本地 Proxy 路径

纯 L4 或无 TUN 模式下:

浏览器 / 应用
  → PAC 或手工 Proxy 127.0.0.1
  → NS 本地代理读取原始域名
  → 授权 Service 路由
  → WG/WSS/Relay
  → Service Endpoint

PAC 只是告诉系统“哪些域名走本地代理”,不包含访问权限。真正授权仍由 services/grants 投影和目标端校验执行。Next 的 L3 默认 TUN;Proxy 是 Next 自己的可选服务数据面,不是旧产品兼容层。

#6.4 服务状态不能混淆

事实用户状态
有 Grant 且至少一个健康 Endpoint在线
有 Grant,Endpoint 全离线/健康失败暂无可用后端
Service 被管理员 disabled已停用
Grant 被撤销从普通用户目录移除;管理员可见“未授权”
NSD/存储读取失败暂时无法刷新服务,不显示空目录
DNS/路由尚未安装正在准备访问路径
协议版本无法解析客户端需要更新

#7. 用户、用户组、Network 与访问权限闭环

#7.1 添加成员

组织管理员有四个入口:单个邀请、批量粘贴、CSV 导入、SCIM 同步。批量导入每行包含邮箱、显示名和用户组;组不存在时在预览中列出并要求一次明确确认后创建。

上传/粘贴
  → 服务端解析与去重
  → 预览新增用户、已有用户、待建组、错误、配额
  → 管理员确认具体 digest + 待建组清单
  → 事务提交
  → 发送邀请 / 写审计

重复邮箱首行生效并标记;同 Organization 已存在用户不重复创建;跨 Organization 不泄漏归属,只返回不可用。预览后数据变化导致 digest 不同,提交返回“预览已变化”,要求重新确认。

#7.2 用户组与 Network Membership

Group 是 Organization 级身份集合,但不会自动进入所有 Network:

  1. 在 People & Groups 创建或同步 Group;
  2. 在目标 Network 的 Members 中分配 User/Group,并选择 Member/Admin/Auditor;
  3. Membership 只决定可见与管理边界;
  4. 再用“访问权限”创建 Node/Service/Route/Exit Grant;
  5. 移除 Group 的 Network Membership 会使该 Group 在该 Network 的 Grants 失去主体,不影响其在其他 Network 的身份。

UI 必须分开“加入网络”和“可以访问什么”,避免管理员误以为把员工加进 Network 就已全互通。

#7.3 创建访问规则

规则向导使用自然语言四步:

  1. 谁:用户、用户组、Machine Principal、标签或本人;
  2. 访问什么:节点、服务、子网路由、出口;
  3. 做什么:连接、调用、使用路由、使用出口;
  4. 从哪里/什么条件:具体设备、受管状态、协议/端口、姿态、时间、来源 Network。

保存前展示影响模拟:新增可达关系、失去的访问、受影响设备数和冲突。发布后显示 config revision、投影进度和失败节点。读取/编译失败不能发布一个空 Grant 集合。

发布能力、PublicApplication 访客认证和管理角色不在这个向导里。它们分别进入 Capability、Public Applications 和 Roles 页面,避免管理员误以为“允许访问一个服务”同时允许节点发布它或把它暴露到公网。

#7.4 个人用户的 ACL

个人空间默认使用“我的设备互通”模板,让首次体验简单;用户仍能打开“访问权限”进行完整控制:

  • 只让 Mac 访问 Windows 的 RDP;
  • 分享 NAS 的 445 给家庭成员;
  • 允许朋友访问一个 Service,但不访问承载节点;
  • 允许自己的手机使用一个 Exit;
  • 为临时分享设置到期时间。

邀请第一个成员并不会自动扩大个人模板,也不会自动进入付费试用。用户之后明确进入升级向导时,向导必须把 user:self 规则与新成员规则分开确认。

#7.5 撤销

  • 删除 User:先暂停登录,再显示其 Device、Service、Route、Share 和 ownership 影响;
  • 移出 Group:只撤销由该 Group 获得的权限;其他直接 Grant 保留;
  • disable GrantSet:停止新租约并推送撤销,不删除审计历史;
  • 删除 Network:必须先停用 Route/Exit/Ingress,进入保留期后释放地址和名称;
  • 所有撤销显示预计生效时间,超出 SLA 产生告警。

#8. Device 与 Node 生命周期闭环

#8.1 Device 和 Membership

Device 表示真实安装;Node Membership 表示它在某个 Network 的身份。用户在设备页执行的动作要明确作用范围:

动作作用
断开只停止当前本机运行时,不删除 Device/Membership
从 Network 移除撤销一个 Node Membership,其他 Network 不受影响
隔离设备所有 Membership 进入 quarantined,只保留控制/修复路径
撤销设备吊销 Device key 和全部 Membership
删除本机数据本地退出并删除 key,需要系统确认,不替管理员删除服务端审计

#8.2 审批与姿态

个人设备默认由本人自动批准;企业可要求管理员批准或 MDM 证明。姿态包含 OS、版本、磁盘加密、锁屏、EDR 等结论,敏感原始数据尽量留在设备或姿态提供方。

姿态不满足时显示“设备需要修复”及具体动作,不简单显示“无权限”。隔离状态仍允许访问更新、认证和企业修复端点,修复成功后重新评估。

#8.3 重命名、换机和重装

  • 重命名只改展示名和 DNS alias,不改变 Device/Node ID;
  • 换机创建新 Device,不复制私钥;管理员可转移 Service ownership;
  • 重装默认视为新 Device,若要恢复必须使用一次性恢复流程并撤销旧 key;
  • Node IP 在保留期内不立即复用,防止旧 DNS、ACL 或日志指向新设备。

#9. Network、子网路由与应用连接闭环

#9.1 创建和管理 Network

个人空间自动有一个 Personal Network。团队通常沿用该 Network 原地升级;只有开发/生产、客户隔离或地址域确实不同才创建第二个 Network。

创建 Network 向导:名称 → 地址池/自动分配 → DNS slug → 安全模板 → 管理员 → 完成。地址与当前设备已有系统路由重叠时在连接阶段 fail-closed 并指出冲突 CIDR。

#9.2 Subnet Router

节点本地声明 CIDR 和能力申请
  → CapabilityPolicy 校验申请资格与最大前缀
  → CapabilityActivation 逐实例批准、占配额、写审计、签 Lease
  → ns 上报 route.advertisement
  → 管理员审批并创建 Route
  → 管理员创建 use-route Grant
  → 授权客户端收到 routes snapshot/delta 并安装 TUN 路由
  → 发布节点执行转发与源策略

节点不能仅靠 Enrollment Key 或 CapabilityPolicy 自行发布任意公司网段;key/policy 只设申请上限,实际能力仍要经过同一个 Activation 事务。自动批准也占相同 Managed Resource 配额并产生相同审计。路由重叠、发布节点离线、读取失败分别显示。撤销时先停止新流量并移除客户端路由,再关闭发布端转发。

授权是双端的:客户端只得到自己可用 Route 和签名 RouteAccessCredential,Connector/Router 只得到“哪些来源可到哪些精确目的地、协议和端口”的白名单。Connector 本地验签和校验实际目标,不能向 NSD 逐流查询,也不能因自己位于内网就转发到 Route 之外。

策略变化按 generation 切换。新增权限可在有界窗口平滑重叠;收紧权限默认 security_first,先 staging/ACK Connector 再按 activation epoch 切客户端,未准备的 Connector 移出候选,宁可短暂 fail-closed。选择 bounded_drain 时,UI 必须显示旧权限最晚失效时间;新旧 generation 各自使用自己的目的地集合,永远不做 union。

#9.3 App Connector

App Connector 面向域名集合,不等于开放整段网络:

  1. 管理员创建 Application Route,填写域名/通配后缀和连接器节点;
  2. 连接器本地接受,或请求落在节点本地有效的 ManagedConfigAuthorization 范围内;
  3. 管理员给用户/组添加 use-route Grant;
  4. 客户端 split DNS/域名路由只捕获已授权域名;
  5. 连接器使用 origin DNS 解析真实目标并从其网络访问;
  6. 用户看到应用名称,不需要知道连接器 IP。

动态域名解析出的 IP 必须带短租约,并防止解析到 loopback、link-local、metadata service 或未允许私网范围。域名读取失败不退化成捕获整个默认路由。

Domain Route 只能保证当前解析 IP 的 best-effort L3 捕获,共享 CDN/多租户 IP 可能扩大范围,页面必须展示当前解析集和冲突。需要严格 Host/SNI/path 的应用应创建 DomainService/Gateway Egress,而不是把 Domain Route 标成严格应用级访问。

#10. Relay 与 NSGW 能力闭环

#10.1 基础 Relay

用户不需要选择 Relay。ns 自动按局域网直连 → UDP 打洞 → 基础 Relay → WSS/TLS Relay 的顺序建立路径。首页只显示“直连”或“经中继”,诊断页才展示区域、延迟、候选和失败原因。

基础 Relay 只收到短期 RelayRouteLease、轮换 opaque route/session ID 和两端密文,不收到稳定 Node/Membership/WG 身份、Service 目录或企业边缘配置。Relay 不可用时自动换区域;全部 Relay 不可用且无法直连时显示“安全通道无法建立”,不能回退到公网直连目标业务端口。直连、Relay 和 WSS 切换不改变 Node IP 或系统 TUN MTU。

#10.2 Gateway Exit

Gateway Exit 是用户设备把公网 IPv4 或指定 CIDR 交给企业出口,不是普通 Service。

管理员准备

  1. NSGW 上报 enabled Exit Profile、scope、健康和运行材料;
  2. 管理员在 Network 中把具体 gateway/profile 授权给 User/Group;
  3. NSD 只向该用户下发 authorized candidates;普通 gateway roster 仍可用于组网,但不直接作为出口列表。

用户交互

  1. 设置 → 打开“互联网出口”;该意图会把数据面联动为 TUN;
  2. 点击连接。没有已保存选择时,先建立真实的标准 TUN 连接,私网节点和服务已经可用;
  3. App 显示“已连接,正在获取已授权出口”,候选到达后弹出单选列表;
  4. 用户选择出口并确认;App 写入完整 ExitConfig,再重启为 Exit 模式;
  5. 首页显示“已连接 · 互联网出口 · 香港网关”,IPv6 若由外部 VPN 管理则明确显示未经过公司出口;
  6. 断开不清除选择;下次直接使用 daemon 中的权威配置启动;
  7. 更换网关:已连接时从设置点击当前网关,选择新候选并明确重连;
  8. 不再使用:关闭设置开关,以标准连接重启,但保留上次选择供以后使用。

失败分流

  • no_authorized_candidates:确定未授权。关闭用户偏好并恢复原数据面,明确提示联系管理员;
  • candidates_not_ready:候选尚未到达,保持连接和出口意图,允许取消/重试;
  • read_failed:未知故障,不伪装成未授权;
  • 保存选择失效但尚未捕获:展示最新候选并让用户重选;
  • Exit 已启动且 capture ready、projection 失败:保持范围内流量阻断,提供“重新选择出口”和“关闭出口并恢复标准连接”,第二个必须由用户明确点击;
  • capture 未形成:只说“出口范围内流量当前未经过公司出口”,不虚构已经阻断;
  • 外部 VPN 占有 IPv6:按策略 fail-closed 或 external_unmanaged,状态必须说明 IPv6 去向。

#10.3 Gateway Egress

Gateway Egress 是一个特定 TCP/UDP 服务通过网关访问,不接管用户默认路由:

  1. NSGW 声明 Egress capability 和本地/远端目标;
  2. NSD 创建或投影带 backend=gateway_egress 的 Service;
  3. 管理员为具体用户/组添加 Service Grant;
  4. 用户在服务目录看到“网关出网”标签,访问方式与其他 Service 相同;
  5. 客户端只把该 Service VIP/端口和 ServiceFlowCredential 送到网关;
  6. NSGW 作为 Service publisher 本地校验 credential、Service、目标 allowlist 和 projection digest,再做 NAT/代理并连接目标;建流不回查 NSD。

用户不需要开启 Gateway Exit。Egress 服务不可用只影响该 Service,不应让整个 TUN 或其他 L4 Service 断开。

#10.4 Public Ingress

Public Ingress 把一个已存在、已获本地同意的 Service 暴露给外部:

  1. 发布者先完成 Service 发布;
  2. 管理员在 Service 详情点击“创建公网入口”,创建 PublicApplication,选择域名/path、EdgeAuthPolicy、证书、WAF/限流和 NSGW;
  3. 认证明确选择 OIDC、API Key、Service Credential、Signed URL、mTLS 或 Anonymous;Anonymous 仍执行 TLS/WAF/限流/审计;
  4. NSD 创建 IngressBindingLease,不允许填写一个绕过 Service ID 的任意内网后端;
  5. DNS 验证与证书就绪后,NSD 向指定 NSGW 下发最小 Service Endpoint 与 Edge policy;
  6. 外部请求到 NSGW,完成 EdgeAuthPolicy/WAF;访客形成 EdgeIdentity,但不加入 Network;NSGW 用受限 Gateway identity、IngressBackendCredential 和最小 publisher projection 经 ServiceFlow 访问 Endpoint;
  7. 发布节点仍本地验证 Binding、Service、Endpoint、generation/digest 和本地 Manifest,不向 NSD 逐流查询;
  8. 停用入口先停止新公网请求,不删除内部 Service。

入口状态分为 DNS 待验证、证书签发中、认证策略就绪、Binding 已投影、在线、后端不可用、配置读取失败和已停用,不能只显示一个绿色开关。Service 详情同时显示“内部访问”和“公网入口”两条独立策略,并明确提示:收紧内部 AccessGrant 不会自动收紧 PublicApplication。

安全撤销必须处理在途长连接。管理员可以按应用、策略版本、Binding、EdgeIdentity、API/Service Credential 或 IdP session 踢除;NSGW 在 SLA 内主动关闭 HTTP、WebSocket、gRPC、SSE/raw stream,并返回协议可解释的 401/403/1008/UNAUTHENTICATED 等结果。策略读取失败是 503,后端不可用是 502,不能冒充未授权。

#10.5 固定来源 IP 与受白名单应用

需要让第三方 SaaS 只接受固定 IP 时,管理员选择 Gateway Egress 或 App Connector + NSGW 固定出口。第三方白名单填写的是 NSGW/连接器的公网出口 IP,不是员工电脑公网 IP,也不是 Node IP、Service VIP 或 WireGuard endpoint。

#11. 跨组织分享闭环

首版优先分享 Service:

  1. 资源方管理员在 Service 点击“分享给外部组织”,填写接收方、动作和到期;
  2. 系统生成不可枚举的 ShareOffer,向接收方管理员发送邀请;
  3. 接收方管理员接受并选择本地 User/Group,以及 posture 条件;
  4. 两边 NSD 建立 federation trust,权限取资源方 Grant、ShareOffer、接收方 Binding 和姿态交集;
  5. 接收方用户的服务目录只出现该 Service 的最小信息;
  6. 任一方撤销后停止续租,在撤销 SLA 内不可访问;
  7. 两边审计同一个 opaque share ID,但不复制对方完整目录。

分享失败时区分邀请过期、对方拒绝、federation key 错误、资源已退休和策略读取失败。跨组织 Node 分享和 Network 路由不随 Service 分享自动开启。

#12. 套餐、试用与升级闭环

#12.1 个人到企业是同一空间原地成长

个人空间
  → Personal 配额内邀请成员(不改变套餐)
  → 用户明确启用团队试用
  → 配置组与访问权限
  → 绑定企业域名 / SSO
  → Team / Enterprise entitlement

Organization、Network、Device、Node IP、Service、Grant 和审计 ID 全程不变。升级不是导出/导入,也不要求用户切换到一个新空间。

#12.2 个人能力边界

个人用户使用完整的核心安全模型:L3 Node、L4 Service、访问权限、设备分享、基础 Route、社区 Relay,以及被授权时的 Exit/Egress。商业区分主要是数量、托管资源和治理:

  • 设备/成员/Service/流量配额;
  • 托管 Relay 区域和 SLA;
  • SSO/SCIM/Posture、长审计和 SIEM;
  • 专属 NSGW、固定 IP、WAF、数据地域和企业支持。

不通过“个人版没有 ACL”“个人版不能发布服务”来迫使升级。

#12.3 Entitlement 状态

  • 试用即将到期:提前提示受影响的新增操作;
  • 已超配额:允许查看、删除和降低资源,不允许继续新增;
  • entitlement 读取失败:明确系统错误,在 grace period 使用最后验证结果;
  • 试用结束:先展示影响并让客户选择需冻结的超额资源;已签发收费租约自然到期,托管能力收敛到当前有效 Personal entitlement,不把到期伪装成安全撤销;
  • 欠费、安全撤销和许可证到期分别处理,不能共用一个“无权限”。

#13. NS App 的连接与状态闭环

#13.1 首页只回答三个问题

  1. 我现在是否连接?
  2. 节点/服务是否可用?
  3. 我的流量是否使用了特殊路由或出口?
已连接 · Main
此设备:clark-mac · 100.80.12.34
路径:直连 1 · 中继 1
互联网出口:未启用

首页不展示 ACL 语法、Profile ID、WireGuard key、内部 TUN stack IP 或所有候选 endpoint。

#13.2 连接按钮的真实流程

正在认证
  → 正在注册设备
  → 正在读取 Network 配置
  → 正在创建 TUN
  → 正在安装 DNS 与路由
  → 正在建立安全路径
  → 已连接

进度来自运行时实际阶段,不使用定时器伪进度。标准连接成功但 Exit 尚未就绪时,应显示“已连接,私网服务可用;正在准备互联网出口”,不能隐藏真实可用状态。

#13.3 设置

  • L3 节点网络默认开启并联动 TUN;
  • “仅使用本地 Proxy 访问服务”放在高级设置,仅在平台与应用支持时出现;
  • 互联网出口是独立开关,不因开启 L3 自动启用;
  • Organization/Network 切换放账号页,普通用户不需要理解控制 Profile;
  • 命令行写过的非默认 Exit/DNS/route 设置在 App 中显示只读摘要,App 写入完整配置前必须读取并保留可表达字段;
  • 所有会触发重连的设置在确认前明确说明。

#13.4 错误消息结构

每个错误包含稳定 code、简短标题、事实说明、是否可重试、建议动作和诊断入口。UI 不解析英文字符串判断逻辑。

code 类型示例动作
auth/session重新登录
system_permission打开系统设置
no_authorized_resource联系管理员/打开访问权限
control_read_failed重试、查看服务状态
route_conflict展示冲突软件/Network/CIDR
runtime_incompatible更新 App/runtime
local_manifest_denied编辑本地发布范围
entitlement查看套餐或管理员处理

App 崩溃或 helper 失败后,ns doctor、日志导出和恢复标准连接必须在未连接状态也能使用。

#14. 管理控制台交互闭环

#14.1 Overview 不做装饰性仪表盘

Organization Overview 只展示管理员下一步需要处理的事实:待接受邀请、待批准设备、待批准 Service/Route、策略投影失败、Gateway 异常、试用/配额和高风险审计。每个数字可点击进入过滤后的真实列表。

#14.2 空状态必须可行动

页面空状态主动作
Members还没有其他成员邀请成员 / 批量导入 / 配置 SSO
Devices还没有设备下载 NS App / 复制服务器安装命令
Services还没有服务查看发布步骤 / 向受管节点发发布请求
Access仅有初始模板创建访问权限 / 从模板开始
Capabilities没有能力申请查看节点能力 / 创建策略
Public Applications没有公网应用从现有 Service 创建公网入口
Routes没有待批准路由查看 Subnet Router 配置
Gateways没有网关使用基础 Relay / 部署或购买 NSGW

读取失败不能渲染成上述空状态,必须显示错误、request ID 和重试。

#14.3 危险变更

删除 User、Device、Network、Service、Route、Gateway、AccessGrant、CapabilityActivation 或 PublicApplication 前,服务端生成影响预览并返回 digest。确认必须绑定这个 digest;提交时重新规划,不一致返回“影响已变化”。高风险变更支持二人审批、计划生效和 canary。

Capability 页面分别展示 Activation、Availability、Projection 和 Runtime。暂停说明“仍占用 1 个受管资源额度”,可选显式 auto_revoke_at;离线不改写暂停/授权;只有撤销释放额度。页面不得把这些轴合成一个 Active。

#15. 审计、通知与支持闭环

#15.1 审计事件

每个产品动作至少记录:Organization/Network、actor、action、resource ID、result、request ID、before/after revision、来源和时间。安全事件不得记录私钥、Enrollment Key 明文、完整业务 payload 或不必要的批量邮箱清单。

关键事件包括:登录、邀请、Device 注册/审批/撤销、Service 声明/批准/拒绝、Grant 发布/回滚、Route 批准、Exit 选择、Ingress 变更、Share 接受/撤销、entitlement 变化和管理员导出。

#15.2 通知

  • 用户需要处理:设备审批、发布请求、出口失效、邀请、姿态修复;
  • 管理员需要处理:待审批资源、策略投影失败、撤销超 SLA、Gateway/Relay 容量、配额;
  • 通知只提示一次并可追踪,不自动替用户开启出口、切数据面或接受分享;
  • 邮件/站内/Webhook 都引用稳定事件 ID,避免重复操作。

#15.3 诊断

App 诊断包包含脱敏版本、控制连接状态、TUN/DNS/route ownership、peer path、Service/Exit readiness 和最近错误码。不包含私钥、token、完整用户目录或业务内容。管理员控制台可以用 request ID 关联服务端审计,但不能直接读取终端隐私数据。

#16. 权威对象、接口与事件映射

下表是实现时的跨仓库契约。名称是目标语义,具体 URL 可在 API 设计阶段确定。

事件信封、幂等、revision、错误和能力协商统一遵守跨组件共享契约。具体组件实现见ns、Client、NSD和NSGW。

功能权威对象上行/命令NSD 处理下行事件数据面执行
登录/空间发现Account, OrganizationOIDC callback, Directory query会话、邀请、空间列表session/profileApp
Device 注册Devicedevice.register绑定 owner、姿态、审批device.statusApp/ns
加入 NetworkNode Membershipmembership.enroll分配 Node IP/key scopenetmap snapshot/deltans TUN/WG
Node ACLAccessGrantSet/Rulegrant publish编译 peer/port policygrants + netmap源/目标 ns
Service 发布Local Manifest + CapabilityActivation + Servicecapability request / service.declare资格、批准、配额、VIP/名称activation + services + dns发布/消费 ns
发布请求PublicationRequestadmin request / node accept校验本地接受或 managed scopepublication.request/status节点 ns/App
Service ACLAccessGrantSet/Rulegrant publish编译目录与路由services + grants双端 ns
Subnet RouteCapabilityActivation + Routecapability request / route.advertise配额、审批、双端授权、generationclient/connector routes客户端/路由节点
App ConnectorApplicationRoutedomains + connectorDNS 安全、授权routes + dnsns connector
RelayRelay leasepath candidates区域/租约选择gateways/netmapns ↔ Relay
Gateway ExitExit Profile/Grant/Selectionprofile report / selection候选授权、投影gateway candidates/readinessns + NSGW
Gateway EgressService + gateway backendgateway declarationService 投影与 ACLservices snapshot/deltans + NSGW
Public IngressPublicApplication + EdgeAuthPolicy + IngressBindingLeaseadmin create/revokeDNS/cert/WAF/auth/backendedge ingress configNSGW + ns
跨组织分享ShareOffer/Bindingoffer/accept/revoke双边交集、租约shared resource lease两边 NSD/ns
EntitlementSigned snapshotbilling/license updateAPI/配额/编译检查feature/quota statusNSD/NSGW;非客户端自报

#16.1 事件共同要求

所有下行事件包含稳定 deployment、Organization/Network 作用域、类型化目标(Device、Membership、Gateway 或 Client Session)、schema version、config revision、epoch、有效期和签名。Client 本地 Profile ID 不进入线协议。消费者必须:

  • 拒绝跨 Organization、Network 或目标类型/ID 重放;
  • 对未知必需字段或版本返回 typed incompatibility,不猜默认;
  • snapshot 与 delta 断档时请求完整 snapshot;
  • 不把一个 source 的 Grant、DNS 或 Gateway 候选扩大到另一个 source;
  • 持久化最后验证版本和来源,读取失败不覆盖为默认空对象。

#17. 各组件具体负责什么

#17.1 ns

  • Device/Node key、TUN/WG、DNS/Proxy、路径选择和本机恢复;
  • 本地 Service Manifest、Route/Capability 声明和健康;
  • 源端/目标端 Grant 执行;
  • Service VIP、Node IP、Route、Exit 的系统投影;
  • CLI、守护进程和 App FFI 使用同一 runtime,不各写一套策略。

#17.2 NS App

  • 登录、连接、系统权限、设备/服务目录、服务发布和设置;
  • 只把用户意图写给 runtime,不自行实现 supports_scope、ACL、路由冲突或授权算法;
  • 显示 runtime/NSD 的结构化状态,不从日志字符串猜结果;
  • 未连接时仍可查看诊断、修改安全设置和清理失败配置。

#17.3 NSD

  • Organization/Network/User/Group/Device/Membership/Service/Route/Grant/Share/Entitlement 权威;
  • 地址、名称、租约、审批、策略编译、签名分发和审计;
  • 接受节点声明但不能扩大节点本地发布上限;
  • 不承载业务流量,不保存节点私钥。

#17.4 NSGW / Relay

  • Relay capability 只转发端到端密文;
  • Ingress/Egress/Exit 各有独立 capability、租户配置、凭据和审计;
  • 不因为能 relay 就自动获得 Service 目录或 NAT 权限;
  • 托管能力校验 NSD 签发的短期 entitlement/capability lease。

#18. 分阶段实现顺序

每个阶段都交付可使用的纵向闭环,不以“数据库表建好了”作为退出条件。

跨仓库依赖、合并顺序、环境和 Definition of Done 见实施蓝图。

#M0:原生契约和安全护栏

  • 固定 Device/Node/Service/Grant/Route/Gateway ID 与 Next v1 schema;
  • 落地 Enrollment Request/Grant 两台状态机、组织隔离 Device Key、Entitlement head 和 Quota Reservation 契约;
  • 建立 ABI、事件、错误码和真实序列化契约测试;
  • 建立 L3、L4、Gateway Egress/Exit、Public Ingress 的 Next 原生回归矩阵。

验收:空数据库可完成首个 Organization、首个 Network 和首台 Device 注册;Next 不读取旧 NSIO 状态或连接旧协议端点。

#M1:统一 ns,先完成 L4 闭环

  • 从 Next v1 Capability 实现统一 ns 运行时,不建立消费端/发布端二进制角色;
  • 同一个 ns 和 App 既能访问 Service,也能发布 Service;
  • services.toml、App 和 CLI 统一进入 Local Manifest;
  • NSD publication request 与本地接受模型落地。

验收:一台用户电脑通过 App 发布本地 Web,另一台电脑被授权后打开;禁用 Grant、停发布、后端离线和读取失败状态全部准确。

#M2:统一账号与个人空间原地成长

  • Identity Authority、邮箱密码、Google、GitHub、企业 OIDC、Directory 和自动 Personal Organization/Network;WebAuthn 首版用于 MFA/step-up;
  • 系统浏览器 + PKCE、账号绑定/解绑、MFA assurance、按操作 step-up、会话轮换和分类撤销;
  • Device 注册、邀请、个人空间原地升级团队;
  • 用户组、批量导入、Membership 和访问权限向导。

验收:个人不进控制台完成首台设备;Google/GitHub 不要求先填邮箱;App 不接触密码;邀请成员不重建已有 Node/Service;普通 logout 不断数据面;SCIM 离职在 SLA 内收敛且公司 Device 保留。

#M3:基础 L3

  • 全平台 TUN/VPN、Node IP、Node DNS、双端 Grant;
  • endpoint discovery、STUN、直连、基础 Relay、WSS fallback;
  • 网络切换、冲突和恢复。

验收:两台设备在 LAN、普通 NAT、CGNAT、双 symmetric NAT 和 UDP 封锁下按名称互访;无 Grant 不可见不可达。

#M4:企业路由与应用

  • Subnet Router、App Connector、自定义域名;
  • SSO/SCIM/Posture、策略模拟/版本/审批;
  • 应用门户和跨组织 Service Share。

验收:企业关闭横向 L3,仅按组开放 Git Service 和一个 SaaS 域名;离职/撤销在 SLA 内生效。

#M5:NSGW 商业闭环

  • Managed Relay、Gateway Egress/Exit、Public Ingress;
  • 固定 IP、证书/WAF、区域、SLA、流量元数据;
  • entitlement 和自建/托管部署。

验收:不购买 NSGW 的个人仍可完成 L3/L4;购买后只出现被授权能力,关闭增值能力不破坏普通节点和服务访问。

#M6:可发行、可购买、可运营

  • 唯一 ns runtime、签名 artifact、灰度更新、企业托管和完整卸载;
  • desktop user-owned runtime 的单活跃 OS 用户、快速切换安全、本地 IPC 授权和 managed-device 边界;
  • Product Catalog、Quote/Order/Subscription、付款、发票和 Entitlement 激活;
  • 分服务 SLI/SLA、状态页、事故通报、支持和隐私激活漏斗;
  • Hosted/Self-hosted 备份、restore epoch、RPO/RTO 演练;
  • 数据导出、账号/Organization 删除、Legal Hold、Trust Center 和合规证据。

详细规格见发行生命周期、采购计费、服务运营、备份恢复和信任合规。这些工作与 M1-M5 并行启动,不能等网络功能完成后再补。

验收:五平台从安装到卸载不会破坏网络;首个付费订单可追到 entitlement;一次区域事故和一次空环境恢复完成;导出/删除/Hold 不互相误判。

#19. 必须执行的端到端验收旅程

#用户旅程成功标准
1新个人用户登录并连接首台设备可直接选择邮箱密码、Google 或 GitHub;三分钟内获得 Node IP/DNS,不进入控制台
2第二台设备登录可按短名 Ping/SSH;直连失败自动 Relay
3个人收紧 ACL只允许指定节点端口,其他端口双端拒绝
4个人邀请成员并升级团队Organization/Network/Node IP/Service ID 不变化
5企业邀请/SSO 员工登录成功但设备未批准时不可访问,状态准确
6服务器 Enrollmentkey 过期/超次数/越权 capability 被拒绝
7App 发布本地 Service本地确认、NSD 审批、授权消费、停用完整闭环
8NSD 请求用户设备发布用户拒绝后没有 Endpoint,且有审计
9受管服务器自动发布只在派生的本地 ManagedConfigAuthorization 范围内接受,越界 fail-closed;本地撤销后回落待确认且旧 revision 不能恢复
10访问远程白名单 SaaS目标看到连接器/NSGW 固定公网 IP
11Subnet RouterCapability 未批准不启用;批准+Grant 后双端可达;Connector 不能转发到 Route 外目标;撤销后移除
12自定义域名 TUN 访问split DNS 命中 Service VIP,TLS Host/SNI 保持
13Gateway Exit 首次选择标准连接可用、候选选择、重连、IP 改变、关闭恢复
14Exit 投影失败按 capture 事实阻断/提示,不自动静默本地直出
15Gateway Egress仅目标 Service 经网关,其他服务和公网不受影响
16Public Ingress只能绑定已有 Service;六种 Edge Auth 可执行;按身份撤销长连接;停入口不删除内部服务
17跨组织 Service Share双边确认、最小目录、任一方撤销生效
18NSD/存储读取失败显示故障并保留有效缓存,不出现假空列表
19Tailscale/企业 VPN 共存冲突具体可见,不抢外部 route,关闭 NS 可恢复
20设备/用户离职ownership 先转移,Membership/Grant 在 SLA 内撤销
21身份生命周期logout、解绑、SCIM 离职、Device 撤销结果各自准确;会话过期默认不断隧道
22App 与独立 ns 共存App/CLI 连接同一 daemon,升级不启动第二个 TUN/runtime
23客户端升级与卸载灰度可暂停;中断可恢复;卸载后 helper/route/DNS/driver 无残留且公网正常
24移动端商店发布entitlement/declaration、App 内披露、真机 VPN 和商店审核材料一致
25个人升级付费订单只扣一次,发票可查,entitlement 激活失败可对账且不重复扣款
26企业报价与降档Quote/SLA 受控;降档显示影响,不删除存量资源或伪装安全撤销
27托管区域故障客户端、状态页、支持和 SLA bucket 对同一服务/区域给出一致事实
28Hosted/Self-hosted 恢复从空环境恢复,旧授权/删除对象不复活,RPO/RTO 有真实记录
29导出、注销与 Legal Hold导出完整性可验证;Hold 只保留覆盖数据;删除失败不误报成功
30多 OS 用户与开机恢复B 无法看到或控制 A 的 runtime;切换到 B 前撤销 A 的系统网络投影;冷启动时 user-owned 等待 owner、managed-device 无人值守恢复;管理员 reset 不冒充远端 revoke
31Route 策略 generationadditive 无过宽窗口;restrictive 按 security-first/bounded-drain 精确收敛;新旧目的地不 union
32Capability 生命周期suspended 仍占额度、unavailable 不改授权、revoked 才释放且恢复需重新申请
33PolicyKernel 升级同地域 shadow diff、确认/canary、新 effective revision 与完整 provenance 可追踪

#20. 关键问题的直接答案

#用户先登录还是先创建 Organization?

先登录。系统自动给首次用户一个真实但 UI 称为“个人空间”的 Organization 和默认 Network。个人升级团队/企业在同一 Organization 内改变商业能力,不新建或重建资源;只有明确需要独立边界时才另建 Organization。

#登录前是否必须先填邮箱?

不必须。邮箱密码登录才填写邮箱和密码;Google、GitHub 直接进入各自流程;只有用户主动选择“企业 SSO”后,才输入企业邮箱或组织域名用于发现企业 IdP。App 始终打开系统浏览器,不接触密码。Passkey 主登录属于后续 Connector。

#个人用户能否使用 ACL 和完整能力?

能。个人默认用简单模板,但底层和企业使用同一 Grant 引擎,可以控制节点、端口、服务、分享、Route 和 Exit。套餐限制治理与托管资源,不移除基础安全能力。

#L3 默认是不是 TUN?

是。桌面和移动端默认 TUN/VPN API,Linux 服务器可选内核 WireGuard。Next 可选提供本地 Proxy 服务访问模式,但它不承担 L3 节点组网。

#如何访问另一个节点?有 ns.io 域名吗?

连接后使用 Node IP、短名或 <node>.<network>.<org>.node.ns.io。域名由按授权下发的 split DNS 解析,不公开泄漏节点目录。

#一台机器五个服务怎么命名?

机器只有一个 Node IP/Node 名;每个 Service 有独立 Service ID、Service VIP 和 <service>.<network>.<org>.svc.ns.io,因此可以做服务级 ACL 和多后端。

#发布服务还是由 ns 上报吗?

是。统一 ns 从本地 manifest 上报签名声明。NS App、CLI、services.toml 只是不同编辑入口,最终共用一份本地权威。

#NSD 能不能下发发布服务?

能下发发布请求或受管 desired manifest,但用户设备必须本地接受;受管服务器也只能在注册时派生且尚未被节点撤销的 ManagedConfigAuthorization 范围内自动接受。NSD 可以禁用远端可达性,不能凭空扩大本地发布范围。

#自定义域名必须用 Proxy 吗?

不必须。默认 TUN 通过 split DNS 把内部自定义域名解析到 Service VIP;Proxy/PAC 是平台支持时的可选服务数据面。公网访问使用 Public Ingress。

#L3 和 L4 会不会冲突?

不会共用授权语义。Node Grant 控制节点/端口,Service Grant 控制独立 Service;两者可以共用 TUN 和加密传输。企业可以关闭横向 L3 但继续开放 L4 Service。

#不买 NSGW 能不能使用?

能。基础 L3 使用直连和免费/社区 Relay,基础 L4 由节点发布。NSGW 增加区域/SLA、固定 IP、Ingress、Egress 和 Exit,不是基本连接开关。