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
@@ -0,0 +1,77 @@
|
||||
# Android 远程设备桥接
|
||||
|
||||
让本机普通 `adb devices` 显示远程手机,同时保留本地 ADB 服务及其他本地设备。
|
||||
|
||||
```text
|
||||
本地 adb → 127.0.0.1:15555(本程序)
|
||||
→ 192.168.5.222:5037(远程 ADB 服务)
|
||||
→ 已连接的 192.168.100.141:5555
|
||||
→ 手机自身 localhost:5555(adbd)
|
||||
```
|
||||
|
||||
本地无需能访问手机网段。远程电脑必须能访问手机,手机必须已开启 TCP ADB 5555;仅 USB 或 TLS 无线调试设备不能直接套用本方案。
|
||||
|
||||
## 远程电脑
|
||||
|
||||
保持下面的服务运行(停止旧服务会中断已有调试连接):
|
||||
|
||||
```powershell
|
||||
adb kill-server
|
||||
adb -a -P 5037 nodaemon server start
|
||||
```
|
||||
|
||||
另开窗口:
|
||||
|
||||
```powershell
|
||||
adb connect 192.168.100.141:5555
|
||||
adb devices
|
||||
```
|
||||
|
||||
只允许可信 VPN 客户端访问远程 TCP 5037。ADB smart socket 没有客户端认证和加密,不应直接暴露公网。以后走公网时,把 `--remote-host` 和 `--remote-port` 改成 SSH 等认证加密隧道的本地入口。
|
||||
|
||||
## 本地电脑
|
||||
|
||||
需要 Python 3、ADB;画面操作另外需要 scrcpy。
|
||||
|
||||
在项目目录执行并保持窗口运行:
|
||||
|
||||
```powershell
|
||||
python .\adb_bridge.py
|
||||
```
|
||||
|
||||
另开 PowerShell,清除之前指向远程服务的环境变量,仅影响当前窗口:
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
应出现 `127.0.0.1:15555 device`。首次可能是 `unauthorized`,需要在手机上批准本地电脑的 RSA 调试密钥;远程电脑的授权不会自动授予本地电脑。
|
||||
|
||||
画面及鼠标操作:
|
||||
|
||||
```powershell
|
||||
scrcpy -s 127.0.0.1:15555
|
||||
```
|
||||
|
||||
这是真正注册到本地 ADB 服务的 TCP 设备,Android Studio 应能发现它(需使用同一个本地 ADB 服务)。安装、shell、logcat、forward/reverse 均走本地 ADB 的正常设备通道;实际设备上的兼容性仍需验证。断点调试要求目标应用可调试。
|
||||
|
||||
## 参数、诊断及停止
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
- `--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。
|
||||
|
||||
协议依据:本项目自带的 `adb/docs/dev/services.md` 中 `host:transport:<serial-number>` 及设备 `tcp:<port>` 服务。
|
||||
@@ -0,0 +1,36 @@
|
||||
# ADS relay protocol v1
|
||||
|
||||
All requests use `Authorization: Bearer <token>`. Agent and client roles have separate shared tokens. Tickets are opaque random 192-bit values and must not be logged. Public deployments use HTTPS/WSS with normal certificate verification; TLS ends at the relay.
|
||||
|
||||
## Endpoints
|
||||
|
||||
| Endpoint | Role | Purpose |
|
||||
|---|---|---|
|
||||
| `GET /healthz` | Public | Liveness only |
|
||||
| `GET /v1/devices` | Client | JSON array of gateway IDs and busy flags |
|
||||
| `GET /v1/agent?device=ID` | Agent | Persistent gateway control WebSocket |
|
||||
| `GET /v1/lease?device=ID` | Client | Persistent exclusive ownership WebSocket |
|
||||
| `GET /v1/connect?device=ID&lease=TICKET` | Client | One binary data WebSocket per local TCP connection |
|
||||
| `GET /v1/data?device=ID&session=TICKET` | Agent | One binary WebSocket paired to a pending client stream |
|
||||
|
||||
IDs contain 1–128 ASCII letters, digits, `.`, `_`, `-`. Device IDs cannot be replaced by another agent until the original connection ends. Duplicate agents / occupied leases return HTTP 409, missing devices return 404, bad roles return 401. Stream limit is 32 per device.
|
||||
|
||||
## Connection flow
|
||||
|
||||
1. Agent connects and receives `{"type":"registered","device":"home-phone"}`.
|
||||
2. Client daemon acquires a lease and receives `{"type":"leased","lease":"..."}`.
|
||||
3. Client daemon accepts a local TCP socket, opens `/v1/connect` with its lease.
|
||||
4. Relay sends the agent `{"type":"open","session":"..."}`.
|
||||
5. Agent connects to the phone's raw TCP adbd (directly, or through an existing ADB smart socket), then opens `/v1/data` with that session ticket.
|
||||
6. Relay pairs the streams. Each session ticket can only be claimed once, by the current registered agent for the requested device.
|
||||
7. Binary WebSocket messages carry consecutive raw TCP bytes. Message boundaries have no ADB meaning. Chunks are at most 64 KiB from Rust; all peers limit received messages to 128 KiB.
|
||||
|
||||
Agent and lease control channels use server-initiated ping every 20 seconds with a 10-second timeout. Device data must attach within 15 seconds. Payload writes time out after 30 seconds; awaited bounded writes propagate backpressure. Disconnecting agent or lease cancels attached streams. A new agent registration or lease never inherits old sessions.
|
||||
|
||||
The client connects the resulting local TCP endpoint with the local ADB Server. The phone therefore authenticates the local computer's ADB key, not just the gateway key. This is the distinction between a real local ADB transport and pointing an adb CLI at a remote ADB Server.
|
||||
|
||||
## Scope
|
||||
|
||||
One relay process, one trusted administration domain. There is no database, per-user ACL, distributed broker or end-to-end encryption in v1. An agent-role token authorizes registering device aliases within that domain; provision it only to trusted gateway hosts.
|
||||
|
||||
Gateways currently require a raw TCP adbd endpoint. Existing smart socket mode uses `host:transport:<serial>` then `tcp:<port>` on the selected device. It does not transparently virtualize a USB-only device. TCP half-close is not carried across a WebSocket close. Reconnection creates fresh transports, not resumable application streams.
|
||||
@@ -0,0 +1,21 @@
|
||||
# Verification record
|
||||
|
||||
Validated on Windows x64 during implementation:
|
||||
|
||||
- `go test ./...`: role authentication, offline devices, duplicate registration, exclusive leases, ticket ownership and replay rejection, bidirectional bytes, stream cancellation, agent disconnect cleanup.
|
||||
- `go vet ./...`: passed.
|
||||
- `cargo test --workspace --locked`: configuration validation and ADB smart socket handshake with fragmented replies.
|
||||
- `cargo clippy --workspace --all-targets --locked -- -D warnings`: passed.
|
||||
- Release builds: Go relay and both Rust executables built successfully.
|
||||
- `python tests/e2e.py` against the release binaries: passed 2 MiB binary transfer, eight concurrent streams, an idle stream across control ping/pong, competing-client rejection, agent restart and relay restart recovery.
|
||||
- Existing Python bridge unit tests: all three passed.
|
||||
|
||||
Read-only real-device smoke test:
|
||||
|
||||
- Remote ADB Server `192.168.5.222:5037` listed `192.168.100.141:5555` as online.
|
||||
- Started a temporary relay and both Rust daemons, with the gateway using the existing remote ADB transport.
|
||||
- Local `adb connect` reached the phone through the new three-program path, but Android returned `unauthorized` for the local computer's key.
|
||||
- Consequently, real `adb shell`, app installation, Android Studio and scrcpy have not been verified through the new path. Approve the local key on the phone, then rerun `tests/real_device.py`.
|
||||
- Temporary processes and local ADB endpoint were disconnected after the test; unrelated local ADB devices were preserved.
|
||||
|
||||
No public server was deployed. Production WSS certificates, real Internet latency, and Linux/macOS runtime behavior still need deployment-environment validation. The Linux Go server is cross-built separately; cross-building is not a Linux runtime test.
|
||||
Reference in new issue
Block a user