Files

78 lines
6.8 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.
# 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/package-lab-android.sh
```
脚本先编译含 system-vpn 功能的 Rust 库,再打包 Flutter APK,输出到 outputs/android。当前使用开发签名,适合本机安装验证。正式发行需配置自己的签名和应用 ID。原生库与 JNI 桥接使用 16 KB ELF 页面对齐;当前真机为 4 KB 页面,16 KB 设备运行尚未验证。
## 签名冲突时使用独立版
无法取得旧版签名时,可执行 `sh scripts/package-lab-android.sh --standalone` 打包“MeshPort 独立版”。其应用 ID 为 `com.meshport.client.standalone`,使用独立持久签名,可与原应用共存;需要重新导入配置,不读取旧应用的私有数据。原应用无需卸载。系统仍只能同时连接一个 VPN。
独立版签名保存在被 Git 忽略的 `work/android-signing/`,构建缓存清理脚本会保留此目录。请备份整个目录,后续独立版升级必须复用该密钥。脚本在密钥或属性文件缺失时拒绝重新生成不完整身份。此签名用于本地分发,不代表已经完成应用商店发布配置。
## 两种模式
- 应用内:通过 meshport_flutter SDK 的 TCP/UDP 接口通信,不创建系统 VPN。
- 系统 VPN:宿主请求用户授权,由前台 VpnService 创建虚拟网卡,将文件描述符交给 Rust 引擎。虚拟网段及符合规则的公告子网自动安装、更新和撤销,不需要填写远端子网。
- 统一 VPN:通过 Android VpnService 建立 TUN,交给 sing-box 接入互联网代理和可选的组网 SOCKS 桥。首次启动默认“仅代理 / 全局代理 / 统一 VPN”;首次导入单个节点自动选中,DNS 默认 `https://cloudflare-dns.com/dns-query`。原有配置与自定义 DNS 保留。设置自动保存,运行中修改需要点击“重连应用修改”。
外层连接通过 VpnService.protect 排除在自己的 VPN 之外。仅组网的系统模式不配置默认路由或 DNS;IPv6 保留系统通路,当前虚拟网络数据面为 IPv4。统一 VPN 的互联网模式接管 IPv4/IPv6 默认路由和 DNS,并跟踪底层物理网络。其他 Android VPN 不能同时作为当前 VPN 运行。
VPN 建立和路由更新会等待 Android ConnectivityService 发布匹配的虚拟地址及路由,再报告就绪,避免新连接提前使用物理源地址。JNI 使用库名链接 Rust 动态库,不携带构建机绝对路径;系统模式启用受保护的 DNS resolver,数字 IP 不经过 DNS 查询。
配置保存到应用私有目录 `filesDir/MeshPort/` 的 `proxy-profile.json` 和 `network-profile.toml`,目录权限 0700、文件权限 0600,使用原子写入,关闭 Android 备份。文件内容为明文,由应用沙箱隔离。旧版 Keystore 加密配置首次读取时迁移;迁移失败可在设置页手动重试,保留旧备份。启动恢复表单,自动连接由独立开关控制;后台服务仍运行时重新打开界面会恢复该会话。
## 真机验证
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
# Use a normal APK and its matching build number; restore it automatically.
sh scripts/test-android-device.sh DEVICE_SERIAL NORMAL_APK BUILD_NUMBER network
```
测试中的系统 VPN 授权必须由用户在手机上完成。测试结束应删除两条 adb reverse 并关闭夹具。测试使用固定地址,不覆盖公网打洞、移动网络切换、长期后台存活或实际游戏负载。
互联网统一 VPN 使用单独的隔离 SOCKS5 夹具,手机与电脑须在同一局域网。仅接受明确指定的手机 IP,测试地址返回确定的 TCP/UDP 回显,公共 HTTPS 和默认 DoH 使用真实上游;不读取或修改用户节点配置。
```sh
python3 scripts/android-proxy-fixture.py --host COMPUTER_LAN_IP --device PHONE_LAN_IP
sh scripts/test-android-device.sh DEVICE_SERIAL NORMAL_APK BUILD_NUMBER proxy COMPUTER_LAN_IP
```
覆盖普通系统 TCP/UDP、TUN DNS、默认加密 DNS、证书验证的 HTTPS、两次启停与断开恢复。实际结果记录在 [开发验证](development-validation.md),脚本存在不代表设备已通过。包装脚本用 `flutter drive --keep-app-running` 避免 Flutter 默认卸载测试 APP;结束或失败时覆盖安装并打开普通 APK,保留已有存储。测试完成后停止夹具。直接使用 `flutter test` 会在结束时卸载测试 APP,不能用于保留用户配置的测试。
## Android 连接日志
APP 的“诊断与日志”记录配置校验、授权、引擎启动与运行错误。Flutter 在输出前隐藏已知凭据,Android 同步到 `MeshPortRuntime`;VPN 服务的阶段事件使用 `MeshPortVPN`,不打印完整配置。可以通过以下命令采集本次连接事件:
```sh
adb -s DEVICE_SERIAL logcat -s MeshPortRuntime:I MeshPortVPN:I AndroidRuntime:E
```
2026-10-10 在 OPPO PJZ110(API 37、4 KB 页面)完整通过:加密配置保存/重新读取/删除、SDK 应用内 TCP/UDP、Java 与 Dart 普通系统 TCP/UDP 经 VPN 通信、公告子网自动安装及撤销。隔离测试不修改用户配置。公网打洞、长期后台运行及移动网络切换尚未验证。
## 自用默认配置
自用配置文件为 `apps/meshport_lab/assets/config/default.private.toml`,不会提交 Git。可以从同目录的 `default.example.toml` 复制后填写网络身份、密钥、虚拟 IP 和初始节点。每台设备应使用不同的静态虚拟 IP。
开发构建脚本会先执行 `sh scripts/prepare-lab-default.sh`,将私人文件复制为安装包资源 `default.toml`;没有私人文件时使用示例。直接运行 Flutter 命令之前也应先执行该脚本。APK 里的默认配置可以被提取,含密钥的自用安装包不要分发。
发布打包使用 `package-lab-android.sh` 或 `package-lab-macos.sh`,仅打入公开示例配置,并恢复本地开发配置。
客户端优先读取应用私有目录中已保存的配置;没有可用保存配置时加载安装包默认配置,并默认开启配置保存。默认配置只预填表单,不会自动连接。保存后下次启动会恢复修改后的配置;删除保存配置后,下次启动重新使用安装包默认值。
最新同步版构建与验证结果见 [Android 最终包验证](../outputs/validation/android-final-sync-20261013.md)。