迁移计划：ns 与 nsgw
状态：原迁移计划已批准；当前进度按 2026-10-20 同步的远端分支与验收记录更新，依赖 pin 与库发布补充至 2026-10-26，见 §4.1–§4.2。 M1、M4 与节点侧 Quick v2 已实现，真实 NSD / relay 已参与限定范围验收；M6 仍在推进，不能再概括为“NSD / nsgw 未开始”，也不能据局部通过宣称全部完成。R1 只达到开发完成条件，R3 按已批准的普通 Node 模型推进。本文原始 crate 清单及 M0–M9 是 2026-10-02 的迁移基线；现行推进边界见 §8 和 NSGW 新架构，不将历史实现或切换安排当作当前产品行为。
| 原则 | 做法 |
|---|---|
| 旁路构建，一次切换，切换后删除 | 新实现与旧实现并存于 main，由 cargo feature 或独立二进制隔离；每种协议只有一个切换版本；切换后的下一个版本删除旧代码 |
| 账户模式先换引擎，再换协议 | 先在协议不变的前提下把 tunnel-wg 换成 nsplane 引擎（可用现有回归与 live e2e 验证），再做地址与 relay 的不兼容切换。M4 实际按 ns 的决策 2026-10-03-account-mode-engine-only 直接删除了旧路径，没有保留运行时开关：产品尚未发布，两条路径只会让测试矩阵翻倍 |
| Quick 直接上 v2 | v1 的 quick-runtime 不移植到引擎上（那是一次性代码）；Quick 在引擎上直接实现 v2，切换时整体替换 |
| 协议只定义一次 | 线上类型先进 nsshared，ns 与 nsgw 都从它引入，用同一组测试向量 |
| 每一步可发布 | 每个里程碑结束时两个仓库的 main 都能通过各自的质量门并发布；没有长期分支 |
| 不保留兼容 | 按后续产品决定：新 ns 不读取、迁移或保留旧状态、身份、CLI / FFI 与状态 schema；旧的“Quick v1 只保留 I”安排已失效 |
2. 现状要点
Section titled “2. 现状要点”本节保留原始迁移基线及早期补注，当前进度以 §4.1 为准。
| 事实 | 影响 |
|---|---|
ns 仍用仓库内的 control、common、acl、tunnel-ws、telemetry 副本，与 nsshared 已分叉（nsshared §3：这些控制面 crate 随 M6 重新设计） | v2 协议 crate 已在 nsshared，ns 自 2026-10-04 起依赖它；这些 v1 控制面副本留在 ns，随 M6 由新的契约（nsshared 的 L8、L11）取代 |
ns 有两套数据面：tunnel-wg（18.5k 行）与 quick-runtime（31.6k 行），都基于 crates.io boringtun 0.7 | 两套都迁到 nsplane 引擎（M4、M5） |
nsgw 有两套 relay：nsgw-wg::relay（7.2k 行，mac1 分流 + NSD 配对表）加 nsgw-wss 的不透明 WSS 中继；以及 nsgw-quick-relay（34k 行，KNR1、/keynet/v1、/quick/v1、标记库、区域） | 新架构只有一个 relay 协议（v2 §8）：两套都换成 relay v2（D1） |
nsgw-wg::gateway_exit、gateway_egress 与 nsgw-routing 只处理 IPv4（代码里没有任何 Ipv6） | 网关侧直接改为 IPv6：wg0、ACL、路由、出口、Egress 与公网入口后端都按 node6 处理，不保留 IPv4 覆盖地址，也不做逐配对的 IPv4 分配（M6，D3） |
nsplane 第 1–5 阶段（packet、core、驱动、TUN、多传输与 PathPolicy、netstack、ACL、翻译）及其后续修复已于 2026-10-03 全部合入 | ns 的引擎迁移不再等待 nsplane（§4 依赖列中的 nsplane 阶段均已满足） |
libns（ns-ffi，20.6k 行）对外有 ABI 与 JSON schema 契约；Windows 原生 TUN 是发布门 | 引擎与地址切换都要走 just ns-ffi-contracts 与原生 smoke |
3. 每个 crate 去哪里
Section titled “3. 每个 crate 去哪里”本节保留原始 crate 迁移映射；后续决定覆盖的部分按现行计划执行。
3.1 ns
Section titled “3.1 ns”| 现有 | 去向 | 里程碑 |
|---|---|---|
control、common、acl、tunnel-ws、telemetry（仓库内副本） | 留在 ns，直到 M6 换成重新设计的控制契约（nsshared 的 L8、L11）；只属于节点的部分一直留在 ns。telemetry 中的 tracing 初始化可以先换成 nsshared-telemetry | M6 |
quick-wire（4.8k） | 由 nsshared 的 v2 协议 crate 取代（记录、派生、relay 报文 v2） | M1 建、M5 删 |
quick-pairing（0.6k） | 由 ns 的应用通道（配对是其上的应用）取代；nsshared 只提供 /rendezvous/v1 的信箱消息类型 | M1 建、M5 删 |
quick-runtime（31.6k） | 报文、分片、校验和、翻译、MTU、数据面 → nsplane（过滤器与引擎）；relay_client、transport → overlay 的 RelayClient 与路径阶梯；配对与持久化 → overlay 的 quick 来源；KeyBinding、轮换预约、续期 → 被 NodeRecord 取代，删除 | M3、M5 |
tunnel-wg（18.5k） | 设备循环、peer 表、UDP 批处理 → nsplane 引擎；relay、p2p、candidate_report、recovery_probe → overlay 的路径阶梯规则（实现 nsplane 的 PathPolicy）；node_l3 → nsplane ACL 过滤器的规则来源 | M4 |
netstack（3.0k） | nsplane-netstack | M4 |
nat（6.4k） | subnet_route、packet_nat 的翻译 → nsplane 翻译过滤器；router（服务解析）→ features/services；conntrack → nsplane 第 5 阶段 | M4（按原协议接入）、M6（v2 地址） |
proxy（0.8k） | edge（呈现层的 L4 转发辅助） | M7 |
ns：engine/、link_ladder、pair_transport、gateway_rtt | overlay（来源、合并对端表、阶梯规则）与 edge（TUN、DNS、代理的启动） | M3、M4 |
ns：addressing、dns/、short_dns | overlay 的地址派生 v2 与名字表（n.ns.io） | M6、M8 |
ns：config_store（单 active NSD）、current_context、space_* | 多来源配置：每个 NSD 的每个 Network 一个 nsd:<uuid>/<network> membership，同时运行（2026-10-12 已完成：engine::memberships，manifest schema v3，无 active NSD） | M6 |
ns：quick.rs、quick_ipc/、cli/quick/ | quick 来源与 v2 命令（v2 §13） | M5 |
ns：socks5_proxy、http_proxy、pac、engine/startup_{tun,dns,proxy} | edge，对所有来源可用 | M7 |
ns：subnet/、exit_*、provider_runtime、服务发布 | features/*，各自一个开关 | M7 |
ns-ffi | 保留；启动参数、状态与事件 schema 随 M5、M6 升版本 | M5、M6 |
secure-storage、posture、updater、privdrop、certstore、平台 crate | 不变 | — |
新增：crates/overlay（M3）、crates/edge（M7）、crates/ns/src/features/*（M7）。
3.2 nsgw
Section titled “3.2 nsgw”下表保留原始迁移映射。后续已批准的 G22 普通 Node 模型与 R3 阶段计划取代其中网关专用 carrier、旧 Exit / Egress 路径等安排；当前交付边界见 NSGW · 新架构设计，不能再按本表恢复旧路径。
| 现有 | 去向 | 里程碑 |
|---|---|---|
nsgw-quick-relay：core.rs、carrier.rs、service.rs | relay 报文 v2：NSR2、29 字节头、节点 ID 作 slot、删除 INTRO、/ns/v2 WSS 载体、能力宣告 | M2 |
nsgw-quick-relay：quick.rs（/quick/v1） | /rendezvous/v1（原草案 /quick/v2）：会合信箱 + 登记表（publish、lookup_node）+ 目录 v2 | M2 |
nsgw-quick-relay：store.rs（标记库） | v2 标记库（以 I 为键、记录标记）+ 登记表 + 信箱持久化；v1 库在切换时丢弃 | M2、M5 |
nsgw-quick-relay：region/ | 同一套 mesh、复制与 owner 栅栏，把 16 字节 slot 换成 12 字节、KeyBinding 标记换成记录标记；登记记录纳入复制 | M2 |
| relay 核心（上面四项中与进程无关的部分） | 抽成库 crate nsgw-relay，由 relay 二进制使用；账户 relay 是同一个二进制按 NSD 投影的名单准入，独立成进程，nsgw-server 不内嵌它（D1） | M2 抽取、M6 部署 |
nsgw-wg::relay（mac1 中继）与 register_source、探测集合 | 被 relay v2 取代后删除 | M6 切换、M9 删 |
nsgw-wss：不透明中继（/client?mode=wss-relay、/wss-relay、pending） | 被 relay v2 的 WSS 载体取代后删除 | M6 切换、M9 删 |
nsgw-wss：Exit 的 WSS 承载（/exit-wss/v1）及 gateway-exit-wss 令牌 | 被 relay v2 的 WSS 载体取代后删除：网关是一个节点，UDP 被阻断的节点经 relay 到达它（D1、D4）；节点侧的承载客户端（ns 的 exit_wss）与 NSD 的 exit_wss_token 签发一并删除 | M6 切换、M9 删 |
nsgw-wss：/relay connector（公网入口的 WSS 传输） | 不进入新线：公网入口到发布端只走 WireGuard，UDP 被阻断的发布端经 relay v2 的 WSS 载体到达；公网服务 tunnel 字段的 ws、wss、prefer_wss 取值在 M6 契约中重新定义或废弃；节点侧的 connector 客户端一并删除 | M6 切换、M9 删 |
nsgw-wss：节点侧 terminate（/client）、acl_gate、registry | /client 不保留（D4）；公网入口的 ACL 门移到 nsgw-routing，规则的主体与目的地改为节点 ID / node6；nsgw-wss 不再作为 crate 存在 | M6 |
nsgw-wg：kernel、userspace、reconciler、routes（wg0） | 保留；wg0 只配 IPv6，peer 的 AllowedIPs 改为 node6 / node4 /128；网关自己的覆盖地址同样由其身份键派生 | M6 |
nsgw-wg::gateway_exit、gateway_egress、nsgw-gateway-egress | 保留，改为 IPv6：nft 表与 TPROXY 拦截按 node6 源匹配，出口对公网做 NAT66；IPv4 目的地见 §6.1 | M6 |
nsgw-envoy、nsgw-api、nsgw-routing | 保留；后端寻址从 Node IPv4 改为 node6 | M6 |
nsgw-control | 保留；删除中继配对表（gateway_wg_relay / gateway_wss_relay）与探测集合的消费，新增 relay 注册名单的消费 | M6 |
| 用量计量 | relay 路径按节点身份计量，由 NSD 归到账户 | M6 |
nsshared 依赖 keynet-proto、keynet-quick | 换成 v2 协议 crate | M2、M5 |
4. 里程碑
Section titled “4. 里程碑”下表保留最初的目标分组，进度以 §4.1 为准。后续决定已改变部分切换方式：新 ns 不读取、迁移或保留旧状态与身份；R3 显式 CIDR 核心交付与默认 Exit 分开，不能把原里程碑顺序当作所有工作的串行实现门。
| # | 交付 | 仓库 | 依赖 | 验证门 |
|---|---|---|---|---|
| M0 前置收敛 | ns 改为依赖 nsshared 的 v2 协议 crate（v1 控制面副本留到 M6）；nsgw 完成 rustls → aws-lc-rs 与 /relay connector 路径删除；ns 把 boringtun 0.7 换成 nsplane-noise（decapsulate 源地址改为 SocketAddr）；nsshared 的 keynet-* 改名 | ns、nsgw、nsshared | — | 各仓库 just qa；行为不变 |
| M1 协议 crate | nsshared 新增 v2 协议 crate：NodeRecord 与派生（标签、节点 ID、node6 / node4；lan6 与 IPv4 别名属于 ns）、relay 报文 v2、会合 v2（信箱、登记表、目录、能力）的消息类型；测试向量取自 v2 §2.3 | nsshared | M0 | 向量在 ns 与 nsgw 的测试里都通过；属性测试覆盖编解码与 §3.3 的顺序规则 |
| M2 relay v2 服务端 | nsgw-relay 库与 nsgw-quick-relay 的 v2 实现（§3.2 前五行），作为独立 feature / 二进制目标与 v1 并存；部署到 DEV 的独立端口 | nsgw | M1 | just qa；两实例 + 区域三成员的集成测试；登记冲突、限速与容量测试；DEV 上的端到端冒烟 |
| M3 覆盖网核心 | ns crates/overlay：身份与派生 v2、RelayClient（按能力选 UDP / WSS）、登记客户端、PeerSource trait、合并对端表、来源策略命名空间、路径阶梯（实现 nsplane 的 PathPolicy）。以库形式存在，尚未接入运行时 | ns | M1；nsplane 2 | 单元测试 + 对 M2 的 DEV relay 的集成测试；just dev-check |
| M4 账户模式换引擎 | nsd 来源运行在 nsplane 引擎上，协议与地址不变：tunnel-wg、netstack 的职责移到引擎，nat 的翻译按现有地址计划接成过滤器，阶梯走 overlay。由 feature 切换，默认仍为旧路径，回归通过后翻转默认 | ns | M3；nsplane 2、3、4 | 账户模式全部现有测试；tests/live-e2e；Windows / macOS 原生 TUN smoke；吞吐不低于旧实现；just ns-ffi-contracts |
| M5 Quick v2 切换（切换一） | quick 来源在引擎上直接实现 v2：记录、信箱配对、按 ID 放行、登记表发布与重新同步、隧道内控制通道、v2 命令；nsgw-quick-relay v2 上 PROD；目录换成 relay.ns.io 名字 + IP。两边同一版本发布，随后删除 v1 | ns、nsgw | M2、M3、M4；nsplane 5（翻译） | Quick 全部用例重写为 v2；两节点 + 区域 relay 的 live e2e；v1 状态迁移测试（只保留 I）；发布说明写明”需要重新配对” |
| M6 账户地址与 relay 切换（切换二） | NSD 停止分配 Node IPv4，投影节点 ID / node6；ns 的 nsd 来源改用派生 v2，多个 NSD 与 Quick 同时运行，跨来源策略生效；账户 relay 以独立进程部署（relay 二进制按 NSD 名单准入），nsgw-server 作为节点接入它，wg0、ACL、路由、出口、Egress、公网入口后端改为 IPv6（node6）；mac1 中继、不透明 WSS 中继与节点侧的逐路由 terminate 回退停用 | ns、nsgw、nsd | M4、M5；NSD 的配套工作（§5） | 三仓库同一发布窗口；账户模式 live e2e 全量；Quick ↔ 账户互通用例；多 NSD 并存用例；出口、Egress、公网入口回归 |
| M7 呈现统一与功能模块 | edge：TUN、netstack、DNS-VIP、SOCKS5 / HTTP / PAC 对所有来源可用；features/*：服务发布、公网入口、子网、出口、本地代理各自一个开关 | ns | M6 | 呈现 × 传输矩阵（新架构 §6）逐格测试；逐个禁用模块的回归 |
| M8 应用与名字 | ns send / ns receive（文件发送）；应用会话接口；自研权威 DNS 服务（读取 relay 登记表，发布 n.ns.io）与短名分配；本地 resolver 的名字表统一 | ns、nsgw | M5、M7 | 文件发送设计用例；DNS 示例记录的校验测试；无 DNS 时的全部路径（新架构 §5.5） |
| M9 清理与转正 | 删除 ns 的 tunnel-wg、quick-runtime、quick-wire、quick-pairing、netstack、nat 的残余；删除 nsgw 的 mac1 中继、不透明 WSS 中继与 v1 代码；本站把设计页转为现状页 | ns、nsgw、docs | M6–M8 | cargo shear 无残留依赖；各仓库 just qa；文档链接检查 |
2026-10-17 的 M6 私有服务实施切片：服务身份/P/ready 使用许可与本地统一 Short DNS，详见 服务控制契约。依赖 nsgw/next R1 Relay v2 的真实名单、目录及登记承载；不依赖 R2 Exit/Egress/公网入口，不包含 Subnet 迁移。公共短名和权威 DNS 仍留 M8，本地 Node/Service 名字统一提前到本次切片。真实 NSD、两个 ns、R1 前置和业务直连 E2E 通过才完成该切片，不据此标记全部 M6 完成。D4 不保留逐路由 terminate 回退，D7 平等 membership 与所有者裁决继续适用。
依赖关系：
M0 ─► M1 ─┬─► M2 ─────────────┐ └─► M3 ─► M4 ─► M5 ─┴─► M6 ─► M7 ─► M8 ─► M9nsplane: 2 ──────►3、4 ──►5M2 与 M3 可以并行；M4 不依赖 M2。nsplane 的第 2 阶段是 M3 的前置，第 3、4 阶段是 M4 的前置，第 5 阶段（翻译过滤器）是 M5 的前置。
4.1 进度
Section titled “4.1 进度”截至 2026-10-20，已重新 fetch 七个相关仓库的全部 origin 分支，并核对非主线实现。以下是代码与既有验收记录的核对（reviewed），本次文档更新未重跑产品测试。分支已实现、指定产物验收通过、合入主线和生产发布是不同状态。
| 里程碑 | 状态 | 已有证据与剩余边界 |
|---|---|---|
| M0 | 前置依赖已推进；按消费分支对齐 | ns main 与 nsgw next 自 2026-10-25/26 起都使用 nsplane v0.19.1（afae107）；nsshared 方面 ns main 固定重组前、含 Service Control 的 3c48566b，nsgw next 已采用 2026-10-25 重组后的 95f1688，nsd 的 pin 与二者不同。R3 消费分支另有 L8 候选 pin。不能继续使用 v0.14.0 / v0.5.0 作为全仓现状，也不能把最新库分支自动当成所有消费者已采用 |
| M1 | v2 基础协议已交付；后续 family 分开推进 | v0.1.0–v0.6.0 的身份、relay、会合、登记与持久化格式已交付；Service Control 已进入共享库 main。L8 分支有部分 family、registry 和候选向量，完整 producer / consumer 接入与发布仍未闭合；L9 短名及 DNS 供数仍待交付 |
| M2 | R1 开发完成条件已交付；生产门未闭合 | nsgw next 已包含真实 relay v2、会合、登记与区域实现，已用于限定范围的节点 / 服务联调。生产持久存储、恢复及运维门仍需 R1 自身证据；L10 类型已交付不等于这些生产门已过 |
| M3 | 覆盖网核心已运行并有后续限定验收 | 账户与 Quick 共用 overlay / nsplane。真实 macOS / Linux Node DNS、ICMP 与精确私有服务验收已记录；不再用“仅待最终 QA”代表当前全部状态。普通 Node 固定 I / K / IP 撤销仍有独立 nsplane owner 提案，不能由私有 Service 退役证据代替 |
| M4 | 账户模式换引擎已完成 | 旧数据路径已删除。后续指定产物的 QA 与原生 Node / 服务矩阵通过；当前 pin 的全平台发布义务仍分别验收，不把历史通过外推至所有新分支 |
| M5（切换一） | 节点 v2 已实现，已有真实开发 relay；生产切换待验收 | 已删除 Quick v1 运行时；独立 NSD / Quick 的连续性有限定 Linux 进程证据。生产切换仍等待 R1 生产门及对应发布验收，不能再写“服务端只有 v1、只能对 mock”，也不能宣称已对外生产可用 |
| M6（切换二） | 三仓均有实现与限定验收；完整账户 / 网关交付未完成 | 平等 membership、派生身份地址、私有 Service Control、本地 Node / Service DNS 已推进到真实 NSD 验收。ns 的双独立 NSD 分支已修复地址聚合和命名空间问题，不能再以“仅首个来源可达”概括现状。最新 PLAN-269 / NS-INTEGRATION-011 在精确 NS / NSD 产物配对上通过 scoped logout：两个旧后端 TCP 关闭，另一 NSD 和 Quick 原连接继续；快速重授予仍是组件级证据。R3 普通网关、完整 L8 family、真实跨仓组合、当前 pin 发布及主线集成仍分别待闭合 |
| M7 | 统一呈现与独立功能开关尚未整体验收 | 本地 DNS 和私有服务已有实现；不等于所有来源 × TUN / DNS-VIP / SOCKS5 / HTTP / PAC 的矩阵完成。可按可独立验收工作块推进，无需把全部工作排在 R3 之后 |
| M8 | 本地名字已有部分交付；文件传输本轮范围完成，整体里程碑未完成 | 应用会话基础与文件传输已接入；2026-10-25 文件传输按已批准范围完成，固定候选及验收见文件发送。C05 延期不阻塞本轮完成或合并，仅在用户通知后恢复；Windows 原生验收仍是对应发布门。公共 Node ID DNS / 短名和 L9 仍待实现与验收，本地 resolver 不代表公网权威 DNS，权威服务归属仍未决定 |
| M9 | 部分旧节点路径已删除；整体转正未完成 | 清理随已完成切片进行。R3 未完成前不能宣称所有旧网关路径已退役，也不能把本站全部设计页改成现状页 |
4.2 分支与验收依据
Section titled “4.2 分支与验收依据”下列入口定位核对过的分支与记录；记录中的精确源码、产物摘要和环境边界决定证据适用范围。分支后续前进不自动扩大已有验收结论。
| 仓库 / 分支 | 核对入口 | 结论边界 |
|---|---|---|
ns main / fix/live-e2e | Node DNS、ICMP 与私有服务验收 | 指定 macOS / Linux 产物在部署、容器重建 / 重启、原身份 Mac 重启后通过；QA 记录为 4,497 pass、17 skip。原过渡失败保留；不含 R2 Exit、Subnet、公共短名、真实整机睡眠或不中断 / UDP 零丢包承诺 |
ns fix/container-dns-authority；nsd test/m6-multi-nsd-authority | NS-INTEGRATION-011、QUALIFICATION-017；ns PLAN-245、254、255、256、265、267–269；nsd PLAN-303–306 | 最新严格 Linux cohort 通过：24 条目标负路径、42 条 Account 正路径、48 次 B keepalive、156 次 Quick payload、4 条 ping；26 份损坏回执被拒绝。真实 ns / NSD 进程配测试传输、每个 NSD 一个 Network；并非同一 NSD 多 Network、生产 relay / G22、当前 pin 原生发布或 main 集成证明 |
ns / nsd feat/r3-gateway-node | ns 共享候选对齐、NSD 真实控制引导 | receipt、family inventory、候选 pin 与 HTTPS 引导已有交付；不能据此关闭普通网关运行时或全部 family adapter |
nsgw next / fix/live-e2e；feat/r3-campaign-1 | R3 账户切换、NSD / NS 工作包 | R1 开发交付、R2 缩减范围交付；R2 的 Egress promotion、组合验收与 Run B 已撤销。R3 分支已有身份 custody、store / domain / lifecycle、用量与 relay 机制，整体装配及真实组合验收未完成 |
nsshared main；feat/l8-account-profile | L8 profile、候选审查请求 | main 已包含 Service Control；L8 是部分候选。registry 有条目不等于所有 family / 独立 NSD 向量已交付；审查请求不等于审批或发布 |
nsplane main；docs/fixed-k-source-revocation-plan | 发布记录、固定来源撤销提案 | v0.19.2（2026-10-26）已发布：0.17 起增加 nsplane-ether、nsplane-dns 与 netstack 透明终结，0.19.1 修复普通规则接受的流其回复许可不随授权撤销（GitHub #8）；0.16 的通用 per-flow revoke / receipt / context 仍是撤销方案的输入；提案分支只有文档，普通 ACL stale allowance 仍待 owner 审查，不能当作已修复 |
nsc-app main 与新同步的 release / fix / acceptance 分支 | release/app-0.9.5-31、fix/client-usability-update-handoff、docs/release095-acceptance 均已包含在 main | 没有新的未合入 App 前置；旧 App 验收也不证明当前 ns ABI 4 / status.v14 已接入 |
本次 Git fetch 已成功。产品结论来自上述既有证据记录的核对；本次仅运行文档与图件检查。
5. 两次切换
Section titled “5. 两次切换”以下为原始发布安排的历史记录；当前新 ns 不读取或迁移旧状态与身份，不能执行其中“只保留 I”的旧迁移方案。R3 的普通 Node 与显式 / 默认 Exit 交付边界优先。
| 切换一：Quick v2（M5） | 切换二：账户地址与 relay（M6） | |
|---|---|---|
| 同时发布 | ns、nsgw-quick-relay | ns、nsgw-server、nsd |
| 用户可见的变化 | Quick 对端全部需要重新配对；地址与名字改变；ns quick 命令按 v2 调整 | 节点地址从 NSD 分配的 IPv4 变为 node6；应用里写死的 100.64.x.x 失效（名字不受影响）；可以同时连接多个 NSD 与 Quick；每台设备重新登记（ns 不读取旧状态与身份） |
| 状态处理 | 备份状态目录，只保留 I；relay 以空的 v2 库启动 | 不迁移：身份改由设备密钥链派生（按 NSD 加盐），旧状态与身份不读取，每台设备在每个 NSD 重新登记（ns 决策 2026-10-11-node-memberships 第 9 条，2026-10-12 修订）；NSD 侧 Node 记录改为身份键；本机 IPv4 别名由 ns 分配 |
| 回退 | 回退到上一个版本并恢复备份；v2 期间新建的配对丢失 | 三个组件一起回退；NSD 保留 IPv4 分配数据直到 M9 |
| 不受影响 | 账户模式（M4 之后已在引擎上，协议未变） | Quick（已是 v2） |
切换二的 NSD 工作包已经进入实现及限定验收，不再处于“待派发 / 未开始”。以下保留原工作包范围供对照，已交付与剩余项以 §4.1–§4.2 和 R3 family 工作包为准：停止分配并投影 Node IPv4（ns 侧已经要求：WgConfig 没有 ip_address，node_identity 携带 Node 的 Ed25519 身份键 identity 而不是 tunnel_ip，allowed_ips 为 N6 / N4 的 /128，withdrawn 是唯一的撤回方式）；接受同一台设备在不同 NSD 使用不同的身份；wg_config、routing_config、acl_config 等事件改用节点 ID 与 node6；按节点 ID 查找 relay 登记表；向网关投影 relay 注册名单；Short DNS 名字迁到 zone 之下；出口与 Egress 的投影改为 IPv6；用量按节点身份归账。
下表保留原决策演进。D3 的旧 carrier / NAT64 争议已由后续 G22 普通 Node 与 R3 设计接替；现存 carrier 代码是待替换实现，不是新设计。D6 的“待派发”是历史状态，当前 NSD 进度见 §4.1。
| # | 问题 | 决定（2026-10-02） |
|---|---|---|
| D1 | 账户网关的中继是否换成 relay v2 | 换，全部基于 relay v2。 relay 核心抽成 nsgw-relay 库；公共 Quick relay 接受任意身份注册，账户 relay 只接受 NSD 投影的名单内身份。2026-10-07 修订：账户 relay 是 relay 二进制按名单准入的独立进程，nsgw-server 不内嵌 relay，像其他节点一样接入它（NSGW 新架构设计 的 G21）。节点侧只有一个 RelayClient，NSD 不再投影逐对的中继表；mac1 中继与不透明 WSS 中继在 M6 停用、M9 删除 |
| D2 | Quick v2 与 Quick 换引擎是否合并成一次切换 | 合并（M5）。 v1 不移植到引擎上，用户只重新配对一次 |
| D3 | 覆盖网只有 IPv6 后，网关侧怎么处理 | 网关直接用 IPv6，不做 IPv4 转换。 网关由我们控制：wg0、ACL、路由、出口、Egress 与公网入口后端都按 node6 处理，不给节点分配任何网关侧的 IPv4。唯一仍涉及 IPv4 的情形见 §6.1。2026-10-12 修订（ns 侧决定 B5b，待所有者确认）：ns 的 membership 运行时保留了一条 IPv4 路径——到网关载体（terminate 服务、出口默认路由）的 IPv4 从 membership 的本机 carrier4 不经翻译在 WireGuard 内发出，地址不上报；因此 nsgw 需要接受已准入客户端的任意 IPv4 源并按 WireGuard 对端伪装回包，nsplane 不需要 NAT64（ns 否决了保留 NSD IPv4 与在 ns 内逐报文翻译两个方案）。这与“网关不做任何 IPv4”不同，也会取代 §6.1 的 NAT64 方案；确认前 §6.1 保留原文 |
| D4 | 节点侧是否保留”逐路由 terminate”这一级回退 | 不保留。 relay v2 的 WSS 载体覆盖 UDP 被阻断的情形。2026-10-06 修订：公网入口也不保留流代理，网关到发布端只走 WireGuard（NSGW 新架构设计 的 G20）。M6 一并删除节点侧的第三级 |
| D5 | n.ns.io 的权威 DNS 由谁提供 | 自研 DNS 服务器。 relay 把已校验的 NodeRecord 交给它发布，relay 进程自己不应答 DNS；在 M8 立项 |
| D6 | NSD 配套工作的归属与时间 | 现在不处理。 本计划完善后把 §5 的清单派发给 nsd 实现；它只阻塞 M6。2026-10-12：ns 侧已按新线上格式实现，工作包现在是阻塞项 |
| D7 | 多 NSD 并存的模型（2026-10-11，ns 决策 2026-10-11-node-memberships，本计划之外） | 平等的 membership，节点决定。 一个 NSD 的一个 Network、Quick、应用会话各是一个 membership，没有主 NSD，不按排序解决冲突；NSD 只提议，生效配置按受管配置 → 所有者决定 → 提议由节点决定，节点不在 membership 之间转发，也不向 NSD 上报其他 membership；每个 membership 的身份由一条设备密钥链按 NSD 规范 URL 加盐派生，运营方无法关联；不与旧 ns 兼容。M6 的节点侧按此实现 |
6.1 出口上的 IPv4 目的地
Section titled “6.1 出口上的 IPv4 目的地”历史方案：本节记录 2026-10-12 前后的 NAT64 / carrier 分歧，不是当前实施方向。后续已批准的 G22 / R3 以普通 Node、Egress Service 和 Subnet session proxy 取代专用 carrier；显式 CIDR 与默认 Exit 分开交付。
D3 之后，节点与网关之间只有 IPv6，这对公网入口、Egress、中继、IPv6 出口都没有问题。剩下一种情形绕不开 IPv4：节点经出口访问 IPv4 公网地址，目的地本身是 IPv4。这不需要给节点分配 IPv4，也不需要新机制，沿用节点已有的 4↔6 翻译过滤器即可：
| 位置 | 做法 |
|---|---|
| 节点 | 发往出口的 IPv4 报文由翻译过滤器映射为 IPv6：源为本机 node6，目的为 64:ff9b::/96 内嵌 IPv4 目的地（RFC 6052）。与 alias4 ↔ node6 是同一个过滤器的另一条规则 |
| 隧道内 | 只有 IPv6 |
| 网关 | 对 64:ff9b::/96 的目的地做 NAT64 后发往公网；其余 IPv6 目的地做 NAT66 |
网关侧的 NAT64 是这次迁移中 nsgw 唯一新增的翻译点，放在出口路径上：内核 WireGuard 没有原生 NAT64，实现上有两个选择——用户态路径直接复用 nsplane 的翻译过滤器，或内核路径配合独立的 NAT64 组件。这一点在 M6 的 nsgw 计划里确定，不影响前面的里程碑。只走 IPv6 出口的部署不需要它。
下表保留原迁移风险。当前不允许据其中旧安排保留已退役 ns schema、恢复旧状态兼容或旧数据路径；发布门应使用对应现行 plan 的验收条件。
| 风险 | 缓解 |
|---|---|
| nsplane 阶段延迟拖住 ns | M0–M3 不依赖 nsplane 2 之后的阶段；M2（nsgw）完全不依赖 nsplane |
| M4 换引擎引入性能或平台回归 | feature 切换、默认不变；吞吐基准与原生 TUN smoke 是翻转默认的条件 |
| 切换二跨三个仓库 | 在 DEV / TEST 用同一组 live e2e 预演；NSD 保留旧分配数据到 M9 以便回退 |
libns 宿主（移动端）跟不上 schema 变化 | schema 升版本并保留旧版本一个发布周期；just ns-ffi-contracts 进入 M5、M6 的门 |
| 多个会话同时修改同一仓库 | 每个里程碑拆成各仓库自己的任务与计划，按 crate 划分工作流，避免跨工作流改同一文件 |
| 文档与实现脱节 | 每个里程碑的完成条件包含更新本站对应页面；M9 把设计页转为现状页 |
8. 下一步
Section titled “8. 下一步”- 收敛已完成的 DNS、双 NSD 与 scoped logout 分支修复，并针对实际集成版本保留 / 补齐配对验收；不重复把已通过的限定 cohort 写成未开始，也不跳过主线与发布门。
- R3 按 L8 family 的真实生产者、消费者 adapter 和独立向量逐项解锁：身份 / 配置流、普通 Node / Egress、显式 CIDR Exit、发布端 / 公网入口分别推进。receipt 或候选 pin 对齐不替代运行时交付。
- 先交付可验收的 explicit core；默认 / 嵌套 Exit 后续配对。nsplane
v0.19.1（当前 pin）已有的接口直接作为输入；普通 Node ACL 撤销 owner 提案只阻断它所影响的范围。 - Quick 生产切换继续等待 R1 持久性、恢复与运维证据；全来源代理、DNS-VIP、独立功能开关和应用会话按自身边界推进。
- M8 公共名字另行完成 L9、relay 供数 / 短名分配和权威 DNS 服务验收；先明确权威 DNS 服务归属，不能把本地名字成功视为公共 DNS 已交付。