# 基于nps的USB/IP远程USB Hub挂载需求规格说明书

## 1. 项目背景
通过位于长沙的树莓派4将USB Hub上的设备（特别是JLINK等调试器/串口设备）共享至上海阿里云VPS，再由上海浦东的Windows 11客户端挂载，实现跨地域USB设备访问，支持开发调试与自动化测试场景。

## 2. 系统架构

- **树莓派4（长沙）**：运行Raspberry Pi OS，连接USB Hub，作为USB/IP服务器（usbipd），绑定需要共享的USB设备。
- **VPS（上海阿里云）**：作为公网中继节点，运行nps服务端（frps），接受树莓派的连接，并将USB/IP服务暴露至公网。
- **Windows 11客户端（上海浦东）**：运行USB/IP客户端（usbipd-win或其他实现），通过VPS与树莓派建立连接，挂载并使用远程USB设备。

数据流：
`USB设备` → `树莓派USB/IP server (TCP 3240)` → `npc客户端隧道` → `VPS nps服务端` → `Windows 11 usbip attach`

## 3. 功能需求

| 需求ID | 描述 | 优先级 |
|--------|------|--------|
| F-01 | 树莓派自动加载USB/IP内核模块，并绑定指定USB Hub下的所有设备，支持JLINK等调试器及通用串口设备 | 高 |
| F-02 | 使用nps实现反向穿透，将树莓派的3240端口暴露到VPS的指定TCP端口 | 高 |
| F-03 | Windows 11客户端可通过`usbip attach -r <VPS_IP> -p <port> -b <busid>`命令挂载远程设备，支持通过WSL 2进行挂载 | 高 |
| F-04 | 支持设备热插拔：树莓派自动绑定新插入的设备，Windows客户端无需重启服务即可通过脚本化流程重连 | 中 |
| F-05 | 断线自动重连：npc客户端及USB/IP连接具有自动恢复能力 | 中 |
| F-06 | 安全性：VPS防火墙仅允许可信IP（如Windows客户端公网IP）访问USB/IP转发端口；若nps支持，可启用加密传输 | 中 |
| F-07 | 支持SEGGER J-Link Remote Server作为JLINK远程调试的备选方案，以应对USB/IP可能存在的兼容性问题 | 中 |

## 4. 非功能需求

- **延迟**：长沙至上海阿里云专线/公网RTT预计在20-40ms，可勉强支持USB全速设备（12 Mbps）的基本操作；JLINK等调试器对延迟敏感，建议严格测试。
- **吞吐量**：受限于树莓派USB 2.0/3.0及VPS带宽，单设备持续读写建议≤10 Mbps。
- **并发**：同时挂载不超过4个USB设备。
- **可用性**：系统服务（nps, npc, usbipd）应配置为开机自启，网络恢复后自动重连。

## 5. 关键组件与版本建议

| 组件 | 推荐版本 | 备注 |
|------|----------|------|
| 树莓派OS | Raspberry Pi OS (Bookworm/Legacy) with kernel≥5.10 | 需内置usbip工具 |
| USB/IP服务端 | usbip (linux-tools-generic) | 服务端：`usbipd -D` |
| nps服务端/客户端 | nps 0.26.10+ | 服务端部署于VPS，客户端（npc）部署于树莓派 |
| Windows USB/IP客户端 | usbipd-win | 适用于Windows 11，支持WSL 2；注意需以管理员权限安装驱动 |
| JLINK备选方案 | J-Link Remote Server (v7.x+) | 若USB/IP稳定性不佳，可启动该服务并将端口通过nps转发 |

## 6. 详细部署步骤

### 6.1 树莓派（长沙）配置
1.  **安装USB/IP支持**：
    ```bash
    sudo apt update
    sudo apt install usbip hwdata -y