415 lines
30 KiB
Markdown
415 lines
30 KiB
Markdown
# RemLink v1.0（Userspace Netstack 版）实施规格
|
||
|
||
> 权威设计来源：仓库根目录《RemLink_v1.0_技术设计与AI开发规格书_Netstack版.docx》（版本日期 2026-08-19）。本文件将其转化为 spec-driven 开发格式；若实现中发现本文件与 docx 原文有冲突，以 docx 为准并回改本文件。禁止为了让代码跑通而绕开核心约束。
|
||
|
||
## 背景与目标
|
||
|
||
工业自动化远程调试中，工程师需要在异地直接访问现场设备 IP（如 192.168.13.10 的 PLC、HMI HTTP、RDP），而端口代理需逐个配置、协议适配无法泛化。RemLink 通过中心式 IPv4 L3 虚拟组网 + Engineer 动态下发远程 CIDR + Site 端 gVisor netstack userspace 子网网关，让 Windows 普通 IP 应用无需任何协议适配即可访问现场地址，且允许多个现场使用完全相同的网段。
|
||
|
||
## 变更内容
|
||
|
||
- 全新构建 RemLink v1.0 三端产品（绿地项目，全部为新增能力）：
|
||
- **Server**：Ubuntu / Docker / Linux Kernel WireGuard + Go（wgctrl 编排）+ SQLite + Vue 3 Web UI
|
||
- **Engineer**：Windows Wails GUI + wireguard-go（嵌入进程）+ 单一 RemLink Wintun + PacketMux
|
||
- **Site**：Windows Console + wireguard-go（嵌入进程）+ 单一 RemLink Wintun + gVisor netstack SubnetGateway
|
||
- 架构基线：**单 Wintun + wireguard-go + PacketMux + gVisor netstack**；不使用 WinNAT、Windows IP Forwarding、Transit CIDR、WireGuardNT
|
||
- 按 Phase 0–10 分阶段实施，Gate A–D 为关键验收关卡（见 tasks.md）
|
||
- 仅 IPv4；Remote Subnet v1 支持 TCP / 单播 UDP / ICMP Echo，不实现二层
|
||
|
||
## 影响范围
|
||
|
||
- 受影响规格：无（首个 change）
|
||
- 受影响代码：全新 Go monorepo `remlink/`（目录结构见 R15）
|
||
- 固定版本外部依赖：Wintun DLL、wireguard-go（锁定 commit）、gVisor netstack（锁定 commit）、wgctrl、SQLite driver、Wails、Vue 3 + Vite、golang.org/x/net/icmp
|
||
|
||
## 新增需求
|
||
|
||
### 需求： R1 总体架构与不可变约束
|
||
|
||
系统 必须 采用中心式 Hub-and-Spoke 架构：所有 Engineer/Site 节点只与 Server 建立 WireGuard 连接，数据始终经 Server Hub 中转；节点只配置 Server 公网 IP/端口，不配置彼此公网地址。
|
||
|
||
系统 必须 遵守以下不可变决策：
|
||
|
||
| 决策项 | v1.0 最终选择 |
|
||
|---|---|
|
||
| 虚拟组网 | 中心式 Hub-and-Spoke，无 P2P |
|
||
| Windows 虚拟网卡 | 每个 Engineer/Site 只有 1 块名为 RemLink 的 Wintun |
|
||
| Windows WireGuard | wireguard-go 嵌入进程，不用 WireGuardNT |
|
||
| Server WireGuard | Linux Kernel WireGuard |
|
||
| 数据层 | IPv4 L3 捕获；Remote Subnet v1 = TCP/UDP/ICMP Echo |
|
||
| 远程子网 | Engineer 建立 Session 时动态下发；Site 配置不保存现场 CIDR |
|
||
| Site Subnet Gateway | gVisor netstack userspace relay，不依赖 WinNAT/IP Forwarding |
|
||
| Engineer 并发 | 一个 Engineer 同时最多连接一个 Site |
|
||
| Site 并发 | 底层允许多个 Engineer 同时连接同一个 Site |
|
||
| 现场网段重复 | 允许不同 Site 使用完全相同的 192.168.x.0/24 |
|
||
| 二层 | 明确不做 ARP/以太网帧/DCP/LLDP/TAP/Bridge |
|
||
| 服务端网络地址 | Server Web UI 配置；Node IP 由 Server IPAM 自动分配 |
|
||
|
||
明确不在 v1 范围：二层协议、P2P/STUN/TURN/UDP 打洞、IPv6、IP 广播/组播、SCTP/GRE/ESP、用户注册/多租户/RBAC/OAuth、HA/Cluster/K8s、自研 TCP/IP 栈/VPN/网卡驱动/NAT、一个 Engineer 同时连多个 Site。
|
||
|
||
#### 场景： 两个 Site 使用相同现场网段
|
||
|
||
- **当** Site-A 与 Site-B 都使用 192.168.13.0/24 作为现场网段，且分别被 Engineer-A、Engineer-B 通过 Session 访问
|
||
- **则** 两条 Session 同时工作互不串流；Server WireGuard 不出现路由冲突（Server 只按 Overlay /32 选路，现场 CIDR 位于 Session UDP Payload 内）
|
||
|
||
#### 场景： 尝试 P2P 或二层能力
|
||
|
||
- **当** 任何实现引入 P2P 直连、打洞、ARP/TAP/Bridge 代码
|
||
- **则** 违反不可变约束，不被接受
|
||
|
||
### 需求： R2 Overlay 虚拟组网与 Server IPAM
|
||
|
||
系统 必须 提供 Overlay 虚拟组网与集中式 IPAM：
|
||
|
||
- 默认 Overlay CIDR 为 10.88.0.0/16（仅初始值，Server Web UI 必须允许修改）；Server 地址默认取该网段第一个可用地址（如 10.88.0.1）；Engineer 与 Site 使用统一 Node Pool。
|
||
- 每个 Node 的地址在 Server WireGuard Peer 上以 /32 AllowedIPs 登记；客户端到 Server 的唯一 Peer 使用整个 Overlay CIDR 作为 AllowedIPs。
|
||
- Server 是 Overlay 地址唯一权威来源，客户端不得自行填写虚拟 IP。
|
||
- Node 首次注册时由 IPAM 分配地址，后续重启保持同一地址；地址不得为网络地址、广播地址、Server 地址或已占用地址。
|
||
- Web UI 可手动修改 Node IP；修改后触发该 Node 重新 Bootstrap/重建 WireGuard。
|
||
- 删除 Node 后撤销 WireGuard Peer、Node Token，并释放地址。
|
||
|
||
修改 Overlay CIDR 时系统 必须 按 7 步流程执行：Web UI 提交并校验新 CIDR → 所有 Active Session 进入 STOPPING/CLOSED → IPAM 为现有 Node 重新分配/迁移地址 → 重建 wg0 地址和 Peer AllowedIPs → 在线 Node 经旧 Control 通道收 REBOOTSTRAP_REQUIRED（通道断则自动走公网 Bootstrap API）→ Windows Node 更新 Adapter IP/路由并重启 wireguard-go → Site 重建 NetworkConfig 与 Session Gateway（不修改 Windows NAT/Forwarding）。
|
||
|
||
Node 必须 在应用新 Overlay CIDR 前检查其与本机现有直连网络是否重叠；发现冲突时不得强行启用，向 Server 报告 OVERLAY_LOCAL_CONFLICT。
|
||
|
||
#### 场景： Node 地址稳定
|
||
|
||
- **当** 已注册 Node 重启后再次 Bootstrap
|
||
- **则** 获得与之前相同的 Overlay IP
|
||
|
||
#### 场景： Node 本地网络与 Overlay 冲突
|
||
|
||
- **当** Node 本机直连网络与 Overlay CIDR 重叠
|
||
- **则** 拒绝启用新配置并上报 OVERLAY_LOCAL_CONFLICT
|
||
|
||
### 需求： R3 Windows 单虚拟网卡数据面（MuxTun / PacketMux）
|
||
|
||
Engineer 与 Site 必须 都只创建一块名称固定为 RemLink 的 Wintun L3 Adapter（默认 MTU 1280），同时承载 Overlay 节点通信和 Engineer 的 Remote Subnet 路由。不存在第二块 Subnet Adapter，也不存在 Transit CIDR。
|
||
|
||
系统 必须 将真实 Wintun 包装为 MuxTun（实现 wireguard-go 的 tun.Device 接口，Read/Write 代理给真实 Wintun）后交给 wireguard-go Device，使 RemLink 能在"Windows 网络栈 ↔ WireGuard 引擎"边界做 L3 分流。MuxTun 必须尽量薄。
|
||
|
||
Engineer 出方向 PacketMux 必须 仅根据目标 IPv4 地址分类：
|
||
|
||
- 目标属于 Overlay CIDR：原包不修改，直接交给 wireguard-go。
|
||
- 目标属于当前 Active Session 的任一 Remote CIDR：不交给 wireguard-go，将原始 IPv4 bytes 放入 SubnetSender 的有界队列。
|
||
- 其他目标：丢弃并做限速日志。
|
||
|
||
SubnetSender 必须 使用普通 Go UDP Socket（绑定 Engineer Overlay IP，目标为 Site OverlayIP:6200）发送 `RemLinkHeader + 原始 IPv4 Packet`，由 Windows TCP/IP 生成外层 IP/UDP Header；该外层 UDP Packet 因目标属于 Overlay CIDR 再次进入同一 Wintun，被 PacketMux 判定为 Overlay 流量交给 wireguard-go（防循环：外层目标为 Site Overlay IP，不属于 Remote CIDR，只进入一次 WireGuard）。
|
||
|
||
MuxTun 并发要求：
|
||
|
||
- PacketMux Read 不得在发送 Remote Packet 时直接阻塞等待 UDP 网络 I/O；使用有界 channel + 独立 Sender goroutine。
|
||
- 当一次 Wintun batch 全部为 Remote Packet 时，Read 应继续读取，直到能向 wireguard-go 返回至少一个 Overlay Packet 或收到关闭/错误事件，避免返回 0,nil 造成 busy loop。
|
||
- Wintun Write 由 wireguard-go 入方向和 Site Session 注入共用时，通过统一 Writer/锁序列化。
|
||
- packet buffer 尽量复用池；先保证正确性，再做 batch 优化。
|
||
|
||
#### 场景： Remote 包外层再入 Wintun
|
||
|
||
- **当** Engineer 应用访问 192.168.13.10，PacketMux 拦截后由 SubnetSender 以 UDP 发往 Site Overlay IP:6200
|
||
- **则** 外层 UDP 再次进入同一 Wintun 后被识别为 Overlay 流量交给 wireguard-go，无死锁、无无限循环
|
||
|
||
### 需求： R4 Remote Subnet Session
|
||
|
||
Session 业务规则：
|
||
|
||
- Remote CIDR 由 Engineer 用户在连接 Site 时输入并下发；Site 本地配置不预存现场网段。
|
||
- 一个 Engineer 同时最多一个处于 CREATING/PREPARING_SITE/ACTIVE 的 Site Session。
|
||
- 一个 Session 可携带多个 IPv4 CIDR，数据结构从第一天就使用数组。
|
||
- Site 底层允许同时服务多个 Engineer；通过 SessionID + Engineer Overlay IP 区分。
|
||
- 两个不同 Site 的 Remote CIDR 可以完全相同。
|
||
- 目标 CIDR 不得与 RemLink Overlay CIDR 重叠，不得与 Engineer 本地非 RemLink 网络发生任何前缀重叠。
|
||
- v1 禁止 0.0.0.0/0 Exit Node 模式。
|
||
|
||
Session 状态机 必须 为：CREATING → PREPARING_SITE → READY → ACTIVE → STOPPING → CLOSED，以及 FAILED（任一关键检查失败）。
|
||
|
||
Session 建立顺序 必须 为：Engineer GUI 选择 Site 并输入 CIDR → Engineer 本地冲突检查（失败不请求 Server）→ CREATE_SESSION → Server 校验（已有 Session/Site 在线/CIDR 合法性）→ Server 生成随机 64-bit SessionID、状态 PREPARING_SITE、向 Site 下发 PREPARE_SESSION → Site 对每个 CIDR 做 Windows Route Lookup 并检查 SubnetGateway 能力与 flow capacity → Site 返回 PREPARE_RESULT（含 subnet_gateway=netstack）→ Server 向 Engineer 返回 SESSION_CONFIG（SessionID、Site Overlay IP、Remote CIDRs、MTU、Session UDP Port）→ Engineer 添加 Windows Remote Routes 并启动 SessionTransport → Engineer 发送 ROUTES_READY → Server 置 ACTIVE 并通知 Site。
|
||
|
||
Session 数据包格式（两个方向统一）SHALL 为：
|
||
|
||
| 字段 | 长度 | 说明 |
|
||
|---|---|---|
|
||
| Magic | 4 bytes | ASCII: RMLK |
|
||
| Version | 1 byte | v1 = 1 |
|
||
| Type | 1 byte | v1 固定 0x01 = IPv4 |
|
||
| Flags | 2 bytes | v1 置 0 |
|
||
| SessionID | 8 bytes | Server 生成的 uint64 |
|
||
| PayloadLen | 2 bytes | 原始 IPv4 Packet 长度 |
|
||
| Reserved | 2 bytes | 置 0 |
|
||
| Payload | N bytes | 完整原始 IPv4 Packet |
|
||
|
||
不加入 TCP 风格序号/ACK/重传/拥塞控制；不做 TCP-over-TCP。WireGuard 已提供外层完整性和加密，不再增加自研加密或可靠 UDP。
|
||
|
||
Session 双向收包校验 必须 满足：
|
||
|
||
- Engineer 与 Site 都只在自己的 OverlayIP:6200 上监听 Session UDP，不监听公网地址或 0.0.0.0。
|
||
- 根据 SessionID 查找 Active Session。
|
||
- UDP 外层源 Overlay IP 必须等于该 Session 对端绑定的 Overlay IP（双向都校验）。
|
||
- Engineer→Site 方向内层 IPv4 Source 默认必须等于 Engineer Overlay IP（应用显式绑定其他物理源地址的流量不保证可用）。
|
||
- Engineer→Site：内层 Destination 必须属于 Session Remote CIDR；Site→Engineer：内层 Source 必须属于 Session Remote CIDR，Destination 必须等于 Engineer Overlay IP。
|
||
- IPv4 Total Length、版本和实际 Payload 长度必须一致。
|
||
- 校验失败直接丢弃并做限速安全日志。
|
||
|
||
#### 场景： Engineer 已有 Active Session 再连第二个 Site
|
||
|
||
- **当** Engineer 在 ACTIVE Session 期间请求连接另一个 Site
|
||
- **则** 拒绝并返回 ENGINEER_SESSION_EXISTS
|
||
|
||
#### 场景： 目标 CIDR 与本地网络冲突
|
||
|
||
- **当** Engineer 本机存在 192.168.0.0/16，用户输入 192.168.13.0/24
|
||
- **则** 本地冲突检查失败（前缀重叠），不向 Server 发起请求
|
||
|
||
### 需求： R5 Site Userspace Subnet Gateway（gVisor netstack）
|
||
|
||
Site 收到 Session UDP 后 必须 取出原始 IPv4 Packet，直接交给 gVisor netstack SubnetGateway（通过 channel.Endpoint.InjectInbound），不注入 Windows Wintun 做内核转发。gVisor netstack 负责 TCP/UDP 连接状态和报文重建；RemLink 不实现 TCP 状态机。现场侧实际出站使用 Windows 普通 host socket（net.Dial / UDPConn），目标设备看到的源地址是 Site 的现场可达地址。
|
||
|
||
- v1 不创建 Transit CIDR，不创建 RemLinkNAT，不要求 PLC/网关认识 Overlay 网段。
|
||
- 能力边界：v1 明确支持 TCP、单播 UDP 和 ICMP Echo（Ping）；IP 广播/组播、SCTP、GRE、ESP 及其他非 TCP/UDP IP 协议不在保证范围。
|
||
- SubnetGateway 接口：
|
||
|
||
```go
|
||
type SubnetGateway interface {
|
||
Prepare(ctx context.Context, cfg SessionConfig) error
|
||
InjectIPv4(ctx context.Context, sessionID uint64, packet []byte) error
|
||
CloseSession(ctx context.Context, sessionID uint64) error
|
||
}
|
||
// v1 default / only backend: GVisorNetstackBackend
|
||
```
|
||
|
||
- 优先直接依赖 upstream gVisor netstack 并固定 commit；可参考 Tailscale wgengine/netstack（BSD-3-Clause）实现模式，但不得引入整个 Tailscale 控制面。未来 Kernel/NAT Backend 必须保持接口不变。
|
||
- TCP Relay：gVisor netstack 接收 Engineer 的 SYN，创建 Engineer-facing TCP endpoint；RemLink 使用 host net.Dial("tcp", target) 建立 Site→PLC 连接，以 io.CopyBuffer 双向搬运字节；不做应用协议识别。
|
||
- UDP Relay：按 SessionID + Engineer 源/目标五元组维护轻量 flow mapping；每个 flow 使用 host UDPConn 与现场目标通信，收到回复后写回 gVisor UDP endpoint；flow 使用可配置 idle timeout 做 GC。
|
||
- 返回包必须使用 Session 封装（对称封装，v1 强制设计）：gVisor netstack 生成面向 Engineer 的 IPv4 响应包（SRC=现场 IP → DST=Engineer Overlay IP）后，Site 必须将其再封装成 Session UDP（Outer SRC=Site Overlay IP，Outer DST=Engineer Overlay IP，Payload=SessionHeader+RawIPv4）；不得把该 Raw Packet 直接交给 WireGuard（Server 对 Site Peer 的 AllowedIPs 只有 /32，源地址会被 cryptokey routing 拒绝）。Engineer SessionListener 校验后将 Raw IPv4 写入本机 Wintun 入站方向；Windows 最终看到 SRC=现场 IP、DST=Engineer Overlay IP。
|
||
- ICMP Echo Relay：v1 只支持 Echo Request/Reply；收到 Echo Request 后由 PingRelay 使用成熟 ICMP 库或受控系统 ping 从 Site 探测目标；目标响应后构造与原请求 ID/Sequence 对应的 Echo Reply Raw IPv4 经 SessionTransport 返回 Engineer；其他 ICMP 类型不支持。
|
||
- Site PREPARE 时 必须 对每个目标 CIDR 做 Windows Route Lookup：DIRECT（直连）允许；ROUTED（明确静态/动态路由）允许；DEFAULT_ONLY（仅默认路由）默认拒绝；NO_ROUTE 拒绝（SITE_NO_ROUTE）；OVERLAY_CONFLICT 拒绝。
|
||
- 建议初始 flow 上限（均可配置）：TCP 2048 flows、UDP 4096 flows、UDP idle timeout 60s。
|
||
|
||
#### 场景： 现场设备返回路径
|
||
|
||
- **当** PLC 192.168.13.10 响应 Site host socket 的连接
|
||
- **则** Site 经 gVisor netstack 生成面向 Engineer 的 Raw IPv4，再以 SessionHeader 封装经 UDP 发往 Engineer Overlay IP；PLC 无需任何 Overlay 返回路由
|
||
|
||
### 需求： R6 控制面与节点协议
|
||
|
||
系统 必须 分离 Bootstrap 与正常 Control：
|
||
|
||
- Bootstrap（公网 HTTP）：`http://SERVER_IP:8080/api/v1/bootstrap/...`
|
||
- WireGuard：`SERVER_IP:51820/udp`
|
||
- Control（仅 Overlay）：`ws://10.88.0.1:7001/control`
|
||
|
||
节点第一次启动无 WireGuard 时使用公网 Bootstrap API 获取 Overlay IP、Server WireGuard PublicKey 和 Endpoint；建立 WireGuard 后所有控制消息走 Overlay 内 Control WebSocket。
|
||
|
||
Node 身份 必须 包含：NodeID（UUID，首次运行生成并持久化）、NodeType（engineer/site）、NodeName、WireGuard PrivateKey（本地生成，仅本机保存）、WireGuard PublicKey（注册时提交 Server）、NodeToken（Server 注册成功后生成，用于后续身份验证；不是用户系统）。
|
||
|
||
Windows 本地敏感字段（WG PrivateKey、NodeToken）SHALL 优先使用 Windows DPAPI 保护后落盘，不以明文 YAML 保存私钥；为简化自用部署，首次注册 Join Token 可以明文保存在 Engineer/Site YAML 中。Server PrivateKey 保存到数据目录并设置严格文件权限。
|
||
|
||
Server 必须 维护可轮换 Join Token：新 Node 注册必须提供 Join Token；注册成功后改用 NodeToken。v1 不实现 HTTPS，公网 Bootstrap/管理 HTTP 的机密性不由 TLS 提供，作为部署边界在文档中说明。
|
||
|
||
Heartbeat 参数（默认值）：interval 5s；ONLINE=最近心跳 ≤15s；UNSTABLE=15–30s；OFFLINE=>30s；Reconnect backoff=1s,2s,5s,10s,30s 上限。
|
||
|
||
### 需求： R7 Server 设计
|
||
|
||
Server 必须 承担：Bootstrap API 和 Web UI、IPAM/Node Registry/Node Token、Linux Kernel WireGuard interface 和 Peer 编排（wgctrl）、Control WebSocket Hub、Session Manager、节点/Session 统计聚合、SQLite 持久化和日志查询；不逐包处理 WireGuard Overlay 数据。
|
||
|
||
Server wg0 必须 配置 Address 10.88.0.1/16（随 Overlay CIDR）、ListenPort 51820；每个 Node Peer 的 AllowedIPs 为其 Overlay /32。Linux 必须启用 IPv4 forwarding 并允许 wg0→wg0 转发；Server 不对 Overlay 做 SNAT。v1 不同时实现 kernel WireGuard 与 wireguard-go 两套 Server Backend。
|
||
|
||
Docker Compose 基线 必须 只授予 NET_ADMIN（不用 privileged: true），映射 /dev/net/tun、51820/udp、8080/tcp，挂载 ./data:/app/data，sysctls net.ipv4.ip_forward=1。镜像启动 Preflight 必须检查内核 WireGuard 能否创建接口；失败时明确报错并退出，不静默切换。
|
||
|
||
Web UI 必须 提供五个页面：
|
||
|
||
| 页面 | 核心内容 |
|
||
|---|---|
|
||
| Dashboard | Uptime、Overlay CIDR、在线 Engineer/Site、Active Session、流量 |
|
||
| Nodes | 名称、类型、Overlay IP、WG PublicKey 摘要、Handshake、App 状态、版本、LastSeen |
|
||
| Sessions | Engineer、Site、Remote CIDRs、状态、上下行流量、持续时间、强制断开 |
|
||
| Network | Overlay CIDR、Server IP、WG Port、Join Token 轮换 |
|
||
| Logs | 按时间/级别/模块/Node/Session 过滤事件 |
|
||
|
||
### 需求： R8 Engineer 设计
|
||
|
||
Engineer 进程（RemLinkEngineer.exe）SHALL 包含：Wails GUI、Bootstrap/Control Client、Node Identity Store、Wintun Adapter Manager、MuxTun/PacketMux、wireguard-go Device、Session Manager、SessionTransport（UDP Sender + Listener）、RouteManager、Stats、Logging。
|
||
|
||
GUI 必须 提供：Server 公网地址/Overlay 状态/本机虚拟 IP/Control 状态/版本显示；全部 Site 列表（Name、Overlay IP、Online、RemoteSubnetCapability、LastSeen）；选择 Site 后输入一个或多个 CIDR；连接前执行本地 CIDR 冲突检查；连接后显示 SessionID、目标 Site、CIDR、上传/下载、包数、时延和日志；Active Session 时禁止再选择第二个 Site。
|
||
|
||
Session READY 后 Engineer 必须 为每个 Remote CIDR 增加指向 RemLink Adapter 的 Windows 路由，由 RouteManager 统一创建并带 RemLink ownership metadata/本地状态记录以便异常恢复。不得通过降低 Metric 强抢冲突路由；发现 Remote CIDR 与本机现有非 RemLink 直连/静态/VPN 前缀重叠时直接拒绝建立 Session。
|
||
|
||
应用显式绑定网卡的情况：普通 Socket 由 Windows 根据 Remote Route 选择 RemLink Adapter；显式绑定物理网卡或固定源 IP 的工业软件不完全透明，应在其网络接口选择中选择 RemLink Adapter；v1 不增加源地址改写。
|
||
|
||
### 需求： R9 Site 设计
|
||
|
||
Site 进程（RemLinkSite.exe，Console）SHALL 包含：Bootstrap/Control Client、Node Identity Store、Wintun Adapter Manager、MuxTun/PacketMux、wireguard-go Device、UDP Session Listener :6200（Overlay only）、gVisor Netstack SubnetGateway、TCP/UDP/Ping Relay、Route Inspector、Flow Manager/Stats、Logging。
|
||
|
||
Site 启动能力检测 必须 按 7 步执行：加载 Node Identity 并获取 Server NetworkConfig → 检查 Overlay CIDR 与本地直连网络冲突 → 创建/复用 RemLink Wintun 并配置 Overlay IP/Prefix/MTU → 启动 wireguard-go 并等待 Server Overlay 可达 → 初始化 gVisor netstack SubnetGateway（TCP/UDP forwarder 与 flow limits；无需检查或修改 WinNAT）→ 启动仅绑定 OverlayIP:6200 的 Session UDP Listener（同一端口承载双向）→ 连接 Control WebSocket 并报告能力、OS、版本、netstack 状态与 flow capacity。
|
||
|
||
Console 输出 必须 展示 Server、Node、Overlay IP、WireGuard/Control/Remote Subnet/SubnetGateway 状态及 SESSION/ROUTE 事件。
|
||
|
||
### 需求： R10 数据库与数据模型
|
||
|
||
Server 必须 使用单 SQLite 数据库文件（如 /app/data/remlink.db），database/sql + 稳定 SQLite Driver，迁移采用成熟 migration 工具或嵌入 SQL migration 文件，不在代码中散落 CREATE TABLE。
|
||
|
||
核心表 必须 包含：
|
||
|
||
| 表 | 关键字段 |
|
||
|---|---|
|
||
| settings | key, value, updated_at |
|
||
| nodes | node_id, type, name, overlay_ip, wg_public_key, node_token_hash, status, version, os_version, last_seen |
|
||
| sessions | session_id, engineer_node_id, site_node_id, status, created_at, active_at, closed_at, error_code |
|
||
| session_cidrs | session_id, cidr |
|
||
| session_stats | session_id, tx_bytes, rx_bytes, tx_packets, rx_packets, updated_at |
|
||
| event_logs | time, level, module, node_id, session_id, message, fields_json |
|
||
|
||
Windows Node 不使用 Server SQLite；Engineer 与 Site 必须作为完全独立的便携式包发布，持久状态放在各自 EXE 所在目录，且不得共用运行文件。敏感字段用 DPAPI，至少保存 NodeID、NodeToken、WireGuard PrivateKey、Server URL、NodeName、最后一次 NetworkConfig 版本，以及 RemLink 创建过的路由状态用于 Reconcile。
|
||
|
||
### 需求： R11 API 与消息定义
|
||
|
||
Public Bootstrap API 必须 提供：GET /api/v1/server/info（Server ID、版本、WG Endpoint、Bootstrap 信息）、POST /api/v1/bootstrap/register（首次 Node 注册）、POST /api/v1/bootstrap/config（已注册 Node 用 NodeID+NodeToken 拉取最新 NetworkConfig）。
|
||
|
||
Admin Web API 必须 提供：GET /api/v1/admin/nodes；PATCH /api/v1/admin/nodes/{id}（改名/改 Overlay IP）；DELETE /api/v1/admin/nodes/{id}（撤销 Node）；GET /api/v1/admin/sessions；POST /api/v1/admin/sessions/{id}/disconnect（强制断开）；GET /api/v1/admin/network；PUT /api/v1/admin/network；GET /api/v1/admin/logs。v1 不做用户系统；如需保护仅实现可选的单一 Admin Token，不设计账户/角色体系。
|
||
|
||
Control WebSocket 消息 必须 包含：
|
||
|
||
| Type | 方向 | 关键字段 |
|
||
|---|---|---|
|
||
| HELLO | Node→Server | node_id, node_token, config_version, capabilities |
|
||
| WELCOME | Server→Node | server_time, network_config_version |
|
||
| NODE_LIST | Server→Engineer | sites[] |
|
||
| CREATE_SESSION | Engineer→Server | site_node_id, target_cidrs[] |
|
||
| PREPARE_SESSION | Server→Site | session_id, engineer_overlay_ip, target_cidrs[] |
|
||
| PREPARE_RESULT | Site→Server | ok, route_results[], subnet_gateway_status, tcp_capacity, udp_capacity, error |
|
||
| SESSION_CONFIG | Server→Engineer | session_id, peer_overlay_ip, cidrs[], mtu, udp_port |
|
||
| ROUTES_READY | Engineer→Server | session_id |
|
||
| SESSION_ACTIVE | Server→Engineer/Site | session_id |
|
||
| STOP_SESSION | 任意→Server / Server→Node | session_id, reason |
|
||
| SESSION_STATS | Engineer/Site→Server | cumulative counters |
|
||
| HEARTBEAT | 双向 | timestamp/status |
|
||
| REBOOTSTRAP_REQUIRED | Server→Node | config_version, reason |
|
||
|
||
错误码基线 必须 包含：SERVER_UNREACHABLE、JOIN_TOKEN_INVALID、NODE_AUTH_FAILED、OVERLAY_LOCAL_CONFLICT、ENGINEER_SESSION_EXISTS、SITE_OFFLINE、CIDR_INVALID、CIDR_LOCAL_CONFLICT、CIDR_OVERLAY_CONFLICT、SITE_NO_ROUTE、NETSTACK_UNAVAILABLE、FLOW_LIMIT_REACHED、SESSION_TIMEOUT、SESSION_INJECT_FAILED。
|
||
|
||
### 需求： R12 路由冲突、异常与恢复
|
||
|
||
Engineer 本地 CIDR 冲突算法 必须 使用 net/netip 做真正的 Prefix overlap（不使用字符串比较）：收集 Windows 有效路由和所有非 RemLink 直连前缀；默认路由 0.0.0.0/0 不作为冲突依据；任何更具体的现有本地/VPN 路由只要与 Remote CIDR 有重叠即拒绝。
|
||
|
||
Reconcile 规则：
|
||
|
||
- Engineer 启动时检查 RemLink Adapter 上由自身记录创建但没有对应 Active Session 的 Remote Routes，删除残留。
|
||
- Site 启动时初始化/重建 userspace SubnetGateway；不检查、不创建、不删除任何 Windows NAT。
|
||
- Site 清理上次异常退出遗留的 userspace flow/session 状态；Windows 系统路由、NAT、Forwarding 不需要恢复。
|
||
- Wintun Adapter 可复用，不要求每次退出删除；卸载/显式清理时再删除。
|
||
|
||
Server 重启后所有 Remote Session 必须 直接标记 CLOSED，不实现透明 Session Resume；Node 的 wireguard-go/Control 自动重连，Engineer 用户重新点击连接，Site userspace flow 随 Session 关闭并清理。
|
||
|
||
网络切换（Wi-Fi→网线/热点）时由 WireGuard 正常 roaming/重新握手处理；客户端只配置 Server 固定 Endpoint，Server Peer Endpoint 由 WireGuard 根据握手学习；Control WebSocket 断线使用指数退避重连。
|
||
|
||
### 需求： R13 日志、统计与可观测性
|
||
|
||
日志模块 必须 分为：CORE、BOOTSTRAP、WG、IPAM、CONTROL、SESSION、ROUTE、NETSTACK、TUN、SUBNET、SYSTEM。高频 packet 日志默认关闭；DEBUG 也禁止逐包打印 Payload，只允许限速采样（防止 PLC 下载/RDP 时写满磁盘）。
|
||
|
||
Session 流量统计 必须 以 Engineer 视角定义：Upload=Engineer→Site LAN，Download=Site LAN→Engineer；Engineer PacketMux 在拦截 Remote 出包时累计上传，Engineer SessionListener 在校验并注入 Remote Reply 前累计下载；每 5 秒向 Server 上报累计值。Server 不为了统计进入 WireGuard packet path；节点层 WireGuard 总流量可由 wgctrl 读取作为辅助指标。
|
||
|
||
### 需求： R14 安全边界
|
||
|
||
- WireGuard 负责公网数据通道加密、认证和完整性；RemLink 不重复实现。
|
||
- 每个 Node 独立 WireGuard KeyPair；PrivateKey 不上传 Server。
|
||
- Server WireGuard Peer 只允许该 Node 的 /32 Overlay IP，防止节点伪造其他 Overlay Source。
|
||
- Engineer 与 Site 的 Session UDP Listener 都只绑定 Overlay 地址，并按方向校验 SessionID、Outer Source、Inner Source/Target CIDR、Inner Destination。
|
||
- Join Token 仅用于首次加入；NodeToken 用于应用层身份。
|
||
- v1 按需求不实现 HTTPS；公网暴露时可由外部反向代理/防火墙补充，但不是 v1 内核功能。
|
||
- 绝不自动关闭 Windows Firewall；如需要规则，只创建带 RemLink 前缀、可识别且可回滚的规则。
|
||
|
||
### 需求： R15 项目结构、关键接口与依赖管理
|
||
|
||
Monorepo 结构 必须 为：
|
||
|
||
```
|
||
remlink/
|
||
├─ cmd/
|
||
│ ├─ server/
|
||
│ ├─ engineer/
|
||
│ └─ site/
|
||
├─ internal/
|
||
│ ├─ model/
|
||
│ ├─ protocol/
|
||
│ ├─ config/
|
||
│ ├─ identity/
|
||
│ ├─ ipam/
|
||
│ ├─ control/
|
||
│ ├─ session/
|
||
│ ├─ subnet/
|
||
│ │ ├─ header.go
|
||
│ │ ├─ sender.go
|
||
│ │ ├─ listener.go
|
||
│ │ └─ validator.go
|
||
│ ├─ overlay/
|
||
│ │ ├─ clientwg/
|
||
│ │ │ ├─ device.go
|
||
│ │ │ ├─ muxtun.go
|
||
│ │ │ └─ adapter.go
|
||
│ │ └─ serverwg/
|
||
│ ├─ platform/
|
||
│ │ ├─ windows/
|
||
│ │ │ ├─ route/
|
||
│ │ │ ├─ netinfo/
|
||
│ │ │ ├─ socket/
|
||
│ │ │ └─ dpapi/
|
||
│ │ └─ linux/
|
||
│ │ └─ netlink/
|
||
│ ├─ subnetgateway/
|
||
│ │ ├─ netstack/
|
||
│ │ ├─ tcprelay/
|
||
│ │ ├─ udprelay/
|
||
│ │ └─ pingrelay/
|
||
│ ├─ database/
|
||
│ ├─ logging/
|
||
│ └─ stats/
|
||
├─ frontend/
|
||
│ ├─ server/
|
||
│ └─ engineer/
|
||
├─ deploy/docker/
|
||
└─ docs/
|
||
```
|
||
|
||
关键接口 必须 为：
|
||
|
||
```go
|
||
type RouteManager interface {
|
||
AddRemote(prefix netip.Prefix, ifIndex uint32) error
|
||
RemoveRemote(prefix netip.Prefix) error
|
||
Conflicts(prefix netip.Prefix) ([]RouteConflict, error)
|
||
Lookup(dst netip.Addr) (RouteInfo, error)
|
||
}
|
||
|
||
type SubnetGateway interface {
|
||
Prepare(ctx context.Context, cfg SessionConfig) error
|
||
InjectIPv4(ctx context.Context, sessionID uint64, packet []byte) error
|
||
CloseSession(ctx context.Context, sessionID uint64) error
|
||
}
|
||
|
||
type SessionTransport interface {
|
||
SendIPv4(sessionID uint64, peer netip.Addr, packet []byte) error
|
||
}
|
||
```
|
||
|
||
MuxTun 约束：必须实现所固定 wireguard-go 版本的 tun.Device 接口，go.mod 锁定 wireguard-go commit/version，升级前先跑 MuxTun Windows POC；base Device 的 Name/MTU/Events/BatchSize 按原语义代理；Read 方向负责 OS→WireGuard 分类；Write 方向负责 WireGuard→Windows 原样写入（Engineer SessionReceiver 的 Remote Reply 也通过统一 Wintun inbound writer 注入；Site netstack 数据不注入 Windows Wintun）；Close 必须可幂等，并使所有 goroutine 退出。
|
||
|
||
依赖管理：所有 Go module、NPM package、Wintun DLL、gVisor commit 均固定版本/commit，禁止生产构建使用 latest 浮动依赖（gVisor netstack API 不保证稳定，升级必须经过 POC）；Wintun DLL 使用 go:embed 打入 EXE，首次运行释放到当前角色 EXE 所在目录，不得通过 `%ProgramData%` 在 Engineer 与 Site 之间共享；发布包提供 THIRD_PARTY_NOTICES（WireGuard/Wintun/gVisor 及参考复用代码许可证，如直接采用 Tailscale 代码片段遵循其 BSD-3-Clause）；Windows Engineer 与 Site 都要求管理员权限（创建 Wintun、配置接口/路由；Site v1 不修改 WinNAT 或 IP Forwarding）。
|
||
|
||
### 需求： R16 阶段化开发与验收
|
||
|
||
开发 必须 按 Phase 0–10 顺序执行（详见 tasks.md），每阶段通过明确验收后才进入下一阶段；先完成 Phase 1–7 网络 Gate，再投入完整 GUI。Gate A–D 为关键关卡：
|
||
|
||
- Gate A：wireguard-go 能通过 MuxTun 使用唯一 Wintun，正常 Overlay 通信。
|
||
- Gate B：Remote Packet 被 MuxTun 截获后，普通 UDP Socket 的外层 Overlay Packet 能通过同一 Wintun 再进入 WireGuard，不死锁、不无限循环。
|
||
- Gate C：Site 收到 Session Raw IPv4 后能注入 gVisor netstack；TCP/UDP Forwarder 能建立 host socket 到现场目标并完成双向数据搬运。
|
||
- Gate D：gVisor netstack 能把返回数据重新构造成 Engineer 看到的原始目标 IP 流，并通过 Session UDP 反向封装回 Engineer；Ping Relay 能正确返回 ICMP Echo Reply。
|
||
|
||
最终验收 必须 通过规格书第 19 章 T01–T18 全部场景（详见 checklist.md）。测试 TCP/102、TCP/502、HTTP、RDP、ICMP Echo、UDP 的目的是证明通用 TCP/UDP/Ping userspace gateway 成立；生产代码中禁止出现 S7Proxy、ModbusProxy、HTTPProxy 等应用协议专用模块；PingRelay 是唯一明确的 ICMP Echo 诊断模块。
|
||
|
||
## 修改需求
|
||
|
||
无（绿地项目）。
|
||
|
||
## 删除需求
|
||
|
||
无（绿地项目）。
|