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

87 lines
10 KiB
Markdown
Raw Permalink 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.
# 客户端联合运行控制
更新日期: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、组网基础、打洞、高级与线路策略均有独立页面。页面实现和限制见 [界面实现清单](ui-implementation.md)。
- 草稿节点可独立检测 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 与规则集已接入,细节见 [高级客户端功能](advanced-client-features.md);完整 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
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 和公告撤销端到端验证见 [引擎接入](singbox-integration.md)。构建产物和本轮验证记录见 [开发验证记录](development-validation.md)。
## 尚未完成
Android 单一 VPN 真机通信与网络切换、macOS 互联网统一模式全局 DNS 和网络切换、相机及真实登录启动恢复、长时间和后台稳定性测试仍需验证。规则集、扫码/文件导入、自动订阅更新与应用启动自动连接已接入,见 [高级客户端功能](advanced-client-features.md)。自动测速选出口按用户要求不实现。原有 Android 独立组网真机测试与本轮新增代理联合模式测试是不同范围。
## 概览测速与代理日志
概览移除测试耗时、测试趋势和快速连接测试入口;原有诊断工具仍可从详情页访问。代理及联合模式增加手动测速卡片,通过本机 127.0.0.1 的受管理 HTTP/SOCKS 混合入口下载 Cloudflare 资源,不回退到直接连接。最多下载 32 MB,15 秒停止,支持取消;重连清除前次结果。显示端到端平均下载 Mbps / MB/s 和首字节耗时。测速占用带宽、遵循当前分流规则;直连模式或命中直连规则时不代表节点性能,结果也不代表 YouTube CDN 吞吐。
代理引擎收集 info 及以上级别的连接、出口和错误事件,原始输出保持写入空设备,只有脱敏事件返回界面。引擎保留最近 128 条,界面保留最近 300 条会话日志;日志页可筛选代理日志并复制当前范围。应用内与统一 VPN 共用该采集路径。不会收集数据包内容,目标地址保留,已知密码、UUID、URL 认证与查询参数隐藏。