一、前言：现有投屏方案痛点

做自动化测试、云手机、多机群控、远程运维安卓设备时，传统方案存在大量无法解决的短板：

  1. 原生 Scrcpy 局限：只能本地 USB/局域网无线连接，公网穿透复杂，必须安装客户端，移动端无法直接操控；
  2. 普通 Web-Scrcpy：基于 WebSocket 转发视频流，延迟高、带宽占用大，无成熟 TURN 中转，移动 4G/IPv6 网络打洞成功率极低；
  3. 商用云手机：收费高昂，不支持私有化部署，设备数据第三方托管，无法自定义群控、自动化接口；
  4. 其他 WebRTC 投屏项目：缺少完整管理后台、无群控、不支持 Root/Shizuku 免 Root 双部署、无独立单机手机运行模式。

基于以上痛点，我开发了 ScrcpyOverWebRTC（穿云投屏），一套完全开源、私有化部署、网页直连、支持公网穿透、群控、多设备接入的云手机系统，融合 Scrcpy 硬编码低延迟能力与 WebRTC 点对点传输优势，全平台浏览器无需客户端即可操控安卓设备。

项目开源地址：https://github.com/hqw700/ScrcpyOverWebRTC

当前最新版本：v0.3.2（2026-07-27，新增设备共享、群控高频预览功能）

二、项目核心架构与技术亮点

2.1 整体架构：Fat Agent 直连架构

整体分为三大模块：

  1. 服务端（信令 + Web 管理面板 + 内置 Coturn TURN）
    • 信令服务：处理 WebRTC SDP/ICE 协商、设备注册、账户鉴权、群控会话调度；
    • Web 管理后台：Vue3 前端，设备大盘、批量部署、画质动态调节、群控操作、日志查看；
    • 内置 TURN 中转：解决运营商 CGNAT、多层路由无法 P2P 直连问题，原生支持 IPv6 穿透。
  2. Android Agent 被控端

    三种部署方式覆盖全场景：ADB 一键部署（免 Root）、Magisk/KSU 模块（Root 开机自启）、独立 Android App（Root/Shizuku 双引擎，支持单机离线模式）。

  3. Web 前端主控

    纯浏览器运行，支持 Windows/macOS/Linux/iOS/Android 所有终端，内置多点触控、键盘映射、WebADB、双向剪贴板、实时码率监控。

2.2 核心技术优势（区别同类项目）

  1. 媲美原生 Scrcpy 的极低延迟

    采用 零扫描流解析（Zero-Search Parsing） + 硬件级 PTS 透传，无额外内存拷贝，视频编码链路复用 Android MediaCodec 硬编，延迟与本地 Scrcpy 几乎无差别。

  2. 公网穿透能力拉满

    原生支持 IPv6 直连，内置 Coturn 完整 TURN 服务，规避移动运营商 CGNAT 封锁，4G/5G 环境 P2P 打洞成功率远超同类方案；支持自定义公网 IP、非对称端口映射适配 NAT 网关。

  3. 全能交互能力

    多指触控、物理按键模拟、自定义键盘映射、WebADB 终端、实时高频快照；连接中动态修改分辨率/码率/帧率，自动 BWE 动态带宽调节。

  4. 一站式群控体系

    高同步率一控多，从控设备高帧率实时预览，批量点击、滑动、输入，自动化测试、游戏批量操作场景友好。

  5. 多部署方案适配不同场景
    • Docker 一键部署（Host/Bridge 两种网络模式，适合服务器、NAS）；
    • 绿色单二进制（Linux/macOS/Windows 免容器，轻量化服务器）；
    • 安卓 App 单机模式：服务端 + 被控全部运行在手机，无需云服务器，局域网浏览器直接访问。
  6. 免 Root/Root 双兼容
    • Shizuku 模式：Android 11+ 无线调试激活，纯免 Root，完整屏幕录制 + 输入权限；
    • Root 模式：Magisk/KernelSU/APatch 模块开机自启，后台保活，cpctl 命令行热配置。
  7. 全端无客户端依赖

    iOS/安卓手机、平板、电脑任意浏览器打开 HTTPS 地址直接控制，不用安装任何软件。

三、快速部署教程（三种主流方式）

前置说明

默认 Web 访问端口：8443（HTTPS），TURN 端口 3478，TURN 媒体 UDP 区间默认 50000~50100；默认账号 admin，密码 admin123。

方式 1：Docker Host 模式（推荐，独立公网 IP/纯内网 Linux）

容器直接复用宿主机网络，无 NAT 损耗，性能最优：

docker run -d \
  --pull=always \
  --rm \
  --name cp-aio \
  --net=host \
  -v ./data:/app/data \
  -e PUBLIC_IP=你的内网/公网IP \
  buutuu/scrcpy-over-webrtc:latest
  • -v ./data:/app/data：持久化存储账号、设备配置、日志，升级容器不丢失数据；
  • PUBLIC_IP：内网填服务器局域网 IP，有公网独立 IP 则填公网 IP；
  • 放行防火墙端口：8443、3478 TCP/UDP，50000-50100 UDP。

方式 2：Docker Bridge/NAT 模式（Windows/macOS Docker、多端口映射场景）

分两种映射策略，禁止全量映射 49152-65535 端口段，会导致宿主机 OOM

策略 A：对称端口映射（端口无占用）
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
策略 B：非对称端口映射（8443/3478 被占用，外部端口不一致）

例如外部 18443 映射容器 8443、13478 映射 3478，必须传入外部端口环境变量，否则 TURN 连接黑屏：

docker run -d --name cp-aio \
  --pull=always \
  --rm \
  -p 18443:8443 \
  -p 13478:3478/tcp \
  -p 13478:3478/udp \
  -p 55000-55100:55000-55100/udp \
  -e PUBLIC_IP=192.168.100.242 \
  -e COTURN_MIN_PORT=55000 \
  -e COTURN_MAX_PORT=55100 \
  -e EXTERNAL_SIGNALING_PORT=18443 \
  -e EXTERNAL_TURN_PORT=13478 \
  buutuu/scrcpy-over-webrtc:latest

方式 3：绿色单二进制（不装 Docker，轻量化服务器）

  1. 项目 Release 页下载对应系统安装包 cloudphone-vX.Y.Z.zip；
  2. Linux/macOS 启动： 
    unzip cloudphone-v0.3.2.zip -d cloudphone
cd cloudphone
chmod +x start_server.sh
./start_server.sh
  3. Windows：解压后进入 bin\windows_amd64 执行 run.bat；

注意：二进制版不内置 TURN 服务，局域网使用开箱即用；公网穿透需自行部署 Coturn 并通过 -ice_servers 参数指定。

自定义启动参数示例（修改端口、关闭认证、自定义 STUN/TURN）：

# 修改监听 9443 端口，内网调试关闭登录
./start_server.sh -port 9443 -no-auth

四、安卓设备三种入网部署方案

打开管理后台 https://服务器IP:8443，进入【部署新设备】页面获取对应配置与资源包。

方案 1：ADB 一键部署（免 Root，临时调试首选）

  1. 手机开启开发者选项 + USB 调试，电脑 USB 连接手机；
  2. 下载页面 agent-deploy.zip 一键部署包解压；
  3. 终端执行自动推送 Agent 脚本： 
    # Linux/macOS
chmod +x run.sh && ./run.sh -id 自定义设备ID -signaling wss://服务端IP:8443
# Windows CMD
run.bat -id 自定义设备ID -signaling wss://服务端IP:8443

执行完成后设备自动上线后台。

方案 2：Magisk/KSU 刷机模块（Root 设备，长期 7*24 运行）

适合自动化机房、批量真机集群，重启自动重连保活：

  1. 后台下载 cloudphone-agent-magisk.zip 传输至手机；
  2. Magisk/KernelSU 本地安装模块，重启手机；
  3. 终端 su 权限配置服务地址与设备 ID： 
    su
cpctl set CP_AGENT_SIGNALING "wss://服务端IP:8443"
cpctl set CP_AGENT_ID "device01"
cpctl restart
# 查看运行状态
cpctl status

方案 3：CloudPhone App 被控端（免电脑，Root/Shizuku 双模式）

  1. Release 下载官方 APK 安装至安卓手机；
  2. 打开 App → 进入【被控端模式】；
  3. 二选一权限引擎：
    • Root 模式：直接授予 su 权限；
    • Shizuku 模式：Android 11+ 无线调试激活 Shizuku，纯免 Root；
  4. 填入信令地址与设备 ID，启动 Agent；
  5. 特色单机模式：开启后服务端完整运行在本机，无需云服务器，同局域网浏览器访问手机 IP:8443 即可控制。

五、前端二次开发指南（Vue3 源码开源）

项目 web-app 目录完整开源 Vue3 前端，支持本地热更新开发，无需编译后端：

  1. 启动服务端 Docker 容器；
  2. 进入前端目录安装依赖： 
    cd web-app
npm install
  3. 本地开发（代理转发 API 至后端容器）： 
    VITE_PROXY_TARGET=https://服务器IP:8443 npm run dev
  4. 生产打包： 
    npm run build

打包产物自动输出至项目 assets 目录，替换容器内静态资源即可升级面板；详细开发文档查看 docs/DEVELOPMENT.md。

六、环境变量配置大全（自定义服务参数）

启动容器时通过 -e 传入自定义配置，常用参数：

环境变量用途
PUBLIC_IP服务器公网/内网 IP，WebRTC ICE 候选地址
TURN_USER/TURN_PASSWORDTURN 中转账号密码，生产务必修改
SIGNALING_PORT容器内部 Web 服务端口，默认 8443
EXTERNAL_SIGNALING_PORT非对称映射外部 Web 端口
EXTERNAL_TURN_PORT非对称映射外部 TURN 端口
COTURN_MIN_PORT/COTURN_MAX_PORTTURN 媒体 UDP 端口区间
NO_AUTH=true关闭登录验证，仅内网测试
DEFAULT_SETTINGS新接入设备默认画质 JSON，示例 {"maxBitrate":8,"fps":60}

完整自定义 Docker 示例（限制 8 Mbps 码率、60 帧、修改 TURN 账号）：

docker run -d \
  --pull=always \
  --rm \
  --name cp-aio \
  --net=host \
  -v ./data:/app/data \
  -e PUBLIC_IP=xxx.xxx.xxx.xxx \
  -e TURN_USER=phone_turn \
  -e TURN_PASSWORD=SecurePass123456 \
  -e DEFAULT_SETTINGS='{"maxBitrate":8,"minBitrate":2,"fps":60,"size":1920,"bitrate":6}' \
  buutuu/scrcpy-over-webrtc:latest

七、适用场景

  1. 企业真机自动化测试：多设备网页群控，批量执行 UI 自动化，WebADB 远程调试；
  2. 私有化云手机机房：自研云手机替代商用平台，数据本地存储；
  3. 远程运维安卓设备：异地操控手机、工控安卓平板，公网低延迟访问；
  4. 手游批量群控：高同步一控多，高频预览，动态调节画质节省带宽；
  5. 移动端演示、直播投屏：浏览器直接投屏，无需数据线，多终端随时查看；
  6. 无服务器离线场景：安卓 App 单机模式，手机本地运行整套服务，外出调试。

八、开源协议与补充说明

  1. 前端 web-app 目录采用 MIT 开源协议，可自由二次开发商用；
  2. Docker 镜像内置的后端二进制程序仅允许个人学习、非商用测试；
  3. 项目持续迭代，最新 Release、更新日志、完整文档：ScrcpyOverWebRTC (CloudPhone) 官方指南与帮助文档 | ScrcpyOverWebRTC Docs
  4. 仓库地址：GitHub - hqw700/ScrcpyOverWebRTC: A high-performance, web-based Android remote control solution powered by scrcpy and WebRTC. Control your devices with ultra-low latency directly from your browser. · GitHubA high-performance, web-based Android remote control solution powered by scrcpy and WebRTC. Control your devices with ultra-low latency directly from your browser. - hqw700/ScrcpyOverWebRTChttps://github.com/hqw700/ScrcpyOverWebRTC，欢迎 Star、提交 Issue
# 开源 # webrtc
Logo
火山引擎视频云技术社区

火山引擎视频云技术社区，是面向 AI 音视频开发者的技术交流平台。这里汇聚源自抖音、豆包等亿级 DAU 产品的 RTC、直播、点播、AI 媒体处理、音视频互动技术，提供接入指南、最佳实践、性能调优、场景案例、Demo 代码、开源项目、白皮书和 API 文档。社区汇聚官方工程师与一线开发者，为 AI 视频通话、数字人、AI 视频处理等应用的开发与落地提供技术支持。

更多推荐

洛雪音乐桌面版完整实战：找歌、攒列表、定制与排障一次讲清

装完洛雪音乐桌面版（lx-music-desktop），很多人卡在同一件事上：歌是搜到了，播放却不一定响得起来，或者听了几首歌就不知道往哪放。这个基于 Electron + Vue 3 开发的开源播放器，默认设置并不刻意迁就新手，但它的五个在线音乐源、本地列表管理、桌面歌词和音效模块，只要按顺序摸一遍，日常使用就足够了。这篇指南按"找歌 → 攒列表 → 调体验 → 进阶玩法 → 故障排查"五个环节

avatar 火山引擎视频云技术社区

基于 WebRTC-Experiment 的 Firefox 屏幕捕获扩展：从自定义域名到 AMO 发布全指南

> 本文以 [Firefox-Extensions/README.md](https://link.gitcode.com/i/d51aa89ee4d31cc869ed4221467fa333) 为主体，结合仓库内 `enable-screen-capturing` 等目录的源码，讲解如何通过 Firefox 扩展为 WebRTC 页面启用屏幕捕获能力：包括扩展的工作原理（preference 白

avatar 火山引擎视频云技术社区

洛雪音乐桌面版：5 个快捷键加 3 个启动参数，把找歌速度提上来

深夜想找那首老歌，搜索页卡了十秒。洛雪音乐聚合多个音乐源，基于 Electron+Vue 3。掌握洛雪音乐快捷键，搜索到播放只需两步。## 洛雪音乐 30 秒上手：打开、搜索、播放1. 打开软件，焦点默认在搜索框（随时按 `F1` 重新聚焦），输入歌名，结果直接出来。2. 单击歌曲即可试听，默认会先加入"我的列表"的试听列表再播放。3. 想连续听多首，按下节的顺序多选并建歌单。[!

avatar 火山引擎视频云技术社区