Files

6.8 KiB
Raw Permalink Blame History

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。

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 访问自动公告子网,以及公告撤销。

# 先在项目根目录启动本机夹具
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 使用真实上游;不读取或修改用户节点配置。

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、两次启停与断开恢复。实际结果记录在 开发验证,脚本存在不代表设备已通过。包装脚本用 flutter drive --keep-app-running 避免 Flutter 默认卸载测试 APP;结束或失败时覆盖安装并打开普通 APK,保留已有存储。测试完成后停止夹具。直接使用 flutter test 会在结束时卸载测试 APP,不能用于保留用户配置的测试。

Android 连接日志

APP 的“诊断与日志”记录配置校验、授权、引擎启动与运行错误。Flutter 在输出前隐藏已知凭据,Android 同步到 MeshPortRuntime;VPN 服务的阶段事件使用 MeshPortVPN,不打印完整配置。可以通过以下命令采集本次连接事件:

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 最终包验证。