17 KiB
Android Device Streaming
一个控制中心 + 多个中继节点 + P2P 优先。两端连接控制中心取得设备租约、交换信令,优先通过 WebRTC DataChannel 直连;直连失败时自动选择独立 WSS 中继。普通本地 adb devices 显示本地映射地址,Android Studio / scrcpy 使用同一通道。
ads-server 控制中心(注册、租约、信令、节点健康)
↙ WSS WSS ↘
本地 ADB → ads-client ═══════ WebRTC P2P ═══════ ads-agent → 手机 adbd
╲ 失败则 WSS 中继 ╱
relay-1 / relay-2 / …
Agent 管理已同时接入 Avalonia 和 Flutter;服务器无需 GUI,可使用 adsctl 管理本机或远程 Agent。安装与命令示例见 Agent 管理。
Windows 现支持可选的 USB ADB 模拟,默认网络模式保持不变。
已部署的集群和使用方法见 集群部署与协议。不配置集群时保留原有 v1 单中继模式,供兼容旧客户端;以下原有单机启动命令也仍可使用。
目录说明
下表覆盖项目根目录及主要自有子项目;第三方源码的内部目录由其自身文档说明。语言列为主要语言或文件格式,产物目录不视为源码模块。
| 目录 | 作用 | 主要语言/格式 |
|---|---|---|
android_agent/ |
手机直接联网的 Android 设备端,Kotlin 传统 View、前台服务与 Rust JNI 网关;不申请运行时权限 | Kotlin、Rust、Gradle Kotlin DSL、XML、TOML |
agent/ |
无界面多手机守护程序 ads-agent、独立监督进程、私有 IPC 和远程管理;兼容单设备参数;源码在 src/ |
Rust、TOML |
ctl/ |
adsctl 命令行管理端,本机/远程设备、配置、日志、重启及系统启动托管;源码在 src/ |
Rust、TOML |
usb/ |
可选 ads-usb 本机虚拟 ADB USB 设备,提供回环 USB/IP、描述符和 ADB 帧适配;Windows 使用已签名 USBip 虚拟控制器,Linux 使用内核 vhci_hcd(CLI) | 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-management/ |
Agent 配置及管理协议、Windows 命名管道/Unix socket、私有文件与系统服务操作;源码在 src/ |
Rust、TOML |
crates/ads-core/ |
共用网络与协议代码,包括 WSS、WebRTC P2P、节点回退、ADB smart socket 和流式转发;源码在 src/ |
Rust、TOML |
flutter_manager/ |
独立 Flutter Windows 管理中心,使用 Cupertino UI,提供电脑分组设备、Agent 管理、按天滚动日志、多设备连接、虚拟 USB、托盘与内嵌投屏 | Dart、C++、CMake、YAML、ICO |
desktop/ |
跨平台桌面客户端及其测试项目、.NET SDK 配置与使用说明 | C#、Avalonia XAML(AXAML)、JSON、Markdown |
desktop/Ads.Desktop/ |
Avalonia 多设备工作台,管理独立连接、自动端口分配、USB 模拟、多个 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 设备端准备与计划任务部署、桌面安装包定义及配置示例 | PowerShell、Inno Setup(ISS)、JSON、Markdown |
scripts/ |
项目构建、Windows 安装包、Linux deb/tar.gz 打包及本地启动脚本 | 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 产物、apk/ Android 安装包及 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 |
控制中心:认证、注册、设备独占、信令、健康检查;独立中继:数据转发 |
android_agent/ |
手机直接联网的 Android 设备端,Kotlin 传统 View、前台服务与 Rust JNI 网关;不申请运行时权限 | Kotlin、Rust、Gradle Kotlin DSL、XML、TOML |
agent/ |
ads-agent |
远程电脑后台进程,主动注册设备、接通手机、断线重连 |
client/ |
ads-client |
本地后台进程,保持设备租约,提供本地端口,自动调用 adb connect |
crates/ads-management/ |
Agent 配置及管理协议、Windows 命名管道/Unix socket、私有文件与系统服务操作;源码在 src/ |
Rust、TOML |
crates/ads-core/ |
共用 Rust 库 | WSS、协议、ADB smart socket、流式转发 |
deploy/ |
部署示例 | Caddy、systemd、launchd 示例 |
网络后端、adsctl 与可选 ads-usb 均为独立可执行文件,不依赖 Python 运行正式程序。Agent 可由 Windows 计划任务或 Linux systemd 托管;Avalonia 与 Flutter 管理界面是可选入口。Windows 使用计划任务,并非原生 SCM 服务。
编译
需要 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 是四个网络后端及一个可选 ads-usb .exe。Go 服务器和 Rust 核心使用跨平台 API;Rust 两端和桌面在 Windows x64 验证,Go 控制中心与中继已部署到 Linux amd64;其余平台仍需验证构建、进程托管和 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,与新三端实现独立。
桌面客户端(Avalonia)
设备列表、配置、连接管理、托盘、运行日志及 scrcpy 独立窗口手机控制现已放在 desktop/。启动和工具路径配置见 桌面客户端说明。
Agent 管理发行入口:scripts/build-desktop.ps1 生成 bin/desktop-win-x64/,scripts/build-flutter.ps1 生成 bin/flutter-win-x64/,两者均包含 Agent/CLI,均不包含私有凭据。Avalonia 本机 Agent 托盘使用 scripts/start-agent-tray.ps1。
Linux 安装包:bash scripts/build-linux-packages.sh,提供 .deb 和 .tar.gz,详见 Linux 打包。
Linux 原生虚拟 USB 已在 Ubuntu 实机通过 CLI 验证,部署和权限说明见 Linux USB。Avalonia Linux GUI 已接入 pkexec 挂载,Flutter Linux 尚未接入。
Flutter 管理中心已迁移 Cupertino UI,设备按电脑归属分组,支持按电脑名搜索;运行日志按天保存并按大小滚动,路径及策略见 Flutter 使用说明。
桌面日志界面提供“打开日志文件夹”。Avalonia 与 Flutter 均按天保存日志,单文件达到 5 MiB 后滚动,每日最多 5 份,保留最近 14 天。设备列表显示所属电脑及 Agent。Windows 安装包默认安装到 %LOCALAPPDATA%/Programs/TongTongStudio/ADS-{Edition};用户配置和日志位置保持兼容。升级保持原 AppId,安装目录不再自动沿用旧的 TTSTD 路径。
发布打包约定
每次新发布打包将版本号的补丁位增加 1(例如 0.2.0 → 0.2.1),同步 Cargo 工作区与锁文件、Avalonia、Flutter 和安装包版本。Windows 必须生成 Setup.exe,Linux 采用 deb 安装包;普通开发编译不增加版本。同一版本的 Windows/Linux 安装包只递增一次,另一平台使用复用版本选项。打包失败后重试复用已分配版本,避免重复递增。发布产物不包含私有凭据。
scripts/release-version.py 为共享版本分配脚本(Python)。Windows 使用 scripts/build-installers.ps1 自动递增并重建后端与桌面安装包;同一次发布的重试或第二平台使用 -ReuseVersion。Linux 使用 bash scripts/build-linux-packages.sh 自动递增,另一平台已分配版本时设置 ADS_REUSE_VERSION=1,须提供该版本重新构建的原生产物。
Windows 发布精简:Avalonia 合并托管程序集、保留原生库;Flutter 源码插件静态链接 MSVC CRT。scripts/check-windows-crt.py 使用 Python 标准库检查 PE 直接及延迟导入,防止缺失运行库。安装升级清理应用根目录旧 DLL,保留配置和独立工具目录。
升级从 Programs/TTSTD 迁至 Programs/TongTongStudio 后,两个桌面客户端自动修复保存的工具路径,保留有效自定义路径及私有凭据。Flutter 在启动与连接前进行迁移和文件检查。
Android APK 交付目录固定为 bin/apk/(APK 格式,无业务源码,自动生成且 Git 忽略);android_agent 的 assembleRelease / assembleDebug 成功后自动复制到该目录。