RiftBus

让同一所有者管理的一组机器，按需把某台机器上插入的 USB 设备共享给另一台机器使用，且不必逐对手工配对。

---

这是什么

RiftBus 面向「自己的一组机器」这个场景：插在某台机器上的 USB 设备，可以按需给同组的另一台机器直接使用。提供方把设备导出，接收方把它接入本机，用起来和本地插上硬件没有区别。共享以「个人设备组」为单位组织，成员能否加入由组管理者批准，传输只在用到的两台机器之间发生。

功能特性

• 按组共享，组间隔离：一台机器可以同时加入多个组；加入某个组不等于把本机设备交出去，设备目录也不会在组之间流动。
• 设备要主动纳入：系统扫描到的硬件只是候选，只有你手动添加后才会进入受管清单，扫描本身不会替你登记设备。
• 同一设备同时只服务一台机器：物理设备被占用时，其他机器的普通连接会被拒绝；要接手，得先看到当前会话、再确认抢占。
• 拉取为主，推送需授权：组内已批准的成员可以直接把设备拉过来用；反向推送需要接收方按组单独打开开关。
• 一个后端，多个入口：CLI、桌面窗口和浏览器界面连的是同一个 daemon，看到的状态一致；桌面窗口只负责窗口与 riftbus://local 协议桥，托盘和系统通知由独立的用户会话程序提供，关闭窗口不影响 daemon 或设备会话。
• 默认只开本地管理接口：管理入口默认是 Unix 域套接字；要开网页界面时，额外启用只绑回环地址（如 127.0.0.1）的 HTTP，并要求一份 0600 的用户名/密码文件。electron 模式通过 UDS 工作，不需要启用 HTTP；minimal 模式的浏览器入口依赖已启用的回环 HTTP。
• 对内核的要求很小：提供方走用户态 usbfs，不用加载 usbip_host；接收方接入远端设备时才需要 vhci_hcd。

平台与成熟度

• 平台：目前只支持 Linux x86_64（x86_64-linux），没有 Windows 或 macOS 版本，也不对这些平台作兼容承诺。
• 成熟度：项目处于 MVP。核心模型、daemon、CLI、共享界面、桌面集成和 NixOS 模块都已实现。
• 实体设备兼容性：目前只在有限的硬件上验证过，没有在大范围真实 USB 设备和浏览器上验证；部署到生产前请先用你自己的设备试通。
• 会话不保留：daemon 重启后不会恢复之前的设备会话，也不会重放中断的请求，需要重新连接。
• 离线与成员边界：普通成员退出要等管理者确认；管理者不在线时，已缓存的成员之间仍能连接设备，但新成员审批会暂停。尚未被批准的申请者看不到其他成员的资料和设备目录。

组件

启用 NixOS 模块（services.riftbus.enable = true）会默认安装完整的 RiftBus 软件包，包含以下组件（原分项 flake 包属性仍保留供开发与构建使用）：

组件	说明	命令 / 产物
daemon	作为系统服务后台常驻的管理服务，保存节点身份与状态，并在 Unix 域套接字上提供 JSON API 与 SSE；托管网页界面，也可选开本地回环 HTTP。业务与设备会话不依赖桌面进程。	riftbus-daemon
CLI	命令行客户端，覆盖设备、组、共享与连接等操作，本身不另存状态。	riftbus
共享 Web 界面	由 daemon 托管的操作界面，浏览器与 Electron 窗口用的是同一套前端。	share/riftbus/web
桌面集成	用户会话程序（riftbus-desktop-integration.service）：提供系统托盘与系统通知；electron 模式下从托盘打开或聚焦 Electron 窗口，minimal 模式下从托盘用默认浏览器打开已启用的回环 HTTP 页面。	riftbus-desktop-integration
Electron 桌面壳	纯窗口外壳：通过内部 riftbus://local scheme 访问 daemon 托管的界面；保持无边框外观与顶栏拖动区域，关闭窗口即退出 Electron 进程，不提供托盘或通知。	riftbus-desktop

快速开始（NixOS）

1. 在两台 NixOS 机器上安装并重启：在系统 flake.nix 中引入 git+https://git.gjz010.com/gjz010/riftbus 的 riftbus.nixosModules.default，启用 services.riftbus.enable = true 并将桌面登录用户加入 riftbus 组（如 users.users.alice.extraGroups = [ "riftbus" ];；完整可粘贴配置示例与模块选项见安装与部署（NixOS））。切换配置后重启一次系统：

   sudo nixos-rebuild switch --flake .#my-host
   

2. 设置本节点与建立网络组：重启后在两台机器上从托盘或应用菜单打开 RiftBus（或运行 riftbus-desktop），在首次弹出的「设置本节点」中填写节点名称并点「保存并继续」；机器 A 在「网络组」→「创建网络组」，进组详情「邀请」→「导出邀请」→「复制邀请」；机器 B 在「网络组」→「加入网络组」粘贴票据并点「发送加入请求」；机器 A 在「待批准成员」中点「批准」。
3. 添加设备并共享到组：机器 A 插入待共享的 USB 设备（先关闭机器 A 上占用该设备的应用，存储设备先卸载），在「设备」→「添加设备」→「添加所选设备」纳入本机管理，再到目标组详情「已共享到该组的设备」区域，从「选择设备」下拉框选中它并点旁边的「+」图标按钮。
4. 拉取设备、验证与断开：机器 B 在同组详情「远程设备（其他成员）」中点「拉取设备」，在「设备」页「会话」区域看到连接建立后，打开对应实际应用验证设备识别与操作；用完后（存储设备先在机器 B 保存并卸载）在「会话」区域点「断开」即可让设备回到机器 A 使用。完整步骤见快速开始。

services.riftbus.desktopIntegration.mode 默认 electron，登录图形会话后自动运行原生托盘与系统通知，并可从托盘或菜单打开桌面窗口；也可按需设为 minimal（保留托盘与系统通知，用默认浏览器打开已启用的回环 HTTP 页面，不引入 Electron）或 off（关闭托盘通知与桌面集成，仅保留后台服务、CLI 与可选网页入口）。三种模式的说明见图形界面操作。

文档

面向用户的手册源码在 docs/site/：

• 快速开始
• 安装与部署（NixOS）
• 图形界面操作
• 命令行操作
• CLI 参考
• 本地管理 API 概览
• 备份与恢复
• 故障排查与安全

本地预览或构建文档站时，先进入 Nix 开发环境（nix develop，或让 direnv 自动进入），再在仓库根目录用根 justfile 的快捷入口：

just docs-install    # 首次或依赖更新时，按 docs/package-lock.json 安装依赖
just docs            # 前台启动开发服务器 http://127.0.0.1:5173
just docs-build      # 生成静态站点到 docs/.vitepress/dist/
just docs-preview    # 先构建，再前台预览 http://127.0.0.1:4173

just --list 可查看全部入口（含 build：构建 daemon、CLI、Web 与桌面 Nix 包）。这两个服务器只绑回环地址、留在前台，不会自动打开浏览器或启动 daemon；docs-install 需要在首次使用前手动跑一次。

参与开发

源码、构建方式和贡献入口都在项目仓库：https://git.gjz010.com/gjz010/riftbus。

许可与第三方声明

本项目以 GNU GPL-3.0-or-later（GPLv3 或更高版本）发布，完整文本见 LICENSE。第三方依赖的许可与归属见 docs/THIRD_PARTY_NOTICES.md。