Files

100 lines
8.0 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 手机直接联网设备端
独立 Android Gradle 项目,Kotlin 传统 View(无 Compose)+ Rust JNI。手机无需连接现场电脑,通过本机 adbd 接入现有控制中心、P2P 与中继,远端继续使用 ads-client、ADB、scrcpy 和可选 ads-usb。
## 目录
| 目录 | 用途 | 语言/格式 |
|---|---|---|
| app/ | Android APK 模块 | Kotlin、XML、Gradle Kotlin DSL |
| app/src/main/java/com/ttstd/ads/ | Activity、前台服务、开机恢复、配置加密、日志和 JNI 声明 | Kotlin |
| app/src/main/jniLibs/ | 构建脚本生成的多 ABI JNI 运行库,Git 忽略 | SO,无业务源码 |
| native/ | 独立 Cargo 工作区,JNI、生命周期、状态及输入校验 | Rust、TOML、Cargo.lock |
| native/src/ | Rust 网关入口与单元测试 | Rust |
| scripts/ | Windows NDK 多 ABI 构建脚本 | PowerShell |
build/、.gradle/、native/target/ 为自动生成产物或缓存,不纳入源码。当前直接通过源码路径复用 ../agent/src/gateway.rs 和 ../crates/ads-core,所以本目录需要与整个仓库一起检出,不能只复制此目录构建。
## 当前实现
- 支持最低 Android 6 / API 23,compile/target API 35;API 26+ 通知渠道与 startForegroundService;API 34+ specialUse 类型;不使用受新版限时约束的 dataSync 类型冒充长期连接。
- Kotlin Activity 提供控制中心、设备 ID、内置 Agent 令牌、本机 adbd 端口、启动/停止和实时日志。
- Service 工作线程调用 JNI,Tokio 双线程执行网络;UI 不阻塞等待网络。控制连接断线时终止旧会话,按现有网关 1–30 秒退避重连。
- 原样复用现有网关 v1/v2:设备注册、独占租约、WebRTC P2P、独立中继回退、32 路并发限制、流控和超时。
- 当前测试包从 Git 忽略的 agent.local.properties 读取 agentToken 并编入 BuildConfig;界面无需输入,不回显、不传 Intent、不写入日志。内置令牌可从 APK 提取,此包仅用于受控测试,不应公开分发。
- Rust 日志有界队列 300 条;服务每秒转入 Logcat(ADS-Agent)及应用内 300 条环形日志。记录启动、ABI、adbd 探测、注册、连接失败、重试、转发失败和退出,不记录票据、SDP、ADB 内容。
- BOOT_COMPLETED 仅在用户已启用时尝试恢复;不支持解锁前启动。停止按钮关闭下次开机恢复,关闭界面不停止服务。
## 系统前置条件与边界
按需求不实现运行时权限申请、通知权限弹窗、忽略电池优化申请、Shizuku、root、setprop 或隐藏 API 提权。Manifest 中正常声明网络、开机及前台服务权限。
ROM 必须预先提供可被本应用访问的原始 adbd TCP 端点(固定连接 127.0.0.1,默认 5555),并配置必要的 SELinux、系统预授权和后台策略。此处连接的是手机 adbd,不是电脑 ADB server 的 5037,也不是 Android 无线调试的配对/TLS 端口。程序不会自动开启 adbd,不会关闭 ADB 认证。电脑首次调试密钥授权仍由 adbd/ROM 管理。
注册成功仅代表手机已连中继,不代表 adbd 可调试。ADBD_PROBE_OK 仅代表端口可连接;探测失败仍允许注册,实际数据通道会明确报无法连接 adbd。
当前是 APK 内的 Rust JNI 服务,不是 init 托管 native 守护。START_STICKY 和开机广播不能保证 OEM 强杀、强制停止、Doze、未解锁或系统禁止前台启动时仍永久在线;系统签名也不能替代 ROM 的策略配置。未实现独立 init 服务和 SELinux 策略,不能宣称已完成所有 ROM 常驻适配。
支持 ABI:arm64-v8a、armeabi-v7a、x86_64;不包含 x86。设置 16 KB ELF 对齐,仍需在真实 16 KB 系统验收。Android 6–15 是代码适配范围,不是实机兼容认证;更高版本需要按目标 ROM 验证。
## 只构建,不安装
准备 JDK 17、Android SDK 35、Gradle 8.11.1+(当前插件 8.9.2)、NDK r28+、Rust Android targets。仓库不包含平台签名私钥,不自动签系统应用,不执行安装、刷机或更改设备配置。
```powershell
# 仓库根目录;仅编译现有工具链,不安装任何目标或软件
.\android_agent\scripts\build-native.ps1 -Ndk F:\AndroidSDK\ndk\28.2.13676358
cd android_agent
# ANDROID_HOME 指向已安装 SDK;或在 Git 忽略的 local.properties 配置 sdk.dir
gradle :app:assembleDebug
```
APK 构建会检查三种 ABI 的 SO 是否存在,不允许静默输出缺少 native 核心的 APK。当前默认使用本机提供的 Crosshatch 证书签名;系统预装、权限白名单和 SELinux 集成仍由设备厂商 ROM 流程完成。
```powershell
cargo test --manifest-path android_agent/native/Cargo.toml --locked --lib
# 如需纯 Kotlin/Manifest 编译检查(不能将其产物视为可用 APK)
gradle :app:compileDebugKotlin -x verifyNative
```
日志查看(将来安装验证时):`adb logcat -s ADS-Agent`。启动失败按 CONFIG_INVALID、JNI_LOAD_FAILED、FGS_DENIED、ADBD_PROBE_FAILED、START_FAILED 排查。不要把令牌/配置 JSON 添加到诊断输出。
参考:[前台服务类型](https://developer.android.com/develop/background-work/services/fgs/service-types)、[启动前台服务](https://developer.android.com/develop/background-work/services/fgs/launch)。
## 本次验证
- Rust 主机侧 3 项测试通过;ARM64、ARMv7、x86_64 的 Release SO 均编译完成。
- Gradle Release 编译、Manifest/资源处理、Lint Vital 和 APK 打包通过;使用 SDK 35 本地 aapt2 解决离线工具依赖缺失。
- apksigner verify 通过,v1/v2 签名有效;证书 SHA-256 与指定 keystore 别名导出的证书一致:`c8a2e9bccf597c2fb6dc66bee293fc13f2fc47ec77bc6b2b0d52c11f51192ab8`。
- APK 包含三个 ABI 的 JNI 库与 classes.dex;minSdk 23、targetSdk 35。ARM64 ELF LOAD 对齐检查为 0x4000。
- 已签名 APK:`../bin/apk/ads-android-agent-0.1.0-crosshatch.apk`(12,846,591 字节)。
- 未安装、刷机或进行真机多版本、休眠保活及公网远程调试验收。
## 默认签名
app/build.gradle.kts 默认对 debug 和 release 使用 crosshatch 签名。当前机器的密钥位置、别名和口令存放在 Git 忽略的 signing.local.properties,不把口令写入可提交构建脚本。复制项目到其他机器时需提供该文件(storeFile、storePassword、keyAlias、keyPassword),或对应 ADS_SIGNING_STOREFILE、ADS_SIGNING_STOREPASSWORD、ADS_SIGNING_KEYALIAS、ADS_SIGNING_KEYPASSWORD 环境变量。
```powershell
gradle :app:assembleRelease
```
Gradle 中间输出为 app/build/outputs/apk/release/app-release.apk;成功后自动交付到 ../bin/apk/,debug 文件增加 -debug 后缀。签名不会自动获得系统应用身份、ROM 白名单或 SELinux 权限;需要与目标 ROM 平台证书及系统预装配置匹配。
本机打包时可使用现有 SDK 的 aapt2(PowerShell 参数需保留引号):
```powershell
gradle :app:assembleRelease '-Pandroid.aapt2FromMavenOverride=F:/AndroidSDK/build-tools/35.0.0/aapt2.exe'
```
## 固定 Agent 测试包(0.1.1)
按当前要求,构建时将现有 config/private/agent.env 中的 ADS_AGENT_TOKEN 写入 Git 忽略的 agent.local.properties,通过 BuildConfig.AGENT_TOKEN 固定在 APK 内。界面已移除令牌输入框,保存配置只保存服务器、设备 ID 和 adbd 端口;旧版加密令牌字段在保存时清理,运行时始终使用内置值。
重新构建仍需本机 agent.local.properties;该文件和签名配置都不得提交。没有新增自动启动或自动开启 adbd 行为,仍需用户点击保存并启动。产物为 ../bin/apk/ads-android-agent-0.1.1-crosshatch.apk,versionCode=2,默认 Crosshatch 签名。
后续 APK 统一交付到仓库 `bin/apk/`,该目录只保存自动生成的 APK,无业务源码且不纳入 Git。
## 可选 Zhanxun 签名
默认保留 Crosshatch;使用 `gradle :app:assembleRelease -PadsSigning=zhanxun` 选择 Zhanxun。密钥参数放在 Git 忽略的 `signing.zhanxun.local.properties`,字段与默认签名相同。产物名称带 `-zhanxun`,输出到根目录 `bin/apk/`。