Files
MeshPort/docs/android.md
T

42 lines
2.8 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.
# Android 客户端与 SDK
当前实现面向 Android 8.0(API 26)及以上的 ARM64 设备。
## 构建
构建环境需要 Flutter、JDK 17、Android SDK、NDK 28.2.13676358、CMake 3.22.1,以及 Rust 的 aarch64-linux-android target。
```sh
scripts/build-lab-android.sh --release
```
脚本先编译含 system-vpn 功能的 Rust 库,再打包 Flutter APK,输出到 outputs/android。当前使用开发签名,适合本机安装验证。正式发行需配置自己的签名和应用 ID。原生库与 JNI 桥接使用 16 KB ELF 页面对齐;当前真机为 4 KB 页面,16 KB 设备运行尚未验证。
## 两种模式
- 应用内:通过 meshport_flutter SDK 的 TCP/UDP 接口通信,不创建系统 VPN。
- 系统 VPN:宿主请求用户授权,由前台 VpnService 创建虚拟网卡,将文件描述符交给 Rust 引擎。虚拟网段及符合规则的公告子网自动安装、更新和撤销,不需要填写远端子网。
外层连接通过 VpnService.protect 排除在自己的 VPN 之外。系统模式不配置默认路由或 DNS;IPv6 保留系统通路,当前虚拟网络数据面为 IPv4。其他 Android VPN 与此系统 VPN 不能同时作为当前 VPN 运行。
VPN 建立和路由更新会等待 Android ConnectivityService 发布匹配的虚拟地址及路由,再报告就绪,避免新连接提前使用物理源地址。JNI 使用库名链接 Rust 动态库,不携带构建机绝对路径;系统模式启用受保护的 DNS resolver,数字 IP 不经过 DNS 查询。
配置使用 Android Keystore 的 AES-GCM 密钥加密,私有存储仅保存密文与 IV,关闭 Android 备份。启动恢复表单,不自动连接;后台服务仍运行时重新打开界面会恢复该会话。
## 真机验证
integration_test/android_network_test.dart 使用隔离网络身份和 USB 转发的本机测试网关,覆盖加密存储、应用内 TCP/UDP、普通系统 Socket 经 VPN 访问自动公告子网,以及公告撤销。
```sh
# 先在项目根目录启动本机夹具
scripts/cargo-local.sh run -p meshport-easytier --example android_test_server
adb reverse tcp:18080 tcp:18080
adb reverse tcp:18081 tcp:18081
cd apps/meshport_lab
flutter test integration_test/android_network_test.dart -d DEVICE_SERIAL
```
测试中的系统 VPN 授权必须由用户在手机上完成。测试结束应删除两条 adb reverse 并关闭夹具。测试使用固定地址,不覆盖公网打洞、移动网络切换、长期后台存活或实际游戏负载。
2026-10-10 在 OPPO PJZ110(API 37、4 KB 页面)完整通过:加密配置保存/重新读取/删除、SDK 应用内 TCP/UDP、Java 与 Dart 普通系统 TCP/UDP 经 VPN 通信、公告子网自动安装及撤销。隔离测试不修改用户配置。公网打洞、长期后台运行及移动网络切换尚未验证。