shenandshen c94143dfae Keep macOS client running in the menu bar when its window closes
Retain the main Flutter window, add reopen and explicit quit actions, and preserve its controller while hidden. Fix native test host paths and cover the window and menu lifecycle with XCTest.
2026-10-12 18:46:53 -07:00

MeshPort

虚拟组网 SDK,默认应用内模式,复用 Rust EasyTier 核心,通过用户态 TCP/IP 栈提供 TCP/UDP 通信。Flutter MeshPort Lab 是使用同一公开 SDK 的验证客户端。

目前为 0.1.0 开发原型。已实现真实网络通信,不是 UI 模拟。macOS Apple Silicon 已验证;Android ARM64 已通过真机应用内与系统 VPN TCP/UDP,以及公告子网自动接入和撤销。其他平台原生库打包与运行尚未完成。

快速开始

需要 Rust ≥1.95、protoc 和 Flutter。当前机器的项目本地工具链位于 work/toolchain/,scripts/cargo-local.sh 会自动使用它;其他机器可使用系统工具链,或运行 scripts/bootstrap-local.sh 安装到项目内。

scripts/cargo-local.sh test --workspace --locked
scripts/run-lab-macos.sh

构建内含 Rust 动态库、可直接启动的 macOS 开发版:

scripts/build-lab-macos.sh
open apps/meshport_lab/build/macos/Build/Products/Debug/MeshPort.app

进入设置,填写与游戏服务器一致的网络名称、网络密钥、唯一虚拟 IPv4 和初始节点地址。启动引擎后等待节点出现,然后测试服务器虚拟 IP 和游戏端口。引擎 Running 不代表服务器已可达。

Android 构建:scripts/build-lab-android.sh --release;安装包输出到 outputs/android。平台接入与验证说明见 Android。

TCP 建连测试可以针对游戏端口。数据回显校验与 UDP 测试需要协作的回显服务,不能拿任意游戏端口当 echo 服务。

在已安装 EasyTier 的游戏服务器上,另开测试端口:

cargo run -p meshport-test-server -- 10.77.0.2:7007

将地址替换成服务器真实的虚拟 IPv4,防火墙允许 TCP/UDP 测试端口。工具默认只绑定 127.0.0.1:7007,需要显式指定虚拟网地址。

目录

下一阶段的设计文档:移动端 UI V4(24 页与公共状态)、组网与代理组合架构。这些是拟实施方案,当前实现范围仍以下文为准。

已完成的下一阶段基础能力:SOCKS 桥接、sing-box 引擎封装与本机 TCP/UDP 联调。新增 客户端原生绑定、代理配置与联合运行,支持节点/订阅导入、规则/全局/直连和基础 DNS;高级客户端功能已接入自动订阅更新、规则集、DoH/DoT、原生文件和二维码导入、登录启动与自动连接。出口仍手动选择。Android 单一 VPN 原型待真机验证,macOS 统一 TUN/helper、FakeIP 和 24 页主要界面已接入;具体测试范围及禁用功能见 验证记录。

  • crates/meshport:Rust 公共 API。
  • crates/meshport-easytier:固定上游快照、配置约束、实例与状态适配。
  • crates/meshport-netstack:复用 EasyTier 已有 smoltcp 数据面,提供通信类型和回显验证。
  • crates/meshport-ffi:C ABI、实例/连接句柄、JSON 控制接口。
  • crates/meshport-socks:可选的本机 SOCKS5 IPv4 TCP/UDP 组网桥接,原生任务并发转发;接入说明。
  • engines/singbox:固定版本 Go 引擎封装,受管理的本机组网分流与跨语言验证。
  • bindings/flutter/meshport_flutter:Dart FFI SDK,原生调用放在后台 isolate。
  • apps/meshport_lab:响应式 Flutter 验证工具。
  • tools/meshport-vpn-helper:macOS 开发版特权 TUN 控制与自检。
  • tools/meshport-test-server:普通系统 socket 的 TCP/UDP echo 服务。
  • vendor/easytier:保留许可证的上游源码快照与本地选路定制。
  • docs:架构、配置、ABI 契约、验证记录。
  • outputs/ui:设计参考图。

使用边界

  • 默认应用内模式不创建 TUN/TAP,只影响 SDK 连接;macOS 开发版可切换系统组网模式,创建 utun 并安装虚拟网段路由。详见 系统组网。
  • IPv4 数据面;底层 TCP/UDP 传输。其他协议、安全模式和完整 EasyTier 配置未全部开放。
  • UDP 接收当前按已经主动发送过的远端会话匹配;不支持陌生远端首包的通用 UDP 服务端监听。
  • Rust API 为 async;ABI v1 是同步、每 context 串行的开发接口。Dart 放到后台 isolate 避免阻塞 UI,但尚不适合高并发/低开销的最终游戏数据面。
  • 超时写入可能已经发送部分 TCP 数据,不能盲目重发。
  • macOS 设置页可独立保存配置到 Keychain,启动自动回填,手动连接;扫码、文件导入、完整候选路径优化、长期压测和移动端后台运行尚未完成。
  • 稳定性页面目前执行真实的重复连接/回显探测;不表示所有设计稿中的测试模式均已实现。

线路策略和实测工具见 跨国线路优化。

本地定制核心基于 EasyTier 7af7bdc16a41d64d58743d15023a63b3eed2102c(2.7.0 开发源码)。需另行验证与现有服务器实际版本的互通,不能把同版本本地测试当成全版本兼容。

详见 架构、配置、ABI、验证记录和兼容范围。

两种模式均自动学习符合规则的节点公告子网,无需填写远端 CIDR。应用内模式仅供 SDK TCP/UDP 访问;系统模式自动同步 OS 路由。规则及 macOS 启动方式见 系统组网。

S
Description
No description provided
Readme
27 MiB
Languages
Dart 34.8%
Rust 28.9%
Go 14.1%
Python 6.7%
Kotlin 4.9%
Other 10.6%