# 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 / … ``` 已部署的集群和使用方法见 [集群部署与协议](docs/cluster.md)。不配置集群时保留原有 v1 单中继模式,供兼容旧客户端;以下原有单机启动命令也仍可使用。 ## 目录说明 下表覆盖项目根目录及主要自有子项目;第三方源码的内部目录由其自身文档说明。语言列为主要语言或文件格式,产物目录不视为源码模块。 | 目录 | 作用 | 主要语言/格式 | | --- | --- | --- | | `agent/` | 远程设备守护程序 ads-agent,注册设备、连接手机 ADB、建立转发并重连;源码在 `src/` | 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 | | `desktop/` | 跨平台桌面客户端及其测试项目、.NET SDK 配置与使用说明 | C#、Avalonia XAML(AXAML)、JSON、Markdown | | `desktop/Ads.Desktop/` | Avalonia 桌面应用,管理配置、设备列表、连接、托盘及 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 示例 | 四个后端程序均为独立可执行文件;另有 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 是四个后端 `.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)。