SDK: - Add build_config/migrate_config, mesh_cidrs, route_generation, health and start_bridged; expose abi_info (capability revision 2). - Add wait_routes long-poll; stop wakes waiters, and context_free now stops the network immediately instead of waiting for waiters to time out. Hosts: - Dart: waitRoutes(), MeshProxySession route watcher, ABI capability check. - Android: fix a deadlock where every VPN request waited on its own single-thread worker; requests are now async, status is served from a snapshot, and combined mode reports Partial when the mesh stops. - macOS helper: mesh-only unified mode stops when the mesh is lost; installed_subnet_routes excludes the overlay. - Lab: restore Partial sessions, write migrated profiles back, remove the unreachable TOML import dialog; native test now connects via the form. Docs updated accordingly. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
6.0 KiB
sing-box 引擎接入:第一阶段
更新日期:2026-10-10。本文件记录第一阶段组网桥接的验证路径,下文“本阶段”均指最初 mesh-only 范围。当前已追加普通代理出口、配置与订阅、模式和基础 DNS;Android 单一 VPN 为待真机验证原型。最新范围见 客户端运行控制。
已实现的路径
flowchart LR
Test[本机 SOCKS5 测试客户端] --> Go[sing-box:回环入口与受管理分流]
Go --> Rust[MeshPort SOCKS5:原生并发 TCP/UDP]
Rust --> SDK[应用内 MeshPort / EasyTier]
SDK --> Gateway[远端节点:自动学习的合规公告子网]
Gateway --> Service[TCP / UDP echo 服务]
引擎固定使用 sing-box 1.14.3,依赖版本与校验记录在 engines/singbox/go.mod 和 go.sum。项目本地脚本设置独立 Go 模块、构建缓存,工具链最低要求由 go.mod 的 Go 1.25.5 声明决定;没有升级系统 Go 安装。
SOCKS 出口依据 sing-box 官方接口接入;本阶段只注册所需的本机 SOCKS 能力。模块固定上游版本,不改写下载缓存内的源码;当前规则集并发修补通过项目私有模块副本构建,见 补丁说明。上游许可证副本见 sing-box LICENSE。
模块职责
| 文件 | 作用 |
|---|---|
| engines/singbox/bridge/config.go | 从有效组网前缀生成受管理配置;验证回环端点、地址范围和数量 |
| engines/singbox/bridge/engine.go | 引擎启动、停止、状态及失败恢复;重复启动拒绝,停止可重复调用 |
| engines/singbox/bridge/inbound.go | 跟踪已接受但尚未路由的 TCP 控制连接;停止时关闭全部控制连接,最多 128 个 |
| engines/singbox/bridge/outbound.go | TCP 使用上游 SOCKS 出口;UDP 标准化关联握手并复用上游报文封装 |
| engines/singbox/cmd/meshport-singbox | 读取受管理配置、输出一次就绪状态、响应退出信号的开发程序 |
| crates/meshport-socks | 本机 SOCKS 到独立组网 SDK 的桥接 |
只有配置前缀内的 IPv4 流量进入组网出口;其他目标和域名请求显式拒绝,没有普通互联网出口。当前前缀额外限制为私网 /16–/32,不接受所有私网、公共段、IPv6 或默认路由。地址属于允许范围不等于已公告,宿主仍需从 SDK 的合规有效投影生成配置。
mesh_cidrs 直接取自 SDK 状态的 platform_network.mesh_cidrs(或 start_bridged 返回值),宿主原样传入,不是用户手动远端子网列表,也不再由各宿主重复计算。Go 使用启动时快照;公告撤销由底层 SDK 即时阻止转发。现有客户端核心按有效投影变化自动重建 Go 引擎,无需手动列表;变化会关闭已有代理连接。无损热更新仍待实现;当前客户端核心已保留本次会话中的已知前缀,撤销目标由显式拒绝规则保护。
组网目标没有路由时返回连接失败或关闭连接,UDP 不交给其他出口。域名在分流第一条即拒绝,不做系统 DNS;此处描述最初 mesh-only 配置;当前联合模式已实现组网 DNS 和普通代理解析,FakeIP 已实现,范围见客户端运行控制。
联调中修正的问题
- TCP 半关闭时远端 FIN ACK 可能因路由撤销而无法返回,Rust 桥接加入有界收尾时间,避免永久占用会话。
- 引擎停止时,尚未完成 SOCKS 请求的连接还没进入路由连接管理器;Go 接入层在协议处理前跟踪连接,保证停止时主动关闭。
- UDP ASSOCIATE 按 RFC 1928表达客户端预计使用的来源端点。Go 适配层在尚未分配 UDP 端点时发送 IPv4 0.0.0.0:0,避免将远端私网目标或其服务端口误当作来源。Rust 的来源 IP/端口隔离保持有效;不修改上游版本的握手实现。
Go UDP 握手受上下文取消和最长 5 秒超时控制;仅接受同一桥接 IP 返回的有效 IPv4 回环端点。取得关联后保留 TCP 控制通道,关联关闭会清理控制和 UDP 资源。宿主在上下文取消后仍需调用 Engine.Stop;Snapshot 不将已取消上下文标作 Running。
构建与验证
sh scripts/go-local.sh mod download
sh scripts/go-local.sh test -race ./...
sh scripts/go-local.sh vet ./...
sh scripts/build-singbox.sh
sh scripts/test-singbox-bridge.sh
scripts/cargo-local.sh test -p meshport-socks -p meshport-ffi --locked
开发程序输出到 target/debug/meshport-singbox,缓存和二进制均在 Git 忽略目录。配置输入上限 64 KiB,拒绝未知字段和尾随 JSON,不接收任意完整 sing-box 配置;默认关闭内核日志,只输出就绪状态,不打印配置或凭据。
端到端测试自行建立本机真实 EasyTier 网关、客户端和 echo 服务,自动学习测试公告;网关将测试私网映射到回环地址。它启动 Go 引擎,然后验证四个并发 TCP 连接、空闲 TCP 与两组 UDP 会话、公告撤销后的 TCP/UDP 失败及程序停止。测试不需要管理员 VPN 权限,不改系统路由,不读取个人网络配置。
第一阶段 Go 引擎有 3 项测试(配置约束、拒绝未配置目标/域名、启停与恢复),通过 race 检查;新增代理策略测试见客户端验证记录。Rust 桥接/FFI 常规测试 7 项通过。跨语言端到端测试默认显式忽略,由 test-singbox-bridge.sh 构建引擎后单独执行,已通过。Rust Clippy 与 Go vet 通过。
本次验证平台为开发机 macOS ARM64。链接器仍报告上游/工具链的重复 objc 与 race 对象符号表警告,编译与测试成功;不据此宣称已通过 Android 或实际系统 VPN 验证。
后续进度
以 客户端运行控制 和 开发验证记录 为准。macOS 统一 TUN 的限定子网 TCP/UDP 与清理自检已通过;Android 联合模式仍需真机验证。新增高级功能范围见 高级客户端功能。