USB-Share 是一款极简且高性能的底层原生 USB 设备共享工具。它基于标准的 USB/IP 协议，允许用户通过 TCP/IP 网络，将本地插入的 USB 设备（如加密狗、扫描仪、开发板等）以“原生插拔”的方式共享给远程电脑。远程电脑识别到的设备如同直接插入物理接口，确保所有原始驱动和功能完整可用。
USB-Share 解决了远程办公或多机协作场景下，物理 USB 设备（尤其是加密狗或特定硬件）无法灵活调度的痛点。
- 原生体验：在 USB 协议层 (URB) 进行拦截与重定向，远程端无需模拟，直接使用原始驱动。
- 高性能传输：针对网络波动优化，禁用 Nagle 算法，确保低延迟的数据同步。
- 跨机器连接：支持局域网自动发现与手动 IP 指定。
- ✅ 底层原生共享：支持各种类型的 USB 设备（HID、Mass Storage、Vendor Specific）。
- ✅ 双端角色支持：同一程序既可作为服务端（分享者）也可作为客户端（使用者）。
- ✅ 自动发现机制：内置 UDP 广播，一键搜索局域网内的分享端。
- ✅ 连接保护：内置心跳检测与超时重连逻辑，解决连接卡死问题。
本项目基于 Linux 内核主线收录的 USB/IP 协议 (The USB/IP Project)，采用 C/S 架构实现 USB 设备的跨网络透传。
-
服务端 (Server / Stub Driver):
- 位于物理插入 USB 设备的主机 (Host A)。
- 核心职责: 使用桩驱动 (Stub Driver) 将物理设备从原操作系统解绑，截获其 USB 请求块 (URB)，并通过 TCP 封装转发。
- 实现方案: Windows 端推荐使用成熟的 usbipd-win。
-
客户端 (Client / VHCI Driver):
- 位于需要使用 USB 设备的远程主机 (Host B)。
- 核心职责: 使用虚拟主控制器接口 (VHCI) 模拟一个虚拟 USB 端口，欺骗操作系统认为有真实设备插入。将系统的 USB 指令封装为 TCP 包发送给服务端。
- 实现方案: 采用 usbip-win2 提供的内核级 VHCI 驱动 (WHLK认证级别架构)。
- 标准 USB/IP (TCP 3240):
- 负责底层的设备枚举、握手与高频数据传输。
- 这是一个二进制协议，直接在内核态 (Kernel Mode) 处理 TCP 流，确保极低延迟。
- 设备发现 (UDP 3241):
- USB-Share 独有功能。
- 服务端定时发送 UDP 广播，客户端监听以实现“即插即用”的局域网自动发现，无需手动输入 IP。
USB-Share 本身不制造驱动，而是作为应用层编排者 (Orchestrator)：
- GUI 封装: 将复杂的命令行操作 (usbip list/attach) 转化为简单的点击。
- 连接管理: 维护心跳，处理断线重连，防止驱动僵死。
- 环境统筹: 统一管理服务端与客户端的配置，屏蔽底层驱动的碎片化差异。
- 操作系统: Windows 10 Version 1903 (Build 18362) 或更高版本 / Windows 11。
- 网络: 两台电脑需处于同一局域网，或通过 VPN 建立 TCP/IP 通道。
- 权限: 驱动安装与程序运行需要管理员权限。
本工具依赖特定的内核驱动来实现 USB 转发。根据您的角色（分享者或使用者），需要安装不同的驱动组件。
服务端需要安装“桩驱动” (Stub Driver) 来接管物理 USB 接口。
- 推荐安装: usbipd-win (dorssel)。
- 步骤:
- 下载并运行
.msi安装包。 - 重启电脑。
- 在管理员权限下运行
usbipd list确认安装成功。
- 下载并运行
客户端需要安装“虚拟总线驱动” (VHCI Driver) 来创建虚拟 USB 端口。
- 核心组件: usbip-win2 (vadimgrn)。
- 关键步骤:
- 开启测试模式: 管理员权限执行
bcdedit /set testsigning on并重启电脑（必须，否则驱动无法加载）。 - 安装证书: 在
driver_temp/usbip-win2/drivers/package中找到usbip.pfx，双击安装。将其导入到“受信任的根证书颁发机构”和“受信任的发布者”。 - 安装驱动: 在管理员终端进入驱动目录，执行：
pnputil /add-driver usbip2_ude.inf /install
- 开启测试模式: 管理员权限执行
-
在 PC-A (服务端) 操作：
- 运行
usb_share.exe。 - 在 "Local Devices" 选项卡中点击 "Refresh"。
- 选中您的 USB 设备，点击 "Share"。
- 运行
-
在 PC-B (客户端) 操作：
- 运行
usb_share.exe。 - 切换到 "Remote Connect" 选项卡。
- 在 "Discovered Devices" 列表中应该能看到 PC-A，双击它或手动输入 IP。
- 点击 "Connect"。
- 成功后，Windows 会发出发现新硬件的声音，设备将出现在您的设备管理器中。
- 运行
- IDE: Visual Studio 2022
- 编译器: MSVC (C++ 17+)
- 框架: Qt 6.x (Widgets)
- 驱动开发: Windows Driver Kit (WDK)
如果您在 Linux 下开发，可以使用我们的自动化脚本快速编译 Windows 版本的 GUI 程序。
- 详细指南: Linux 下交叉编译指南
- 快捷命令:
python3 scripts/setup_cross_compile.py cmake -DCMAKE_TOOLCHAIN_FILE=toolchain-mingw.cmake -B build_win_cross . cmake --build build_win_cross python3 scripts/deploy_windows.py # 这一步生成带 DLL 的发布包
- 安装依赖: 确保已安装 Qt 6 和 CMake。
- 生成项目:
mkdir build && cd build cmake ..
- 编译: 使用 VS 2022 打开
.sln或直接运行msbuild。 - 自动化脚本: 我们提供了
build_windows.ps1用于一键打包。
| 问题 | 原因 | 解决方法 |
|---|---|---|
| 连接一直处于 Connecting | 协议握手失败或防火墙拦截 | 确保服务端 usbipd 已启动，且防火墙允许 TCP 3240 端口。 |
| 客户端无法安装驱动 | 未开启测试签名模式 | 执行 bcdedit /set testsigning on 并重启。 |
| 找不到设备 | UDP 广播被拦截 | 检查防火墙是否允许 UDP 3241 端口，或手动输入 IP。 |
| 连接超时 | 网络延迟过高或服务端无响应 | 本程序已设置 5s 超时自动断开，请检查网络质量。 |
- MVP 核心转发功能
- 局域网 UDP 自动发现
- 基于
usbip-win2的客户端 VHCI 方案集成 - 连接握手优化与超时处理
- 系统托盘最小化运行
- 传输层 AES 数据加密
- 自动挂载规则（Persistent Devices）
- 特别感谢 usbipd-win 和 usbip-win2 提供的底层驱动支持。
- 本项目采用 MIT 许可证 授权。
保持简单，保持原生。