# Cloud phone

**Repository Path**: qs0010/cloud-phone

## Basic Information

- **Project Name**: Cloud phone
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-26
- **Last Updated**: 2026-04-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CloudPhone - 云真机平台

一个开源的云手机远程控制平台，无需 ADB，通过 WebRTC 实现低延迟屏幕串流和远程操控。

## 架构

```
┌──────────────────┐     WebSocket/WebRTC      ┌──────────────────┐
│   Android 手机    │ ◄────────────────────────► │   云服务器 (Node)  │
│                  │                            │                  │
│ MediaProjection  │     WebSocket (控制)        │  信令服务器        │
│ WebRTC 推流      │ ◄────────────────────────► │  设备注册管理      │
│ Accessibility    │                            │  静态资源服务      │
│ Service (输入)   │                            │                  │
└──────────────────┘                            └────────┬─────────┘
                                                         │
                                                         │ WebSocket/WebRTC
                                                         │
                                                  ┌──────▼─────────┐
                                                  │   Web 浏览器     │
                                                  │                │
                                                  │ WebRTC 视频接收  │
                                                  │ 触控事件采集     │
                                                  │ 虚拟按键控制     │
                                                  └────────────────┘
```

## 核心特性

- **零 ADB 依赖**：手机端安装 Agent App，通过 WebSocket/WebRTC 直连服务器
- **WebRTC 低延迟串流**：H.264 硬件编码，P2P 传输
- **实时触控反馈**：触控事件通过 WebSocket 实时回传
- **虚拟按键**：Home / Back / Recent / 音量 / 电源
- **多设备支持**：同时管理多台手机
- **网页端访问**：浏览器直接使用，无需安装

## 快速开始

### 1. 启动服务器

```bash
cd server
npm install
npm start
# 访问 http://localhost:3000
```

### 2. 安装 Android App

用 Android Studio 打开 `android/` 目录，编译安装到手机。

### 3. 连接使用

1. 打开 Android App，输入服务器地址，点击启动
2. 浏览器打开服务器地址，即可看到在线设备
3. 点击设备即可远程控制

## 技术栈

| 组件 | 技术 |
|------|------|
| 服务器 | Node.js + Express + ws |
| Web 客户端 | 原生 HTML/CSS/JS + WebRTC |
| Android | Kotlin + WebRTC + MediaProjection + AccessibilityService |
| 信令协议 | WebSocket (JSON) |
| 视频编码 | H.264 (硬件加速) |

## 目录结构

```
cloud-phone/
├── server/                 # 服务端
│   ├── package.json
│   ├── server.js           # 主服务 (信令 + HTTP)
│   └── public/             # Web 客户端
│       ├── index.html
│       ├── style.css
│       └── app.js
├── android/                # Android Agent App
│   ├── app/
│   │   ├── build.gradle.kts
│   │   └── src/main/
│   │       ├── AndroidManifest.xml
│   │       ├── java/com/cloudphone/agent/
│   │       │   ├── MainActivity.kt
│   │       │   ├── ScreenStreamService.kt
│   │       │   ├── SignalingClient.kt
│   │       │   └── RemoteInputService.kt
│   │       └── res/
│   └── build.gradle.kts
└── README.md
```

## 命令行编译 APK

无需 Android Studio，可通过命令行直接编译 Debug APK。

### 环境依赖

| 依赖 | 版本 | 说明 |
|------|------|------|
| JDK | 17 | 推荐 Oracle JDK 或 Eclipse Temurin |
| Android SDK (Command-Line Tools) | latest | 用于安装 SDK 平台和构建工具 |
| Android SDK Platform | android-34 | compileSdk = 34 |
| Android Build Tools | 34.0.0 | AGP 8.2.0 所需 |
| Gradle | 8.5 | 项目自带 gradlew，自动下载 |

### 编译步骤

#### 1. 安装 JDK 17

```bash
# Ubuntu / Debian (apt)
sudo apt install openjdk-17-jdk-headless

# 或手动下载 Oracle JDK
wget https://download.oracle.com/java/17/archive/jdk-17.0.12_linux-x64_bin.tar.gz
tar xzf jdk-17.0.12_linux-x64_bin.tar.gz
export JAVA_HOME=$(pwd)/jdk-17.0.12
export PATH=$JAVA_HOME/bin:$PATH
```

#### 2. 安装 Android SDK

```bash
# 下载 Command-Line Tools
wget https://dl.google.com/android/repository/commandlinetools-linux-11076708_latest.zip
mkdir -p /opt/android-sdk/cmdline-tools
unzip commandlinetools-linux-11076708_latest.zip
mv cmdline-tools /opt/android-sdk/cmdline-tools/latest

export ANDROID_HOME=/opt/android-sdk
export PATH=$ANDROID_HOME/cmdline-tools/latest/bin:$PATH

# 接受许可 & 安装必要组件
yes | sdkmanager --licenses
sdkmanager "platforms;android-34" "build-tools;34.0.0" "platform-tools"
```

#### 3. 配置项目

在 `android/` 目录下创建 `local.properties`：

```properties
sdk.dir=/opt/android-sdk
```

#### 4. 编译

```bash
cd android
chmod +x gradlew
./gradlew assembleDebug
```

编译产物位于：

```
android/app/build/outputs/apk/debug/app-debug.apk
```

> 首次编译需下载 Gradle 及所有依赖，耗时较长（约 5-10 分钟）。后续编译会快很多。

### 已验证的编译环境

- Ubuntu 24.04 (Noble)
- JDK 17.0.12 (Oracle)
- Android SDK 34 + Build Tools 34.0.0
- Gradle 8.5 (wrapper 自动下载)

## 信令协议

所有消息格式为 JSON：

```json
{ "type": "message_type", "payload": { ... } }
```

### 设备端消息
- `device:register` — 注册设备
- `device:heartbeat` — 心跳保活

### 信令消息
- `signal:offer` — WebRTC Offer
- `signal:answer` — WebRTC Answer
- `signal:ice` — ICE Candidate

### 控制消息
- `control:touch` — 触控事件 (坐标归一化 0~1)
- `control:key` — 按键事件
- `control:swipe` — 滑动手势