# sing-box 引擎接入:第一阶段 更新日期:2026-10-10。本文件记录第一阶段组网桥接的验证路径,下文“本阶段”均指最初 mesh-only 范围。当前已追加普通代理出口、配置与订阅、模式和基础 DNS;Android 单一 VPN 为待真机验证原型。最新范围见 [客户端运行控制](client-runtime.md)。 ## 已实现的路径 ```mermaid 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 官方接口](https://sing-box.sagernet.org/configuration/outbound/socks/)接入;本阶段只注册所需的本机 SOCKS 能力。模块固定上游版本,不改写下载缓存内的源码;当前规则集并发修补通过项目私有模块副本构建,见 [补丁说明](../engines/singbox/patches/README.md)。上游许可证副本见 [sing-box LICENSE](upstream/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](https://www.rfc-editor.org/rfc/rfc1928)表达客户端预计使用的来源端点。Go 适配层在尚未分配 UDP 端点时发送 IPv4 0.0.0.0:0,避免将远端私网目标或其服务端口误当作来源。Rust 的来源 IP/端口隔离保持有效;不修改上游版本的握手实现。 Go UDP 握手受上下文取消和最长 5 秒超时控制;仅接受同一桥接 IP 返回的有效 IPv4 回环端点。取得关联后保留 TCP 控制通道,关联关闭会清理控制和 UDP 资源。宿主在上下文取消后仍需调用 Engine.Stop;Snapshot 不将已取消上下文标作 Running。 ## 构建与验证 ```sh 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 验证。 ## 后续进度 以 [客户端运行控制](client-runtime.md) 和 [开发验证记录](development-validation.md) 为准。macOS 统一 TUN 的限定子网 TCP/UDP 与清理自检已通过;Android 联合模式仍需真机验证。新增高级功能范围见 [高级客户端功能](advanced-client-features.md)。