Android Device Streaming
公网中继 + 远程设备守护程序 + 本地连接守护程序。两端主动出站连接服务器,无需 VPN 或路由器端口映射。连接后,普通本地 adb devices 可以显示远程手机,Android Studio / scrcpy 使用本地 ADB 的正常设备通道。
本地 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:
.\scripts\build.ps1
# 更快的本地调试构建:.\scripts\build.ps1 -DebugBuild
Linux / macOS:
sh scripts/build.sh
产物在 bin/,Windows 是三个 .exe。Go 服务器和 Rust 核心使用跨平台 API;当前实际编译和集成测试平台为 Windows x64,Linux/macOS 仍需在对应平台验证构建、进程托管和 ADB 权限。
1. 公网服务器
生成两枚不同的随机令牌,每枚至少 32 字符。服务器保存两枚,远程端仅配置 agent 令牌,本地端仅配置 client 令牌。不要用演示文字作为真实令牌。
PowerShell 生成令牌示例:
python -c "import secrets; print(secrets.token_hex(32))"
配置环境变量后启动(默认仅监听回环地址):
$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 服务;也可直接使用:
.\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 时:
$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 选择设备,用于复用当前环境:
.\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 环境设置:
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'。令牌优先通过环境变量传入,避免出现在进程命令行中。
另开终端:
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。本地端口强制使用回环地址。
本机联调
三个窗口分别运行,令牌保持一致:
# 窗口 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。
查询与验证
Invoke-RestMethod https://devices.example.com/v1/devices -Headers @{Authorization="Bearer $env:ADS_CLIENT_TOKEN"}
返回 [{"id":"home-phone","busy":false}]。在线表示网关控制连接在线,并不保证手机此刻可达;只有建立数据连接时才检查手机 TCP 接入。
自动化检查:
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 启动真实三个程序和模拟手机,验证大数据、多连接、独占和重连;不用接入真手机。可选只读真机测试:
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,与新三端实现独立。