173 lines
5.0 KiB
Markdown
173 lines
5.0 KiB
Markdown
# YAMA Android 客户端
|
||
|
||
YAMA 的 Android 客户端，允许服务端将 Android 设备作为受控主机进行远程查看和操控。功能包括：
|
||
|
||
- 屏幕实时截图并推流给服务端
|
||
- 接收服务端的触控/按键指令并注入到系统
|
||
- 后台保持心跳连接，支持长期驻留
|
||
|
||
---
|
||
|
||
## 编译前：配置服务端地址
|
||
|
||
服务端 IP 和端口在源码中硬编码，编译前必须修改：
|
||
|
||
文件：`app/src/main/java/com/yama/client/MainActivity.kt`
|
||
|
||
```kotlin
|
||
private val serverIp = "91.99.165.207" // 改为你的服务端 IP
|
||
private val serverPort = 443 // 改为你的服务端端口
|
||
```
|
||
|
||
改完再执行编译，否则客户端连不上服务端。
|
||
|
||
---
|
||
|
||
## 编译环境
|
||
|
||
在 **WSL（Ubuntu）或原生 Linux** 上编译，Windows 原生环境不支持。
|
||
|
||
| 依赖 | 版本要求 | 安装命令 |
|
||
|---|---|---|
|
||
| Java | 17+ | `sudo apt install openjdk-17-jdk` |
|
||
| CMake | 3.22+ | `sudo apt install cmake` |
|
||
| Ninja | 任意 | `sudo apt install ninja-build` |
|
||
| Android SDK | 含 build-tools | 见下方说明 |
|
||
| Android NDK | 30.x（Linux 版） | 见下方说明 |
|
||
|
||
### Android SDK
|
||
|
||
推荐通过 Android Studio 安装，安装后 SDK 默认在：
|
||
|
||
- Windows：`%USERPROFILE%\AppData\Local\Android\Sdk`
|
||
- Linux：`~/Android/Sdk`
|
||
|
||
WSL 环境下脚本会自动检测 Windows 侧的 SDK，也可以手动指定：
|
||
|
||
```bash
|
||
export ANDROID_HOME=/mnt/c/Users/<用户名>/AppData/Local/Android/Sdk
|
||
```
|
||
|
||
### Android NDK（Linux 版）
|
||
|
||
> **重要**：必须使用 **Linux 版 NDK**，Windows NDK 的 `.exe` 工具无法在 WSL 内执行。
|
||
|
||
```bash
|
||
# 下载 Linux NDK（约 600 MB）
|
||
wget https://dl.google.com/android/repository/android-ndk-r30b-linux.zip
|
||
unzip android-ndk-r30b-linux.zip -d $HOME
|
||
|
||
# 解压目录名可能带字母后缀（r30、r30b 等），统一重命名
|
||
mv $HOME/android-ndk-r30* $HOME/android-ndk
|
||
```
|
||
|
||
脚本会自动检测 `~/android-ndk`，也可以通过环境变量指定：
|
||
|
||
```bash
|
||
export ANDROID_NDK_HOME=$HOME/android-ndk
|
||
```
|
||
|
||
---
|
||
|
||
## 签名密钥（一次性准备）
|
||
|
||
Release APK 需要签名密钥。密钥库文件 `yama-release.jks` 已在仓库中，**密码需向仓库维护者获取**，或通过以下方式传入：
|
||
|
||
```bash
|
||
# 方式一：环境变量（推荐，避免每次输入）
|
||
export YAMA_PWD=密钥库密码
|
||
|
||
# 方式二：编译时脚本会交互提示输入
|
||
```
|
||
|
||
如需重新生成密钥库（密码遗失等情况）：
|
||
|
||
```bash
|
||
cd android/
|
||
keytool -genkeypair -keystore yama-release.jks \
|
||
-alias yama -keyalg RSA -keysize 2048 -validity 10000 \
|
||
-dname 'CN=YAMA,O=Internal,C=CN'
|
||
```
|
||
|
||
> 密钥库文件本身不含私密信息，可以提交到 git；密码不要提交。
|
||
> 重新生成密钥库后，已安装旧版本的设备需要先卸载再安装。
|
||
|
||
---
|
||
|
||
## 编译
|
||
|
||
在 WSL 或 Linux 终端中，进入 `android/` 目录：
|
||
|
||
```bash
|
||
cd android/
|
||
|
||
# 编译 Release（默认，约 1.7 MB，推荐部署用）
|
||
./build_apk.sh
|
||
|
||
# 编译 Debug（约 4 MB，含调试符号，开发排查用）
|
||
./build_apk.sh debug
|
||
|
||
# 清理所有编译产物（切换配置或遇到奇怪错误时使用）
|
||
./build_apk.sh clean
|
||
```
|
||
|
||
编译成功后产物：
|
||
|
||
| 类型 | 路径 |
|
||
|---|---|
|
||
| Release | `ghost.apk` |
|
||
| Debug | `ghost-debug.apk` |
|
||
|
||
---
|
||
|
||
## 安装到设备
|
||
|
||
### 1. 传输 APK
|
||
|
||
将 `ghost.apk` 拷贝到手机（USB 传输、微信文件传输等均可）。
|
||
|
||
### 2. 安装
|
||
|
||
在手机上用文件管理器找到 APK，点击安装。
|
||
|
||
如提示"禁止安装未知来源应用"，需先开启允许：
|
||
|
||
- **Android 8+**：设置 → 应用 → 找到你使用的文件管理器 → 允许安装未知应用
|
||
- **MIUI/ColorOS 等**：设置 → 隐私/安全 → 安装未知应用
|
||
|
||
### 3. 解除受限设置（Android 13+ 必须）
|
||
|
||
Android 13 及以上系统对手动安装的 APK 有额外限制，若不解除，无法授权 Accessibility Service：
|
||
|
||
1. 打开 **设置 → 应用 → YAMA**
|
||
2. 点击右上角 **三点菜单**
|
||
3. 选择 **"允许受限设置"**（Allow restricted settings）
|
||
4. 使用 PIN 或指纹确认
|
||
|
||
> 此步骤每次重新安装 APK 后都需要重复执行一次。
|
||
|
||
### 4. 授权必要权限
|
||
|
||
**Accessibility Service**（必须，用于注入触控/按键）
|
||
|
||
设置 → 无障碍 → 已安装的应用 → YAMA → 开启
|
||
|
||
> 重装 APK 后此权限会被重置，需重新授权。
|
||
|
||
### 5. 启动
|
||
|
||
点击桌面 YAMA 图标启动，系统会弹出屏幕录制确认框，点击 **"立即开始"** 授权。
|
||
|
||
授权后应用进入后台运行，通知栏会显示一条持久通知表示服务正在运行。此后服务端即可在主机列表中看到该设备。
|
||
|
||
> 屏幕录制确认在每次应用重启后都会弹出，这是 Android 系统的强制要求，无法跳过。
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
- 建议在电池优化设置中将 YAMA 设为 **"不限制"**（或"不优化"），防止系统在后台将其杀掉
|
||
- 路径：设置 → 应用 → YAMA → 电池 → 不限制
|
||
- 心跳间隔最小 30 秒，长期后台运行耗电量与微信后台相当
|
||
- 服务端可在设置中调大上报间隔（建议不超过 60 秒）以进一步降低耗电
|