Files
MeshPort/docs/socks-bridge.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

78 lines
5.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 应用内组网 SOCKS 桥接
更新日期:2026-10-10。下一阶段第一批实现:新增 `crates/meshport-socks`,并提供 C ABI 与 Dart 控制入口。[sing-box 本机引擎联调](singbox-integration.md)已完成;统一 TUN 和新 UI 尚未接入,现有客户端不会自动启动此桥接。
## 接入方式
```text
本机代理引擎/测试程序 → 回环 SOCKS5 → Rust MeshPort 数据面 → EasyTier → 虚拟地址/合规公告子网
```
每个连接/关联在 Tokio 独立任务中运行,转发直接使用 Rust 数据面,不通过串行 JSON 字节读写。现有 ABI 的普通 TCP/UDP 读写操作仍是每 context 串行;本次没有将它们改为异步 ABI。
按 [RFC 1928](https://www.rfc-editor.org/rfc/rfc1928)的报文格式实现受限的本机桥接:CONNECT 与 UDP ASSOCIATE,IPv4 地址、无认证协商。没有 GSSAPI、用户名密码、BIND、IPv6、域名解析或 UDP 分片,不能作为完整公开 SOCKS 服务使用。不支持的 TCP 请求返回协议错误;不支持的 UDP 报文丢弃。
- 仅允许 IPv4 回环监听,默认动态端口;调用者持有同一应用内 `Network`。
- SDK 公共 TCP 数据面采用 OverlayOnly,未找到组网路由时失败,不调用普通互联网直连。UDP 使用组网数据面,不提供外部回退。
- 公告子网仍由现有 SDK 自动学习、过滤与撤销;无需手动填写远端 CIDR。
- 域名需上层按 DNS 策略解析到 IPv4,再交给桥接;桥接不使用系统 DNS,避免意外域名泄漏。
- UDP 关联绑定 TCP 控制连接来源 IP,按请求端口或首个合法数据报固定来源端口;仅向本关联已发送过的目标接收返回数据。
- 关联在控制连接关闭、空闲超时或桥接停止后释放。TCP 在任一方向 EOF 后给另一方向有限的收尾时间,防止路由失效后无限等待 FIN ACK。
- 本机无认证监听不隔离同一设备上的其他进程;后续正式集成若需要隔离,应增加认证或平台内通道,不能把回环监听视为秘密凭据保护。
## Rust
```rust,ignore
let network = std::sync::Arc::new(meshport::Network::start(&toml).await?);
let mut bridge = meshport_socks::Bridge::start(
network.clone(),
meshport_socks::Options::default(),
).await?;
let endpoint = bridge.local_addr();
// 将 endpoint 配置为宿主代理引擎的组网 SOCKS 出口。
bridge.stop().await?;
network.stop().await;
```
生命周期顺序:启动组网 → 启动桥接 → 启动宿主代理;停止时先停宿主代理,再停止桥接,最后停止组网。`Bridge::stop` 等待子任务清理,可重复调用;Drop 发起取消但不能同步保证异步任务已回收。
默认限制:128 个会话,握手 5 秒,连接/UDP 建立 10 秒,TCP 半关闭收尾 30 秒,UDP 空闲 120 秒、单次发送 5 秒,每关联最多 64 个尝试目标。超限不排队创建无限任务;关联目标集合包含发送失败的尝试,避免底层 flow 无限增长。Rust Options 可调整,启动时校验范围和非零超时。
SOCKS IPv4 UDP 封装增加 10 字节,当前每个数据报最多承载 65497 字节。大于此值的远端响应会丢弃;这不表示实际线路 MTU 支持同样大的无分片报文。TCP/UDP 协议和 MTU 限制不提供 ICMP 转发。
## C ABI / Flutter
新增控制请求(保留 ABI 版本 1):
```json
{"op":"socks_start","port":0,"max_sessions":128}
{"op":"socks_status"}
{"op":"socks_stop"}
```
`socks_start` 返回 running、listen、tcp、udp、ipv4_only、dns_resolution。已有桥接时启动失败;系统 VPN 模式或未启动网络时启动失败。`socks_status` 返回运行状态、当前/累计会话、完成/失败会话、容量拒绝及 UDP 丢弃数量;这些是桥接计数,不是链路丢包率或应用流量。
`stop` 和 context free 会先停止桥接,再停止组网,关闭监听与所有会话;`socks_stop` 保留组网实例。容量拒绝的连接不计入 accepted;取消的会话不会计入 completed/failed,因此累计值不要求严格相加相等。
```dart
await client.start(applicationToml);
final bridge = await client.startSocksBridge();
final endpoint = bridge['listen'];
final status = await client.socksBridgeStatus();
await client.stopSocksBridge();
await client.stop();
```
运行这些方法需要重新构建原生 FFI 库。只更新 Dart 而加载旧库会返回未知操作,不会产生可用桥接。平台宿主的单一 TUN 与外层连接保护留给下一批实现。
## 验证
```sh
scripts/cargo-local.sh test -p meshport-socks -p meshport-ffi --locked
scripts/cargo-local.sh run -p meshport-socks --example local_bridge -- /path/to/application.toml
```
测试使用本机真实 EasyTier 引导节点与远端网关,网关将公告私网映射到回环 TCP/UDP echo 服务,不修改系统路由,不读取私人配置。覆盖:并发 TCP、空闲 TCP 不阻塞其他会话、双 UDP 关联隔离、来源端口限制、分片拒绝、公告学习与撤销、协议错误、容量/握手/空闲超时、重启及 FFI/context 清理。
这批验证只覆盖开发机本地网络。Android 原生构建与真机、macOS 实际组合 VPN、远程高延迟与长时间压测仍需后续验证。