NextPaste：跨设备剪切板同步的工程实践

剪切板同步看似是一个简单的问题——不就是复制粘贴吗？但当我们试图在 HarmonyOS Next 与 Windows/Mac/Linux 之间实现实时、可靠、支持大图的剪切板流转时，传统方案的瓶颈迅速暴露：Base64 编码带来的 33% 体积膨胀、WebSocket 帧大小限制导致的 OOM 风险、跨平台剪贴板 API 的兼容性地狱，以及 HarmonyOS 后台保活与回环检测等棘手问题。

为了彻底解决这些问题，我们开发了 NextPaste —— 一个由 ArkTS、Go、Vue3 深度融合的跨设备剪切板同步架构。

这篇文章将为你拆解 NextPaste 背后的工程思考。

0. 全局架构总览

在深入细节之前，我们先通过一张全局架构图来看看 NextPaste 是如何跨越 HarmonyOS 客户端、PC 桌面端与中继服务器的：

flowchart TB
  subgraph HarmonyOS ["HarmonyOS 客户端 (ArkTS)"]
    UI[Index.ets - MVVM]
    ViewModel[ClipboardViewModel]
    Controller[ClipboardController]
    WS[WebSocketManager]
    Monitor[ClipboardMonitor]
    Protocol[BinaryProtocolManager]
    BG[BackgroundTaskManager]
  end

  subgraph PC ["PC 桌面端 (Wails: Go + Vue3)"]
    Vue[Vue3 前端界面]
    App[App.go - Wails 桥接]
    WSServer[WebSocket Server]
    WSClient[WebSocket Client]
    ClipMon[Clipboard Monitor]
    GoProtocol[BinaryProtocolManager]
  end

  subgraph Relay ["中继服务器 (纯 Go)"]
    RelayCore[RelayServer]
    RoomV1[房间 V1 - JSON]
    RoomV2[房间 V2 - 二进制]
  end

  UI --> ViewModel --> Controller
  Controller --> WS --> Protocol
  Controller --> Monitor
  Controller --> BG
  
  HarmonyOS <-->|V1.1 二进制协议| PC
  HarmonyOS <-->|V2 二进制| Relay
  PC <-->|V1/V2| Relay
  
  Vue --> App
  App --> WSServer --> GoProtocol
  App --> WSClient --> GoProtocol
  App --> ClipMon
  
  RelayCore --> RoomV1
  RelayCore --> RoomV2

1. 协议演进：从 JSON Base64 到 NPBP 二进制帧

1.1 V1.0 的困境

最初，我们采用了纯文本 JSON 协议：

{
  "action": "CLIPBOARD_SYNC",
  "data": {
    "type": "image",
    "content": "iVBORw0KGgoAAAANSUhEUgAA..." // Base64 字符串
  }
}

这种设计的致命缺陷在于：

• 体积膨胀 33%：10MB 图片需要传输 13.3MB
• 内存与 CPU 开销：发送端 Binary → Base64，接收端 Base64 → Binary，移动设备易 OOM
• 无法分片：JSON 是整体解析，大图无法流式传输

1.2 V1.1 NPBP 协议设计

我们参考 TCP/IP 头部设计，定义了 33 字节固定包头 + 变长载荷 的二进制帧结构：

block-beta
  columns 16
  
  block:header:16
    columns 16
    n["Magic (2)"]
    v["Ver"]
    t["Type"]
    f["Flags"]
    r["Reserved"]
    mid["MsgID (4)"]
    seq["Seq (4)"]
    sid["Sender UUID (16)"]
    plen["PayloadLen (4)"]
  end
  
  block:payload:16
    columns 16
    p["Payload Data..."]
  end

关键字段：

• Magic (0x4E50)：ASCII 'NP'，协议识别符
• Type：消息类型（0x0 心跳 / 0x1 握手 / 0x2 文本 / 0x3 图片 / 0x4 文件）
• Flags：标志位（MF=有后续分片, HAS_META=包含元数据）

1.3 智能分片传输

图片传输采用首帧携带元数据 + 后续分片的模式：

// 首帧结构
[MetaLen(2字节)] + [元数据 JSON] + [图片二进制片段1]

// 后续帧
[图片二进制片段N]

sequenceDiagram
  participant Sender as 发送端
  participant WS as WebSocket
  participant Receiver as 接收端
  
  Sender->>WS: 首帧 [HAS_META|MF] + 元数据 + 32KB 数据
  WS->>Receiver: 转发首帧
  
  loop 64KB 分片
    Sender->>WS: 中间帧 [MF]
    WS->>Receiver: 转发中间帧
  end
  
  Sender->>WS: 尾帧 [无标志]
  WS->>Receiver: 转发尾帧
  Receiver->>Receiver: 重组完整数据

2. 回环检测：避免"自己给自己发消息"

当用户复制内容后，如果同步回来又触发写入，就会形成无限循环。我们在协议层引入了 16 字节设备 UUID：

sequenceDiagram
  participant DeviceA as 设备 A
  participant Server as 服务器
  participant DeviceB as 设备 B
  
  DeviceA->>Server: 二进制帧 [SenderUUID: A的UUID]
  Server->>DeviceB: 转发 [SenderUUID: A的UUID]
  Server->>DeviceA: 转发 [SenderUUID: A的UUID]
  DeviceA->>DeviceA: 检测到 SenderUUID == 本地 UUID
  DeviceA->>DeviceA: 丢弃消息，不写入剪贴板

// ArkTS 端回环检测
private static isLoopback(senderBytes: Uint8Array): boolean {
  const local = BinaryProtocolManager.DEVICE_UUID_BYTES;
  for (let i = 0; i < 16; i++) {
    if (senderBytes[i] !== local[i]) {
      return false;
    }
  }
  return true;
}

3. Windows 剪贴板兼容性地狱

Windows 端的图片读取是一个著名的兼容性陷阱。微信截图、Snipaste 等工具写入剪贴板的格式各不相同。

3.1 读取策略扩展

我们对 golang.design/x/clipboard 进行了 fork，实现了多格式优先级读取：

// 读取优先级
CF_DIBV5 -> CF_DIB -> 注册格式 PNG -> CF_BITMAP (HBITMAP, GDI 转 PNG)

flowchart TD
  A[检测剪贴板图片] --> B{CF_DIBV5?}
  B -->|成功| Z[返回数据]
  B -->|失败| C{CF_DIB?}
  C -->|成功| Z
  C -->|失败| D{注册格式 PNG?}
  D -->|成功| Z
  D -->|失败| E{CF_BITMAP?}
  E -->|成功| F[GDI 转换为 PNG]
  F --> Z
  E -->|失败| G[读取失败]

3.2 Watch 行为修复

原版 clipboard.Watch 存在 goroutine/ticker 泄漏问题：

// 修复：确保 ticker.Stop() 被调用
func watch() {
  ticker := time.NewTicker(interval)
  defer ticker.Stop() // 关键！
  
  for {
    select {
    case <-ctx.Done():
      return
    case <-ticker.C:
      // 即使读取失败，也要推进 sequence number
      // 避免同一次变更被重复触发
    }
  }
}

4. HarmonyOS 后台保活：长时任务的艺术

HarmonyOS 对后台应用有严格的限制，但我们找到了合法的保活方案。

4.1 长时任务申请

// 申请 dataTransfer 类型的长时任务
const bgModes: Array<string> = ['dataTransfer'];
const result = await backgroundTaskManager.startBackgroundRunning(
  this.context,
  bgModes,
  this.wantAgentInstance
);

4.2 进度通知保活

利用实况窗通知定期更新进度，防止任务被系统杀掉：

// 使用随机间隔（15-60秒），避免固定模式
private getRandomInterval(): number {
  return Math.floor(Math.random() * (60000 - 15000 + 1)) + 15000;
}

// 更新进度通知
const downloadTemplate = {
  name: 'downloadTemplate',
  data: {
    title: 'NextPaste Syncing',
    fileName: 'clipboard_sync',
    progressValue: this.currentProgress, // 30-95 随机值
  }
};

5. MVVM 架构：ArkTS 端的优雅分层

HarmonyOS 客户端严格遵循 MVVM 模式：

flowchart TB
  subgraph View ["View 层"]
    Index[Index.ets]
    Components[UI 组件]
  end
  
  subgraph ViewModel ["ViewModel 层"]
    VM[ClipboardViewModel]
    Controller[ClipboardController]
  end
  
  subgraph Model ["Model 层"]
    WS[WebSocketManager]
    Monitor[ClipboardMonitor]
    Protocol[BinaryProtocolManager]
    BG[BackgroundTaskManager]
  end
  
  Index --> VM
  VM --> Controller
  Controller --> WS
  Controller --> Monitor
  Controller --> BG
  WS --> Protocol
  Monitor --> Protocol

职责分离：

• ViewModel：管理 UI 状态（连接状态、日志列表、配置）
• Controller：协调各服务模块（WebSocket、剪贴板、后台任务）
• Service：具体业务逻辑（协议封装、监听、保活）

6. 中继服务器：突破局域网限制

当设备处于不同网络时，需要一个公网中继服务器来转发消息。

6.1 房间隔离架构

flowchart TB
  subgraph RelayServer ["RelayServer"]
    RM[RoomManager]
    
    subgraph V1Rooms ["V1 房间"]
      R1A[team-dev V1]
      R1B[personal V1]
    end
    
    subgraph V2Rooms ["V2 房间"]
      R2A[team-dev V2]
      R2B[personal V2]
    end
  end
  
  ClientA[客户端 A - V2] --> R2A
  ClientB[客户端 B - V2] --> R2A
  ClientC[客户端 C - V1] --> R1A
  
  R2A -.->|物理隔离| R1A

关键设计：

• 版本隔离：V1 和 V2 即使 roomID 相同也是完全独立的房间
• 自动清理：房间为空时自动删除
• 纯转发：不处理剪贴板数据，保护隐私

6.2 高并发设计

// 每个房间独立的读写协程
func (s *RelayServer) serveWS(w http.ResponseWriter, r *http.Request) {
  room := s.getOrCreateRoom(roomID, isV2)
  
  go s.readPump(client, room)   // 读取并广播
  go s.writePump(client, room)  // 发送队列消费
}

结语

开发 NextPaste 的过程，是对 HarmonyOS 后台机制、Windows 剪贴板 API、WebSocket 二进制协议以及跨平台架构设计的一次深度实践。

我们创建这个项目的初衷非常纯粹：让剪切板真正实现跨设备无缝流转。我们不满足于仅仅实现一个"能同步文本"的工具，我们希望它能够在传输效率、平台兼容性、后台稳定性等方面都达到商业级水准。

目前，NextPaste 仍在持续迭代中。开源不仅是共享代码，更是共享思考。如果你在工程实践中对跨设备同步有任何想法，欢迎在 GitHub 上与我们探讨。