
MuClip:基于 Rust 的局域网剪贴板同步与加密文件传输引擎
MuClip:基于 Rust 的局域网剪贴板同步与加密文件传输引擎
在多设备工作场景中,电脑与手机之间传输文本、复制代码片段或发送文件,往往需要依赖云服务、第三方应用,或者繁琐的共享目录配置。
MuClip 是一个基于 Rust 开发的局域网剪贴板同步与加密文件传输引擎。它采用无中心服务器的 P2P 架构,通过自动设备发现、配对认证、加密通信与原生接口,为 Windows、Android 及其他支持原生调用的应用提供跨设备数据同步能力。
与传统剪贴板软件不同,MuClip 更注重底层基础设施的设计:它不是一个完整的桌面应用,而是一套可以直接集成到其他软件中的原生核心库。
一、项目简介
MuClip Core 使用 Rust 2024 Edition 开发,采用 rlib 与 cdylib 双重构建形式,支持多种语言和平台接入。
- 项目地址: GitHub - MuClip
- 开发语言: Rust
- 支持平台: Windows、Android
- 许可证: MIT
- 主要接口: C ABI、JNI、UniFFI
目前 MuClip 已应用于小沐 OCR 的跨设备剪贴板同步与局域网文件互传功能,并提供独立的 Android 客户端接入方案。
二、核心功能
1. 零配置局域网设备发现
MuClip 通过 UDP 组播、子网广播、单播回应以及 TCP 心跳机制实现设备发现与在线状态维护。
同一局域网中的设备可以自动发现彼此,无需手动输入 IP 地址、配置中心服务器或建立共享目录。
设备发现主要使用 UDP 42110 端口,数据同步使用 TCP 42424 端口。
2. 剪贴板跨设备同步
MuClip 支持将文本剪贴板内容同步到已配对设备。
同步内容包含文本数据、内容类型以及 SHA-256 指纹,并通过多端并发推送机制传递数据。
值得注意的是,底层引擎不会直接修改接收设备的系统剪贴板,而是通过回调将内容交给宿主应用,由应用自行决定如何处理。
这种设计使 MuClip 可以灵活集成到不同的剪贴板管理软件中。
3. 加密局域网文件传输
MuClip 内置独立的文件传输模块,支持设备之间直接发送文件,无需经过云端中转。
文件传输采用固定 128 KiB 分块机制,每个数据块独立进行 AEAD 加密与认证。
接收端会对传输数据进行完整性校验,包括:
- 数据块数量与总字节数校验
- 全文件 SHA-256 校验
- 分块认证失败检测
- 临时文件写入与原子重命名
- 双向传输取消与实时进度反馈
只有在文件完整校验通过后,接收端才会将临时文件正式落盘,避免不完整文件被误认为正常结果。
4. 高吞吐原生文件传输
MuClip 针对大文件传输进行了专门的内存与 I/O 优化。
其主要设计包括:
- 128 KiB 固定分块传输
- 内存池租借与原位加解密
- 接收端 1 MiB 缓冲写入
- 独立文件传输 TCP 连接
- 减少跨语言内存复制
- 分块密钥派生与独立认证
项目提供了可复现的文件传输基准测试。
根据 README 公布的测试结果,在千兆网络环境下,端到端文件传输实测约为 100~110 MiB/s,接近千兆链路的理论吞吐上限。
实际速度仍取决于网络环境、磁盘性能与设备硬件。
三、安全机制设计
MuClip 的一个重要特点是,它并不单纯依赖普通 TCP 连接,而是围绕设备配对、身份认证和会话密钥建立了一套加密通信机制。
1. 六位 PIN 配对
设备配对使用 SPAKE2 密码认证密钥交换机制。
用户通过六位 PIN 完成配对,PIN 本身不会以明文形式传输到网络中。
配对完成后,双方生成独立的长期配对密钥,用于后续通信身份认证。
2. XChaCha20-Poly1305 加密通信
MuClip 使用 XChaCha20-Poly1305 进行数据加密与认证。
每次 TCP 连接建立时,双方通过临时 X25519 密钥协商生成独立会话密钥,并使用长期配对密钥完成双向身份认证。
这种设计使长期配对密钥主要承担身份认证职责,而不是直接用于所有业务数据加密。
3. 前向保密机制
MuClip 为剪贴板同步与文件传输引入了连接级临时密钥协商。
即使未来长期配对密钥发生泄露,攻击者也不能仅凭长期密钥直接还原此前捕获的会话通信内容。
临时私钥使用完毕后会通过 Zeroizing 机制清理,降低敏感密钥残留风险。
4. 不做中继与消息扩散
MuClip 采用直接设备通信模式:
- 不依赖中心服务器
- 不提供云端中继
- 不自动转发其他设备的消息
- 不根据广播信息自动完成配对
每台设备只处理自身接收的数据,不会将某一设备的消息扩散给其他已配对设备。
需要注意的是,设备发现广播仍会暴露设备名称、端口等元信息,局域网环境也并非天然可信。MuClip 更适合家庭或办公局域网使用,而不是直接假设公共 Wi-Fi 环境安全。
四、本地数据存储与加密备份
除了实时同步,MuClip 还包含一套本地剪贴板历史管理模块。
其功能包括:
- SQLite 本地存储
- 历史记录自动去重
- 全文搜索与分页查询
- 过期记录清理
- LRU 内存热缓存
- 常用语与时间规则管理
- 单文件加密备份与恢复
其中,.mubc 是 MuClip 自定义的加密备份格式。
备份文件会对历史记录、常用语、规则模板与配置项进行归档,支持增量合并或完全覆盖恢复。
加密备份采用 PBKDF2-HMAC-SHA256 派生密钥,并使用 XChaCha20-Poly1305 加密,支持先压缩再加密的数据处理流程。
此外,MuClip 还支持可选的 SQLCipher 4 数据库加密。
需要特别说明:SQLite 数据库加密默认并未启用。 如果需要本地数据库以密文形式保存,必须在构建时显式开启 SQLCipher 特性。
五、跨语言原生架构
MuClip 的另一项设计重点是跨语言集成。
整个同步引擎、网络通信、加密处理、连接池与 SQLite 存储均由 Rust 原生核心负责,上层应用主要承担 UI、系统剪贴板交互与配置管理。
Windows / C# / Avalonia
Windows 端通过 C ABI 调用 muclip_core.dll。
支持剪贴板同步、文件发送、配对管理、设备查询、诊断日志以及本地历史数据库等功能。
对于 C# 应用,MuClip 提供了原生内存池租借接口,可以减少部分跨语言数据复制与托管堆分配。
Android / Kotlin
Android 端通过 JNI 调用 libmuclip_core.so。
同时支持 DirectByteBuffer 相关零拷贝接口,让部分数据能够直接在 Java/Kotlin 堆外内存与 Rust 之间传递。
Android 后台剪贴板写入受到系统版本限制,因此底层引擎也允许宿主应用自行管理接收内容与前台写入流程。
其他语言
MuClip 还提供 UniFFI 接口以及 C ABI 导出能力。
理论上,只要目标语言能够调用相应原生接口,就可以复用 MuClip 的核心功能,而无需重新实现底层同步协议与加密机制。
六、诊断日志与开发支持
MuClip 内置了一套轻量级诊断日志系统,主要面向 GUI 应用的原生库集成场景。
支持:
- 最近 512 条日志的环形缓冲
- 日志快照与清空读取
- 外部日志回调
- 日志级别控制
- stderr 输出开关
- 回调线程安全设计
这对于没有控制台的 Windows 桌面应用尤其有价值。
宿主应用可以直接读取 Rust 核心的诊断信息,并将其写入自己的日志系统,从而更方便地定位设备发现失败、配对异常、文件传输错误或数据库问题。
七、项目应用与未来方向
MuClip 目前已经用于以下项目:
| 项目 | 平台 | 技术栈 |
|---|---|---|
| 小沐 OCR | Windows | C# / Avalonia |
| MuClip-Android | Android | Kotlin / Jetpack Compose |
| MuClip-Slint | Windows 实验客户端 | Slint / C ABI |
其中,小沐 OCR 可以将识别结果直接写入 MuClip 核心,再同步到手机,实现 OCR 结果跨设备流转与局域网文件互传。
项目后续还计划完善断点续传、设备指纹核对、更加明确的配对密钥管理接口,以及 Linux / macOS 桌面客户端支持。
八、总结
MuClip 并不是一个简单的剪贴板同步工具,而是一套面向多设备应用的原生局域网通信基础设施。
它将自动设备发现、加密配对、P2P 数据传输、文件分块处理、本地历史管理与跨语言接口整合在一个 Rust 核心库中。
对于希望在 Windows 与 Android 之间实现数据同步的开发者而言,MuClip 提供了一种不依赖云服务、无需中心服务器、可以直接嵌入应用的实现方案。
如果你正在开发桌面工具、剪贴板管理器或跨设备协作软件,MuClip 是一个值得关注的开源项目。
项目地址: https://github.com/katomegumi1999/MuClip
作者主页: https://github.com/katomegumi1999
许可证: MIT,可用于商业项目与闭源集成,遵循许可证要求即可。