Files
AndroidDeviceStreaming/README.md
T

221 lines
13 KiB
Markdown
Raw 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 Device Streaming
一个控制中心 + 多个中继节点 + P2P 优先。两端连接控制中心取得设备租约、交换信令,优先通过 WebRTC DataChannel 直连;直连失败时自动选择独立 WSS 中继。普通本地 `adb devices` 显示本地映射地址,Android Studio / scrcpy 使用同一通道。
```text
ads-server 控制中心(注册、租约、信令、节点健康)
↙ WSS WSS ↘
本地 ADB → ads-client ═══════ WebRTC P2P ═══════ ads-agent → 手机 adbd
╲ 失败则 WSS 中继 ╱
relay-1 / relay-2 / …
```
Windows 现支持可选的 [USB ADB 模拟](docs/windows-usb.md),默认网络模式保持不变。
已部署的集群和使用方法见 [集群部署与协议](docs/cluster.md)。不配置集群时保留原有 v1 单中继模式,供兼容旧客户端;以下原有单机启动命令也仍可使用。
## 目录说明
下表覆盖项目根目录及主要自有子项目;第三方源码的内部目录由其自身文档说明。语言列为主要语言或文件格式,产物目录不视为源码模块。
| 目录 | 作用 | 主要语言/格式 |
| --- | --- | --- |
| `agent/` | 远程设备守护程序 ads-agent,注册设备、连接手机 ADB、建立转发并重连;源码在 `src/` | Rust、TOML |
| `usb/` | 可选 ads-usb 本机虚拟 ADB USB 设备,提供回环 USB/IP、描述符和 ADB 帧适配;Windows 使用已签名 USBip 虚拟控制器 | Rust、TOML |
| `client/` | 本地守护程序 ads-client,维护设备租约、监听本地端口并自动调用 adb connect;源码在 `src/` | Rust、TOML |
| `server/` | ads-server 控制中心、旧协议兼容转发及独立 ads-relay 中继节点 | Go |
| `server/cmd/ads-relay/` | 独立中继入口,提供短期票据认证、WSS 数据配对及可选 STUN | Go |
| `server/internal/relay/` | 中继票据、数据通道、租约撤销、STUN 与测试 | Go |
| `crates/` | Rust 工作区共享库容器 | Rust、TOML |
| `crates/ads-core/` | 共用网络与协议代码,包括 WSS、WebRTC P2P、节点回退、ADB smart socket 和流式转发;源码在 `src/` | Rust、TOML |
| `flutter_manager/` | 独立 Flutter Windows 管理中心,提供设备/中继总览、多设备连接、本机 ADB、托盘与独立 scrcpy 窗口 | Dart、C++、CMake、YAML、ICO |
| `desktop/` | 跨平台桌面客户端及其测试项目、.NET SDK 配置与使用说明 | C#、Avalonia XAML(AXAML)、JSON、Markdown |
| `desktop/Ads.Desktop/` | Avalonia 多设备工作台,管理独立连接、自动端口分配、USB 模拟、多个 scrcpy 窗口及托盘;`Assets/` 保存图标资源 | C#、AXAML、XML(csproj)、PNG |
| `desktop/Ads.Desktop.Tests/` | 桌面客户端单元测试 | C#、XML(csproj) |
| `desktop/Ads.Desktop.Smoke/` | 桌面离屏布局、连接及可选真机冒烟验证入口 | C#、XML(csproj) |
| `deploy/` | 服务器/设备端部署脚本与 Caddy、Nginx、systemd、launchd 配置示例 | Shell、服务/代理配置、XML(plist)、Markdown |
| `deploy/windows/` | Windows 设备端准备、安装和运行脚本,通过计划任务托管 agent,附配置示例 | PowerShell、JSON、Markdown |
| `scripts/` | 项目构建、打包及本地启动脚本 | PowerShell、Shell |
| `tests/` | Python 桥接测试、三端集成测试及可选真机验证 | Python |
| `docs/` | 协议、部署、验证及旧局域网桥接说明 | Markdown |
| `config/` | 本地配置容器;`private/` 保存私有凭据等配置,已被 Git 忽略,不纳入发布包 | 环境变量文件等配置格式,无业务源码 |
| `adb/` | 本地第三方 AOSP ADB 源码检出,用于参考与研究;已被 Git 忽略,不是 adb 可执行文件目录 | 主要为 C++,另含 Python、Shell、Android.bp |
| `scrcpy/` | 本地第三方 scrcpy 源码检出;已被 Git 忽略,不是可直接运行的发行包 | C(客户端)、Java(Android 服务端)、Meson、Gradle |
| `QtScrcpy/` | 本地第三方 QtScrcpy 源码检出,供参考与研究;已被 Git 忽略 | C++、Qt、CMake |
| `bin/` | 编译/分发产物和运行工具,如 ads 三端程序、桌面包、Linux 产物及 `tools/`;已被 Git 忽略 | 可执行文件、运行库及资源,无独立源码语言 |
| `target/` | Cargo 生成的编译产物与缓存;已被 Git 忽略 | Rust 构建产物,无独立源码语言 |
| `work/` | 本地联调、测试输出、截图、日志、工具下载与临时脚本;已被 Git 忽略,不作为正式源码入口 | 混合格式,含 Python、PowerShell、日志及图片 |
| `__pycache__/` | Python 自动生成的字节码缓存;已被 Git 忽略 | Python 字节码,无手写源码 |
| `.git/` | 当前仓库的版本控制元数据,由 Git 管理 | Git 内部数据,无业务源码 |
桌面项目下的 `bin/`、`obj/` 同样是 .NET 生成的构建产物与中间文件,已被 Git 忽略。根目录的 `adb_bridge.py` 与 `start-bridge.ps1` 是旧局域网桥接入口,分别使用 Python 和 PowerShell,不属于上述目录。
新增或调整目录时,需按 `AGENTS.md` 的目录维护约定同步说明用途和主要语言/格式。
## 程序划分
| 目录 | 输出 | 职责 |
|---|---|---|
| `server/` | `ads-server` / `ads-relay` | 控制中心:认证、注册、设备独占、信令、健康检查;独立中继:数据转发 |
| `agent/` | `ads-agent` | 远程电脑后台进程,主动注册设备、接通手机、断线重连 |
| `client/` | `ads-client` | 本地后台进程,保持设备租约,提供本地端口,自动调用 `adb connect` |
| `crates/ads-core/` | 共用 Rust 库 | WSS、协议、ADB smart socket、流式转发 |
| `deploy/` | 部署示例 | Caddy、systemd、launchd 示例 |
四个网络后端与可选 ads-usb 均为独立可执行文件;另有 Avalonia 桌面工作台,不依赖 Python 运行正式程序。两端守护程序当前作为前台长运行进程,启动安装交给各平台进程管理器;尚未实现原生 Windows Service 安装器。
## 编译
需要 Go 1.24+、近期稳定版 Rust/Cargo;Windows Rust MSVC 工具链还需要 C++ Build Tools。优先使用仓库中的依赖锁文件。
Windows PowerShell:
```powershell
.\scripts\build.ps1
# 更快的本地调试构建:.\scripts\build.ps1 -DebugBuild
```
Linux / macOS:
```sh
sh scripts/build.sh
```
产物在 `bin/`,Windows 是四个网络后端及一个可选 ads-usb `.exe`。Go 服务器和 Rust 核心使用跨平台 API;Rust 两端和桌面在 Windows x64 验证,Go 控制中心与中继已部署到 Linux amd64;其余平台仍需验证构建、进程托管和 ADB 权限。
## 1. 公网服务器
生成两枚不同的随机令牌,每枚至少 32 字符。服务器保存两枚,远程端仅配置 agent 令牌,本地端仅配置 client 令牌。不要用演示文字作为真实令牌。
PowerShell 生成令牌示例:
```powershell
python -c "import secrets; print(secrets.token_hex(32))"
```
配置环境变量后启动(默认仅监听回环地址):
```powershell
$env:ADS_AGENT_TOKEN = '<生成的设备端令牌>'
$env:ADS_CLIENT_TOKEN = '<生成的本地端令牌>'
.\bin\ads-server.exe --listen 127.0.0.1:8080
```
公网部署必须启用 TLS,可用 `deploy/Caddyfile` 把 `https://devices.example.com` 代理到该 HTTP 服务;也可直接使用:
```powershell
.\bin\ads-server.exe --listen 0.0.0.0:443 --tls-cert fullchain.pem --tls-key privkey.pem
```
需要客户端信任的有效域名证书。只有域名和 443 对公网暴露,不暴露手机的 5555 和 ADB Server 的 5037。反向代理应支持 WebSocket 升级、长连接,并避免将带会话票据的 URL 写入访问日志。
## 2. 远程电脑
手机已开启 TCP ADB,且远程电脑能访问 `192.168.100.141:5555` 时:
```powershell
$env:ADS_AGENT_TOKEN = '<与服务器一致的设备端令牌>'
.\bin\ads-agent.exe --server wss://devices.example.com --device home-phone --target 192.168.100.141:5555
```
该模式直接连接手机,不需要在远程电脑额外公开 ADB Server。
也支持通过已有的 ADB Server 选择设备,用于复用当前环境:
```powershell
.\bin\ads-agent.exe --server wss://devices.example.com --device home-phone --adb-server 127.0.0.1:5037 --adb-serial 192.168.100.141:5555
```
**两个模式都要求手机已经开启 TCP adbd。仅 USB、未开启 TCP adbd 的手机暂不支持;TLS 无线调试端口也不能当作普通 5555 使用。** `--adb-serial` 模式通过已连接的 adbd,在手机自身回环地址打开 `tcp:5555`。
一个 agent 进程对应一个设备 ID。多手机可启动多个进程,ID 必须不同。
## 3. 本地电脑
需要 Android SDK Platform Tools(`adb`);投屏另外安装 scrcpy。先清除当前窗口中旧的远程 ADB 环境设置:
```powershell
Remove-Item Env:ADB_SERVER_SOCKET -ErrorAction SilentlyContinue
Remove-Item Env:ANDROID_ADB_SERVER_ADDRESS -ErrorAction SilentlyContinue
Remove-Item Env:ANDROID_ADB_SERVER_PORT -ErrorAction SilentlyContinue
$env:ADS_CLIENT_TOKEN = '<与服务器一致的本地端令牌>'
.\bin\ads-client.exe --server wss://devices.example.com --device home-phone
```
客户端默认监听 `127.0.0.1:15555`,获得设备租约后每 5 秒尝试本地 `adb connect`,支持断线后的新连接恢复。ADB 不在 PATH 时加 `--adb 'F:\AndroidSDK\platform-tools\adb.exe'`。令牌优先通过环境变量传入,避免出现在进程命令行中。
另开终端:
```powershell
adb devices -l
adb -s 127.0.0.1:15555 shell getprop ro.product.model
scrcpy -s 127.0.0.1:15555
```
预期设备是 `127.0.0.1:15555 device`。首次出现 `unauthorized` 时,在手机上批准**本地电脑**的调试密钥;远程电脑已经获得授权不代表本地电脑自动获得授权。程序不会绕过 Android 授权。
可用 `--listen 127.0.0.1:15556` 指定其他本地端口;`--no-auto-connect` 禁止自动调用 ADB,由用户手动执行 `adb connect`。本地端口强制使用回环地址。
## 本机联调
三个窗口分别运行,令牌保持一致:
```powershell
# 窗口 1
$env:ADS_AGENT_TOKEN = '<设备端令牌>'
$env:ADS_CLIENT_TOKEN = '<本地端令牌>'
.\bin\ads-server.exe
# 窗口 2:当前 VPN 环境下复用远程 ADB 验证
$env:ADS_AGENT_TOKEN = '<设备端令牌>'
.\bin\ads-agent.exe --server ws://127.0.0.1:8080 --allow-insecure --device home-phone --adb-server 192.168.5.222:5037 --adb-serial 192.168.100.141:5555
# 窗口 3
$env:ADS_CLIENT_TOKEN = '<本地端令牌>'
.\bin\ads-client.exe --server ws://127.0.0.1:8080 --allow-insecure --device home-phone
```
`--allow-insecure` 仅供隔离开发环境使用,禁止用于真实公网。该示例把 agent 临时放在本地是为了验证;真实部署时把 agent 放到远程电脑,改用 WSS 公网服务器和其可达的手机地址,即可去掉 VPN。
## 查询与验证
```powershell
Invoke-RestMethod https://devices.example.com/v1/devices -Headers @{Authorization="Bearer $env:ADS_CLIENT_TOKEN"}
```
返回 `[{"id":"home-phone","busy":false}]`。在线表示网关控制连接在线,并不保证手机此刻可达;只有建立数据连接时才检查手机 TCP 接入。
自动化检查:
```powershell
Push-Location server
go test ./...
go vet ./...
Pop-Location
cargo test --workspace --locked
cargo clippy --workspace --all-targets --locked -- -D warnings
python tests/e2e.py
```
`tests/e2e.py` 启动真实三个程序和模拟手机,验证大数据、多连接、独占和重连;不用接入真手机。可选只读真机测试:
```powershell
python tests/real_device.py --adb-server 192.168.5.222:5037 --serial 192.168.100.141:5555
```
## 当前边界
- 单中继进程、内存设备注册;服务器重启后两端重新注册、获取租约,不保留历史。
- 两个角色的共享令牌,只适用于同一个受信任管理域;不是多租户账号、每设备权限或完整用户系统。
- 每台设备只能由一个本地守护程序占用;每设备最多 32 条转发连接。
- 断线后建立新连接,旧的安装、shell、调试和串流会话不能无缝续传。
- 数据采用 TLS 分段加密,中继服务器可见转发内容;未实现端到端加密。
- 原始 ADB 数据流不重新编码;不解析 shell 命令,不改写 ADB 协议,不内置画面解码。
- 当前 WebSocket 关闭会结束整个 TCP 通道,不保留半关闭语义;已覆盖常规双向流量,额外工具的特殊连接语义需单独测试。
协议说明见 `docs/protocol.md`。此前的 Python 局域网桥接保留在 `adb_bridge.py`,说明在 `docs/local-bridge.md`,与新三端实现独立。
## 桌面客户端(Avalonia)
设备列表、配置、连接管理、托盘、运行日志及 scrcpy 独立窗口手机控制现已放在 `desktop/`。启动和工具路径配置见 [桌面客户端说明](desktop/README.md)。