Files
MeshPort/docs/client-runtime.md
shenleiandClaude Opus 5.5 dc1bfc99d2 Move mesh networking logic into the SDK and fix lifecycle bugs
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>
2026-10-15 18:17:42 +09:00

10 KiB
Raw Permalink Blame History

客户端联合运行控制

更新日期:2026-10-10。应用内代理与组网联合运行、节点配置、订阅导入和基础 DNS 已接入。Android 单一 VPN 已实现并交叉编译,真机验证按用户要求暂缓;macOS 统一系统 TUN/helper 已接入,实际测试范围见开发验证记录。此文区分已验证能力和待验证能力,架构图中的最终目标不等于全部完成。

模块边界

模块 职责
crates/meshport-socks 回环 SOCKS5 到独立组网 SDK 的 TCP/UDP 桥接
engines/singbox/bridge 受管理代理配置、分流、DNS、生命周期及宿主 TUN 适配
engines/singbox/cmd/meshport-singbox-ffi 数字上下文、JSON 控制、C ABI 与 socket 保护回调
bindings/flutter/singbox_flutter 工作 isolate 中的原生调用、按上下文排队
packages/meshport_client_core 联合会话、配置模型、节点与订阅解析
apps/meshport_lab 概览、代理、组网、设置四个主页面,24 个页面入口及平台安全存储

其他应用只依赖 meshport_flutter,继续使用独立组网 SDK,无需加载 sing-box。代理功能属于客户端可选层。

已实现的配置和界面

  • 功能选择:仅组网、仅代理、代理与组网;仅代理不启动 MeshPort,也不要求网络名称或密钥。
  • 普通互联网模式:绕过中国大陆、自定义规则、全局、直连。绕过中国大陆使用受管理的大陆 IP 列表,大陆 IP 与普通私网直连,其他走所选代理;保存的自定义规则和默认出口在该预设下暂停。全局和直连暂停普通规则,仍保留组网优先及失效目标保护。
  • 节点协议:SOCKS、HTTP、Shadowsocks、VMess、VLESS、Trojan;受支持的 TLS/uTLS/Reality、WebSocket、gRPC 参数由固定上游版本验证。
  • 节点按协议编辑,认证字段默认隐藏;订阅节点编辑保存为手动副本。高级传输保留 JSON 编辑入口。
  • 导入分享链接、Base64 订阅和 sing-box JSON。只提取支持的节点,完整 JSON 的入口、路由、DNS 不会覆盖受管理配置。导入先预览,再确认。
  • HTTPS 订阅添加、更新、删除;更新显式触发,禁止跳转,限制超时和内容大小。删除选中出口前确认,手动节点保留。
  • 草稿、保存、运行出口分离。保存不改变连接;运行期间应用草稿需确认重连。macOS Keychain 和 Android KeyStore 加密保存代理配置,组网配置独立保存。
  • 普通规则支持域名、域名后缀、CIDR 与 proxy/direct/reject,已使用表单编辑;DNS、组网基础、打洞、高级与线路策略均有独立页面。页面实现和限制见 界面实现清单。
  • 草稿节点可独立检测 HTTPS 连通性,显示 HTTP 耗时;不保存、不切换运行出口,不创建 TUN。

应用内入口为 127.0.0.1:10818 SOCKS5,不自动设置 macOS 系统代理或系统路由。系统 VPN 组网原有路径保持独立;统一 VPN 使用 sing-box 唯一 TUN,MeshPort 使用应用内数据面。macOS helper 只加载 App 内固定 Go 动态库,互联网外层绑定物理接口,组网桥接明确绑定 lo0,避免本机回环连接被错误绑定物理网卡。

macOS 统一 VPN 的仅组网模式使用 IPv4 TUN,只安装合规公告及会话保护前缀,可与其他默认路由 VPN 共存;互联网代理模式接管拆分默认路由,检测到其他 TUN 占用时拒绝启动,不删除其他软件路由。统一模式使用静态组网 IPv4。网络切换及长期运行仍需验证。

生命周期与保护

组网启动由 SDK start_bridged 一步完成 MeshPort 与 Rust SOCKS 桥接(失败由 SDK 一并回滚),再启动 Go 引擎;停止顺序相反。会话只在 start_bridged 成功后取得 context 所有权,context 已被占用时不会误停对方网络。网络停止失败保留所有权以便重试。组网配置由 SDK build_config 生成,旧版保存的配置经 migrate_config 迁移。close() 等待队列并释放代理上下文;宿主最终关闭 MeshPort。

宿主状态轮询直接读取 SDK 的 platform_network.mesh_cidrs(虚拟网段加已接受公告子网,已规范化),并用 health.mesh_routable 判断组网是否可用;客户端不再自行解析或掩码计算前缀。集合变化才重建 Go 配置,无需手动远端子网列表。MeshProxySession 启动后另开一个 wait_routes 长轮询循环,路由一变化就排队重建,不必等下一次宿主轮询;宿主轮询仍负责健康检查。Android 服务用独立线程长轮询 wait_routes,把路由应用投递到服务的 worker 线程。重建关闭已有代理连接,尚非无损热更新。

本次连接期间见过的合规组网前缀形成保护集合。有效前缀先走组网,撤销的已知前缀被拒绝,不能落入普通代理或直连;显式停止会话后清空集合。SDK 数据面也独立验证当前有效公告。

应用内联合模式中,组网暂不可用时普通代理可继续运行,状态为 Partial,组网目标保持拒绝。仅组网出现故障则清理会话。Android 单一 VPN 同样按 health.mesh_routable 处理:联合(combined)模式下组网停止只撤掉组网路由、代理继续,状态报告 Partial(Lab 仍视为已连接,可断开);仅组网模式与系统 VPN 整体停止。该行为尚需真机验证。

Android MeshVpnService 的所有状态只在其 worker 线程上修改:Activity 发来的请求、2 秒健康检查、底层网络回调与路由更新都在这一个线程串行执行。请求接口为异步回调,不在 worker 上阻塞等待;每次 worker 任务结束后刷新状态快照,status 请求直接返回快照,不会被耗时的重建阻塞。installed_subnet_routes 在 Android 与 macOS 辅助进程中含义一致:只含已安装的公告子网,不含虚拟网段。

DNS

  • 启动解析使用明确 IP 的 UDP DNS,默认 1.1.1.1,不依赖尚未建立的代理。
  • 客户端默认发送 dns_protection=true。自定义规则、绕过大陆和全局模式均须显式配置代理 DNS,经所选代理查询,失败不回退;普通目标默认解析器使用代理 DNS。直连模式使用直连 DNS 或启动 DNS。代理节点、解析器地址使用单独的启动解析避免循环依赖。
  • 组网 DNS 配置指定后缀及合规组网 IP,经 MeshPort 查询;其服务公告撤销后拒绝对应查询,不回退公共 DNS。
  • 组网域名查询及后续连接均保持组网出口优先。
  • FakeIP 可选:IPv4 198.18.0.0/15、IPv6 fc00::/18。组网 DNS 规则先匹配且排除 FakeIP,普通 localhost/local/lan 默认排除;支持自定义后缀。真实 TCP 测试验证 FakeIP 反查与代理出口,以及公告重建后保留映射。
  • 缓存放入宿主私有临时目录;Go 引擎 stop/start 保留当前会话缓存,最终释放上下文删除文件。重新连接会话会清理缓存,旧连接可能中断。
  • macOS 互联网统一模式向 Dynamic Store 增加临时 DNS 补充项,helper 退出时移除,不改写持久网络服务配置;全局 DNS 与现有 TUN 共存不承诺。
  • DoH/DoT 与规则集已接入,细节见 高级客户端功能;完整 IPv6 端到端验证尚未完成。

Android 单一 VPN 原型

MeshVpnService 持有唯一系统 TUN,MeshPort 使用应用内网络,sing-box 接收宿主提供的重复 FD 并负责 TUN 分流。JNI 为 Rust/Go 外层 socket 提供 VpnService.protect 回调,选择非 VPN 底层网络并监听变化;有效公告变化重建配置,组网专用捕获路由随公告更新。

入口标注“待真机验证”。仅组网捕获保护子网;互联网代理模式捕获默认路由。联合模式暂要求静态组网 IPv4。代码和 APK 编译成功不代表底层网络切换、后台运行或实际单一 VPN TCP/UDP 已验证。

原生接口和验证

C ABI 提供 version、context_new、call、string_free、context_free,以及宿主 socket 保护回调注册。请求为 NUL 终止 UTF-8,JSON 最大 64 KiB;未知字段、尾随数据与操作拒绝,错误不返回配置凭据。Java JNI 使用标准 UTF-8,避免认证字段中非 ASCII 字符损坏。

sh scripts/go-local.sh test -race ./...
sh scripts/go-local.sh vet ./...
sh scripts/test-client-runtime.sh
sh scripts/test-singbox-bridge.sh
sh scripts/build-lab-macos.sh
sh scripts/build-lab-android.sh --debug

Go 测试包含真实 SOCKS/直连通信、三种模式的组网优先、DNS 域名规则、撤销 DNS 拒绝及 ABI 并发释放。Flutter 测试包含生命周期、失效前缀保护、组网故障后的部分运行、配置导入、节点编辑与真实 Rust/Go 动态库启停。跨语言组网 TCP/UDP 和公告撤销端到端验证见 引擎接入。构建产物和本轮验证记录见 开发验证记录。

尚未完成

Android 单一 VPN 真机通信与网络切换、macOS 互联网统一模式全局 DNS 和网络切换、相机及真实登录启动恢复、长时间和后台稳定性测试仍需验证。规则集、扫码/文件导入、自动订阅更新与应用启动自动连接已接入,见 高级客户端功能。自动测速选出口按用户要求不实现。原有 Android 独立组网真机测试与本轮新增代理联合模式测试是不同范围。

概览测速与代理日志

概览移除测试耗时、测试趋势和快速连接测试入口;原有诊断工具仍可从详情页访问。代理及联合模式增加手动测速卡片,通过本机 127.0.0.1 的受管理 HTTP/SOCKS 混合入口下载 Cloudflare 资源,不回退到直接连接。最多下载 32 MB,15 秒停止,支持取消;重连清除前次结果。显示端到端平均下载 Mbps / MB/s 和首字节耗时。测速占用带宽、遵循当前分流规则;直连模式或命中直连规则时不代表节点性能,结果也不代表 YouTube CDN 吞吐。

代理引擎收集 info 及以上级别的连接、出口和错误事件,原始输出保持写入空设备,只有脱敏事件返回界面。引擎保留最近 128 条,界面保留最近 300 条会话日志;日志页可筛选代理日志并复制当前范围。应用内与统一 VPN 共用该采集路径。不会收集数据包内容,目标地址保留,已知密码、UUID、URL 认证与查询参数隐藏。