# 任务 #11 libbox 桥接方案

> 任务链：11A（本文，数据面定稿） → 11C（Dart 桥接 PoC） → 11D/11E/11F（隧道/DNS/路由验证） → 11H（M6 联调）

---

## 关键技术选型 —— 数据面协议决策记录

**日期**：2026-06-13  
**状态**：已定稿（tsk_9uMrd9kUpmVA）  
**影响范围**：#5/#6（控制面 connect 接口实现）· 11C（客户端桥接 PoC）· 11H（M6 联调）

### 背景

`design/server/ARCHITECTURE.md` 初稿（v0.1）将数据面定为 **WireGuard**（peer 注册模式，
节点 agent 下发 endpoint/pubkey/内网 IP/DNS）。但实际情况如下：

- **现网基础设施**（`deploy/`）已运行 sing-box Hysteria2（UDP/443）和 xray
  VLESS+REALITY（TCP/11443），两协议均已通过 phase-0 线路验证（晚高峰 YouTube 1080p
  流畅、REALITY 未见主动探测封锁）。
- **客户端路线图**（`plan/phase-3-自研与规模化.md`）明确以 **sing-box libbox（gomobile）**
  作为 Flutter 端隧道内核，libbox 原生支持 REALITY/Hy2/WireGuard 三种出站，无需额外
  桥接层。
- WireGuard 在 iOS/macOS 沙盒环境下依赖 Network Extension，而 libbox TUN 模式同样需要
  Network Extension，且 libbox 已统一抽象平台差异。

### 备选方案对比

| 方案 | 优点 | 缺点 |
|------|------|------|
| **A. WireGuard peer 注册（原方案）** | 内核级性能；行业标准 | 需独立 wintun（Win）/ NEPacketTunnel（iOS）；与现网基础设施不兼容；节点 agent 需实现 peer CRUD | 
| **B. 订阅链接下发（Clash/sing-box URL）** | 服务端极简 | 客户端需内置订阅解析器或依赖三方 App；改品牌客户端难精控格式 |
| **C. libbox + 完整 config JSON 下发**（本方案） | 复用现网 REALITY/Hy2 基础设施；libbox 三协议皆支持；客户端零组装；gomobile 跨 iOS/Android/Desktop；WireGuard 可作 outbound 随时补加 | 服务端需按订阅/设备生成完整 JSON；节点 agent 由 peer 注册改为凭证上报 |

### 结论

采用 **方案 C：libbox 统一承载 REALITY/Hy2 outbound**（必要时追加 WireGuard outbound）。

核心理由：**最不后悔原则** —— libbox 三协议皆支持，现网基础设施零改动，客户端接入
最简，未来切换协议只需修改服务端生成的 JSON，架构不动。

### 影响面

| 组件 | 变更 |
|------|------|
| `ARCHITECTURE.md §0` | 数据面描述：WireGuard → sing-box libbox (REALITY/Hy2) |
| `ARCHITECTURE.md §1` | 拓扑图：wireguard+agent → singbox+agent |
| `ARCHITECTURE.md §3` | connect 响应：WireGuard 配置 → 完整 sing-box config JSON |
| `ARCHITECTURE.md §4.3` | 连接流程：peer 注册 → config JSON 下发 |
| 节点 agent 职责 | 由 WireGuard peer CRUD → 向控制面注册节点凭证（REALITY 公钥/Hy2 口令）|
| 客户端（11C） | 接收 JSON 后原样传入 `libbox.start(configJson)`，不做任何组装 |
| #5/#6 | connect 接口响应体按 §3.1 规范实现 |
| 11H M6 联调 | 以本契约为准，不依赖旧 WireGuard 格式 |

---

## §3.1 详细契约（摘要见 ARCHITECTURE.md §3）

完整规范见 `design/server/ARCHITECTURE.md §3` 及 §3.1 子节。

示例配置文件：`doc/plans/client-connect-config.example.json`

> PoC 阶段（11D/11E/11F）可本地直接使用示例文件，不依赖控制面；11H 联调时切换到
> 控制面动态下发。