tsk_9uMrd9kUpmVA: 数据面定稿 + 修订 ARCHITECTURE.md connect 契约

决策：libbox 统一承载 REALITY/Hy2 outbound（方案 C），弃用 WireGuard peer 注册。现网 deploy/ 基础设施（singbox Hy2 + xray REALITY）已验证，零改动复用。变更文件： - design/server/ARCHITECTURE.md v0.2： · §0 数据面描述改为 sing-box libbox (REALITY/Hy2) · §1 拓扑图更新（wireguard+agent → singbox+agent，客户端标注 libbox 内嵌） · §2 devices 表移除 pubkey；nodes 表改为 reality_public_key/short_id/uuid/hy2_password · §3 connect 响应由 WireGuard 配置改为完整 sing-box config JSON · §3.1（新增）connect 契约详细规范：四块 inbounds/outbounds/route/dns、客户端透传原则、字段与 deploy/ 模板逐字段对照、占位符替换说明 · §4.3 连接流程更新（peer 注册 → config JSON 渲染下发） · 附录 A（新增）v0.1→v0.2 变更汇总 - doc/plans/11-libbox-bridge.md（新建）：完整决策记录（背景/备选/结论/影响面），任务链 11A→11C→11D/E/F→11H - doc/plans/client-connect-config.example.json（新建）：最小示例 config，字段与 deploy/ 模板对齐，可用 sing-box check -c 校验 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-06-13 01:43:17 +08:00
parent a642bf16a2
commit ab2bbaf683
3 changed files with 278 additions and 32 deletions
@@ -0,0 +1,64 @@
+# 任务 #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 联调时切换到
+> 控制面动态下发。
@@ -0,0 +1,99 @@
+{
+  "log": {
+    "level": "warn",
+    "timestamp": true
+  },
+  "inbounds": [
+    {
+      "type": "tun",
+      "tag": "tun-in",
+      "address": ["172.19.0.1/30"],
+      "mtu": 9000,
+      "auto_route": true,
+      "strict_route": true,
+      "stack": "system"
+    }
+  ],
+  "outbounds": [
+    {
+      "type": "vless",
+      "tag": "reality-out",
+      "server": "__NODE_HOST__",
+      "server_port": 11443,
+      "uuid": "ffffffff-ffff-ffff-ffff-ffffffffffff",
+      "flow": "xtls-rprx-vision",
+      "tls": {
+        "enabled": true,
+        "server_name": "www.apple.com",
+        "utls": {
+          "enabled": true,
+          "fingerprint": "chrome"
+        },
+        "reality": {
+          "enabled": true,
+          "public_key": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+          "short_id": "deadbeef"
+        }
+      }
+    },
+    {
+      "type": "hysteria2",
+      "tag": "hy2-out",
+      "server": "__NODE_HOST__",
+      "server_port": 443,
+      "password": "__HY2_PASSWORD__",
+      "tls": {
+        "enabled": true,
+        "insecure": true,
+        "alpn": ["h3"]
+      }
+    },
+    {
+      "type": "urltest",
+      "tag": "auto",
+      "outbounds": ["reality-out", "hy2-out"],
+      "url": "https://www.gstatic.com/generate_204",
+      "interval": "3m",
+      "tolerance": 50
+    },
+    {
+      "type": "block",
+      "tag": "block"
+    },
+    {
+      "type": "direct",
+      "tag": "direct"
+    }
+  ],
+  "route": {
+    "rules": [
+      {
+        "ip_cidr": [
+          "10.0.0.0/8",
+          "172.16.0.0/12",
+          "192.168.0.0/16",
+          "127.0.0.0/8"
+        ],
+        "outbound": "direct"
+      }
+    ],
+    "final": "auto",
+    "auto_detect_interface": true
+  },
+  "dns": {
+    "servers": [
+      {
+        "tag": "remote",
+        "address": "tls://8.8.8.8",
+        "detour": "auto"
+      },
+      {
+        "tag": "local",
+        "address": "223.5.5.5",
+        "detour": "direct"
+      }
+    ],
+    "final": "remote",
+    "strategy": "ipv4_only"
+  }
+}