6.7 KiB
可选 Windows USB 模拟
原理与范围
本机原版 ADB / WinUSB
↕ USB 请求
已签名 USBip UDE 虚拟控制器
↕ 本机回环 USB/IP
ads-usb(本项目的虚拟 ADB USB 设备)
↕ 本机原始 adbd 流
ads-client → P2P / WSS 中继 → ads-agent → 手机 TCP adbd
这是 USB 枚举与端点适配,不会执行 adb connect 来冒充 USB 设备。已有远程手机仍可保持 LAN ADB 接入,远程电脑、控制中心和中继无需为此更改程序或开放 USB/IP 端口。网络 ADB 是默认模式,USB 模拟为可选开关。
本项目没有新增内核驱动,而是使用上游 usbip-win2 已签名的 UDE 控制器。虚拟 ADB 接口为 FF/42/01,bulk IN 0x81 / OUT 0x02,512 字节最大包,提供 Microsoft OS 1.0 的 WinUSB 兼容 ID 与 Android ADB 接口 GUID。当前兼容设备身份为 18D1:4EE7,序列号 ADS-设备ID(超长 ID 使用哈希),用于本机软件模拟,不能把它作为自有硬件 VID 分配。
只模拟 ADB,不包含 MTP、fastboot、音视频 USB 接口。P2P/中继和网络延迟仍然存在。Linux/macOS 后端未实现;当前驱动安装脚本固定支持 Windows x64。
安装
以 PowerShell 7 从项目根目录运行:
# 只下载、验证,不更改系统
.\scripts\install-windows-usb.ps1
# 启动上游安装器;管理员 UAC 确认后完成安装
.\scripts\install-windows-usb.ps1 -Install
固定上游 USBip 0.9.8.1 x64,脚本同时核对 SHA256 和有效 Authenticode 发布者证书:
- SHA256:38CAD6D4432B52D5BB9409D9AD03B72FDFFC4ADA4CD3A48FBECA1A2752A8518A
- 发布者:Cloudyne Systems (Scheibling Consulting AB)
- 证书指纹:9AC56B6C76141395D74FFF6652818376E80B9C95
安装会短暂重启 USB 集线器;安装器可能要求随后重启 Windows。脚本不会强制重启、打开测试签名或关闭 Secure Boot。升级版本时需重新核验发布资产、签名及驱动兼容性。第三方安装包不进入 Git;Windows 客户端分发包附带经固定哈希及签名校验的原版安装器,由用户选择安装。
2026-11-12 已在当前 Windows 安装驱动,usbip2_ude 与 usbip2_filter 均运行。安装器报告需要重启,但未自动重启;重启前的虚拟 USB 枚举、远程 shell 已通过。
桌面使用
- 构建后端和工作台(scripts/build.ps1、scripts/build-desktop.ps1)。
- 进入“连接配置 → 可选 USB 模拟 · Windows”。勾选 USB 模拟,指定 usbip.exe(默认 C:\Program Files\USBip\usbip.exe)。
- USB/IP 端口默认 3240,仅回环,必须与本地 ADB 隧道端口不同且未占用。
- 连接设备。桌面支持同时挂载多台设备,每台自动分配独立 ADB、USB/IP 与投屏端口;工作台先启动 ads-client 并等待设备租约,再启动虚拟设备并调用 usbip 挂载。
- 本机 ADB 显示 ADS-home-phone,使用
adb -s ADS-home-phone shell或桌面投屏。无需 adb connect。 - 断开连接时关闭本次虚拟设备和本次网络客户端,释放远端租约,不卸载控制器驱动,不操作其他 USB 设备。
同机有其他 USB 手机时,adb -d 会报告 more than one USB device,这是原版 ADB 的行为;使用 -s 指定模拟设备。只连接这一个 USB ADB 设备时才能用 -d 唯一选择。
移除可选组件可通过 Windows“已安装的应用”卸载 USBip;先断开本项目 USB 模式。卸载涉及系统驱动,应遵循其卸载器提示。取消桌面开关即可继续使用网络模式。
协议与验证
USB/IP import/list、独占导入、设备/配置/字符串/WinUSB 描述符、端点 STALL、bulk IN/OUT、UNLINK、零长度包、断开与资源回收均在本项目实现。按 ADB 24 字节包头和载荷重建传输边界,避免把 TCP 分段误当 USB 短包;最大 ADB 载荷和单 URB 为 1 MiB,接收队列与待处理 URB 有界。USB/IP 无公网认证层,因此严格限制为回环;跨公网只走已有认证、加密的 ADS 通道。
cargo test -p ads-usb --locked
python tests/usb_e2e.py
cd desktop
dotnet run --project Ads.Desktop.Smoke -c Debug -- --live --screen --usb
2026-11-12:协议集成测试通过,包含任意 TCP 分段下的 ADB 包头/载荷还原、512 字节载荷后的 ZLP、取消无多余完成包、畸形/超大 URB 拒绝。真实已签名 Windows 控制器导入后,原版 ADB 枚举 ADS-home-phone 并执行远端 echo / getprop;本机已有物理 USB 手机未被移除,adb -d 正确报告多 USB 设备。
参考:USB/IP 协议、Microsoft UDE、AOSP Windows USB transport。
桌面 USB 模式实测通过:P2P 路线状态、USB 序列号选择、设备型号、真实 scrcpy 视频、重新连接、断开后释放租约、清理本机隧道端口时一并移除虚拟 USB,以及凭据不写入配置/日志。结束后 USBip 控制器导入数量为 0,物理 USB 手机保持在线。
多设备工作台中,切换当前设备不会断开其他 USB 设备;清理所选设备的隧道端口只释放该设备。退出和“断开全部”释放本工作台的全部虚拟 USB 设备,不卸载驱动或操作物理 USB 手机。
Flutter Windows
“连接配置”勾选“挂载为 USB 设备 · Windows”,先检测 USBip 控制器、usbip.exe 和 ads-usb。未安装控制器时弹出安装提示;选择安装后验证随包安装器的 SHA-256 和发布者签名,启动交互安装器请求 UAC,不静默安装、不重启 Windows。安装完成后重新检测并勾选、保存配置,再连接设备。
Flutter 连接会等待租约状态为 true,禁用网络 adb connect,分配独立回环 USB/IP 端口并挂载;设备列表和投屏使用 ADS- 序列号。断开/退出停止本次 ads-usb,借助 --once 与 TCP EOF 移除本设备,不按可能复用的控制器端口 detach。
Windows 包在 drivers/ 下附带原版 USBip-0.9.8.1-x64.exe 及来源说明;ADS 主安装器只复制该文件,不自动安装驱动。
安装 APK 时的双向流控
USB/IP bulk OUT 写入由独立有界任务处理,不再阻塞控制请求和 bulk IN 完成;仅在远端实际接收写入后确认 OUT 完成。避免 APK 安装等双向高负载下主事件循环等待网络写入、无法处理返回数据而触发断线。tests/usb_e2e.py 包含远端停止读取且上行堆积 12 MiB 时的控制请求回归测试。更新 ads-usb 后需要重新连接虚拟 USB 才能使用新进程。