初版功能完成

2026-08-29 13:12:17 +08:00
commit 142e5dc7d6
217 changed files with 21313 additions and 0 deletions
@@ -0,0 +1,80 @@
+# RemLink v1.0 T01–T18 验收执行手册
+
+本文是证据模板，不代表真实环境已经通过。每次运行先执行 `scripts/validation/New-AcceptanceRun.ps1`；在指定主机证据齐全前，场景保持 `NOT_RUN`。每个 PASS 都必须在同一运行目录内包含时间戳、节点名、应用日志和指定主机快照。
+
+只能通过 `Set-AcceptanceResult.ps1` 记录结果；脚本要求证据文件位于运行目录内，并保存 SHA-256 和大小。每批记录后及归档前执行 `Test-AcceptanceRun.ps1`。验证器会拒绝缺失、移动或修改过的证据并执行 Gate 前置条件，但不会代替人工判断所选截图是否真正证明场景。
+
+~~~powershell
+./scripts/validation/Set-AcceptanceResult.ps1 -RunDirectory evidence/run-001 -ID T01 -Status PASS -EvidencePath engineer-a/inventory.json,site-a/inventory.json
+./scripts/validation/Test-AcceptanceRun.ps1 -RunDirectory evidence/run-001
+~~~
+
+## 必需拓扑
+
+- 一台 Linux Server：内核 WireGuard、公网可达 UDP endpoint，只公开受保护的 Bootstrap/Admin 入口和 `51820/udp`。
+- Engineer-A、Engineer-B、Site-A、Site-B：分别位于受支持 Windows 系统，RemLink 进程均以管理员运行。
+- Site-A 和 Site-B 各自可达一个 `192.168.13.0/24` 测试网段；Site-A 另外可达 `192.168.21.0/24`。
+- 目标提供 ICMP Echo、TCP 102、TCP 502、HTTP、RDP 和普通 UDP echo；不能用 RemLink 内部的协议专用代码替代。
+
+在相关场景前后，分别在 Windows 节点运行 `Collect-WindowsEvidence.ps1`，在 Server 运行 `Collect-ServerEvidence.sh`。第三方 WinNAT 只做只读快照。Server 采集器故意只使用公开 WireGuard 视图，绝不执行可能暴露私钥或预共享密钥的 `wg show ... dump`。
+
+## 场景步骤与通过条件
+
+| ID | 执行与必需证据 | 通过条件 |
+|---|---|---|
+| T01 | 启动 Engineer/Site，采集 Admin 节点页和 Windows inventory | 两者 ONLINE；每节点恰好一个 `RemLink` 适配器；无 WireGuardNT |
+| T02 | Engineer 执行 `ping <Site Overlay IP>`，采集 ping 和 Server `wg show` | 经 Server hub 回复成功，WireGuard 计数增加 |
+| T03 | Engineer 连接 Site，CIDR 为 `192.168.13.0/24`；采 GUI 与 Session 日志 | Session 到 ACTIVE，且只出现一条自有 Remote route |
+| T04 | Engineer 本地接入 `192.168.13.0/24` 后请求相同远程网段 | 在 Server 创建前以 `CIDR_LOCAL_CONFLICT` 拒绝 |
+| T05 | 删除 Site 到 `192.168.13.0/24` 的全部非默认路由后请求 | PREPARE 以 `SITE_NO_ROUTE` 失败；无 ACTIVE Session 或泄漏 flow |
+| T06 | T03/T07–T09 前后分别快照 Hyper-V/Docker/WinNAT | 远程访问成功，第三方 NAT 快照完全一致 |
+| T07 | 对 PLC/测试目标执行 `Test-RemoteTargets.ps1` | 四个 Echo Reply 保留目标身份，无注入错误 |
+| T08 | 探测 TCP 102/502/80/3389，并对每项运行一次真实连接 | 全部服务经通用 TCP relay 连接；源码审计无协议代理 |
+| T09 | 向 UDP echo 发送不同数据报，等待超过 idle timeout 后再发 | 两次均成功；间隔后 flow 数回到基线 |
+| T10 | 一个 Session 同时请求 `192.168.13.0/24` 和 `192.168.21.0/24` | 两网段目标均通过 ICMP 及至少一项 TCP/UDP |
+| T11 | Engineer-A→Site-A 与 Engineer-B→Site-B 同时连接；两个 Site 都声明 `192.168.13.0/24` | 两个 SessionID 保持 ACTIVE；载荷标记只回到来源 Engineer |
+| T12 | 两个 Engineer 同时连接 Site-A，以不同标记访问同一 endpoint/port | Site flow/事件正确区分 SessionID 和 Engineer Overlay IP，无串流 |
+| T13 | Engineer-A 已 ACTIVE 时请求第二个 Site | UI 禁止选择；构造请求被 Server 以 `ENGINEER_SESSION_EXISTS` 拒绝 |
+| T14 | 持续 ping/TCP 时把 Engineer Wi-Fi 切到手机热点 | WireGuard 与 Control 在有限中断后重连；用户可重建不会自动恢复的 Session |
+| T15 | ACTIVE 流量期间重启 Server | 数据库非终态 Session 变 CLOSED；节点自动重连并能新建 Session |
+| T16 | 强制终止 Engineer，管理员重启，采集前后路由 | 接受新 Session 前 reconcile 删除自有陈旧 Remote route |
+| T17 | 在 Admin UI 修改一个在线 Node 的 Overlay IP | Session 关闭；Node 公开 Bootstrap；新 IP 下单适配器重连 |
+| T18 | 在 Admin UI 修改完整 Overlay CIDR | 全部 Session 关闭；`wg0`、数据库分配、Node 适配器、Control 和 Bootstrap 使用递增配置；Site NAT 快照不变 |
+
+## 建议证据目录
+
+~~~text
+evidence/run-001/
+  acceptance-run.json
+  T01-T18-runbook.md
+  server/
+  engineer-a/
+  engineer-b/
+  site-a/
+  site-b/
+  targets/
+  screenshots/
+~~~
+
+文件名应包含场景 ID、主机和 UTC 时间。严禁把 Join Token、Admin token、Node Token、WireGuard 私钥、预共享密钥或数据包载荷放入证据。需要展示配置时只截取非敏感字段。
+
+## Gate 记录
+
+- Gate A 使用 T01/T02 证据，并增加双向 Overlay ping。
+- Gate B 还需持续远程流量，证明同一个适配器承载普通外层 UDP 且无 busy loop/deadlock。
+- Gate C 需要目标侧 TCP/UDP echo 和 Site netstack 日志。
+- Gate D 需要返回 raw IPv4 身份以及 T07/T08/T09 证据。
+
+不能仅根据单元/进程内测试标记 Gate 或场景 PASS。自动化测试证明实现不变量，本手册证明指定物理部署行为。
+
+## 一次完整执行顺序
+
+1. 初始化运行目录，记录版本、包哈希、拓扑、主机名、时间同步状态和人员。
+2. 采集五台主机基线，确认无秘密进入证据。
+3. 先执行 Gate A 与 T01/T02，验证单适配器和中心辐射 Overlay。
+4. 执行 T03–T10，覆盖路由冲突、Site 路由、NAT 不变、ICMP/TCP/UDP 和多 CIDR。
+5. 执行 T11–T13，覆盖并发、重复 CIDR、同 Site 多 Engineer 和单 Engineer 限制。
+6. 执行 T14–T18，覆盖网络切换、Server 重启、异常退出、节点 IP 与 Overlay 迁移。
+7. 采集结束快照、应用日志和目标侧证据，记录每项 PASS/FAIL/NOT_RUN。
+8. 执行验证器；修复证据路径/哈希问题，但不得为通过验证器而改写真实结果。
+9. 将完整运行目录只读归档，并单独保存发布包和外部 ZIP 哈希。
@@ -0,0 +1,33 @@
+# 自动化验证覆盖
+
+权威的 R1–R16 与 Phase 0–10 实现/证据矩阵见 `requirements-evidence.md`；本文补充自动化覆盖细节。
+
+自动化测试覆盖协议 framing、精确错误码、Bootstrap/IPAM/数据库、Control 状态、PacketMux、Session UDP 验证、完整 Session 状态机、进程内 gVisor TCP/UDP/ICMP 往返、Admin 网络迁移、rebootstrap 通知和重复 CIDR 隔离。测试还固定 v1 的 `DEFAULT_ONLY` 拒绝、Session 级注入失败清理、拒绝注入后的监听连续性、限速安全警告、WG `/32` peer、唯一 Server client peer、Admin 日志时间过滤和 Site Console 状态/事件字段。
+
+回归套件还覆盖：
+
+- PREPARE 失败关联、重试和陈旧拒绝隔离；
+- netstack 幂等、PacketMux 计数/队列丢包、严格 IPv4 framing、Sender 关闭 race、UDP 空闲回收；
+- Site flow 上限、Server WG 密钥并发发布、可用 Overlay 主机地址、`/0` 拒绝和事件模块分类；
+- 迁移期间 Session quiesce、迁移后 Session 配置、旧 Control 通知顺序、Overlay 冲突事件、Control rebind 回滚和 Linux 内核变更回滚；
+- 全宽随机 SessionID 的无损十进制 JSON、新 Bootstrap 清理陈旧 Session、严格公网/Overlay endpoint、Site 容量拒绝和 Engineer 单 Session GUI 门禁。
+
+验收工具自测证明：没有证据文件不能 PASS；Gate 前置条件被执行；证据 SHA-256 与大小会持久化；记录后篡改可被发现。架构扫描还禁止 Server 采集器导出 WireGuard dump/私钥，检查 Docker data mount、可配置 WireGuard 映射、发布 Compose 权限和预编译二进制入口。
+
+发布验证器会独立解压 ZIP、检查必需项、重算每条 SHA-256、拒绝未纳入清单的文件，并运行包内验收初始化器，保持全部 Gate/T 为 `NOT_RUN`。
+
+前端渲染 QA 的开发 fixture 只提供展示数据，实际使用与内嵌构建相同的 Vue 组件。最近一次检查覆盖 Server Nodes/Sessions/Network/Logs 交互以及 Engineer Site capability/LastSeen 和导航；页面有有效 DOM，浏览器无 warning/error。该 UI QA 不声称物理网络操作成功。
+
+以下映射只作为支持证据，不能把真实验收场景标记 PASS：
+
+| 验收区域 | 自动化证据 | 仍需真实证据 |
+|---|---|---|
+| T03/T05/T13 | `internal/session` manager/runtime 测试 | 管理员 Engineer/Site 与实际路由 |
+| T04/T16 | Windows 路由、冲突、reconcile 测试 | 真实主机前后路由清单 |
+| T07/T08/T09 | gVisor 主机套接字往返 | 两台 Windows 间 PLC/服务 |
+| T10 | 多 CIDR 状态机与 PacketMux | 两个物理现场子网 |
+| T11/T12 | 并发 Session 与重复 CIDR flow key | 四节点载荷隔离 |
+| T15 | SQLite 关闭开放 Session 与 Control 重连 | 流量中 Server 重启 |
+| T17/T18 | Admin 更新/rebootstrap/迁移回滚测试 | 真实适配器和 `wg0` 迁移 |
+
+Gate A–D 和 T01–T18 在执行手册证据齐全前保持 `NOT_RUN`。
@@ -0,0 +1,67 @@
+# RemLink v1.0 需求与证据矩阵
+
+日期：2026-08-25
+
+本矩阵审计根目录权威 DOCX、`specs/spec.md`、`specs/tasks.md` 和 `specs/checklist.md`，并映射到生产代码与可重复验证。若派生 Markdown 与 DOCX 冲突，以 DOCX 为准。
+
+状态词汇：
+
+- `CODE_TESTED`：存在生产实现，并有可重复自动化测试或策略扫描覆盖该边界。
+- `BUILD_VERIFIED`：目标已编译/类型检查，但不声称管理员权限或物理网络行为成功。
+- `PHYSICAL_NOT_RUN`：Gate/场景需要真实 Linux/Windows 拓扑，不能从单元、集成、浏览器或交叉构建推导 PASS。
+
+## 需求覆盖
+
+| 需求 | 生产证据 | 自动化/构建证据 | 审计状态 | 仍需物理证据 |
+|---|---|---|---|---|
+| R1 架构与不可变约束 | `internal/overlay`、`internal/subnet`、`internal/subnetgateway`、Windows 平台层、`serverwg` | 架构扫描；重复 CIDR manager/netstack 测试；双平台发布构建 | `CODE_TESTED` | Gate A–D、T01–T02、T06、T11–T12 |
+| R2 Overlay 与 Server IPAM | `internal/ipam`、Admin network/handler、Bootstrap、serverwg | IPAM 稳定分配；原子 Node/network 设置；七步迁移、回滚、通知顺序、Node IP 更新/删除 | `CODE_TESTED` | T17–T18 真实适配器、`wg0`、Control |
+| R3 单 Wintun MuxTun/PacketMux | clientwg、Windows Wintun/runtime | 分类、framing、计数、丢包、关闭测试；DLL 并发发布；Windows 构建 | `CODE_TESTED + BUILD_VERIFIED` | Gate A–B、T01–T02 管理员 Windows |
+| R4 Remote Subnet Session | `internal/session`、`internal/subnet`、Windows route | 完整状态机、请求关联、超时、多 CIDR、冲突、双向数据报验证、并发 SessionID 和 MaxUint64 JSON | `CODE_TESTED` | T03–T05、T10、T13 与真实路由 |
+| R5 Site gVisor 网关 | netstack、TCP/UDP/ping relay | 进程内主机套接字往返、prepare 幂等、容量和 UDP idle-GC | `CODE_TESTED` | Gate C–D、T06–T09 真实目标 |
+| R6 Bootstrap、Control、身份 | Bootstrap、Control、nodeagent、identity、DPAPI | 严格 API/config/URL、token/DPAPI、HELLO/心跳/状态/重连/rebootstrap | `CODE_TESTED` | T14–T15 中断 |
+| R7 Server | `cmd/server`、database、Admin、serverwg、Server 前端 | 数据库/Admin/Control；Linux 构建；前端生产扫描；Docker 架构与发布入口 | `CODE_TESTED + BUILD_VERIFIED` | Linux WG/Docker 启动与 UI 拓扑 |
+| R8 Engineer | `cmd/engineer`、Engineer 前端、Engineer Session、Windows adapter/route | runtime 测试；禁止 Demo fallback；Vue 构建；Windows GUI 构建 | `CODE_TESTED + BUILD_VERIFIED` | 管理员 GUI、路由、Wintun、Gate/T |
+| R9 Site | `cmd/site`、Site Session、subnetgateway | Console 字段/事件；route/capacity/injection/relay/reconcile；Windows console 构建 | `CODE_TESTED + BUILD_VERIFIED` | Site Console 与真实 LAN TCP/UDP/ICMP |
+| R10 数据库与模型 | database、model、migrations | 六表迁移/store；原子网络/IP 替换；启动关闭开放 Session | `CODE_TESTED` | T15 部署 Server 重启 |
+| R11 API 与消息 | Bootstrap HTTP、Admin handler、protocol、Control | 严格 JSON/framing/auth/direction/error 与 handler 测试 | `CODE_TESTED` | T03/T17/T18 指定抓包/API |
+| R12 冲突、失败、恢复 | route、nodeagent、Bootstrap reconcile、Session runtime、迁移事务 | 本地/Overlay 冲突、陈旧路由、新 Node 清 Session、重连、超时、注入失败、迁移回滚 | `CODE_TESTED` | T04–T05、T14–T18 |
+| R13 日志、统计、可观测性 | logging、eventlog、Session counter/reporter、Admin log API | 模块分类、限速、仅元数据包警告、统计持久化/过滤、秘密扫描 | `CODE_TESTED` | T07–T12 流量计数与日志 |
+| R14 安全边界 | Node/Join token 哈希、DPAPI、WG `/32`、严格 listener/validator、Admin token | token/auth、地址/URL、listener/validator、证据秘密扫描 | `CODE_TESTED` | 防火墙、暴露面、AllowedIPs |
+| R15 结构、接口、依赖 | monorepo、Go/npm 锁、内嵌 Wintun、第三方声明 | 模块验证、架构扫描、前端清洁安装、双平台构建、发布校验和 | `BUILD_VERIFIED` | 部署策略要求时的签名 |
+| R16 阶段与验收 | tasks/checklist、执行手册、证据脚本 | 自测执行证据哈希、范围、前置条件和篡改检测 | `CODE_TESTED`；物理状态独立 | Gate A–D、T01–T18 均 `PHYSICAL_NOT_RUN` |
+
+## 阶段审计
+
+| 阶段 | 实现状态 | 验收状态 |
+|---|---|---|
+| Phase 0 | 仓库、模型、日志、配置、协议、CI 已实现并测试 | 自动化验收完成 |
+| Phase 1 | Wintun/MuxTun/wireguard-go 与内嵌 DLL；Windows 可构建 | Gate A `PHYSICAL_NOT_RUN` |
+| Phase 2 | 数据库、IPAM、Bootstrap、Server WG、身份 store | 模拟 Node/IPAM 完成；部署由后续物理测试覆盖 |
+| Phase 3 | Control Hub、心跳、节点列表、capability、重连 | 自动化集成完成 |
+| Phase 4 | PacketMux、自有路由与冲突逻辑 | 物理 Wintun 拦截 `PHYSICAL_NOT_RUN` |
+| Phase 5 | 普通 UDP 重入传输和验证 | Gate B `PHYSICAL_NOT_RUN` |
+| Phase 6 | gVisor netstack TCP/UDP 网关 | Gate C `PHYSICAL_NOT_RUN` |
+| Phase 7 | 对称返回传输和 ICMP Echo relay | Gate D `PHYSICAL_NOT_RUN` |
+| Phase 8 | 双边 Session 状态机、错误、统计、reconcile | T03/T04/T05/T13/T16 `PHYSICAL_NOT_RUN` |
+| Phase 9 | Engineer GUI、Server 五页 UI、Admin API | UI 驱动真实工作流 `PHYSICAL_NOT_RUN` |
+| Phase 10 | 并发、重复 CIDR、打包、Docker、证据工具 | T01–T18 与最终重复子网拓扑 `PHYSICAL_NOT_RUN` |
+
+## 复现命令
+
+在仓库根目录运行：
+
+~~~powershell
+go mod verify
+go test -count=1 ./...
+go vet ./...
+npm ci --prefix frontend
+npm run typecheck --prefix frontend
+npm run build --prefix frontend
+./scripts/validation/Test-FrontendProduction.ps1
+./scripts/validation/Test-Architecture.ps1
+./scripts/validation/Test-AcceptanceTools.ps1
+./scripts/build-release.ps1 -Version 1.0.0
+~~~
+
+发布构建会在生成二进制和校验和前重复关键测试。真实结果必须先用 `New-AcceptanceRun.ps1` 初始化，采证后用 `Set-AcceptanceResult.ps1` 记录，最后运行 `Test-AcceptanceRun.ps1`。只有证据文件在该运行目录内且哈希通过时，Gate/T 才允许标记 PASS。