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>
87 lines
10 KiB
Markdown
87 lines
10 KiB
Markdown
# 客户端联合运行控制
|
||
|
||
更新日期: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 认证与查询参数隐藏。
|