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:设计参考图。
使用边界
- SDK 默认应用内模式不创建 TUN/TAP,只影响 SDK 连接;Lab 客户端默认统一 VPN,使用 TUN 接入代理,也可选择仅组网模式。详见 系统组网。
- IPv4 数据面;底层 TCP/UDP 传输。其他协议、安全模式和完整 EasyTier 配置未全部开放。
- UDP 接收当前按已经主动发送过的远端会话匹配;不支持陌生远端首包的通用 UDP 服务端监听。
- Rust API 为 async;ABI v1 是同步、每 context 串行的开发接口。Dart 放到后台 isolate 避免阻塞 UI,但尚不适合高并发/低开销的最终游戏数据面。
- 超时写入可能已经发送部分 TCP 数据,不能盲目重发。
- macOS 和 Android 配置保存到用户私有目录,启动自动回填,自动连接可独立设置;旧配置支持迁移。支持扫码和文件导入,长期压测和移动端后台稳定性仍需验证。
- 稳定性页面目前执行真实的重复连接/回显探测;不表示所有设计稿中的测试模式均已实现。
线路策略和实测工具见 跨国线路优化。
本地定制核心基于 EasyTier 7af7bdc16a41d64d58743d15023a63b3eed2102c(2.7.0 开发源码)。需另行验证与现有服务器实际版本的互通,不能把同版本本地测试当成全版本兼容。
两种模式均自动学习符合规则的节点公告子网,无需填写远端 CIDR。应用内模式仅供 SDK TCP/UDP 访问;系统模式自动同步 OS 路由。规则及 macOS 启动方式见 系统组网。
自动化测试
python3 scripts/test.py # Rust、Go、Flutter 和 macOS 配置存储回归
python3 scripts/test.py sdk engine # 只测 SDK 与引擎联调
python3 scripts/test.py client --native # macOS:重新构建原生库后跑 Flutter 原生测试
python3 scripts/test.py throughput # 可选:本机模拟延迟与吞吐诊断
python3 scripts/test.py speed --min-mbps 10 # 重复测速矩阵、丢包检查及速度门槛
python3 scripts/test.py combined # sing-box + SDK 同进程双路负载、UDP 和故障隔离
脚本逐项保存日志,输出 JSON 与 JUnit 报告,任一步失败时返回非零状态;默认不运行吞吐诊断或系统 VPN/真机测试。参数、依赖和 CI 使用方式见 自动化测试。
清理构建缓存
运行 python3 scripts/clean-build-artifacts.py 预览,增加 --delete 删除可重新生成的构建缓存和临时测试产物。脚本保留工具链、用户配置、Git 历史和 outputs/android、outputs/macos 安装包;下次构建需要重新生成缓存。