Files

91 lines
6.6 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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` 安装包;下次构建需要重新生成缓存。