Files
MeshPort/README.md
T

68 lines
4.3 KiB
Markdown
Raw 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`,需要显式指定虚拟网地址。
## 目录
- `crates/meshport`:Rust 公共 API。
- `crates/meshport-easytier`:固定上游快照、配置约束、实例与状态适配。
- `crates/meshport-netstack`:复用 EasyTier 已有 smoltcp 数据面,提供通信类型和回显验证。
- `crates/meshport-ffi`:C ABI、实例/连接句柄、JSON 控制接口。
- `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 并安装虚拟网段路由。详见 [系统组网](docs/system-vpn.md)。
- IPv4 数据面;底层 TCP/UDP 传输。其他协议、安全模式和完整 EasyTier 配置未全部开放。
- UDP 接收当前按已经主动发送过的远端会话匹配;不支持陌生远端首包的通用 UDP 服务端监听。
- Rust API 为 async;ABI v1 是同步、每 context 串行的开发接口。Dart 放到后台 isolate 避免阻塞 UI,但尚不适合高并发/低开销的最终游戏数据面。
- 超时写入可能已经发送部分 TCP 数据,不能盲目重发。
- macOS 设置页可独立保存配置到 Keychain,启动自动回填,手动连接;扫码、文件导入、完整候选路径优化、长期压测和移动端后台运行尚未完成。
- 稳定性页面目前执行真实的重复连接/回显探测;不表示所有设计稿中的测试模式均已实现。
线路策略和实测工具见 [跨国线路优化](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)。