91 lines
6.6 KiB
Markdown
91 lines
6.6 KiB
Markdown
# 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` 安装到项目内。
|
||
|
||
```sh
|
||
scripts/cargo-local.sh test --workspace --locked
|
||
scripts/run-lab-macos.sh
|
||
```
|
||
|
||
构建内含 Rust 动态库、可直接启动的 macOS 开发版:
|
||
|
||
```sh
|
||
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](docs/android.md)。
|
||
|
||
TCP 建连测试可以针对游戏端口。数据回显校验与 UDP 测试需要协作的回显服务,不能拿任意游戏端口当 echo 服务。
|
||
|
||
在已安装 EasyTier 的游戏服务器上,另开测试端口:
|
||
|
||
```sh
|
||
cargo run -p meshport-test-server -- 10.77.0.2:7007
|
||
```
|
||
|
||
将地址替换成服务器真实的虚拟 IPv4,防火墙允许 TCP/UDP 测试端口。工具默认只绑定 `127.0.0.1:7007`,需要显式指定虚拟网地址。
|
||
|
||
## 目录
|
||
|
||
下一阶段的设计文档:[移动端 UI V4(24 页与公共状态)](docs/ui-design.md)、[组网与代理组合架构](docs/next-stage-architecture.md)。这些是拟实施方案,当前实现范围仍以下文为准。
|
||
|
||
已完成的下一阶段基础能力:[SOCKS 桥接](docs/socks-bridge.md)、[sing-box 引擎封装与本机 TCP/UDP 联调](docs/singbox-integration.md)。新增 [客户端原生绑定、代理配置与联合运行](docs/client-runtime.md),支持节点/订阅导入、规则/全局/直连和基础 DNS;[高级客户端功能](docs/advanced-client-features.md)已接入自动订阅更新、规则集、DoH/DoT、原生文件和二维码导入、登录启动与自动连接。出口仍手动选择。Android 单一 VPN 原型待真机验证,macOS 统一 TUN/helper、FakeIP 和 24 页主要界面已接入;具体测试范围及禁用功能见 [验证记录](docs/development-validation.md)。
|
||
|
||
- `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 组网桥接,原生任务并发转发;[接入说明](docs/socks-bridge.md)。
|
||
- `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 接入代理,也可选择仅组网模式。详见 [系统组网](docs/system-vpn.md)。
|
||
- IPv4 数据面;底层 TCP/UDP 传输。其他协议、安全模式和完整 EasyTier 配置未全部开放。
|
||
- UDP 接收当前按已经主动发送过的远端会话匹配;不支持陌生远端首包的通用 UDP 服务端监听。
|
||
- Rust API 为 async;ABI v1 是同步、每 context 串行的开发接口。Dart 放到后台 isolate 避免阻塞 UI,但尚不适合高并发/低开销的最终游戏数据面。
|
||
- 超时写入可能已经发送部分 TCP 数据,不能盲目重发。
|
||
- macOS 和 Android 配置保存到用户私有目录,启动自动回填,自动连接可独立设置;旧配置支持迁移。支持扫码和文件导入,长期压测和移动端后台稳定性仍需验证。
|
||
- 稳定性页面目前执行真实的重复连接/回显探测;不表示所有设计稿中的测试模式均已实现。
|
||
|
||
线路策略和实测工具见 [跨国线路优化](docs/optimization.md)。
|
||
|
||
本地定制核心基于 EasyTier `7af7bdc16a41d64d58743d15023a63b3eed2102c`(2.7.0 开发源码)。需另行验证与现有服务器实际版本的互通,不能把同版本本地测试当成全版本兼容。
|
||
|
||
详见 [架构](docs/architecture.md)、[配置](docs/configuration.md)、[ABI](docs/ffi-contract.md)、[验证记录](docs/testing.md)和[兼容范围](docs/compatibility.md)。
|
||
|
||
两种模式均自动学习符合规则的节点公告子网,无需填写远端 CIDR。应用内模式仅供 SDK TCP/UDP 访问;系统模式自动同步 OS 路由。规则及 macOS 启动方式见 [系统组网](docs/system-vpn.md)。
|
||
|
||
## 自动化测试
|
||
|
||
```sh
|
||
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 使用方式见 [自动化测试](docs/automated-testing.md)。
|
||
|
||
## 清理构建缓存
|
||
|
||
运行 `python3 scripts/clean-build-artifacts.py` 预览,增加 `--delete` 删除可重新生成的构建缓存和临时测试产物。脚本保留工具链、用户配置、Git 历史和 `outputs/android`、`outputs/macos` 安装包;下次构建需要重新生成缓存。
|