Implement authenticated public relay and Rust device daemons
This commit is contained in:
1 parent
f96c1aa109
commit
e1c152a657
29 files changed
+3244
-39
No files matched your search
@@ -1,77 +1,174 @@
|
||||
# Android 远程设备桥接
|
||||
# Android Device Streaming
|
||||
|
||||
让本机普通 `adb devices` 显示远程手机,同时保留本地 ADB 服务及其他本地设备。
|
||||
公网中继 + 远程设备守护程序 + 本地连接守护程序。两端主动出站连接服务器,无需 VPN 或路由器端口映射。连接后,普通本地 `adb devices` 可以显示远程手机,Android Studio / scrcpy 使用本地 ADB 的正常设备通道。
|
||||
|
||||
```text
|
||||
本地 adb → 127.0.0.1:15555(本程序)
|
||||
→ 192.168.5.222:5037(远程 ADB 服务)
|
||||
→ 已连接的 192.168.100.141:5555
|
||||
→ 手机自身 localhost:5555(adbd)
|
||||
本地 ADB → 127.0.0.1:15555 → ads-client (Rust)
|
||||
│ WSS
|
||||
ads-server (Go)
|
||||
│ WSS
|
||||
ads-agent (Rust) → 手机 adbd TCP:5555
|
||||
```
|
||||
|
||||
本地无需能访问手机网段。远程电脑必须能访问手机,手机必须已开启 TCP ADB 5555;仅 USB 或 TLS 无线调试设备不能直接套用本方案。
|
||||
## 程序划分
|
||||
|
||||
## 远程电脑
|
||||
| 目录 | 输出 | 职责 |
|
||||
|---|---|---|
|
||||
| `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
|
||||
adb kill-server
|
||||
adb -a -P 5037 nodaemon server start
|
||||
.\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
|
||||
adb connect 192.168.100.141:5555
|
||||
adb devices
|
||||
python -c "import secrets; print(secrets.token_hex(32))"
|
||||
```
|
||||
|
||||
只允许可信 VPN 客户端访问远程 TCP 5037。ADB smart socket 没有客户端认证和加密,不应直接暴露公网。以后走公网时,把 `--remote-host` 和 `--remote-port` 改成 SSH 等认证加密隧道的本地入口。
|
||||
|
||||
## 本地电脑
|
||||
|
||||
需要 Python 3、ADB;画面操作另外需要 scrcpy。
|
||||
|
||||
在项目目录执行并保持窗口运行:
|
||||
配置环境变量后启动(默认仅监听回环地址):
|
||||
|
||||
```powershell
|
||||
python .\adb_bridge.py
|
||||
$env:ADS_AGENT_TOKEN = '<生成的设备端令牌>'
|
||||
$env:ADS_CLIENT_TOKEN = '<生成的本地端令牌>'
|
||||
.\bin\ads-server.exe --listen 127.0.0.1:8080
|
||||
```
|
||||
|
||||
另开 PowerShell,清除之前指向远程服务的环境变量,仅影响当前窗口:
|
||||
公网部署必须启用 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
|
||||
adb connect 127.0.0.1:15555
|
||||
adb devices -l
|
||||
adb -s 127.0.0.1:15555 shell getprop ro.product.model
|
||||
$env:ADS_CLIENT_TOKEN = '<与服务器一致的本地端令牌>'
|
||||
.\bin\ads-client.exe --server wss://devices.example.com --device home-phone
|
||||
```
|
||||
|
||||
应出现 `127.0.0.1:15555 device`。首次可能是 `unauthorized`,需要在手机上批准本地电脑的 RSA 调试密钥;远程电脑的授权不会自动授予本地电脑。
|
||||
客户端默认监听 `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
|
||||
```
|
||||
|
||||
这是真正注册到本地 ADB 服务的 TCP 设备,Android Studio 应能发现它(需使用同一个本地 ADB 服务)。安装、shell、logcat、forward/reverse 均走本地 ADB 的正常设备通道;实际设备上的兼容性仍需验证。断点调试要求目标应用可调试。
|
||||
预期设备是 `127.0.0.1:15555 device`。首次出现 `unauthorized` 时,在手机上批准**本地电脑**的调试密钥;远程电脑已经获得授权不代表本地电脑自动获得授权。程序不会绕过 Android 授权。
|
||||
|
||||
## 参数、诊断及停止
|
||||
可用 `--listen 127.0.0.1:15556` 指定其他本地端口;`--no-auto-connect` 禁止自动调用 ADB,由用户手动执行 `adb connect`。本地端口强制使用回环地址。
|
||||
|
||||
## 本机联调
|
||||
|
||||
三个窗口分别运行,令牌保持一致:
|
||||
|
||||
```powershell
|
||||
python .\adb_bridge.py --check
|
||||
python .\adb_bridge.py --remote-host 192.168.5.222 --remote-port 5037 --serial 192.168.100.141:5555 --device-port 5555 --listen-port 15555
|
||||
python -m unittest discover -s tests -v
|
||||
# 窗口 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
|
||||
```
|
||||
|
||||
- `--check` 只检查远程设备选择和手机 TCP 端口,不验证本地 RSA 授权、投屏或 IDE。
|
||||
- 找不到设备:在远程电脑重新 `adb connect`,检查设备序列号。
|
||||
- `tcp:5555` 失败:手机必须监听自身 TCP 5555;某些系统可能限制回环访问。
|
||||
- 远程链路断开后:恢复远程设备连接,再在本地重跑 `adb connect 127.0.0.1:15555`。当前版本不主动自动重连。
|
||||
- 停止:本地执行 `adb disconnect 127.0.0.1:15555`,再在桥接窗口按 Ctrl+C。
|
||||
`--allow-insecure` 仅供隔离开发环境使用,禁止用于真实公网。该示例把 agent 临时放在本地是为了验证;真实部署时把 agent 放到远程电脑,改用 WSS 公网服务器和其可达的手机地址,即可去掉 VPN。
|
||||
|
||||
协议依据:本项目自带的 `adb/docs/dev/services.md` 中 `host:transport:<serial-number>` 及设备 `tcp:<port>` 服务。
|
||||
## 查询与验证
|
||||
|
||||
```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`,与新三端实现独立。
|
||||
Reference in new issue
Block a user