sqlpxc/airhand

项目介绍

Airhand 是一个远程桌面系统：同一个程序既可以充当被控端（host），也可以充当控制端。它面向希望绕过第三方云服务、自行部署低延迟远控的用户——用 Docker Compose 起一个小型中继服务器，客户端通过 QUIC/TLS 连接。

被控端只在屏幕变化时出帧，优先使用硬件 AV1/HEVC/H.264 编码，没有硬件编码器时回退到 OpenH264。控制端用 WebCodecs 在 GPU 上解码并画入 canvas；远端光标的形状被镜像到本地，移动不经过网络，因此不拖影。被控端系统声音以 Opus 推送到控制端，另有文本剪贴板同步、快捷键注入、多显示器与多屏总览。桌面客户端和网页控制台共用一套 React 界面，差异集中在后端适配层（架构说明）。

快速开始

1. 在两端都能访问的机器上部署中继服务器，并记下证书指纹：

   docker compose up -d
   docker compose logs airhand | grep fingerprint
   

   服务器监听 UDP 4433（快速开始）。

2. 在构建桌面客户端时把中继地址和指纹编译进去。Windows 上：

   cd client
   npm install
   $env:AIRHAND_SERVER    = "relay.example.com:4433"
   $env:AIRHAND_SERVER_FP = "<第 1 步得到的指纹>"
   npm run tauri build -- --no-bundle
   

   产物为 client/src-tauri/target/release/airhand.exe。需要 Rust、Node.js 20+ 和 CMake；macOS 和 Linux 还需各自的 Tauri 依赖，Linux X11 另需 PulseAudio 与 GStreamer 开发文件（构建要求）。

3. 在远端电脑上运行 Airhand，它默认只出现托盘图标，右键菜单可看到 6 位控制码。在你自己的电脑上运行同一程序，托盘选择 切换到控制端，输入控制码即可连接。

不想在控制端安装客户端时，可以用 web/ 下的网页控制台：AIRHAND_SERVER=relay.example.com:4433 AIRHAND_SERVER_FP=<指纹> docker compose up -d，然后浏览器打开 8080 端口（网页控制台）。

使用约束

• 被控端支持 Windows 和 X11 Linux 桌面；Wayland 下只能看到和控制 X11（XWayland）应用。Linux 被控端目前只有 OpenH264 软件编码，尚无 VA-API/NVENC。
• macOS 被控端需要在系统设置中授予“屏幕与系统音频录制”和“辅助功能”权限，登录窗口和锁屏无法捕获。Windows 在无提权时同样无法捕获或控制 UAC 提示与锁屏，Ctrl+Alt+Del 无法注入（已知限制）。
• 客户端和服务器必须使用同一版本构建，协议不匹配时会被检测并提示（协议版本）。
• 中继地址和证书指纹编译进客户端，更换中继需要重新构建；指纹留空会关闭证书校验，只应用于开发（构建客户端）。
• 中继服务器是 TLS 终点，能看到会话内容，应部署在可信机器上；剪贴板只同步文本，不转发麦克风音频。
• 桌面客户端不写配置文件，设置只存于内存，控制台 WebView 的临时数据在退出时清理（零文件）。项目使用 MIT 许可证。

HotRepo 点评

Airhand 进入 HotRepo 2026-11-02 的 Rust 新项目榜，统计窗口从 2026-11-01 开始，记录到 102 个新增 Star 和 37 个新增 Fork；全语言日榜名次没有记录。采样到的 Star 曲线在前 12 个小时保持 102，最后一次观测升到 204，看到的是一次跳变而非全天持续增长。值得关注的是它公开的设计细节：逐帧确认加在途帧上限、拥塞时跳到最新帧、控制消息与音视频分队列（视频链路）。README 也区分了实测值和估算值，例如硬件 AV1 单帧约 7 ms、默认音频滞后约 70 ms。项目仍在活跃开发、协议会变，作为生产工具采用时需要留意这一前提。