From ac8eb72319c7b1049f930c6efbb7dafc0cc9cd25 Mon Sep 17 00:00:00 2001 From: tongtongstudio Date: Fri, 13 Nov 2026 03:28:52 +0800 Subject: [PATCH] feat: validate native Linux virtual USB and add recovery services --- AGENTS.md | 4 +-- README.md | 4 ++- deploy/ads-linux-usb-monitor.service | 12 +++++++ deploy/ads-usb-export.service | 13 ++++++++ deploy/ads-usb-upstream.service | 11 +++++++ deploy/linux-usb-monitor.sh | 14 ++++++++ docs/linux-packaging.md | 2 +- docs/linux-usb.md | 49 ++++++++++++++++++++++++++++ 8 files changed, 105 insertions(+), 4 deletions(-) create mode 100644 deploy/ads-linux-usb-monitor.service create mode 100644 deploy/ads-usb-export.service create mode 100644 deploy/ads-usb-upstream.service create mode 100644 deploy/linux-usb-monitor.sh create mode 100644 docs/linux-usb.md diff --git a/AGENTS.md b/AGENTS.md index c27429c..2b286b1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -15,7 +15,7 @@ | --- | --- | --- | | `agent/` | 无界面多手机守护程序 ads-agent、独立监督进程、私有 IPC 和远程管理;兼容单设备参数;源码在 `src/` | Rust、TOML | | `ctl/` | adsctl 命令行管理端,本机/远程设备、配置、日志、重启及系统启动托管;源码在 `src/` | Rust、TOML | -| `usb/` | 可选 ads-usb 本机虚拟 ADB USB 设备,提供回环 USB/IP、描述符和 ADB 帧适配;Windows 使用已签名 USBip 虚拟控制器 | 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 | @@ -47,7 +47,7 @@ ## 可选 USB 模拟功能(Windows 已开始实现) -用户于 2026-11-12 授权新增可选 USB 模拟,先实现 Windows。当前采用独立 Rust USB/IP 虚拟 ADB 设备 + 已签名的 USBip UDE 控制器,复用现有网络隧道,包含桌面开关、驱动检测和安装脚本;详见 docs/windows-usb.md。Linux/macOS 仍仅记录方案,未经后续要求不实现其后端。以下跨平台内容保留为设计依据。 +用户于 2026-11-12 授权新增可选 USB 模拟,先实现 Windows。当前采用独立 Rust USB/IP 虚拟 ADB 设备 + 已签名的 USBip UDE 控制器,复用现有网络隧道,包含桌面开关、驱动检测和安装脚本;详见 docs/windows-usb.md。Linux 已按 2026-11-13 新授权完成原生 USB/IP CLI 验证,见 docs/linux-usb.md;Linux GUI 尚未接入。macOS 仍仅记录方案。以下跨平台内容保留为设计依据。 ### 目标与范围 diff --git a/README.md b/README.md index 3829e0a..d87ae34 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,7 @@ Windows 现支持可选的 [USB ADB 模拟](docs/windows-usb.md),默认网络 | --- | --- | --- | | `agent/` | 无界面多手机守护程序 ads-agent、独立监督进程、私有 IPC 和远程管理;兼容单设备参数;源码在 `src/` | Rust、TOML | | `ctl/` | adsctl 命令行管理端,本机/远程设备、配置、日志、重启及系统启动托管;源码在 `src/` | Rust、TOML | -| `usb/` | 可选 ads-usb 本机虚拟 ADB USB 设备,提供回环 USB/IP、描述符和 ADB 帧适配;Windows 使用已签名 USBip 虚拟控制器 | 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 | @@ -227,3 +227,5 @@ python tests/real_device.py --adb-server 192.168.5.222:5037 --serial 192.168.100 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 打包](docs/linux-packaging.md)。 + +Linux 原生虚拟 USB 已在 Ubuntu 实机通过 CLI 验证,部署和权限说明见 [Linux USB](docs/linux-usb.md)。Linux GUI 开关尚未接入。 diff --git a/deploy/ads-linux-usb-monitor.service b/deploy/ads-linux-usb-monitor.service new file mode 100644 index 0000000..1f36b28 --- /dev/null +++ b/deploy/ads-linux-usb-monitor.service @@ -0,0 +1,12 @@ +[Unit] +Description=ADS Linux virtual USB reattachment +Requires=ads-usb-export.service +After=ads-usb-export.service +[Service] +Type=simple +ExecStart=/usr/local/libexec/ads-linux-usb-monitor 3241 +Restart=on-failure +RestartSec=3 +NoNewPrivileges=true +[Install] +WantedBy=multi-user.target diff --git a/deploy/ads-usb-export.service b/deploy/ads-usb-export.service new file mode 100644 index 0000000..2cae391 --- /dev/null +++ b/deploy/ads-usb-export.service @@ -0,0 +1,13 @@ +# Example matching the validated Ubuntu host; adjust user and executable paths. +[Unit] +Description=ADS loopback virtual ADB USB export +Requires=ads-usb-upstream.service +After=ads-usb-upstream.service +[Service] +User=tt +ExecStart=/home/tt/ads-linux-usb/ads-usb --listen 127.0.0.1:3241 --upstream 127.0.0.1:15557 --serial ADS-home-phone +Restart=on-failure +RestartSec=3 +NoNewPrivileges=true +[Install] +WantedBy=multi-user.target diff --git a/deploy/ads-usb-upstream.service b/deploy/ads-usb-upstream.service new file mode 100644 index 0000000..a159736 --- /dev/null +++ b/deploy/ads-usb-upstream.service @@ -0,0 +1,11 @@ +# LAN validation upstream. Replace with ads-client for public cluster access. +[Unit] +Description=ADS LAN phone loopback upstream +After=network-online.target +Wants=network-online.target +[Service] +User=tt +ExecStart=/usr/bin/socat TCP-LISTEN:15557,bind=127.0.0.1,reuseaddr,fork TCP:192.168.100.141:5555 +Restart=on-failure +RestartSec=3 +NoNewPrivileges=true diff --git a/deploy/linux-usb-monitor.sh b/deploy/linux-usb-monitor.sh new file mode 100644 index 0000000..27c2006 --- /dev/null +++ b/deploy/linux-usb-monitor.sh @@ -0,0 +1,14 @@ +#!/usr/bin/env bash +# Root-only monitor for an existing loopback ads-usb export. No public USB/IP listener. +set -euo pipefail +port=${1:-3241} +[[ "$port" =~ ^[0-9]{1,5}$ ]] && ((port>=1024 && port<=65535)) || { echo 'Invalid USB/IP port' >&2; exit 2; } +((EUID==0)) || { echo 'usbip attach requires root' >&2; exit 1; } +modprobe vhci_hcd +uri="usbip://127.0.0.1:$port/1-1" +while true; do + if ! usbip port | grep -F -- "$uri" >/dev/null; then + usbip --tcp-port "$port" attach --remote 127.0.0.1 --busid 1-1 || true + fi + sleep 3 +done diff --git a/docs/linux-packaging.md b/docs/linux-packaging.md index 097ffba..88d9f85 100644 --- a/docs/linux-packaging.md +++ b/docs/linux-packaging.md @@ -11,7 +11,7 @@ bash scripts/build-linux-packages.sh agent 输出 `bin/installers/linux/` 中的 `.deb`、便携 `.tar.gz` 与 SHA256SUMS。Deb 安装路径 `/opt/ttstd/ads-*`,桌面端添加应用菜单,命令入口 `/usr/bin/ads-*`。通过 `sudo apt install ./包名.deb` 安装并解析依赖,同名包覆盖升级,通过 `sudo apt remove ads-avalonia` 等卸载。不会自动注册或启动 Agent 服务;用 adsctl 初始化并显式安装 systemd 服务,详见 agent-management.md。私有配置不放入包中,卸载不删除用户数据。 -可用 ADS_LINUX_BIN 指定 ads-agent/ads-client/adsctl 所在目录,ADS_SERVER_BIN 指定服务端产物目录,ADS_AVALONIA_BUNDLE 指定已构建的原生 Avalonia 目录并跳过 publish。包会检查 ELF 格式及机器架构,拒绝 Windows EXE 和私有配置。便携包需自行安装系统依赖;解压后从目录运行入口。Linux USB 模拟尚未支持。 +可用 ADS_LINUX_BIN 指定 ads-agent/ads-client/adsctl 所在目录,ADS_SERVER_BIN 指定服务端产物目录,ADS_AVALONIA_BUNDLE 指定已构建的原生 Avalonia 目录并跳过 publish。包会检查 ELF 格式及机器架构,拒绝 Windows EXE 和私有配置。便携包需自行安装系统依赖;解压后从目录运行入口。Linux 虚拟 USB 已有原生 CLI 实机验证,需另部署 ads-usb 和系统 usbip/vhci_hcd,见 linux-usb.md;桌面开关尚未接入。 Flutter 当前仓库没有 Linux 原生宿主,不能直接从 Windows bundle 生成 Linux 应用。打包入口 `ADS_FLUTTER_BUNDLE=/path/to/linux/bundle bash scripts/build-linux-packages.sh flutter` 仅用于后续完成 Linux 宿主与工具路径适配后的原生产物,当前不宣称 Flutter Linux 已可用。 diff --git a/docs/linux-usb.md b/docs/linux-usb.md new file mode 100644 index 0000000..4443a2e --- /dev/null +++ b/docs/linux-usb.md @@ -0,0 +1,49 @@ +# Linux 原生虚拟 ADB USB(CLI) + +2026-11-13 已在 192.168.5.224(Ubuntu 24.04、x86_64、6.8.0-147-generic)验证。无法直连 SSH 时通过 192.168.5.222 的 direct-tcpip 中转,实际 USB/IP 导出始终只监听目标 Linux 本机回环。不是把 Windows 驱动安装到 Linux,也不是将 adb connect 当作 USB 枚举。 + +## 部署结构 + +- `/home/tt/ads-linux-usb/ads-usb`:Rust 原生 Linux USB/IP 导出,使用仓库代码编译,含 APK 双向流控修复。 +- `ads-usb-upstream.service`:TT 身份运行 socat,将手机 192.168.100.141:5555 映射到 127.0.0.1:15557。 +- `ads-usb-export.service`:TT 身份运行 ads-usb,监听 127.0.0.1:3241,上游 127.0.0.1:15557,序列号 ADS-home-phone。 +- `ads-linux-usb-monitor.service`:root 运行 USB/IP 挂载监控,只挂载指定回环端口。启动前加载系统签名的 vhci_hcd;每三秒检查本次导入,缺失时重挂载。 +- `deploy/linux-usb-monitor.sh` 是监控源码,安装为 root 所有、0755 的 `/usr/local/libexec/ads-linux-usb-monitor`;不能从普通用户可修改的脚本路径以 root 启动。systemd 示例见 `deploy/ads-linux-usb-monitor.service`。 + +导出服务与监控已启用开机启动;上游作为导出服务的 Requires 依赖启动。没有重启目标电脑验证开机流程。 + +## 通用手工启动 + +需要原生 ads-usb、usbip、ADB、内核 vhci_hcd。先建立本机 raw adbd 上游,例如 ads-client 的回环映射,或局域网验证用 socat 转发(原始 ADB TCP 不是 ADB server 5037)。 + +```sh +# 无需 root,保持前台运行 +./ads-usb --listen 127.0.0.1:3241 --upstream 127.0.0.1:15557 --serial ADS-home-phone +# 另一终端,仅内核挂载操作需要 root +sudo modprobe vhci_hcd +sudo usbip --tcp-port 3241 attach --remote 127.0.0.1 --busid 1-1 +adb devices -l +adb -s ADS-home-phone get-devpath +adb -d shell getprop ro.product.model +``` + +首次显示 unauthorized 时,在手机允许该 Linux ADB 主机的调试密钥;不复制其他电脑的私钥,不绕过授权。普通用户访问 USB 使用发行版 android-sdk-platform-tools-common 的 udev 配置。`sudo usbip port` 可读 root 创建的导入来源记录;普通用户运行该命令可能显示 unknown host,不代表 ADB 不可用。 + +本次源站为局域网手机,未将手机原有 Windows 连接迁移或抢占租约。连接公网集群时,用 ads-client 替代 socat,向同一回环上游输出原始 adbd 数据;设备仍受集群独占租约约束。TT 的 client.env 经用户明确授权部署,权限 0600,仅 TT/root 可读;本次没有验证该机的公网客户端数据链路。 + +## 当前主机操作 + +```sh +systemctl status ads-usb-export ads-linux-usb-monitor +sudo usbip port +adb -d get-state +adb -s ADS-home-phone shell getprop ro.product.model +# 停止监控和导出,关闭导出连接使本次 USB 设备移除 +sudo systemctl stop ads-linux-usb-monitor ads-usb-export +# 再启动:导出启动上游,监控负责导入 +sudo systemctl start ads-linux-usb-monitor +``` + +已验证原生 `usb:3-1` 枚举、普通 TT 的 adb -d、远程 shell、8 MiB push 的 SHA-256 完整性。目标机原有三个模拟器保持运行。Linux 桌面 UI 的 USB 开关尚未接入,此版本通过 CLI/systemd 使用;MTP、fastboot 和整机 USB 透传不在范围内。目标机既有第三方 APT 源存在 404,部署使用已更新的 Ubuntu 索引,没有改写该源。 + +重挂载测试也已通过:核对来源后仅 detach 本次虚拟端口,监控自动重新导入,adb 重新恢复 device。仓库 deploy/ 下附 export、upstream 和 monitor 三份 systemd 配置示例;安装前按实际账号和路径修改,并拒绝覆盖不属于本项目的同名服务。