Files
AndroidDeviceStreaming/README.md
T

179 lines
8.0 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
公网中继 + 远程设备守护程序 + 本地连接守护程序。两端主动出站连接服务器,无需 VPN 或路由器端口映射。连接后,普通本地 `adb devices` 可以显示远程手机,Android Studio / scrcpy 使用本地 ADB 的正常设备通道。
```text
本地 ADB → 127.0.0.1:15555 → ads-client (Rust)
│ WSS
ads-server (Go)
│ WSS
ads-agent (Rust) → 手机 adbd TCP:5555
```
## 程序划分
| 目录 | 输出 | 职责 |
|---|---|---|
| `server/` | `ads-server` | 角色认证、网关注册、设备独占、会话配对、二进制转发 |
| `agent/` | `ads-agent` | 远程电脑后台进程,主动注册设备、接通手机、断线重连 |
| `client/` | `ads-client` | 本地后台进程,保持设备租约,提供本地端口,自动调用 `adb connect` |
| `crates/ads-core/` | 共用 Rust 库 | WSS、协议、ADB smart socket、流式转发 |
| `deploy/` | 部署示例 | Caddy、systemd、launchd 示例 |
三个程序均为独立可执行文件。没有 UI,不依赖 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 是三个 `.exe`。Go 服务器和 Rust 核心使用跨平台 API;当前实际编译和集成测试平台为 Windows x64,Linux/macOS 仍需在对应平台验证构建、进程托管和 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)。