Files
MeshPort/docs/singbox-integration.md
T
shenleiandClaude Haiku 5.5 2f185f914d Snapshot uncommitted work: proxy UI, sing-box integration, socks bridge
- Lab app: proxy panel, node editor, configuration and detail pages,
  responsive layout, and related tests
- Add meshport-socks crate and sing-box bridge scripts/docs
- Add singbox_flutter binding and meshport_client_core package
- FFI, VPN helper (unified mac path), and Android/macOS runner updates
- Docs for architecture, client runtime, UI design, and validation
- UI design output artifacts under outputs/ui

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
2026-10-12 10:06:15 +09:00

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.subnet_routes 和当前虚拟地址。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 联合模式仍需真机验证。新增高级功能范围见 高级客户端功能。