# VirtualPort虚拟WAN插件白皮书

## 1.执行摘要

VirtualPort是一款面向iKuaiOS的虚拟WAN插件。它把一个代理节点封装成一张可以被iKuai策略路由识别和使用的虚拟网卡，使管理员能够像管理多条WAN线路一样，为不同业务、设备或策略分配不同的代理出口。

它解决的不是“在浏览器里开一个代理端口”，而是把代理能力下沉到路由器的三层转发路径：

```mermaid
flowchart LR
    A[终端或业务流量] --> B[iKuai策略路由]
    B --> C[虚拟WAN wan10000~wan99999]
    C --> D[TAP+Bridge]
    D --> E[VirtualPort用户态数据面]
    E --> F[绑定代理节点]
    F --> G[真实物理WAN]
    G --> H[目标网络]
```

核心产品模型是：

> 一张虚拟WAN绑定一个代理节点；iKuai负责策略路由，VirtualPort负责虚拟接口和代理数据面。

## 2.产品价值

### 2.1把代理出口变成可编排的网络资源

传统代理通常需要在终端逐台配置HTTP/SOCKS代理。VirtualPort将代理出口映射为路由器上的虚拟WAN，管理员可以继续使用iKuai已有的策略路由、WAN选择和业务分流能力。

### 2.2实现一节点一网口

每个VirtualPort实例独占：

- 一个稳定的`wanN`虚拟WAN标识；
- 一个TAP设备；
- 一个Linux bridge；
- 一组/31点到点地址；
- 一个代理节点绑定；
- 一个真实物理WAN上联出口。

因此不同业务可以通过不同虚拟WAN进入不同节点，互不覆盖配置。

### 2.3适合复杂出口编排

支持将一个虚拟WAN的上联设置为另一张VirtualPort虚拟WAN，从而形成代理链，例如：

```text
本地业务 → wan10000 → 香港节点 → wan10001 → 新加坡节点 → 目标网络
```

代码通过`BuildBindings`生成独立的派生代理适配器，并用DFS检测环路，避免`wan10000→wan10001→wan10000`造成无限递归。

### 2.4每卡独立的流量策略

VirtualPort的策略作用于单张虚拟WAN：

- 封禁UDP；
- UDP/443限制，用于限制QUIC；
- WebRTC相关端口限制；
- 上传限速；
- 下载限速；
- UDP强制使用UDP-over-TCP（前提是节点协议支持）。

限速在用户态转发层实现，TCP和UDP分别经过token bucket控制，不依赖终端支持。

## 3.技术架构

### 3.1资源层

`New`负责建立bridge、打开TAP、将TAP加入bridge、设置三组不同的MAC地址、配置MTU和/31地址，并将接口置为UP。

三组MAC必须不同：

|对象|用途|
|---|---|
|gVisor网关MAC|对外回答ARP、代表用户态网关|
|bridge MAC|iKuai侧虚拟WAN接口|
|TAP MAC|内核TAP端口|

这是解决Linux bridge吞掉发往网关MAC的ARP帧的关键设计。

### 3.2数据面

`Datapath`使用gVisor netstack和TAP文件描述符：

- 注册IPv4和ARP协议；
- 注册TCP和UDP转发器；
- 对iKuai发来的ARP请求回答网关MAC；
- TCP连接建立后，通过绑定的代理节点拨号并双向转发；
- UDP会话通过`ListenPacket`建立代理侧PacketConn并转发；
- UDP空闲5分钟回收；
- TCP连接具备KeepAlive；
- TAP由gVisor接管，关闭时释放FD和协议栈。

### 3.3代理节点层

节点以mihomo proxy map形式持久化为JSON，再渲染为`proxies:` YAML并加载到mihomo tunnel。

VirtualPort不启动mihomo的全局监听器、DNS或TUN，也不依赖ProxyFlow进程；它只使用mihomo作为协议适配后端，通过`DialContext`和`ListenPacketContext`为每个VirtualPort拨号。

### 3.4WAN注册层

插件将虚拟WAN写入iKuai的`wan_config`：

```text
bandeth=vnet
name=wan10000~wan99999
default_route=0
```

写入后调用官方`wan.sh init`刷新WAN缓存。虚拟WAN不会成为系统默认路由，真实物理WAN被保护为默认出口。

### 3.5持久化和恢复

配置持久化在`/etc/log/virtualport`：

```text
config.json    # 虚拟WAN期望状态
nodes.json     # 代理节点列表
```

启动时先加载manifest、迁移历史命名、按ownership alias清理旧资源，再使用相同名称重建接口和WAN记录。资源归属不是依赖`ikvp-`前缀，而是依赖内核link alias中的`virtualport:<id>`标记。

## 4.管理能力

HTTP管理API提供：

|能力|接口|
|---|---|
|虚拟WAN列表|`GET /api/v1/virtual-ports`|
|创建虚拟WAN|`POST /api/v1/virtual-ports`|
|修改虚拟WAN|`PUT /api/v1/virtual-ports`|
|删除虚拟WAN|`DELETE /api/v1/virtual-ports?id=...`|
|健康探测|`POST /api/v1/virtual-ports/probe?id=...`|
|节点列表|`GET /api/v1/nodes`|
|添加SOCKS5节点|`POST /api/v1/nodes`|
|批量导入节点|`POST /api/v1/nodes/import`|
|上联接口列表|`GET /api/v1/interfaces`|

普通创建界面只要求名称、上联接口和目标节点；地址池、/31地址、MTU等由系统自动分配，降低误配置概率。

## 5.安全和可靠性设计

### 5.1防止路由黑洞

- 强制拒绝`default_route=true`；
- 虚拟WAN的数据库字段设置`default_route=0`；
- 保护物理WAN默认路由；
- 禁止把自身TAP、bridge或其他LAN/VLAN作为代理上联；
- 禁止代理服务器地址经自身VirtualPort回流；
- 建立数据面前检查节点和上联配置。

### 5.2防止资源误删

恢复逻辑只删除同时满足以下条件的资源：

1.名称匹配manifest；
2.接口存在；
3.alias确认属于对应VirtualPort ID。

同名但alias不匹配时拒绝删除。这避免插件误删物理接口或其他系统组件创建的接口。

### 5.3防止代理链环路

每次创建和修改之前，先模拟新的端口集合，重新计算`dialer-proxy`关系并做DFS环检测；有环时在修改任何系统状态前返回错误。

### 5.4原子配置保存和失败回滚

节点JSON使用临时文件、fsync和rename保存。修改已有VirtualPort时先保存旧配置，创建新资源失败则重新应用旧配置。

## 6.当前实现状态与真实边界

### 已实现或代码中已有明确设计

- x64/arm64纯Go交叉编译路径；
- TAP+bridge资源创建；
- /31地址池，最多256个VirtualPort；
- 独立节点绑定；
- TCP/UDP用户态转发框架；
- SOCKS5节点添加和批量导入；
- UoT能力校验；
- 代理链和环检测；
- 健康探测和延迟显示；
- 每卡上传/下载限速；
- ownership alias和manifest恢复；
- iKuai WAN数据库注册与刷新；
- Web管理界面和API。

### 不能过度宣传的部分

- 源码已按项目流程同步到GitLab；正式构建、依赖版本和双架构制品应以GitLab源码及对应构建记录为准；
- 代码中的数据面集成测试存在，但是否在82上完成了每种协议的端到端验收，要以独立设备记录为准；
- 健康探测成功只能证明该VirtualPort经节点访问指定HTTP目标成功，不能证明所有网站、所有协议都可用；
- UDP吞吐能力必须使用从VirtualPort路径可达的第二台iperf3服务器验证，不能用同机公网回环代替；
- 代理节点协议能力由mihomo适配器决定，SOCKS5不等于天然支持UDP；
- VirtualPort不是完整的代理订阅管理平台，也不是独立的全局透明代理开关；
- `default_route=0`必须在设备最终路由表中复核，不能只看数据库字段。

## 7.目标用户和商业场景

|场景|使用方式|
|---|---|
|多WAN出口编排|将不同业务策略绑定到不同VirtualPort|
|企业分支或实验室|为指定设备组提供独立代理出口|
|跨境电商工作台|不同店铺/业务线使用不同固定出口|
|内容发布和直播|将工作站流量固定到指定节点，降低出口漂移|
|自动化任务|按业务容器、设备或目标网段选择不同虚拟WAN|
|代理链路实验|用多个VirtualPort拼接多级代理链|
|网络产品集成|把代理能力作为iKuai策略路由可调用的网络资源|

## 8.后续产品化建议

1.补齐独立Go module、可复现依赖锁定和完整构建证据；
2.把资源状态、数据面状态、节点健康状态分开显示；
3.在UI中明确“接口已创建”与“代理节点可用”的区别；
4.提供配置导出/导入和版本迁移；
5.为每个VirtualPort显示实际节点、上联WAN、地址、RTT和流量；
6.增加第二台外部iperf3服务器进行TCP/UDP性能回归；
7.补充崩溃、SIGTERM、硬重启后的恢复测试；
8.在正式发布前验证`naixi stop`或AppMarket生命周期是否确实清除所有WAN、bridge、TAP和策略路由残留；
9.提供审计日志，记录创建、修改、删除、恢复和回滚；
10.把客户可见协议文案收敛为“代理节点”“YAML配置”“网络出口”，隐藏不必要的实现细节。

## 9.一句话定位

> VirtualPort把代理节点转换成iKuai可以识别、编排和分流的独立虚拟WAN，让每个业务获得清晰、可控、可回收的专属网络出口。