5.0 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 或桌面分发包。
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 隧道端口不同且未占用。
- 连接设备。工作台先启动 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 手机保持在线。