- 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>
7.2 KiB
下一阶段架构:组网与代理组合客户端
更新日期:2026-10-10。状态:部分实现。现有实现见 当前架构,页面和行为依据见 UI 设计 V4及其交互说明。
开发进度:已完成 MeshPort SOCKS 桥接及 FFI/Dart 控制入口,并新增 sing-box Go 封装,通过本机跨语言 TCP/UDP 与公告撤销验证。组网 SDK 原有 JSON I/O 仍串行;已新增 独立 singbox_flutter 与客户端核心,实现应用内联合生命周期和公告变化后的配置重建;普通代理配置、订阅、模式和基础 DNS 已接入;Android 统一 TUN 为待真机验证原型,macOS 统一 TUN/helper、FakeIP 与新版主要页面已接入,测试范围见 验证记录。下文目录与架构图表达最终目标,具体已实现范围以接入文档为准。
模块架构
保留 MeshPort 独立组网 SDK。代理引擎与组合会话管理属于客户端扩展,不让其他应用使用组网 SDK 时强制依赖 sing-box。
flowchart TD
UI[Flutter 客户端:概览 / 代理 / 组网 / 设置] --> Core[客户端核心:状态 / 配置 / 订阅 / 路由 / DNS]
Core --> MB[meshport_flutter]
Core --> SB[singbox_flutter]
Core --> Platform[平台权限 / 安全存储 / 网络入口]
MB --> FFI[meshport-ffi:C ABI]
FFI --> SDK[meshport:Rust SDK]
SDK --> Adapter[meshport-easytier / meshport-netstack]
Adapter --> ET[EasyTier 核心与应用内数据面]
SB --> Go[sing-box Go 封装]
Go --> Socks[meshport-socks:组网 SOCKS5 桥接]
Socks --> SDK
Platform --> Android[Android:VPN Service / 原生桥接]
Platform --> Mac[macOS:系统接入 / 特权 helper]
Other[其他项目应用] --> MB
客户端核心负责组合状态、配置验证、持久化与生效、公告变化和故障反馈。Rust SDK 负责组网、节点、选路及数据面;Go 封装负责代理引擎运行和接口适配。Flutter 页面不直接拼装内核配置或操作系统路由。
组合模式数据路径
flowchart LR
Apps[系统应用 TCP / UDP] --> TUN[一个平台 TUN]
TUN --> Route[sing-box 统一分流]
Route -->|有效组网地址与公告子网| Socks[MeshPort SOCKS5:TCP / UDP]
Socks --> Stack[MeshPort 应用内数据面]
Stack --> ET[EasyTier:直连或中继]
ET --> Remote[远端节点 / 公告局域网]
Route -->|普通代理目标| Proxy[代理出口]
Route -->|普通直连目标| Physical[物理网络]
Proxy --> Physical
ET --> Physical
这张图表示目标方案。组合会话只允许一个系统 TUN 所有者,MeshPort 使用应用内数据面,不同时启动现有 EasyTier 系统 TUN。现有独立系统组网模式仍可单独使用。
组网优先规则仅包含合规且有效的目标,不泛化为所有私网地址。两侧引擎的外层连接需绕过自身 TUN,避免循环;代理服务器启动解析也不能依赖尚未建立的同一个代理。Android 的连接保护和底层网络选择、macOS 的物理网络出口处理属于原生平台适配职责。
公告接入、撤销和失联时同步更新有效分流与状态。组网目的地不可静默降级到互联网代理;保护记录及恢复本地访问行为按 V4 交互说明实施。
目标目录
“新增”为计划模块,其余保留现有边界;目录名称在落实接口时可调整。
MeshPort/
├── crates/
│ ├── meshport/ # 现有:组网 SDK 公共接口
│ ├── meshport-easytier/ # 现有:EasyTier 适配、选路、公告子网
│ ├── meshport-netstack/ # 现有:应用内 TCP/UDP 数据面
│ ├── meshport-ffi/ # 现有:C ABI
│ └── meshport-socks/ # 新增:组网 SOCKS5 TCP/UDP 桥接
├── engines/
│ └── singbox/ # 新增:Go 引擎封装
│ ├── bridge/ # 启停、状态、统计、出口切换
│ ├── platform/ # TUN 与底层连接接口
│ └── tests/
├── bindings/flutter/
│ ├── meshport_flutter/ # 现有:独立组网 SDK 绑定
│ └── singbox_flutter/ # 新增:代理引擎平台绑定
├── packages/
│ └── meshport_client_core/ # 新增:共用客户端业务逻辑
│ └── lib/
│ ├── runtime/ # 两侧生命周期、组合状态
│ ├── configuration/ # 草稿、保存、运行快照、迁移
│ ├── subscriptions/ # 导入、更新、来源、节点归属
│ ├── routing/ # 组网优先、普通规则、默认出口
│ ├── dns/ # 域名范围、解析出口、失败策略
│ ├── telemetry/ # 状态、流量、测量、脱敏日志
│ └── platform/ # 权限、能力、安全存储接口
├── apps/meshport_lab/ # 现有客户端,逐步重构
│ ├── lib/
│ │ ├── app/ # 导航、主题、依赖组装
│ │ ├── features/
│ │ │ ├── overview/
│ │ │ ├── proxy/
│ │ │ ├── network/
│ │ │ └── settings/
│ │ └── shared/ # 控件、状态视图、确认框
│ ├── android/ # VPN Service、权限、连接保护
│ └── macos/ # 系统接入、helper、安全存储
├── tools/
│ ├── meshport-vpn-helper/ # 现有 macOS 特权入口,按需扩展
│ └── meshport-test-server/ # 现有 TCP/UDP 验证服务
├── tests/integration/ # 新增:组合模式与平台联调
├── scripts/ # Rust/Go 构建、打包、安装
└── docs/ # 架构、设计、配置、验证
开发顺序与完成条件
| 阶段 | 工作 | 完成条件 |
|---|---|---|
| 1:组网桥接 | SOCKS5 TCP/UDP、连接级并发、取消及资源清理 | 并发连接不被单次读取串行阻塞,目标与会话正确隔离,停止无残留 |
| 2:引擎及平台入口 | Go 封装、Android 单一 VPN 入口,随后 macOS | 仅组网、仅代理、组合模式通信通过;两侧外层流量不循环 |
| 3:配置与状态 | 订阅、草稿/保存/生效、DNS、公告接入及撤销 | 部分失败和权限取消准确呈现,更新可确认,失效组网目标不泄漏到互联网代理 |
| 4:UI 与稳定性 | 按 V4 拆页面、后台与恢复、持续验证 | 网络切换、重连、故障恢复及长时间运行通过真实设备验证 |
当前 ABI 每 context 串行,不能直接作为大量 SOCKS 并发连接的最终数据面;先完善异步提交、取消和连接级并发,或为桥接层提供等价的 Rust 原生并发接口。
初期保留 apps/meshport_lab 的目录与安装标识,减少同时迁移构建脚本、包名和配置存储的风险;正式命名迁移另列任务。实现应固定依赖版本、记录构建特性与上游许可证,并按实际平台能力开放 UI。