## 前言

在自动化测试、远程运维、设备实验室、应用兼容性测试等场景中，我们经常需要从电脑集中查看和控制多台 Android 设备。

传统方案通常需要安装专用客户端，或者依赖复杂的 ADB、端口转发和投屏环境。设备数量增加后，连接管理、画面预览和批量操作也会变得越来越麻烦。

最近体验了一个开源项目 **Scrcpy over WebRTC（穿云投屏）**。它将 Scrcpy 的设备控制能力和 WebRTC 的实时传输能力结合起来，把多台 Android 手机统一接入网页管理平台。管理端不需要安装专用客户端，打开浏览器即可查看和控制设备。

项目地址：

- GitHub：[https://github.com/hqw700/ScrcpyOverWebRTC](https://github.com/hqw700/ScrcpyOverWebRTC)

- 使用文档：[https://webrtc-phone.com/docs/](https://webrtc-phone.com/docs/)

## 一、这个项目能做什么？

简单来说，它可以把闲置 Android 手机或测试设备变成可远程访问的“云手机”，并通过网页进行统一管理。

主要能力包括：

- 浏览器直接查看和控制 Android 设备

- 多设备在线状态与卡片式预览

- 多台设备同步群控

- 键盘映射、多点触控和物理按键模拟

- WebADB 终端与文件管理

- 动态调整分辨率、码率和帧率

- 实时快照与设备标签管理

- IPv6 直连及 STUN/TURN 网络穿透

- 支持 Windows、macOS、Linux、Android 和 iOS 浏览器

- 支持 ADB、Magisk/KernelSU/APatch、Root、Shizuku 等设备接入方式

项目采用 Fat Agent 直连架构，视频传输基于 WebRTC，并结合 Scrcpy 完成屏幕采集和控制。对于局域网、设备实验室和具备良好网络条件的远程控制场景，操作延迟和画面流畅度都比较有优势。

## 二、适合哪些使用场景？

这套方案比较适合以下用途：

1. **Android 自动化测试**

   

   集中管理多台不同系统版本、分辨率和品牌的真机。

2. **设备实验室**

   

   将测试手机统一接入内网，研发或测试人员通过浏览器远程使用。

3. **远程技术支持**

   

   在授权和合规的前提下，远程查看设备状态、执行调试命令。

4. **应用兼容性验证**

   

   同时观察应用在多台设备上的界面和运行状态。

5. **个人设备管理**

   

   将闲置 Android 手机接入局域网，作为长期在线的测试终端。

> 请仅将该项目用于拥有管理权限的设备，并遵守相关平台规则、隐私要求和当地法律法规。

## 三、Docker 快速搭建

如果服务器是 Linux，并且有独立公网 IP 或者只在局域网中使用，推荐采用 Host 网络模式。

### 1. 准备环境

需要提前安装：

- Docker

- 一台 Linux 主机或云服务器

- 一台开启 USB 调试的 Android 手机

确认宿主机的 `8443` 和 `3478` 等端口没有被其他服务占用。

### 2. 启动服务

执行以下命令：

```bash

docker run -d \

  --pull=always \

  --rm \

  --name cp-aio \

  --net=host \

  -v ./data:/app/data \

  -e PUBLIC_IP=<宿主机真实IP> \

  buutuu/scrcpy-over-webrtc:latest

```

参数说明：

- `--net=host`：容器直接使用宿主机网络，减少 NAT 转发损耗。

- `-v ./data:/app/data`：持久化用户、设备标签、快照等数据。

- `PUBLIC_IP`：公网环境填写公网 IP，局域网环境填写宿主机内网 IP。

启动后可以查看运行状态：

```bash

docker ps

docker logs -f cp-aio

```

### 3. 打开管理平台

在浏览器访问：

```text

https://<宿主机IP>:8443

```

项目默认管理员账号为：

```text

账号：admin

密码：admin123

```

**首次登录后务必修改默认密码。公网部署时，还必须更换 TURN 用户名和密码，并正确配置防火墙和 HTTPS 证书。**

## 四、Windows 或 Bridge 网络怎么部署？

在 Windows、macOS 或必须使用端口映射的环境中，可以采用 Bridge 模式：

```bash

docker run -d \

  --name cp-aio \

  --pull=always \

  --rm \

  -p 8443:8443 \

  -p 3478:3478/tcp \

  -p 3478:3478/udp \

  -p 55000-55100:55000-55100/udp \

  -v ./data:/app/data \

  -e PUBLIC_IP=<宿主机物理IP> \

  -e COTURN_MIN_PORT=55000 \

  -e COTURN_MAX_PORT=55100 \

  buutuu/scrcpy-over-webrtc:latest

```

这里需要特别注意：

- 不要映射整个 `49152-65535` UDP 端口段，否则可能带来大量端口代理进程或资源占用。

- TURN 使用的 UDP 端口范围必须与 Docker 映射范围一致。

- 如果容器内外端口不一致，需要配置 `EXTERNAL_SIGNALING_PORT` 和 `EXTERNAL_TURN_PORT`。

## 五、如何接入 Android 手机？

服务启动后，进入管理平台中的“部署新设备”页面。项目提供了多种接入方式。

### 方式一：电脑 ADB 一键部署

这种方式不需要 Root，适合首次体验和临时调试。

基本步骤：

1. 手机开启开发者选项和 USB 调试。

2. 使用 USB 数据线连接电脑。

3. 在管理平台下载 `agent-deploy.zip`。

4. 解压后执行页面自动生成的接入命令。

Windows 示例：

```bat

run.bat -id phone-01 -signaling wss://<宿主机IP>:8443

```

Linux 或 macOS 示例：

```bash

chmod +x run.sh

./run.sh -id phone-01 -signaling wss://<宿主机IP>:8443

```

接入成功后，设备会出现在网页的设备列表中。

### 方式二：Magisk / KernelSU / APatch 模块

对于已经 Root、需要长期运行的设备，可以将 Agent 作为系统服务安装，实现开机自启和后台保活。

这种方式适合固定设备实验室，但涉及 Root 和系统模块操作，建议先使用测试机验证。

### 方式三：App + Root 或 Shizuku

官方 Android App 同时支持主控端和被控端模式。没有 Root 的 Android 11+ 设备可以通过无线调试激活 Shizuku，再授权 Agent 运行。

这种方案减少了对电脑 ADB 环境的依赖，适合需要快速接入设备的场景。

## 六、实际使用中比较亮眼的功能

### 1. 网页直接控制

打开浏览器就能进入设备管理页面，不必给每一台管理电脑安装投屏客户端。对于多人共用的测试环境，这种方式更方便。

### 2. 多设备矩阵

设备以卡片方式展示，可以快速确认在线状态和画面。设备数量较多时，可以通过标签、搜索和筛选进行管理。

### 3. 群控

选择一台主控设备后，可以将触控操作同步到多台从控设备。该能力适合测试和统一配置，但实际效果会受到设备型号、分辨率、网络状态和目标应用界面差异影响。

### 4. 动态画质配置

管理端可以调整：

- 分辨率

- 默认码率

- 最低与最高码率

- 帧率

- BWE 动态码率

局域网中可以优先追求画质和帧率；公网或移动网络环境则可以适当降低码率，提高连接稳定性。

### 5. WebADB 与文件管理

除了投屏控制，平台还集成了终端和文件相关能力，方便开发者进行设备调试。

## 七、技术栈与二次开发

项目公开了 Web 前端源码，主要技术栈包括：

- Vue 3

- Vite

- Pinia

- Vue Router

- WebRTC

- WebUSB / WebADB

- xterm.js

- ECharts

进入前端目录安装依赖：

```bash

cd web-app

npm install

```

本地开发：

```bash

VITE_PROXY_TARGET=http://localhost:8443 npm run dev

```

生产构建：

```bash

npm run build

```

如果你需要定制后台界面、设备卡片、品牌样式或业务入口，可以基于公开的前端源码进行二次开发。

需要说明的是：仓库主要开放 Web 前端源码；完整发布包、Android App 和非 Docker 部署版本需要从项目 Releases 页面获取。使用前请仔细阅读项目许可证与发布介质说明。

## 八、部署时必须注意的安全问题

如果只是学习和体验，建议先在局域网中运行。准备暴露到公网时，至少完成以下配置：

1. 修改默认管理员密码。

2. 修改 `TURN_USER` 和 `TURN_PASSWORD`。

3. 使用可信 HTTPS 证书。

4. 只开放实际需要的端口。

5. 不要在公网环境启用 `NO_AUTH`。

6. 定期更新镜像并备份 `data` 目录。

7. 为服务器配置防火墙、访问控制和日志审计。

8. 不要接入未经授权的设备。

## 九、总结

Scrcpy over WebRTC 将 Scrcpy、WebRTC、WebADB 和多设备管理能力整合到一个网页平台中，降低了搭建真机远程控制环境的门槛。

它比较突出的特点是：

- 管理端通过浏览器使用

- 支持多设备集中管理和群控

- 支持多种 Android Agent 部署方式

- 提供 Docker 与绿色单二进制部署方案

- Web 前端源码开放，方便二次开发

如果你正在搭建设备实验室、Android 测试平台，或者手中有多台闲置手机，希望通过网页进行统一管理，可以关注并尝试这个项目。

项目链接：

- GitHub：[https://github.com/hqw700/ScrcpyOverWebRTC](https://github.com/hqw700/ScrcpyOverWebRTC)

- 官方文档：[https://webrtc-phone.com/docs/](https://webrtc-phone.com/docs/)

- Releases：[https://github.com/hqw700/ScrcpyOverWebRTC/releases](https://github.com/hqw700/ScrcpyOverWebRTC/releases)

如果本文对你有帮助，欢迎点赞、收藏，也欢迎在评论区交流实际部署中遇到的问题。