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 成功后自动复制到该目录。

S
Description
No description provided
Readme
1.7 MiB
0 Stars 1 Watchers 0 Forks
Languages
Dart 26.4%
C# 20.6%
Rust 20.5%
Python 8.9%
Go 8.1%
Other 15.5%