gnomeria/usbtree

# usbtree 跨平台 TUI，用于检查 USB 设备树（Linux、macOS、Windows）。通过 [nusb](https://crates.io/crates/nusb) 枚举设备 — 纯 Rust 实现，无需 root 权限，无需 libusb。  [](LICENSE) [](https://github.com/gnomeria/usbtree/actions/workflows/ci.yml) [](https://github.com/gnomeria/usbtree/releases/latest) **网站：** [gnomeria.github.io/usbtree](https://gnomeria.github.io/usbtree)  ## 安装 ### Shell 脚本 (Linux, macOS) ``` curl -fsSL https://raw.githubusercontent.com/gnomeria/usbtree/main/scripts/install.sh | sh ``` 下载适用于您平台的最新版本，通过 `checksums.txt` 验证其 sha256，并安装到 `/usr/local/bin`（如果可写）或 `~/.local/bin`。可通过环境变量进行自定义： | 变量 | 效果 | | --------------------- | ---------------------------------------------------------- | | `USBTREE_VERSION` | 安装特定版本，例如 `0.0.1`（默认：最新版本） | | `USBTREE_INSTALL_DIR` | 覆盖安装目录 | ### 预编译二进制文件 从[最新发布版](https://github.com/gnomeria/usbtree/releases/latest)获取归档文件： | 平台 | 文件名 | | ------------------- | ----------------------------------------- | | Linux x86_64 | `usbtree__linux-amd64.tar.gz` | | Linux arm64 | `usbtree__linux-arm64.tar.gz` | | macOS Apple Silicon | `usbtree__darwin-arm64.tar.gz` | | Windows x86_64 | `usbtree__windows-amd64.zip` | 每个归档文件的 sha256 都列在发布版的 `checksums.txt` 中。 ### 从源码构建 ``` cargo install --git https://github.com/gnomeria/usbtree # or clone + cargo build --release ``` ## 功能 - 实时 USB 树，带有颜色编码的类边栏、特定于类的图标和树枝线条；每秒重新扫描 - 通过回退链解析名称：个人覆盖设置 → 设备描述符字符串 → 下载的 [usb.ids](http://www.linux-usb.org/usb-ids.html) (`--updatelist`) → 内置的 usb.ids 快照 → 供应商和类启发式推断 - 使用 `Enter`/`Space`（或 `h`/`l`）折叠/展开 hub — 折叠的节点会显示 `▸` 和 `+N` 子节点徽章 - 复合/其他 (0xef) 设备会根据其接口类进行分类，因此例如 MOTU M2 音频接口会显示为 Audio，而不是 Misc - 热插拔监控：插入的设备会闪烁绿光，拔出的设备会作为带有红色删除线的幽灵状态保留 30 秒，并且每个事件都会记录在带有时间戳的日志面板中 - 每个设备的实时活动（Linux）：树中的内联迷你图表以及详细信息面板中的带宽图 — 无特权权限下显示 URBs/s，当 usbmon 可读时显示真实的 bytes/s（见下文） - 带有层级符号的速度徽章：`▂` low/full，`▄` high (480M)，`█` SuperSpeed+ (5G/10G) - 详细信息面板：sysfs 路径、vid:pid、供应商、类、速度、序列号、已连接的子设备 - `usbtree --dump` 将树结构打印到 stdout 一次（无 TUI） ## 用法 ``` usbtree # TUI usbtree --dump # print the tree once and exit usbtree --updatelist # download the latest usb.ids into the config dir usbtree --demo # fake device tree with scripted hot-plug + traffic ``` `--demo` 完全不需要 USB 访问权限 — 这是录制截图所使用的模式，也是预览 UI 的快捷方式（结合 `--dump` 可输出单次模拟树）。 | 按键 | 操作 | | --------------------- | ------------------- | | `j`/`k`, 方向键 | 移动选择 | | `Enter`/`Space` | 折叠/展开 hub | | `h`/`←`, `l`/`→` | 折叠 / 展开 | | `g`/`Home`, `G`/`End` | 顶部 / 底部 | | `r` | 强制重新扫描 | | `q` / `Esc` | 退出 | ## 配置 配置文件位于 `~/.config/usbtree/`（Windows 上为 `%APPDATA%\usbtree\`）： - **`overrides.ids`** — 个人命名启发式规则，每行一个 `vvvv:pppp Friendly Name`（允许使用 `#` 进行注释）。优先于描述符字符串和 usb.ids： 07fd:000b MOTU M2 Audio Interface - **`usb.ids`** — 由 `usbtree --updatelist` 写入（从 [systemd/hwdata](https://github.com/systemd/hwdata) 镜像获取）。存在时，优先于编译到二进制文件中的 usb.ids 快照。 ## 活动指标（Linux） 标题栏会显示当前处于活动状态的源： - **`◌ urb activity`** — 无特权的默认模式：来自 sysfs `urbnum` 的 URB 计数增量，显示为相对活动（URBs/s） - **`◉ usbmon bytes/s`** — 当 `/sys/kernel/debug/usb/usbmon` 可读时的真实单设备带宽，即以 root 身份运行并加载了 `usbmon` 模块且挂载了 debugfs 在 macOS 和 Windows 上，树结构、详细信息和热插拔日志均可正常工作；但不提供活动迷你图表功能。 ## 工作原理 该树每秒重新扫描一次；热插拔检测是通过两次扫描之间的快照差异实现的。设备路径在每个平台上都使用 sysfs 风格的命名（`1-1.4` = 总线 1，端口 1，端口 4），这是根据每个设备的端口链构建的。根 hub 是根据总线列表合成的。 版本发布通过 [release-please](https://github.com/googleapis/release-please) 自动化：`main` 分支上的约定式提交（conventional commits）会汇总成一个发布 PR，合并后会打上版本标签并构建上述二进制文件。 ## 开发 常用命令位于 [Taskfile](https://taskfile.dev) 中 — 运行 `task -l`（或直接运行 `task`）列出它们：`task demo` 在模拟数据上运行 TUI，`task test` / `task lint` / `task ci` 镜像 CI 检查的内容，`task shots` 重新渲染截图，`task hooks` 在每次克隆时启用 pre-commit 密钥扫描。 欢迎贡献代码；请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。安全报告请遵循 [SECURITY.md](SECURITY.md)。 ## 截图流水线 `docs/screenshots/` 中的演示 GIF 和 PNG 是在无头模式下渲染的 — 无需真实硬件 — 通过使用来自 `tapes/` 的 [VHS](https://github.com/charmbracelet/vhs) 录像带驱动 `usbtree --demo` 实现。[Screenshots workflow](.github/workflows/screenshots.yml) 会在 `main` 分支上的 `src/` 或录像带发生更改时重新渲染并提交它们；在本地，请运行 `scripts/shots.sh`（需要安装 `vhs`）。 ## 许可证 usbtree 采用 [MIT 许可证](LICENSE)。

标签：Rust, TUI, USB设备, 可视化界面, 系统信息, 网络流量审计, 通知系统