面向局域网的低延迟跨平台剪贴板同步：Linux 和 Windows 间复制文本、图片与文件，文件元数据即时到达，内容在粘贴时高速按需传输。
clipboard-sync 是一个以本机剪贴板体验为中心的跨平台同步 Agent。两台设备加入同一个 group_id 后，复制文本、图片或文件，便可在另一台设备直接粘贴。在稳定的局域网中，元数据同步近乎无感；文件内容不会在复制时预先传完，也不会被广播给所有设备。
| Linux | Windows |
|---|---|
| X11 / Wayland 剪贴板 + FUSE 虚拟文件 | Explorer 原生虚拟文件剪贴板 |
文件管理器直接 Ctrl+V |
资源管理器直接 Ctrl+V |
- 保留原生粘贴体验：无需先下载文件或打开专用客户端，在系统文件管理器中直接粘贴。
- 为低延迟而设计：复制时立即发布轻量元数据，避免大文件阻塞剪贴板同步；真正的数据只在用户粘贴时发送。
- 按需传输：复制阶段只传文件名、大小、校验和与访问 token；只有目标端读取文件时才传输数据。
- 大文件同样流畅：内容按块流式发送，目标端边接收边写入临时文件，不会一次性载入内存。
- 局域网消息总线：控制消息、图片数据和文件分块均经过 NATS，不依赖 HTTP、SSH 或共享目录。
- 多设备隔离：
group_id限定可互相同步的设备，device_id防止本机事件回环。
- 实时同步文本剪贴板
- 同步图片剪贴板
- 同步单个文件、多个文件和文件夹的元数据
- Linux <-> Windows、Linux <-> Linux、Windows <-> Windows 文件粘贴
- 文件内容按目标设备单播，支持重复分块忽略、缺块检测与 SHA256 校验
- NATS 断连后自动持续重连
- Linux FUSE 挂载异常后自动尝试恢复
- 默认仅输出错误日志，正常运行保持安静
准备两台可访问同一 NATS 服务的设备。下面以 Linux 为例；Windows 的构建与运行命令见平台安装。
git clone https://github.com/chendx-github/clipboard-sync.git
cd clipboard-sync
# Linux: X11 选择 xclip，Wayland 选择 wl-clipboard
sudo apt-get update && sudo apt-get install -y xclip fuse3 nats-server
go build -o agent ./cmd/agent
nats-server -p 4222复制一份配置给每台设备，确保它们使用不同的 device_id、相同的 group_id 和可访问的 nats_url：
# configs/linux.yaml
device_id: "linux-a"
group_id: "team-a"
nats_url: "nats://192.168.1.100:4222"
chunk_size: 8388608
token_ttl: 60
poll_interval_ms: 500
log_level: "error"
clipboard_file_format: "uri-list" # Dolphin 使用 uri-list；Nautilus/Files 使用 gnome启动 Agent：
./agent run -config configs/linux.yaml在另一台设备完成同样配置并启动 Agent 后，复制一段文本或一个文件，再在目标设备直接粘贴即可。
- 在设备 A 复制文本或图片。
- 设备 B 自动接收并写入本机剪贴板。
- 在任何支持的应用中粘贴。
- 在设备 A 的文件管理器中复制文件、多个文件或文件夹。
- 设备 B 接收元数据，并把可读取的虚拟文件写入本机剪贴板。
- 在设备 B 的文件管理器或 Windows Explorer 中按
Ctrl+V。 - 文件管理器请求内容后，设备 A 才开始通过 NATS 流式发送数据。
文件需要在 token 有效期内粘贴，默认有效期为 60 秒。过期后重新复制即可。
sequenceDiagram
participant A as 设备 A
participant N as NATS
participant B as 设备 B
participant FM as 文件管理器 / Explorer
A->>N: clipboard.update（文件元数据 + token）
N->>B: clipboard.update
B->>B: 写入虚拟文件到系统剪贴板
FM->>B: 用户粘贴并读取文件
B->>N: clipboard.request（目标设备）
N->>A: clipboard.request
A->>N: file.chunk / file.complete
N->>B: file.chunk / file.complete
B->>FM: 边接收边提供文件内容
| 平台 | 接收远程文件时的实现 |
|---|---|
| Linux | 将远程文件映射到 FUSE 虚拟目录，并把虚拟路径写入 X11/Wayland 剪贴板。 |
| Windows | 使用 OLE 虚拟文件剪贴板对象，供 Windows Explorer 按需读取。 |
Linux 桌面环境对文件剪贴板使用的 MIME 类型并不完全一致。clipboard_file_format 用于选择 Agent 写入远程文件虚拟路径时使用的格式；一次只会提供一种格式。
| 配置值 | 剪贴板 MIME | 载荷格式 | 适用文件管理器 |
|---|---|---|---|
uri-list（默认） |
text/uri-list |
file:// URI 列表 |
Dolphin |
gnome |
x-special/gnome-copied-files |
copy + file:// URI 列表 |
GNOME Files / Nautilus |
如果粘贴时出现“剪贴板内容的文件名”之类的提示，说明文件管理器把剪贴板载荷当作普通文本处理。将 clipboard_file_format 切换为与当前文件管理器对应的值，重启 Agent 后重新从另一台设备复制文件。
| 主题 | 用途 |
|---|---|
clipboard.update |
广播文本、图片或文件元数据 |
clipboard.request |
目标端请求文件内容 |
file.chunk / file.complete |
单播文件数据与完成信号 |
image.chunk / image.complete |
单播图片数据与完成信号 |
- Go
1.22+ - NATS Server
2.9+ - 两台设备网络互通，均可访问同一 NATS 地址
- 每台设备拥有独立
device_id
Agent 必须以当前桌面用户身份运行。以 root 运行可能无法访问用户剪贴板，或导致 FUSE 权限错误。
Debian / Ubuntu：
# X11
sudo apt-get update && sudo apt-get install -y xclip fuse3
# Wayland
sudo apt-get update && sudo apt-get install -y wl-clipboard fuse3- Windows 10 或 Windows 11
- 在 Windows Explorer 中完成文件粘贴
- PowerShell 或 CMD 可运行 Agent
构建：
go build -o agent.exe .\cmd\agent运行：
.\agent.exe run -config configs\config-windows.yaml从 Linux 构建 Windows 二进制：
GOOS=windows GOARCH=amd64 go build -o agent.exe ./cmd/agent示例文件：configs/config.yaml 和 configs/config-windows.yaml。不要将示例中的 device_id 和网络地址直接用于多台设备。
device_id: "linux-a" # 每台设备唯一
group_id: "team-a" # 相同分组互相同步
nats_url: "nats://192.168.1.100:4222" # 共享 NATS 服务
chunk_size: 8388608 # 8 MiB；需不大于 NATS max_payload
token_ttl: 60 # 文件复制元数据有效期（秒）
poll_interval_ms: 500 # 剪贴板轮询间隔（毫秒）
cache_dir: "" # 留空使用系统临时目录
download_dir: "" # spool 和落地目录，留空使用系统临时目录
mount_dir: "" # Linux FUSE 挂载目录，留空使用系统临时目录
log_level: "error" # debug | info | warn | error
clipboard_file_format: "uri-list" # Linux: uri-list (Dolphin) | gnome (Nautilus/Files)配置要点：
nats_url必须是所有设备可访问的地址；远程 NATS 不应填写localhost。chunk_size最低为65536。默认8388608，NATS 服务端的max_payload必须足够大。cache_dir、download_dir和mount_dir在生产环境建议设置为稳定且可写的目录。clipboard_file_format仅影响 Linux 接收远程文件后的文件剪贴板写入。默认uri-list使用标准text/uri-list，适用于 Dolphin。- GNOME Files/Nautilus 使用
gnome，其载荷为x-special/gnome-copied-files和copy操作标记。切换该配置后必须重启 Agent，并重新复制远程文件。
本地开发可直接启动：
nats-server -p 4222局域网使用时，开放 NATS 端口并将配置中的 nats_url 改为实际监听地址。使用 8 MiB 分块时，服务端配置至少应包含：
max_payload: 16777216建议按以下顺序验证部署：
- 两端启动 Agent，确认没有 NATS 连接错误。
- 复制一段文本，在另一端粘贴并核对内容。
- 复制图片，在另一端粘贴并核对图像。
- 复制一个小文件，在目标文件管理器中粘贴并核对大小与内容。
- 复制多个文件和一个文件夹，确认目标端可正常粘贴。
- 使用大文件验证磁盘空间、网络吞吐与内存占用。
- X11 安装
xclip。 - Wayland 安装
wl-clipboard，并确认wl-copy/wl-paste在PATH中。
- 确认安装
fuse3，且mount_dir的父目录可写。 - 确认在文件管理器中粘贴，而不是终端或普通文本输入框。
- 确认 Agent 由当前桌面用户运行。
- Dolphin 使用
clipboard_file_format: "uri-list"；GNOME Files/Nautilus 使用clipboard_file_format: "gnome"。修改配置后重启 Agent，并重新复制远程文件。
- 检查两端
device_id不同、group_id相同。 - 检查
nats_url相同且可从双方访问。 - 检查 NATS 端口和防火墙规则。
- 将
log_level临时设置为info或debug，查看连接与剪贴板事件。
- 确认 NATS 的
max_payload大于chunk_size加上协议开销。 - 使用低延迟网络部署 NATS，避免源文件位于高延迟网络盘。
- 检查目标设备磁盘空间；接收端会先写入本地 spool 文件。
- 复制后等待过久会使 token 过期，重新复制文件即可。
- 使用 systemd 或 Windows 计划任务在用户登录后启动 Agent。
- 为每个设备配置固定的
device_id，并为不同团队或环境分配不同group_id。 - 生产环境将 NATS 部署在可信网络中，并按实际需要配置网络访问控制。
- 默认日志级别为
error；排障结束后恢复该级别，避免正常传输刷屏。
Linux systemd 的服务命令示例：
/path/to/agent run -config /path/to/config.yamlWindows 计划任务的启动命令示例：
C:\path\to\agent.exe run -config C:\path\to\config.yaml# 格式化
# 整理依赖
# 构建 Linux Agent
# 交叉构建 Windows Agent
GOOS=windows GOARCH=amd64 go build -o agent.exe ./cmd/agent- Linux -> Windows 的大文件吞吐可能低于 Windows -> Linux，主要受 Windows Explorer 的 OLE 虚拟文件读取方式影响。
- Linux 文件剪贴板只能同时发布一种 MIME 格式；同一台设备需要在 Dolphin 与 GNOME Files/Nautilus 之间切换使用时，必须修改
clipboard_file_format并重启 Agent。
欢迎提交 Issue 和 Pull Request。修复跨平台兼容性时，请说明操作系统版本、桌面环境、NATS 版本、复现步骤与日志级别，便于定位剪贴板和文件管理器差异。