Files
MeshPort/docs/next-stage-architecture.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

7.2 KiB
Raw Blame History

下一阶段架构:组网与代理组合客户端

更新日期: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。