clip-sync

局域网 P2P 剪贴板同步 — 零配置自动发现、端到端加密、跨平台单二进制

English

---

一台设备复制，另一台设备粘贴。无需云服务、无需账号、无需搭建服务器

特性

• 零配置 — 局域网内自动发现，直接运行即可同步
• 文本 + 图片 — 复制文字和截图都能同步，自动检测类型
• 端到端加密 — AES-256-GCM 加密传输
• 跨平台 — Linux（X11 / Wayland）、macOS、Windows
• 轻量 — 纯 Go 标准库，单二进制 ~3MB，零外部依赖

安装

下载预编译二进制

平台	文件名
Linux x86_64	clip-sync-linux-amd64
Linux ARM64	clip-sync-linux-arm64
macOS Intel	clip-sync-darwin-amd64
macOS Apple Silicon	clip-sync-darwin-arm64
Windows x86_64	clip-sync-windows-amd64.exe

chmod +x clip-sync-*
sudo mv clip-sync-* /usr/local/bin/clip-sync

从源码构建

git clone https://github.com/beixiyo/clip-sync.git
cd clip-sync
go build -o clip-sync .

系统依赖

平台	需要安装
Linux (X11)	xclip 或 xsel
Linux (Wayland)	wl-clipboard
macOS	无（系统自带 pbcopy / pbpaste）
Windows	无（系统自带 clip / Get-Clipboard）

使用

零配置（默认）

所有设备直接运行，局域网内自动发现、自动连接：

# 设备 A
clip-sync

# 设备 B（同一局域网，直接运行）
clip-sync

指定设备连接

跳过自动发现，直连指定设备（适合跨子网或自动发现不可用时）：

clip-sync -peer 192.168.1.100:9878

# 多个设备
clip-sync -peer 192.168.1.100:9878,192.168.1.101:9878

指定设备的同时仍会进行自动发现，两种方式共存

自定义端口

clip-sync -port 7878 -udp-port 7879

所有设备必须使用相同端口

私有组（可选）

不想让局域网内所有人都能同步时，用密码隔离：

# 所有设备用同一个密码
clip-sync -p mypassword

或者用随机 token：

# 设备 A — 创建私有组
clip-sync new

# 设备 B — 加入
clip-sync join <token>

参数

clip-sync [options]
clip-sync <command>

Options

参数	默认值	说明
-v	false	开启详细日志（debug 级别）
-p <passphrase>	—	使用密码创建私有组
-port <port>	9878	TCP 数据传输端口
-udp-port <port>	9879	UDP 发现端口
-peer <addr>	—	直连指定设备，逗号分隔多个 host:port
-max-size <MB>	10	剪贴板最大同步大小（MB），超出跳过。0 为不限制

Commands

命令	说明
new	创建随机私有组，输出 token
join <token>	加入私有组（token 保存到本地）
show	显示当前模式和组信息
reset	清除保存的 token，恢复默认自动发现

端口

端口	协议	用途
9878	TCP	设备间剪贴板数据传输
9879	UDP	局域网设备发现（broadcast + multicast）

工作原理

设备 A                            设备 B
┌──────────┐  UDP broadcast/mcast ┌──────────┐
│ 剪贴板    │ ◄──── discovery ───► │ 剪贴板    │
│ 监听器    │                      │ 监听器    │
└────┬─────┘                      └─────┬────┘
     │        TCP + AES-256-GCM         │
     └──────────── 同步 ───────────────┘

1. 发现 — 每 3 秒通过 UDP broadcast + multicast（239.255.70.83）广播自身
2. 过滤 — 广播包含 group hash，只有同组设备才会连接
3. 连接 — TCP 建立连接，启用 KeepAlive
4. 同步 — 每 500ms 轮询剪贴板，变化后 AES-256-GCM 加密广播
5. 去重 — SHA-256 内容哈希，防止回环（A → B → A）

排错

设备发现成功但连接超时

browse: peer discovered addr=192.168.x.x:9878
connect failed ... i/o timeout

原因：防火墙阻止了入站连接

# Linux (ufw)
sudo ufw allow 9878/tcp comment "clip-sync data"
sudo ufw allow 9879/udp comment "clip-sync discovery"

# Linux (firewalld)
sudo firewall-cmd --add-port=9878/tcp --add-port=9879/udp --permanent
sudo firewall-cmd --reload

macOS 首次运行时会弹窗询问是否允许网络连接，选择 允许。如果之前拒绝了：系统设置 → 隐私与安全性 → 防火墙 → 选项 → 找到 clip-sync 改为允许

macOS 无法打开 clip-sync（"无法验证开发者"）

macOS 默认阻止未签名的二进制。需要允许「任何来源」的应用：

# 允许任何来源
sudo spctl --master-disable

# 添加执行权限
chmod +x clip-sync

# 安全起见，运行后恢复限制
sudo spctl --master-enable

在 系统设置 → 隐私与安全性 底部点击 仍要打开

KDE 剪贴板历史不显示同步的图片

Klipper 默认忽略图片剪贴板条目（IgnoreImages=true），需要手动关闭：

# 关闭忽略图片
kwriteconfig6 --file klipperrc --group General --key IgnoreImages false

# 重新加载配置（无需重启）
qdbus6 org.kde.klipper /klipper org.kde.klipper.klipper.reloadConfig

Plasma 5 用 kwriteconfig5 / qdbus 替代

两边都没有 peer discovered

原因：UDP broadcast / multicast 被路由器屏蔽

排查：

1. 确认两台设备在同一子网（IP 前三段相同）
2. 检查路由器是否开启了 AP 隔离（Client Isolation）
3. 确认未连接访客网络

如果网络层不通，用 -peer 直连：

clip-sync -peer 192.168.1.100:9878

查看详细日志

clip-sync -v

日志	含义
browse: broadcast listener started	UDP 广播监听就绪
browse: multicast joined iface=xxx	组播加入成功
browse: peer discovered addr=...	发现对端设备
peer connected addr=... total=N	TCP 连接建立
clipboard sent bytes=... peers=N	剪贴板已发送
clipboard synced bytes=...	收到并写入剪贴板

图片同步

复制截图或图片时自动检测并同步，无需额外配置。

平台	检测方式	备注
Linux (X11)	xclip -t TARGETS 检查 image/png	需要 xclip（xsel 不支持图片）
Linux (Wayland)	wl-paste --list-types	需要 wl-clipboard
macOS	osascript clipboard info	部分 Chromium 应用复制的图片可能无法检测
Windows	System.Windows.Forms.Clipboard	通过 PowerShell 调用 .NET

超过 -max-size（默认 10MB）的内容会跳过同步并输出警告。

安全性

• 默认模式：所有局域网设备共享同一组，适合家庭 / 个人网络
• 私有组：-p 密码或 new/join token 隔离，只有相同密钥的设备才能解密
• AES-256-GCM 加密传输
• 数据不会离开局域网
• Token 文件权限 0600，存储在 ~/.config/clip-sync/token

License

MIT