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,无主从 |
两个关键定位:
- 不是远程桌面。每台机器的画面仍然渲染在自己的显示器上,网络上跑的是几千字节级的输入事件。所以没有压缩伪影、没有分辨率妥协,延迟天花板远低于任何传像素的方案。
-
对等架构。没有"服务器端/客户端"之分,组内任何一台机器的键鼠都能控制其他机器(
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),用法相当考究:
-
只用单向流:
MAX_BIDI_STREAMS = 0,最多 256 个单向流。每个模块有流类别(StreamKind):Internal、Config、Input、Clipboard、Audio、DnD、Diagnostics……每个流用kind + ordinal标识,中继节点按类别转发而不解释内容。 -
两级优先级:Internal 和 Input 是
Interactive,其余是Normal。网络线程和中继都优先服务 Interactive 流——你复制一个大文件的同时,鼠标移动永远不会排队。 -
可靠流 + 不可靠数据报的组合:按键/按钮走可靠流(Interactive 优先级,绝不丢);纯指针移动走 QUIC 不可靠数据报(I1 流),且是能力协商的——双方握手出
oink.input.relative/1能力才启用。丢一帧移动无所谓,下一帧马上覆盖,换延迟。 -
批量旁路:文件和大剪贴板内容走单独的 TLS-over-TCP 连接池(ALPN
oink-low/1,端口 47472),按需拨号、连接复用、支持反向拨号和预热——大流量完全不与 QUIC 交互流抢带宽。 - 中继:直连不通(防火墙/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,写成了完整方法论):
- 定期用
CGEventSourceKeyState / ButtonState(HID 层真值,不是 Quartz 状态)与"我以为还按着的键"对账; - 连续两次确认(间隔下限)都已松开才补报抬键——单次确认会撞上"抬起事件还在队列里没送到回调"的瞬间;
- tap 被系统停用后重新启用时立即做一次全量核对;
- 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. 局限与风险
客观说几点:
- 项目年轻,单人维护,生产环境大规模验证有限;
- Windows 10 LTSC、Intel Mac 等平台未测试;
- 触控板手势在 Windows 端未充分测试;
- 协议私有且 v1——与 Synergy 系不互通,未来协议演进依赖作者;
- 深度系统集成(内核相邻的音频驱动、凭据提供程序、LL 钩子)意味着系统大版本更新可能破坏它——好在更新机制与崩溃报告是内建的。
8. 结语
Oink 证明了一件事:在"输入事件层"做文章,可以在不传一个像素的前提下,把两台电脑缝成一台。它的技术面貌是——
- 操作系统层:站在 CGEventTap / LL Hook / SendInput / Credential Provider 这些系统钩子上,把平台差异封装在两个 crate 里;
- 网络层:QUIC 的可靠流/不可靠数据报/优先级组合拳 + 无 CA 的 Ed25519 身份 + SPAKE2 配对,是一份可以抄作业的局域网 P2P 安全设计;
- 真正的难点不在"把事件发过去",而在让两套输入子系统对状态达成一致——防卡键的真值对账、钩子的看门狗、float32 的取整、钩子链的顺序博弈。这些细节才是"能用"与"好用"之间的距离。
如果你有多机并桌的开发场景,装一个,五分钟就能体会到"鼠标滑过边缘"的自由;如果你想学系统编程或实时分布式设计,把 tap.rs 和 hook.rs 的头注释打印出来读一遍,值回票价。
文中源码引用基于 2026-11 的 main 分支。