把两台电脑缝成一台:软件 KVM Oink 的技术深潜

Oink — "Oink Is Not only a KVM"。一个用 Rust 从零写成的跨 Mac/Windows 软件 KVM:
一套键鼠控制多机、剪贴板互通、跨系统拖拽、音频聚合、甚至 Windows 自动解锁。
本文基于其开源代码(GPL-3.0)逐层拆解它的架构与技术决策,适合对系统编程、
分布式实时系统、跨平台开发感兴趣的开发者阅读。


0. 引言:双机开发者的日常

如果你同时拥有一台 Mac 和一台 Windows——比如 Mac 写代码、Windows 跑测试和游戏,或者公司发一台、自己攒一台——你大概率经历过这些瞬间:

  • 右手在两套键鼠之间来回横跳,桌面被线缆占领;
  • 想把 Mac 终端里的一条命令贴到 Windows 上,于是打开微信"文件传输助手"给自己发消息;
  • 一个截图要从 Mac 挪到 Windows,先 AirDrop 到手机再传电脑;
  • 两台机器各自接着音箱,声音此起彼伏。

传统解法要么是硬件 KVM 切换器(几百块、按一下切换、不共享剪贴板),要么是远程桌面(传像素,延迟和画质总得牺牲一个),要么是 Synergy/Barrier 这类老牌软件 KVM(协议老、维护乏力、手感糟)。

Oink 给出的答案是:在操作系统的输入事件层做"截获—路由—注入",网络上只传事件,不传像素。鼠标划过屏幕边缘,控制权就切到另一台机器,延迟毫秒级,体验接近单机多显示器。

下文先讲它是什么、给谁用,然后进入正题:源码级的技术原理,以及这个项目里最值钱的那些"难点与解法"。


1. Oink 是什么:与三类既有方案的对比

维度 硬件 KVM 远程桌面 (RDP/VNC) Synergy/Barrier 系 Oink
传输内容 视频/USB 信号 压缩像素流 输入事件(老协议) 输入事件 + 结构化数据
延迟 取决于硬件 数十~百毫秒 中 毫秒级
剪贴板 通常无 有 有 有,自动同步
跨系统拖拽文件 无 受限 弱 原生体验
音频聚合 无 单向 无 有
每台机器需要显示器 需要 不需要 需要 需要
架构 电路切换 C/S C/S(有主从) P2P,无主从

两个关键定位:

  1. 不是远程桌面。每台机器的画面仍然渲染在自己的显示器上,网络上跑的是几千字节级的输入事件。所以没有压缩伪影、没有分辨率妥协,延迟天花板远低于任何传像素的方案。
  2. 对等架构。没有"服务器端/客户端"之分,组内任何一台机器的键鼠都能控制其他机器(oink-network 的全部状态机都按对称设计)。

系统要求:macOS 14.2+(Apple Silicon 最佳,Intel 未充分测试);Windows 10 1809+/Windows 11 x64;同一局域网(包括两台机器网线直连的 169.254 链路本地地址——源码里专门处理了)。GPL-3.0 + 附加条款,个人与商用免费。


2. 应用场景与适用人群

2.1 典型场景

  • Mac + Windows 双机开发(最核心场景):Mac 上写 iOS/前端,Windows 上跑 .NET/测试/游戏;剪贴板互通一条命令、一段 stack trace,比任何"传输助手"都快。
  • 跨平台构建与测试:一套键鼠在两套工具链之间无缝移动,日志在 A 机、复现在 B 机,复制粘贴零摩擦。
  • 多机运维/值班:几台机器排成虚拟桌面,鼠标滑过去就控制,还能聚合音频通知——哪台机器"叮"了一声一目了然。
  • 笔记本 + 台式机并桌:外出带回的笔记本往桌上一放,即刻融入家里的输入环境。
  • 锁屏解锁:走近 Windows,鼠标滑过去自动解锁登录(下文详述)。

2.2 不适合的场景

  • 需要远程看到对方画面的(人在异地)——它不传像素,请用远程桌面;
  • 机器不在同一局域网——设计上就是局域网 P2P;
  • 期望拿它做自动化测试注入的工具——它不是为脚本化注入设计的。

2.3 适合什么样的开发者(作为读者)

即使你不用双机,这个仓库也值得读:它是一个横跨 macOS/Windows 系统编程、P2P 网络、实时传输、安全协议的完整样本,且注释密度罕见地高——很多模块的头注释本身就是设计文档,把踩过的坑、实测日期、系统未文档化行为全部记录在案。


3. 总体架构:一个 Rust Workspace

apps/
  oink/            Tauri 应用(Rust 后端 + WebView 前端;Windows 依赖 WebView2)
  audio-plugin/    macOS Core Audio HAL 驱动(C++,libASPL,虚拟麦克风)
  finder-sync/     macOS Finder Sync 扩展(Swift,拦截 Finder 拖出)
  file-provider/   macOS File Provider 扩展(Swift,接收落地文件)
crates/
  oink-agent       服务进程:组装所有模块,对 UI 提供 API
  oink-foundation  公共类型(坐标、输入事件、剪贴板)+ 配置 + 日志
  oink-network     组网:身份、发现、配对、连接、中继、QoS
  oink-protocol    线上协议:v1 类型注册表、CBOR 帧、准入
  oink-input       截获与注入(macOS / Windows 双实现)
  oink-routing     输入路由状态机(纯逻辑,与系统和网络无关)
  oink-display     屏幕枚举、布局模型、传送门、死区
  oink-clipboard   剪贴板读写(分平台)+ 同步逻辑(通用)
  oink-audio       音频采集、低延迟传输、多路播放(Opus + cpal)
  oink-credential-provider  Windows 自动解锁(C++ Credential Provider V2)
  oink-winsvc / oink-autostart / oink-update / oink-telemetry / oink-crash / oink-locator

几个值得注意的分层决策:

  • oink-routing 是纯状态机,不碰系统 API 也不碰网络——焦点、移交、防卡键、手感换算全部在这里单测覆盖,平台差异被挡在 oink-input 里,网络差异被挡在 oink-network 里。这是典型的 hexagonal/architecture 分层。
  • UI 与核心分离:Tauri 界面只是一个客户端,通过 agent 暴露的 API 控制核心——所以 Windows 的 UI 跑在独立进程,不会干扰底层钩子线程的 Raw Input 注册(后文会看到为什么这至关重要)。
  • 平台原生扩展用原生语言写:音频驱动是 C++,Finder 扩展是 Swift,凭据提供程序是 C++——没有用 Rust 强行 FFI 硬吃。

4. 技术原理

4.1 操作系统提供的两个钩子:截获与注入

整个软件 KVM 建立在两个 OS 能力之上:输入事件的拦截点和输入事件的注入点。

macOS:Quartz Event Services

  • 截获:CGEventTapCreate 创建 active 模式的会话级事件 tap(kCGSessionEventTap),跑在专用线程的 RunLoop 上。回调里能拿到所有键鼠/触控板事件,并决定"吞掉"还是"放行"——oink-input/src/macos/tap.rs(4200 行)。
  • 注入:CGEventPost 配合自建 CGEventSource(HIDSystemState),把合成事件灌回系统——inject.rs(2000 行)。
  • 权限前提:辅助功能授权(AXIsProcessTrusted)。

Windows:低级钩子 + Raw Input + SendInput

  • 截获:WH_MOUSE_LL + WH_KEYBOARD_LL,挂在专用线程的消息循环上;Raw Input(RIDEV_INPUTSINK)作旁路证据源——oink-input/src/windows/hook.rs(4500 行)+ rawinput.rs。
  • 注入:SendInput,按键走扫描码(KEYEVENTF_SCANCODE,E0 扩展键加 KEYEVENTF_EXTENDEDKEY),鼠标移动用归一化到虚拟桌面的绝对坐标(MOUSEEVENTF_MOVE | ABSOLUTE | VIRTUALDESK)——inject.rs。

这两个平台的能力语义差异巨大,正是项目工程量大头。后文"难点"一节展开。

4.2 发现与身份:不依赖任何 CA 的信任模型

发现层(oink-network/src/discovery/)很薄,两条腿:

  • 自有 UDP 广播信标:默认端口 47471,Beacon/Query/Reply 三种包,同样用 v1 CBOR 编码;
  • mDNS/DNS-SD(服务类型 _oink._udp),macOS 走系统 dnssd。

源码注释明确:"发现结果只是不可信的提示"——真实身份认证发生在 TLS 握手,发现层只负责"告诉你哪里可能有台机器"。

身份层是这个项目最优雅的设计之一(tls.rs 头注释原话):

双方都用设备 Ed25519 密钥签发的自签名证书完成 TLS 1.3 握手。验证不依赖任何 CA:
从证书中取出 Ed25519 公钥作为对方的设备 ID,并用这个公钥验证握手签名(CertificateVerify),
握手结束即确知对方身份。

即:证书即身份,公钥即设备 ID。没有 CA、没有域名、没有账户体系,但拿到了双向认证的等价强度。首次配对用 SPAKE2(口令认证密钥交换)从用户输入的配对码派生组密钥,之后设备凭持久 Ed25519 身份自动重连。

4.3 传输层:一份教科书级的 QUIC 用法

主通道是 QUIC(quinn 0.11 + rustls,ALPN oink-wire/1,默认端口 47470),用法相当考究:

  1. 只用单向流:MAX_BIDI_STREAMS = 0,最多 256 个单向流。每个模块有流类别(StreamKind):Internal、Config、Input、Clipboard、Audio、DnD、Diagnostics……每个流用 kind + ordinal 标识,中继节点按类别转发而不解释内容。
  2. 两级优先级:Internal 和 Input 是 Interactive,其余是 Normal。网络线程和中继都优先服务 Interactive 流——你复制一个大文件的同时,鼠标移动永远不会排队。
  3. 可靠流 + 不可靠数据报的组合:按键/按钮走可靠流(Interactive 优先级,绝不丢);纯指针移动走 QUIC 不可靠数据报(I1 流),且是能力协商的——双方握手出 oink.input.relative/1 能力才启用。丢一帧移动无所谓,下一帧马上覆盖,换延迟。
  4. 批量旁路:文件和大剪贴板内容走单独的 TLS-over-TCP 连接池(ALPN oink-low/1,端口 47472),按需拨号、连接复用、支持反向拨号和预热——大流量完全不与 QUIC 交互流抢带宽。
  5. 中继:直连不通(防火墙/NAT)时可以经组内其他设备中继,中继同样优先 Interactive。

4.4 线上格式:6 字节帧头 + Canonical CBOR + 准入控制

oink-protocol 定义了一个高度防御性的二进制格式(v1/frame.rs):

[ u16 LE: type_id ][ u32 LE: payload_length ][ CBOR map: payload ]
  • Canonical CBOR(minicbor,零分配解码):比 JSON 小得多、解析快,适合"一次鼠标移动就是一帧"的高频小消息;
  • 类型注册表:所有消息类型在 v1 注册表中登记,未知 opcode 不解析 payload 直接拒绝——包括所有"实验性"编号;
  • 分级尺寸上限:数据报帧必须塞进 1200 字节最小路径 MTU;可靠帧、配置帧各有上限,超限在发送端就是错误,绝不截断;
  • 解码零分配:注释原话"Decode errors must stay allocation-free, including malformed RT media"——畸形实时媒体不能引发内存分配,这是把 DoS 面直接焊死的写法。

4.5 输入路由:一台"虚拟 KVM 交换机"的状态机

oink-routing + oink-display 实现了核心体验:把 N 台机器的屏幕排成一个虚拟布局,屏幕边缘是"传送门"(portal),角落是"死区"(保证热角不被误触)。

状态机管理每台机器的 Local/Remote 模式:

  • 鼠标撞上指向邻机的传送门 → 本机进入 Remote:光标"停泊"在边缘并隐藏(Windows 用遮罩窗口,macOS 隐藏光标),本地不再消费输入,事件流改发对端;
  • 反向滑回 → 交还控制权,强制释放所有按下的键(两端按键状态对账);
  • 换算:跨机器的坐标映射、DPI/缩放比换算、阻尼与抖动滤波(damping.rs、jitter.rs)。

4.6 事件模型:为什么对面机器的手势是"原生"的

协议里传输的不是录制的输入序列,而是归一化的结构化事件(v1/dto/input_values.rs):

  • 按键:KeyCode(扫描码语义)
  • 指针:移动增量 / 绝对位置、按钮、滚轮(带 phase 与单位)
  • 触控板:原始多点触控接触点流——ContactPoint{id, x, y} + ContactPhase(协议校验:≤5 个活跃触点、坐标必须在传感器表面范围内)
  • 手势:语义事件(Magnify/Rotate/DockSwipe,带 phase/amount/velocity)

这是"手感原生"的根本原因:源机器把触控板的原始触点传过去,目标机器的操作系统用自己的原生手势识别器处理这些触点。双指缩放在对面是系统实时计算的,不是模拟滚轮插值;4pt 内连续点击的点击计数、双击间隔,也都按目标系统自己的规则在注入端合成。

4.7 三条数据通道

剪贴板:oink-clipboard 各平台监听系统剪贴板,变化后经加密通道同步到组内设备,跨系统格式自动转换;大内容走 TCP 批量旁路。

拖拽:macOS 侧装了 Finder Sync 扩展(捕获从 Finder 拖出的内容)和 File Provider 扩展(接收落地的文件),所以能把文件直接拖进对面的 Chrome/终端;协议里有专门的 DnD 流类别(拖拽预览 + 拖拽内容分优先级传输)。

音频:macOS 不允许普通应用采集系统输出,所以 Oink 自带一个基于 libASPL 的 Core Audio HAL 驱动(OinkMicrophone.driver):远端设备的音频传过来后以虚拟麦克风设备呈现,本地音频经隐藏的 feed 输出设备采集。编码用 Opus,播放用 cpal,多路混音;实时音频包走 QUIC 不可靠数据报(M1 流),接收端是无锁分道的固定拷贝环形队列(realtime_datagram.rs),音频回调永不等待网络线程。

4.8 Windows 自动解锁: Credential Provider 深水区

同类软件几乎没人碰的领域:Windows 锁屏界面运行在安全桌面,普通进程的 SendInput 根本到不了那里。Oink 写了一个原生 Credential Provider V2 DLL(oink-credential-provider):

  • 由 SYSTEM 服务注册 CLSID,不注册 filter、不包装系统提供程序、不禁用任何登录方式(注释里逐条声明,防止"这软件会不会改我登录方式"的担忧);
  • 登记的密码用 SYSTEM 作用域 DPAPI 加密,SYSTEM 独占文件,存放在专用的 ProgramData 目录;
  • 命名管道拒绝远程客户端和竞争实例,发送密码前把管道绑定到正在运行的输入服务进程;
  • 支持 CPUS_LOGON 和 CPUS_UNLOCK_WORKSTATION 两种场景。

于是体验变成:鼠标滑向锁屏的 Windows → 自动解锁进入桌面,仿佛那台机器认得你。


5. 难点与解决方案:这个仓库真正值钱的部分

以下每一条都来自源码注释与实现,多数是系统未文档化行为,是作者用实测换来的。

5.1 自反馈循环:自己注入的事件回到自己的钩子

问题:注入的事件同样会经过本机的截获钩子——Mac 上 CGEventPost 出去的事件会被自己的 event tap 收到,Windows 上 SendInput 也会过自己的 LL 钩子。不处理就是无限循环。

解法:macOS 注入时在事件源的 userData 里埋一个 MAGIC 值,tap 回调据此识别"这是我自己注入的"直接放行(inject.rs → tap.rs);Windows 则要求标记事件必须由另一个线程注入——本线程注入的事件不经过本线程的钩子(hook.rs 模式切换章节)。

5.2 防卡键:一个分布式状态一致性问题

问题:源机以为你还按着 Ctrl(没收到抬键事件),目标机就会一直按着、无限重复字符。而漏掉抬键的原因五花八门:macOS 上其他程序的 active HID tap(注释点名"两台 Mac 上都装着飞书")处理超时会吞掉事件;tap 被系统停用期间的事件根本不会交给你。

解法(macOS tap.rs,写成了完整方法论):

  1. 定期用 CGEventSourceKeyState / ButtonState(HID 层真值,不是 Quartz 状态)与"我以为还按着的键"对账;
  2. 连续两次确认(间隔下限)都已松开才补报抬键——单次确认会撞上"抬起事件还在队列里没送到回调"的瞬间;
  3. tap 被系统停用后重新启用时立即做一次全量核对;
  4. Caps Lock 特殊处理:物理状态取自 NX_SYSDEFINED / NX_KEYTYPE_CAPS_LOCK 的 data1,不从 FlagsChanged 推断(Quartz 的 Caps 状态是"锁定状态",不是物理按压快照);Remote 结束后还要由 LocalGuard 恢复本机被 HID 层改掉的锁定状态与输入法。

Windows 侧对应的是 modifier_reconcile / key_releases 模块。这类"最终一致"设计在分布式系统里叫 read repair + 真值源仲裁,出现在输入系统里毫不违和。

5.3 Windows 低级钩子的脆弱性

问题:LL 钩子回调必须在本线程取消息时同步执行,超过 LowLevelHooksTimeout(默认约 300ms)系统就跳过该事件,多次超时后静默卸载钩子——没有任何通知。

解法(hook.rs 头注释,堪称 Windows 输入系统避坑指南):

  • 截获线程 HIGHEST 优先级,回调契约 < 0.5ms:只读结构体、查表、调用处理函数;所有耗时操作(遮罩窗口、跨线程调用)全部异步化;
  • 回调里绝不等待其他线程应答——等待期间新到的钩子消息会重入回调,重入的回调拿不到线程状态、事件被原样放行,造成"光标跳回屏幕中央"的灵异现象(注释记录了 2026-09-29 Windows 11 的实测复现与根因分析);
  • 鼠标看门狗:每秒核对"Raw Input 有鼠标在动而鼠标钩子超过 1 秒没被调"→ 重装钩子;
  • 钩子链博弈:低级钩子后装的先收到事件,所以每次进入 Remote 都"先装新钩子、再卸旧钩子",抢到比后启动的手势/热键软件(注释点名 Quicker)更靠前的位置;
  • 键盘没有看门狗——因为后台注册键盘 Raw Input 会触发 Windows 未公开的 LL 链绕过行为,宁可接受"键盘钩子被摘除后靠重挂兜底"。

5.4 手感工程:DPI、float32 与 1pt 以下的位移

问题:两台机器的分辨率、缩放比、指针加速度曲线都不同,"同样的手部动作"要在对面还原出"同样的手感"。

解法(散布在 inject.rs、damping.rs、dpi.rs,每条都是实测坑):

  • 移动一律发绝对位置 + DeltaX/Y 增量;DeltaX/Y 是整数字段,不足 1pt 的部分累积到下一帧——慢速移动不丢步;指针顶在屏幕边时仍注入朝外的增量,应用能看到"还在往边上顶"(Dock/自动隐藏栏才会弹出);
  • WindowServer 内部用 float32 存光标位置:路由把贴边指针放在 bottom − 1e-6,直接 CGEventPost 会被舍入到屏幕外(右/下边界不属于屏幕),光标画在屏外导致 Dock 闪烁——注入前显式向下取整到 float32;
  • Windows 侧注入的绝对坐标归一化到整个虚拟桌面(多显示器拼接坐标系);
  • 点击计数自己按系统双击间隔和 4pt 距离计算(kCGMouseEventClickState),保证跨机双击语义正确。

5.5 延迟:按消息语义分级传输

问题:键鼠事件是毫秒级敏感的,而剪贴板里可能躺着 50MB 的截图。

解法:整条链路按语义分流——

数据 通道 特性
指针移动 QUIC 不可靠数据报(能力协商) 可丢、最低延迟
按键/按钮 QUIC 可靠流,Interactive 优先级 不丢、优先调度
音频 QUIC 不可靠数据报 + Opus 实时流,无锁接收队列
文件/大剪贴板 TLS-over-TCP 池(独立端口) 与交互流完全隔离
心跳/中继控制 QUIC Internal 流 Interactive

外加发送端 pacing(LowPacingStatus:到下一跳共享预算、按 RTT 与活动流数自适应),保证大传输不挤死小消息。

5.6 安全:每一层都假设对面是恶意的

  • 身份:Ed25519 证书即身份(4.2 节),握手即认证;
  • 配对:SPAKE2,配对码不在网络上明文出现,派生组密钥后密码即销毁(zeroize);
  • 帧:未知 opcode 拒收、尺寸上限、解码零分配、CBOR 严格校验(触点坐标必须在传感器范围内、手势进度有界——协议层就拒绝物理上不可能的值);
  • 自动解锁:密码 DPAPI 加密、SYSTEM 独占、命令行不接收任何密码/路径/账号(防注入与提权);
  • 遥测默认关闭且"closed"(只发数值型崩溃/性能数据)。

5.7 跨系统语义鸿沟

每一对"同一个概念"在两个系统里都不一样,源码逐个抹平:Caps Lock(锁定状态 vs 物理按压)、输入法状态(Remote 期间保存/恢复)、媒体键(macOS 走 NX_SYSDEFINED 合成,系统像实体键一样弹音量 HUD)、触控板(Windows 用 HID 数字化仪报告区分"精确式触摸板"与鼠标,100ms 时间窗关联,甚至处理了"同一进程内其他代码会覆盖 Raw Input 注册"的坑)。


6. 工程文化观察

  • 注释即设计文档:tap.rs / hook.rs / tls.rs 的头注释把系统未文档化行为、实测日期、bug 编号、根因分析全部写进去。读这些注释的价值不亚于读代码。
  • 防御性到偏执:解码零分配、帧上限在发送端强制、命名管道拒绝远程客户端、"未知 opcode 连 payload 都不 parse"。
  • 单人 + AI 辅助开发的样本:作者声明不接受无上下文的 PR("因为没有人力做 code review"),要求 Issue 附带设备环境与 AI 辅助调查的结论。这个模式能维持如此质量的注释与测试,本身值得关注。
  • 测试齐全:tests/ 有专门的 test-support crate,网络层有 testing.rs 构造的假链路,routing 纯状态机全覆盖单测。

7. 局限与风险

客观说几点:

  1. 项目年轻,单人维护,生产环境大规模验证有限;
  2. Windows 10 LTSC、Intel Mac 等平台未测试;
  3. 触控板手势在 Windows 端未充分测试;
  4. 协议私有且 v1——与 Synergy 系不互通,未来协议演进依赖作者;
  5. 深度系统集成(内核相邻的音频驱动、凭据提供程序、LL 钩子)意味着系统大版本更新可能破坏它——好在更新机制与崩溃报告是内建的。

8. 结语

Oink 证明了一件事:在"输入事件层"做文章,可以在不传一个像素的前提下,把两台电脑缝成一台。它的技术面貌是——

  • 操作系统层:站在 CGEventTap / LL Hook / SendInput / Credential Provider 这些系统钩子上,把平台差异封装在两个 crate 里;
  • 网络层:QUIC 的可靠流/不可靠数据报/优先级组合拳 + 无 CA 的 Ed25519 身份 + SPAKE2 配对,是一份可以抄作业的局域网 P2P 安全设计;
  • 真正的难点不在"把事件发过去",而在让两套输入子系统对状态达成一致——防卡键的真值对账、钩子的看门狗、float32 的取整、钩子链的顺序博弈。这些细节才是"能用"与"好用"之间的距离。

如果你有多机并桌的开发场景,装一个,五分钟就能体会到"鼠标滑过边缘"的自由;如果你想学系统编程或实时分布式设计,把 tap.rs 和 hook.rs 的头注释打印出来读一遍,值回票价。

文中源码引用基于 2026-11 的 main 分支。

©著作权归作者所有,转载或内容合作请联系作者
【社区内容提示】社区部分内容疑似由AI辅助生成,浏览时请结合常识与多方信息审慎甄别。
平台声明:文章内容(如有图片或视频亦包括在内)由作者上传并发布,文章内容仅代表作者本人观点,简书系信息发布平台,仅提供信息存储服务。

友情链接更多精彩内容