RustDesk cliprdr 剪贴板文件传输机制从 RDP 虚拟通道协议到跨机文件粘贴的实现剖析【免费下载链接】rustdeskAn open-source remote desktop application designed for self-hosting, as an alternative to TeamViewer.项目地址: https://gitcode.com/GitHub_Trending/ru/rustdesk本文基于 RustDesk 仓库中libs/clipboard子库的官方 README完整解析其网络剪贴板模块cliprdr的工作原理它如何借鉴 Windows RDP 剪贴板虚拟通道扩展协议的七步握手与按需读取流程如何在 Windows 上通过 OLE 事件订阅、在 Linux/OSX 上通过「剪贴板客户端 本地文件清单 FUSE 服务器」三件套实现跨机文件复制粘贴并深入源码印证 PDU 数据结构、4 MiB 分块读取、防死循环过滤与挂载点卸载策略等关键细节。读完后你能掌握该子库的协议骨架、unix-file-copy-paste特性开关的启用方式以及各平台实现的对应源码位置。模块定位把「复制-粘贴」搬到网络上libs/clipboard是 RustDesk 工作区内的一个独立 crate包名clipboard其官方定位非常简洁Copy files and text through network通过网络复制文件和文本。README 明确指出其底层主逻辑源自 FreeRDP 项目——这正是 RDP 协议生态中用于剪贴板重定向的模块协议名称为cliprdrClipboard Redirection。该模块的启用方式按平台区分Windows文件复制粘贴能力默认内置无需额外特性开关。从 libs/clipboard/src/platform/mod.rs 可以看到#[cfg(target_os windows)]分支直接提供create_cliprdr_contextLinux / macOS需要以unix-file-copy-pastefeature 构建。子库自身的 libs/clipboard/Cargo.toml 中unix-file-copy-paste特性会引入x11rb、x11-clipboard、fuserFUSE 实现、libc、dashmap、percent-encoding、utf16string、once_cell以及 macOS 用的cacao等依赖主工程的根 Cargo.toml 将clipboard/unix-file-copy-paste透传为同名的顶层 feature即cargo build --features unix-file-copy-paste即可在 Unix 平台启用该能力。在 RustDesk 主程序中该能力通过全局单例ContextSend统一开关。libs/clipboard/src/context_send.rs 中ContextSend::enable调用create_cliprdr_context(true, false, 30)创建文件传输上下文第三个参数 30 为响应等待超时秒数常量CLIPBOARD_RESPONSE_WAIT_TIMEOUT_SECS 30并记录日志clipboard context for file transfer created.文本剪贴板则由 src/clipboard.rs 以CLIPBOARD_INTERVAL 333毫秒的间隔轮询同步二者互为补充。核心术语与协议来源README 给出了三个基础术语理解它们才能读懂后续流程cliprdr本模块本身剪贴板重定向协议local发起文件复制事件的端点remote将从 local 复制的文件粘贴下来的端点。主要算法来自《Remote Desktop Protocol: Clipboard Virtual Channel Extension》MS-RDPECLIP 规范。协议最初是 Windows RDP 的扩展因此消息包结构与 Windows 契合度极高——这一点在 libs/clipboard/src/cliprdr.h 中体现得非常直接CLIPRDR_MONITOR_READY、CLIPRDR_FORMAT_LIST、CLIPRDR_FORMAT_DATA_REQUEST、CLIPRDR_FILE_CONTENTS_REQUEST等 C 结构体每个 PDU 都以connID / msgType / msgFlags / dataLen四元组头部开始。Rust 侧用枚举ClipboardFile对这套 PDU 做了逐一对应的建模位于 libs/clipboard/src/lib.rs变体包括ClipboardFile 变体对应协议 PDU关键字段MonitorReadyCLIPRDR_MONITOR_READY无FormatListCLIPRDR_FORMAT_LISTformat_list: Vec(i32, String)FormatListResponseCLIPRDR_FORMAT_LIST_RESPONSEmsg_flagsFormatDataRequestCLIPRDR_FORMAT_DATA_REQUESTrequested_format_idFormatDataResponseCLIPRDR_FORMAT_DATA_RESPONSEformat_data: Vecu8FileContentsRequestCLIPRDR_FILE_CONTENTS_REQUESTstream_id / list_index / dw_flags / n_position_low / n_position_high / cb_requestedFileContentsResponseCLIPRDR_FILE_CONTENTS_RESPONSEstream_id / requested_dataTryEmpty清空通知无Files审计/清单上报files: Vec(String, u64)这些变体携带 serde 的#[serde(tag t, content c)]标记说明ClipboardFile会在进程间/网络上以 JSON 形式序列化传输再由 src/client.rs 与 src/server/clipboard_service.rs 等上层模块收发。文件复制粘贴的七步主流程README 将复制粘贴主算法归纳为七步0~6local 与 remote 互相通知「已就绪」Monitor Readylocal 订阅/监听系统剪贴板等待文件复制事件local 一旦捕获文件复制事件通知 remoteremote 确认接收并尝试拉取文件列表local 更新其文件清单remote 将拉取到的文件列表写入本地剪贴板remote 的操作系统或桌面环境管理器发起粘贴其他程序开始读取剪贴板中的文件读取请求被转换为 RPC在 Windows 上所有文件读取都走流式文件 APIstream file API在 Linux/OSX 上用 FUSE 把 POSIX 读取请求转换为 RPC当本地剪贴板内容被反向传回、可能造成死循环时所有指向 FUSE 目录的文件复制事件都会被忽略逐个完成所有文件的粘贴。从网络数据传输视角README 给出的时序图如下这里有两个值得注意的设计点文件内容按需惰性读取remote 的剪贴板中实际只存了「文件列表」元数据真正的字节内容是在某个应用程序执行读取时才以FileContentsRequest(stream_id, list_index, 偏移, 长度)的形式逐块拉取的天然适配大文件双向对称README 特别强调实际实现中两端都可以扮演「发送剪贴板更新」与「请求文件内容」的角色并不存在「只有 local 能更新剪贴板、把文件复制到 remote」的限制。Windows 端实现隐藏窗口 OLE 剪贴板事件该协议最初作为 Windows RDP 的扩展设计因此具体消息包结构与 Windows 天然契合。README 描述的 Windows 实现要点启动 cliprdr 时会派生一个线程用于创建一个不可见窗口并订阅 OLE 剪贴板事件该窗口回调处理各类事件即 libs/clipboard/src/windows/wf_cliprdr.c 中的cliprdr_proc详细的调用关系见文首两张 Windows 方向图A→B 与 B→A 的完整事件流。工程层面libs/clipboard/build.rsbuild build.rs见 libs/clipboard/Cargo.toml用cccrate 直接编译这段 C 实现为mycliprdr并对 MSVC 与 GNU 系编译器分别注入不同编译参数这是该子库中 Rust 与 C 混合的典型形态。Linux/OSX 实现三件套架构在 Unix 类平台上README 将 Cliprdr Server 拆成三个部分Clipboard Client剪贴板客户端、Local File List本地文件清单、FUSE serverFUSE 服务器。下面结合源码逐一印证。Clipboard Client轮询、过滤与去重剪贴板客户端在独立线程中轮询剪贴板上的文件 URL。发现文件 URL 更新后先过滤掉两类事件指向自身 FUSE 目录的防死循环对应主流程第 5 步的说明和重复的随后直接通过FormatList把更新发给 remote。该客户端同时被 cliprdr server 反向使用——既用于设置本地剪贴板内容也用于从系统读取文件路径。源码印证FUSE 挂载路径被显式登记为需要排除的路径libs/clipboard/src/platform/unix/fuse/mod.rs 提供get_exclude_pathsclient/server 各自对应cliprdr-client、cliprdr-server两个挂载点剪贴板客户端据此过滤指向 FUSE 目录的复制事件macOS 侧的防循环更具体远端文件以临时文件形式落地到/tmp/.rustdesk_前缀路径libs/clipboard/src/platform/unix/macos/pasteboard_context.rs 中的TEMP_FILE_PREFIX .rustdesk_主程序 src/clipboard.rs 中的is_file_url_set_by_rustdesk会识别file:///tmp/.rustdesk_前缀避免把自己生成的文件 URL 再当作新的复制事件回传给对端。Local File List缓存、指纹与预加载本地文件清单是一份文件元数据的临时列表。收到对端的FileContentsRequest后server 从中挑出被请求的文件必要时打开文件句柄读取收到 remote 的FormatDataRequest索要文件列表时则需要基于 Clipboard Client 从系统取回的路径重建清单。由于应用程序大概率顺序读取列表中的文件清单上还做了缓存与预加载优化。libs/clipboard/src/platform/unix/serv_files.rs 完整实现了这一层全局缓存CLIP_FILES保存files原始路径、file_listLocalFile元数据列表与预构建好的files_pdu可直接作为FormatDataResponse返回的二进制sync_files采用「路径 指纹」双重判重fingerprint对每个顶层选中项 stat 出size/mtime/is_dirFileSig路径、指纹都相同且不含目录时才跳过重建——同文件原地编辑后再次复制缓存的尺寸/时间戳会随之刷新该行为有专门的单测recopy_after_edit_refreshes_cached_size覆盖read_file_contents按dw_flags区分两类请求0x1表示只请求文件大小FileContentsRequest::Size响应为小端u64尺寸0x2表示按offset length请求内容片段Range偏移越界会返回InvalidRequestoffset length超出实际大小时自动截断到文件末尾预加载每次成功服务一个分块后会跳过目录项、对下一个文件调用load_handle注释原文 hot reload next file把文件句柄和首批缓冲读进内存命中「顺序读取」假设减少后续 RPC 的响应延迟。FUSE server把 POSIX 读转换成 RPCFUSE 服务器把 POSIX 文件读取请求转换为FileContentsRequest/ResponseRPC。收到 remote 文件列表后FUSE server 会解析出文件系统树并重新组织挂载内容——也就是说 remote 端用户看到的是一个「长得像真实目录」的只读挂载点文件管理器对它执行open/read/stat时底层全部走网络。实现位于 libs/clipboard/src/platform/unix/fuse/mod.rs挂载点由 IPC 目录推导分别为cliprdr-client与cliprdr-server见fuse_mount_pointclient 与 server 各自独立上下文FUSE_CONTEXT_CLIENT/FUSE_CONTEXT_SERVER挂载选项为FSName(rustdesk-cliprdr-fs)NoAtimeRO只读并以 3 秒的FUSE_TIMEOUT创建FuseServer具备挂载点状态机HealthyMount / NotMounted / StaleMount / Unknown检测到 stale 挂载会先清理再重挂挂载点被其他上下文占用则返回ClipboardOccupied错误保证多进程场景下不出现双挂载。macOS 上无法使用 FUSEREADME 所述的「Clipboard Client Local File List FUSE server」三件套在此平台被替换为基于系统 Pasteboard 的方案libs/clipboard/src/platform/unix/macos/ 下的pasteboard_context.rs、paste_observer.rs、paste_task.rs、item_data_provider.rs分别负责创建 Pasteboard 上下文、监听粘贴事件、执行按块取数任务以及以NSFilePromiseProvider风格提供文件 URLlibs/clipboard/src/platform/unix/macos/README.md 对该平台实现另有补充说明远端文件先以/tmp/.rustdesk_前缀临时文件呈现给系统见文首第三张示意图。协议数据格式路径、时间与权限的三处「非本地」编码README 的 Groceries 一节指出了三处为了兼容 Windows 而做的编码约定源码中都能找到精确落点常量集中在 libs/clipboard/src/platform/unix/mod.rs1. 路径全部转为 DOS 格式的 UTF-16 LE。协议诞生于 Windows 生态PDU 中的路径一律是 DOS 风格。libs/clipboard/src/platform/unix/local_file.rs 中LocalFile::try_open把 Unix 路径前导/去掉并把/全部替换为\\UNIX /usr/bin/rustdesk - DOS \usr\bin\rustdesk文件名随后以 UTF-16 LE 写入定长的cFileName字段容量 260 个 UTF-16 码元超出会报descriptor name too long错误。2. 时间戳用 LDAP 时间而非 Unix 时间。libs/clipboard/src/platform/unix/mod.rs 定义LDAP_EPOCH_DELTA 116444772610000000100 纳秒单位下 1601-01-01 与 1970-01-01 的差值LocalFile::as_bin在序列化「最后写入时间」时执行unix 纳秒 / 100 LDAP_EPOCH_DELTA的转换。3. 为保留 Unix 权限占用 FileDescriptor PDU 的保留区。每个文件元数据被编码为固定 592 字节的FILEDESCRIPTORWFILE_DESCRIPTOR_SIZE 592与 RDP 规范一致。规范中有一段 16 字节 reserved 区域RustDesk 将其中最后 4 字节用来存放 Unix 文件 mode并置位私有标志FLAGS_FD_UNIX_MODE 0x08注释明确 this flag is not used in windows。相关标志常量pub const FLAGS_FD_ATTRIBUTES: u32 0x04; // has valid file attributes pub const FLAGS_FD_SIZE: u32 0x40; // has valid file size pub const FLAGS_FD_LAST_WRITE: u32 0x20; // has valid last write time pub const FLAGS_FD_PROGRESSUI: u32 0x4000; // show progress pub const FLAGS_FD_UNIX_MODE: u32 0x08; // transferred from unix, contains file mode此外两种「格式」在 Unix 侧有固定 ID 占位FILEDESCRIPTOR_FORMAT_ID 49334名称FileGroupDescriptorW与FILECONTENTS_FORMAT_ID 49267名称FileContents由REMOTE_FORMAT_MAP维护映射。分块大小方面libs/clipboard/src/platform/unix/mod.rs 定义BLOCK_SIZE 4 * 1024 * 10244 MiB注释说明其与FileContentsRequest的异步请求尺寸对齐LocalFile::load_handle也按BLOCK_SIZE * 2分配BufReader容量且支持句柄失效后自动作废重建invalidate_handle文件读完还会主动释放句柄回收资源。挂载点残留问题与卸载策略README 还解释了一个用户常见疑问应用退出后FUSE 挂载点仍被占用。原因是 FUSE server 没有以AUTO_UNMOUNT方式挂载背后是三条权衡对多进程程序实现优雅关闭很难AUTO_UNMOUNT默认未启用且需要全局配置开启user_allow_other让用户去改这种全局配置风险较大直接调用umount()系统调用同样要求该配置。当前的解决方案是直接调用umount用户态程序卸载悬挂的 FUSE 挂载——README 认为这「目前工作得很好」。这一思路与源码一致libs/clipboard/src/platform/unix/fuse/mod.rs 中的 stale 挂载清理路径会先执行unmount_fuse_mount_point再校验挂载状态说明「检测到残留 → 外部卸载 → 重新挂载」是一条经过设计的常规恢复路径而非异常兜底。消息通道与进程内分发协议 PDU 在 RustDesk 进程内的流转由 libs/clipboard/src/lib.rs 的MsgChannel机制负责每个peer_id/conn_id对应一条unbounded_channel接收端包装在ArcTokioMutexUnboundedReceiver中全局表VEC_MSG_CHANNEL用RwLock保护send_data(conn_id, data)按conn_id定向投递Unix 端还支持conn_id 0时广播给所有通道send_data_to_allWindows 端则提供send_data_exclude用于排除指定通道。ClipboardFile::is_stopping_allowed/is_beginning_message等辅助方法则用于在会话停止判断时识别哪些消息可以安全处理体现了该模块对连接生命周期与剪贴板事件交叉场景的细致考量。错误类型统一收敛为CliprdrError含ClipboardOccupied、FileError、InvalidRequest等变体与 FUSE 挂载状态机中的ClipboardOccupied返回值互相呼应。小结libs/clipboard用一套源自 RDP 的 cliprdr 协议把「复制-粘贴」这一桌面隐喻完整搬到了网络上MonitorReady建立双向就绪FormatList/FormatData交换文件元数据FileContentsRequest/Response按 4 MiB 分块惰性传输内容Windows 端依靠隐藏窗口的 OLE 事件订阅Unix 端依靠剪贴板轮询、指纹缓存的文件清单与只读 FUSE 挂载。路径的 DOS 化、时间的 LDAP 化、权限位塞进保留区这些「看起来别扭」的编码都是与 Windows 端保持同构协议格式的必然结果。相关代码入口一览协议建模与消息通道libs/clipboard/src/lib.rs、libs/clipboard/src/cliprdr.h平台抽象与 Unix 常量libs/clipboard/src/platform/mod.rs、libs/clipboard/src/platform/unix/mod.rs文件清单与取数服务libs/clipboard/src/platform/unix/serv_files.rs、libs/clipboard/src/platform/unix/local_file.rsFUSE 挂载与状态机libs/clipboard/src/platform/unix/fuse/mod.rsmacOS Pasteboard 实现libs/clipboard/src/platform/unix/macos/pasteboard_context.rsWindows C 实现libs/clipboard/src/windows/wf_cliprdr.c上下文生命周期管理libs/clipboard/src/context_send.rs主程序集成文本剪贴板轮询、文件 URL 识别src/clipboard.rs、src/clipboard_file.rs特性开关Cargo.toml、libs/clipboard/Cargo.toml【免费下载链接】rustdeskAn open-source remote desktop application designed for self-hosting, as an alternative to TeamViewer.项目地址: https://gitcode.com/GitHub_Trending/ru/rustdesk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
RustDesk cliprdr 剪贴板文件传输机制从 RDP 虚拟通道协议到跨机文件粘贴的实现剖析【免费下载链接】rustdeskAn open-source remote desktop application designed for self-hosting, as an alternative to TeamViewer.项目地址: https://gitcode.com/GitHub_Trending/ru/rustdesk本文基于 RustDesk 仓库中libs/clipboard子库的官方 README完整解析其网络剪贴板模块cliprdr的工作原理它如何借鉴 Windows RDP 剪贴板虚拟通道扩展协议的七步握手与按需读取流程如何在 Windows 上通过 OLE 事件订阅、在 Linux/OSX 上通过「剪贴板客户端 本地文件清单 FUSE 服务器」三件套实现跨机文件复制粘贴并深入源码印证 PDU 数据结构、4 MiB 分块读取、防死循环过滤与挂载点卸载策略等关键细节。读完后你能掌握该子库的协议骨架、unix-file-copy-paste特性开关的启用方式以及各平台实现的对应源码位置。模块定位把「复制-粘贴」搬到网络上libs/clipboard是 RustDesk 工作区内的一个独立 crate包名clipboard其官方定位非常简洁Copy files and text through network通过网络复制文件和文本。README 明确指出其底层主逻辑源自 FreeRDP 项目——这正是 RDP 协议生态中用于剪贴板重定向的模块协议名称为cliprdrClipboard Redirection。该模块的启用方式按平台区分Windows文件复制粘贴能力默认内置无需额外特性开关。从 libs/clipboard/src/platform/mod.rs 可以看到#[cfg(target_os windows)]分支直接提供create_cliprdr_contextLinux / macOS需要以unix-file-copy-pastefeature 构建。子库自身的 libs/clipboard/Cargo.toml 中unix-file-copy-paste特性会引入x11rb、x11-clipboard、fuserFUSE 实现、libc、dashmap、percent-encoding、utf16string、once_cell以及 macOS 用的cacao等依赖主工程的根 Cargo.toml 将clipboard/unix-file-copy-paste透传为同名的顶层 feature即cargo build --features unix-file-copy-paste即可在 Unix 平台启用该能力。在 RustDesk 主程序中该能力通过全局单例ContextSend统一开关。libs/clipboard/src/context_send.rs 中ContextSend::enable调用create_cliprdr_context(true, false, 30)创建文件传输上下文第三个参数 30 为响应等待超时秒数常量CLIPBOARD_RESPONSE_WAIT_TIMEOUT_SECS 30并记录日志clipboard context for file transfer created.文本剪贴板则由 src/clipboard.rs 以CLIPBOARD_INTERVAL 333毫秒的间隔轮询同步二者互为补充。核心术语与协议来源README 给出了三个基础术语理解它们才能读懂后续流程cliprdr本模块本身剪贴板重定向协议local发起文件复制事件的端点remote将从 local 复制的文件粘贴下来的端点。主要算法来自《Remote Desktop Protocol: Clipboard Virtual Channel Extension》MS-RDPECLIP 规范。协议最初是 Windows RDP 的扩展因此消息包结构与 Windows 契合度极高——这一点在 libs/clipboard/src/cliprdr.h 中体现得非常直接CLIPRDR_MONITOR_READY、CLIPRDR_FORMAT_LIST、CLIPRDR_FORMAT_DATA_REQUEST、CLIPRDR_FILE_CONTENTS_REQUEST等 C 结构体每个 PDU 都以connID / msgType / msgFlags / dataLen四元组头部开始。Rust 侧用枚举ClipboardFile对这套 PDU 做了逐一对应的建模位于 libs/clipboard/src/lib.rs变体包括ClipboardFile 变体对应协议 PDU关键字段MonitorReadyCLIPRDR_MONITOR_READY无FormatListCLIPRDR_FORMAT_LISTformat_list: Vec(i32, String)FormatListResponseCLIPRDR_FORMAT_LIST_RESPONSEmsg_flagsFormatDataRequestCLIPRDR_FORMAT_DATA_REQUESTrequested_format_idFormatDataResponseCLIPRDR_FORMAT_DATA_RESPONSEformat_data: Vecu8FileContentsRequestCLIPRDR_FILE_CONTENTS_REQUESTstream_id / list_index / dw_flags / n_position_low / n_position_high / cb_requestedFileContentsResponseCLIPRDR_FILE_CONTENTS_RESPONSEstream_id / requested_dataTryEmpty清空通知无Files审计/清单上报files: Vec(String, u64)这些变体携带 serde 的#[serde(tag t, content c)]标记说明ClipboardFile会在进程间/网络上以 JSON 形式序列化传输再由 src/client.rs 与 src/server/clipboard_service.rs 等上层模块收发。文件复制粘贴的七步主流程README 将复制粘贴主算法归纳为七步0~6local 与 remote 互相通知「已就绪」Monitor Readylocal 订阅/监听系统剪贴板等待文件复制事件local 一旦捕获文件复制事件通知 remoteremote 确认接收并尝试拉取文件列表local 更新其文件清单remote 将拉取到的文件列表写入本地剪贴板remote 的操作系统或桌面环境管理器发起粘贴其他程序开始读取剪贴板中的文件读取请求被转换为 RPC在 Windows 上所有文件读取都走流式文件 APIstream file API在 Linux/OSX 上用 FUSE 把 POSIX 读取请求转换为 RPC当本地剪贴板内容被反向传回、可能造成死循环时所有指向 FUSE 目录的文件复制事件都会被忽略逐个完成所有文件的粘贴。从网络数据传输视角README 给出的时序图如下这里有两个值得注意的设计点文件内容按需惰性读取remote 的剪贴板中实际只存了「文件列表」元数据真正的字节内容是在某个应用程序执行读取时才以FileContentsRequest(stream_id, list_index, 偏移, 长度)的形式逐块拉取的天然适配大文件双向对称README 特别强调实际实现中两端都可以扮演「发送剪贴板更新」与「请求文件内容」的角色并不存在「只有 local 能更新剪贴板、把文件复制到 remote」的限制。Windows 端实现隐藏窗口 OLE 剪贴板事件该协议最初作为 Windows RDP 的扩展设计因此具体消息包结构与 Windows 天然契合。README 描述的 Windows 实现要点启动 cliprdr 时会派生一个线程用于创建一个不可见窗口并订阅 OLE 剪贴板事件该窗口回调处理各类事件即 libs/clipboard/src/windows/wf_cliprdr.c 中的cliprdr_proc详细的调用关系见文首两张 Windows 方向图A→B 与 B→A 的完整事件流。工程层面libs/clipboard/build.rsbuild build.rs见 libs/clipboard/Cargo.toml用cccrate 直接编译这段 C 实现为mycliprdr并对 MSVC 与 GNU 系编译器分别注入不同编译参数这是该子库中 Rust 与 C 混合的典型形态。Linux/OSX 实现三件套架构在 Unix 类平台上README 将 Cliprdr Server 拆成三个部分Clipboard Client剪贴板客户端、Local File List本地文件清单、FUSE serverFUSE 服务器。下面结合源码逐一印证。Clipboard Client轮询、过滤与去重剪贴板客户端在独立线程中轮询剪贴板上的文件 URL。发现文件 URL 更新后先过滤掉两类事件指向自身 FUSE 目录的防死循环对应主流程第 5 步的说明和重复的随后直接通过FormatList把更新发给 remote。该客户端同时被 cliprdr server 反向使用——既用于设置本地剪贴板内容也用于从系统读取文件路径。源码印证FUSE 挂载路径被显式登记为需要排除的路径libs/clipboard/src/platform/unix/fuse/mod.rs 提供get_exclude_pathsclient/server 各自对应cliprdr-client、cliprdr-server两个挂载点剪贴板客户端据此过滤指向 FUSE 目录的复制事件macOS 侧的防循环更具体远端文件以临时文件形式落地到/tmp/.rustdesk_前缀路径libs/clipboard/src/platform/unix/macos/pasteboard_context.rs 中的TEMP_FILE_PREFIX .rustdesk_主程序 src/clipboard.rs 中的is_file_url_set_by_rustdesk会识别file:///tmp/.rustdesk_前缀避免把自己生成的文件 URL 再当作新的复制事件回传给对端。Local File List缓存、指纹与预加载本地文件清单是一份文件元数据的临时列表。收到对端的FileContentsRequest后server 从中挑出被请求的文件必要时打开文件句柄读取收到 remote 的FormatDataRequest索要文件列表时则需要基于 Clipboard Client 从系统取回的路径重建清单。由于应用程序大概率顺序读取列表中的文件清单上还做了缓存与预加载优化。libs/clipboard/src/platform/unix/serv_files.rs 完整实现了这一层全局缓存CLIP_FILES保存files原始路径、file_listLocalFile元数据列表与预构建好的files_pdu可直接作为FormatDataResponse返回的二进制sync_files采用「路径 指纹」双重判重fingerprint对每个顶层选中项 stat 出size/mtime/is_dirFileSig路径、指纹都相同且不含目录时才跳过重建——同文件原地编辑后再次复制缓存的尺寸/时间戳会随之刷新该行为有专门的单测recopy_after_edit_refreshes_cached_size覆盖read_file_contents按dw_flags区分两类请求0x1表示只请求文件大小FileContentsRequest::Size响应为小端u64尺寸0x2表示按offset length请求内容片段Range偏移越界会返回InvalidRequestoffset length超出实际大小时自动截断到文件末尾预加载每次成功服务一个分块后会跳过目录项、对下一个文件调用load_handle注释原文 hot reload next file把文件句柄和首批缓冲读进内存命中「顺序读取」假设减少后续 RPC 的响应延迟。FUSE server把 POSIX 读转换成 RPCFUSE 服务器把 POSIX 文件读取请求转换为FileContentsRequest/ResponseRPC。收到 remote 文件列表后FUSE server 会解析出文件系统树并重新组织挂载内容——也就是说 remote 端用户看到的是一个「长得像真实目录」的只读挂载点文件管理器对它执行open/read/stat时底层全部走网络。实现位于 libs/clipboard/src/platform/unix/fuse/mod.rs挂载点由 IPC 目录推导分别为cliprdr-client与cliprdr-server见fuse_mount_pointclient 与 server 各自独立上下文FUSE_CONTEXT_CLIENT/FUSE_CONTEXT_SERVER挂载选项为FSName(rustdesk-cliprdr-fs)NoAtimeRO只读并以 3 秒的FUSE_TIMEOUT创建FuseServer具备挂载点状态机HealthyMount / NotMounted / StaleMount / Unknown检测到 stale 挂载会先清理再重挂挂载点被其他上下文占用则返回ClipboardOccupied错误保证多进程场景下不出现双挂载。macOS 上无法使用 FUSEREADME 所述的「Clipboard Client Local File List FUSE server」三件套在此平台被替换为基于系统 Pasteboard 的方案libs/clipboard/src/platform/unix/macos/ 下的pasteboard_context.rs、paste_observer.rs、paste_task.rs、item_data_provider.rs分别负责创建 Pasteboard 上下文、监听粘贴事件、执行按块取数任务以及以NSFilePromiseProvider风格提供文件 URLlibs/clipboard/src/platform/unix/macos/README.md 对该平台实现另有补充说明远端文件先以/tmp/.rustdesk_前缀临时文件呈现给系统见文首第三张示意图。协议数据格式路径、时间与权限的三处「非本地」编码README 的 Groceries 一节指出了三处为了兼容 Windows 而做的编码约定源码中都能找到精确落点常量集中在 libs/clipboard/src/platform/unix/mod.rs1. 路径全部转为 DOS 格式的 UTF-16 LE。协议诞生于 Windows 生态PDU 中的路径一律是 DOS 风格。libs/clipboard/src/platform/unix/local_file.rs 中LocalFile::try_open把 Unix 路径前导/去掉并把/全部替换为\\UNIX /usr/bin/rustdesk - DOS \usr\bin\rustdesk文件名随后以 UTF-16 LE 写入定长的cFileName字段容量 260 个 UTF-16 码元超出会报descriptor name too long错误。2. 时间戳用 LDAP 时间而非 Unix 时间。libs/clipboard/src/platform/unix/mod.rs 定义LDAP_EPOCH_DELTA 116444772610000000100 纳秒单位下 1601-01-01 与 1970-01-01 的差值LocalFile::as_bin在序列化「最后写入时间」时执行unix 纳秒 / 100 LDAP_EPOCH_DELTA的转换。3. 为保留 Unix 权限占用 FileDescriptor PDU 的保留区。每个文件元数据被编码为固定 592 字节的FILEDESCRIPTORWFILE_DESCRIPTOR_SIZE 592与 RDP 规范一致。规范中有一段 16 字节 reserved 区域RustDesk 将其中最后 4 字节用来存放 Unix 文件 mode并置位私有标志FLAGS_FD_UNIX_MODE 0x08注释明确 this flag is not used in windows。相关标志常量pub const FLAGS_FD_ATTRIBUTES: u32 0x04; // has valid file attributes pub const FLAGS_FD_SIZE: u32 0x40; // has valid file size pub const FLAGS_FD_LAST_WRITE: u32 0x20; // has valid last write time pub const FLAGS_FD_PROGRESSUI: u32 0x4000; // show progress pub const FLAGS_FD_UNIX_MODE: u32 0x08; // transferred from unix, contains file mode此外两种「格式」在 Unix 侧有固定 ID 占位FILEDESCRIPTOR_FORMAT_ID 49334名称FileGroupDescriptorW与FILECONTENTS_FORMAT_ID 49267名称FileContents由REMOTE_FORMAT_MAP维护映射。分块大小方面libs/clipboard/src/platform/unix/mod.rs 定义BLOCK_SIZE 4 * 1024 * 10244 MiB注释说明其与FileContentsRequest的异步请求尺寸对齐LocalFile::load_handle也按BLOCK_SIZE * 2分配BufReader容量且支持句柄失效后自动作废重建invalidate_handle文件读完还会主动释放句柄回收资源。挂载点残留问题与卸载策略README 还解释了一个用户常见疑问应用退出后FUSE 挂载点仍被占用。原因是 FUSE server 没有以AUTO_UNMOUNT方式挂载背后是三条权衡对多进程程序实现优雅关闭很难AUTO_UNMOUNT默认未启用且需要全局配置开启user_allow_other让用户去改这种全局配置风险较大直接调用umount()系统调用同样要求该配置。当前的解决方案是直接调用umount用户态程序卸载悬挂的 FUSE 挂载——README 认为这「目前工作得很好」。这一思路与源码一致libs/clipboard/src/platform/unix/fuse/mod.rs 中的 stale 挂载清理路径会先执行unmount_fuse_mount_point再校验挂载状态说明「检测到残留 → 外部卸载 → 重新挂载」是一条经过设计的常规恢复路径而非异常兜底。消息通道与进程内分发协议 PDU 在 RustDesk 进程内的流转由 libs/clipboard/src/lib.rs 的MsgChannel机制负责每个peer_id/conn_id对应一条unbounded_channel接收端包装在ArcTokioMutexUnboundedReceiver中全局表VEC_MSG_CHANNEL用RwLock保护send_data(conn_id, data)按conn_id定向投递Unix 端还支持conn_id 0时广播给所有通道send_data_to_allWindows 端则提供send_data_exclude用于排除指定通道。ClipboardFile::is_stopping_allowed/is_beginning_message等辅助方法则用于在会话停止判断时识别哪些消息可以安全处理体现了该模块对连接生命周期与剪贴板事件交叉场景的细致考量。错误类型统一收敛为CliprdrError含ClipboardOccupied、FileError、InvalidRequest等变体与 FUSE 挂载状态机中的ClipboardOccupied返回值互相呼应。小结libs/clipboard用一套源自 RDP 的 cliprdr 协议把「复制-粘贴」这一桌面隐喻完整搬到了网络上MonitorReady建立双向就绪FormatList/FormatData交换文件元数据FileContentsRequest/Response按 4 MiB 分块惰性传输内容Windows 端依靠隐藏窗口的 OLE 事件订阅Unix 端依靠剪贴板轮询、指纹缓存的文件清单与只读 FUSE 挂载。路径的 DOS 化、时间的 LDAP 化、权限位塞进保留区这些「看起来别扭」的编码都是与 Windows 端保持同构协议格式的必然结果。相关代码入口一览协议建模与消息通道libs/clipboard/src/lib.rs、libs/clipboard/src/cliprdr.h平台抽象与 Unix 常量libs/clipboard/src/platform/mod.rs、libs/clipboard/src/platform/unix/mod.rs文件清单与取数服务libs/clipboard/src/platform/unix/serv_files.rs、libs/clipboard/src/platform/unix/local_file.rsFUSE 挂载与状态机libs/clipboard/src/platform/unix/fuse/mod.rsmacOS Pasteboard 实现libs/clipboard/src/platform/unix/macos/pasteboard_context.rsWindows C 实现libs/clipboard/src/windows/wf_cliprdr.c上下文生命周期管理libs/clipboard/src/context_send.rs主程序集成文本剪贴板轮询、文件 URL 识别src/clipboard.rs、src/clipboard_file.rs特性开关Cargo.toml、libs/clipboard/Cargo.toml【免费下载链接】rustdeskAn open-source remote desktop application designed for self-hosting, as an alternative to TeamViewer.项目地址: https://gitcode.com/GitHub_Trending/ru/rustdesk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
