OpenPencil实时协作完全指南：P2P直连、公共中继、区域Hub与配对码加入详解
【免费下载链接】openpencilThe world's first open-source AI-native vector design tool and the first to feature concurrent Agent Teams. Design-as-Code. Turn prompts into UI directly on the live canvas. A modern alternative to Pencil.项目地址: https://gitcode.com/gh_mirrors/op/openpencil
OpenPencil 是一款开源 AI 原生的矢量设计工具，它的实时协作功能支持 P2P 直连、公共中继与区域 Hub 三种连接方式，只需一个 10 位配对码即可跨设备加入同一份设计稿，实时看到队友的远程光标。本文将用简单语言讲清楚每种方式适合什么场景、如何一步步加入协作，以及背后的安全机制。
🎯 为什么需要 OpenPencil 实时协作？
传统设计工具里，"多人一起画"往往意味着导出文件、来回传版本。OpenPencil 的协作让多人同时在同一张活画布上工作：
- 🖱️ 实时远程光标，能看到队友正在编辑哪个元素
- ✍️ 跨账号协作，访客（Guest）与所有者（Owner）角色分明
- ⚖️ 冲突面板：逐条展示每次编辑，还能回放被丢弃的改动
- 🔑配对码加入——局域网场景下甚至不需要注册账号
相关能力由协作协议库 crates/op-collab/（开放的线格式、规范哈希与精确应用逻辑）和传输层 crates/op-collab-transport/（原生加密传输、局域网发现）实现。
📡 三种连接方式：一图看懂
OpenPencil 提供三条链路，网络环境越差，越适合往右走：
| 方式 | 适用场景 | 是否需要公网 | 特点 |
|---|---|---|---|
| P2P 直连 | 同一局域网（办公室、家里） | 否 | 延迟最低，数据只在两人之间走 |
| 公共中继 | 跨城市、跨 NAT | 是 | 中继只转发密文，看不到文档内容 |
| 区域 Hub | 国内 / 全球两套基础设施 | 是 | 就近接入，稳定性更好 |
1️⃣ P2P 直连：局域网里的最快通道
在同一个局域网内，OpenPencil 通过 mDNS（Bonjour）自动发现彼此，也可以手动输入对方 IP 直连。文档字节直接在两台设备之间传输，第三方完全不参与。
- 优点：延迟最低、不依赖任何服务器
- 限制：只能覆盖局域网；mDNS 发现信息是"临时身份证"，不含账号、文档标题等隐私字段
- 局域网会话无需账号即可体验协作
2️⃣ 公共中继：跨 NAT 的兜底链路
不在同一局域网时，双方通过一条 WSS（加密 WebSocket）中继链路完成握手与数据转发。关键点：
- 中继是一个盲转发服务——它只搬运加密字节流，永远收不到明文文档操作
- 真正的加密在两端之间用 Noise XX（X25519 + ChaChaPoly + BLAKE2s）完成，即端到端加密
- 生产模式下中继会执行签名票据、签名定位器、区域、所有者密钥与质询绑定证明的多重校验
部署细节可参考 deploy/collab-relay/README.md。
3️⃣ 区域 Hub：国内与全球双基础设施
OpenPencil 内置国内（CN）与全球（Global）两套区域 Hub，各自拥有独立的定位服务（Locator）与中继服务：
- 所有者发起会话时会选定一个"主页区域"，并写入邀请的签名信息中
- 访客始终按邀请里签名的区域加入，物理位置不会改变区域归属
- 即使海外用户加入 CN 区域会话，也会经由专用 L4 入口固定回传至同一套 CN 中继，而不是"就近改道"
- 区域选择影响的是可达性与延迟，而不是信任关系——两套 Hub 服务的是同一份离线签名文档，用同一组内嵌信任根验证
这套设计的完整契约见 docs/security/p2p-collaboration-threat-model.md，其中公开说明了协议、信任边界与威胁模型。
🔑 用配对码加入：三步上手
生产会话唯一对外暴露的加入入口，就是一段10 字符的区域标记配对码：
- 所有者发起协作会话，OpenPencil 生成 10 位配对码（第 1 位字符表示中继区域，其余 9 位为随机熵）
- 访客在 OpenPencil 中输入配对码，客户端据此从对应的区域控制面领取密封的完整邀请
- 双方完成加密握手后，访客会先看到经过验证的所有者身份确认页——确认无误，才会在本地应用任何文档数据
几个值得注意的设计：
- 配对码的配对窗口最长 1 小时，过期即失效
- 完整邀请是加密密封存储的，持有存储数据也反推不出配对码
- 配对码只是"进入配对流程的能力"，本身不等于准入——所有者仍需逐一审批每位访客
- 中继模式下访客可看到自己走的连接路径，但不会拿到所有者的邀请码
🔒 安全机制速览：中继看不到你的设计
很多用户担心"数据过服务器会不会泄露"。OpenPencil 的答案是：
- ✅中继只转发，不解密：隧道内是逐字节桥接的握手与加密记录，配对后的帧按不透明二进制转发
- ✅票据防重放：协作票据绑定该连接实际观察到的 Noise 静态密钥，被盗票据只能配合绑定的私钥使用，且有效期最多 15 分钟
- ✅拒绝即无副作用：畸形、超大、过期、重放的操作会被整体拒绝，不会留下半个改动的文档
- ✅密钥不落地：设备静态密钥存放在 macOS 钥匙串 / Windows 凭据管理器 / Linux Secret Service，内存中零化清理
完整资产清单、威胁-控制矩阵与残余风险，都写在公开的 威胁模型文档 里——安全协议不依赖实现保密。
📚 相关源码与文档路径
- 协作协议核心（线格式、哈希、精确应用）：crates/op-collab/
- 加密传输、局域网发现与连接限额：crates/op-collab-transport/
- 票据验证与认证桥接：crates/op-auth-bridge/
- 中继服务端与部署文档：deploy/collab-relay/
- 定位服务（Locator）部署：deploy/collab-relay-locator/
- 两进程认证协作冒烟测试：crates/op-collab-smoke/
- P2P 协作威胁模型：docs/security/p2p-collaboration-threat-model.md
❓ 常见问题
问：局域网协作一定要登录账号吗？不需要。局域网会话可以无账号直接体验；中继与跨区域会话则需要登录以获取短期协作票据。
问：配对码给别人后，对方能直接看到我文档吗？不能。配对码只让对方进入配对流程，所有者审批 + 访客确认所有者身份两道人工关卡通过后，才开始同步文档。
问：我的设计稿会被中继服务器保存吗？不会。中继按契约不解密、不持久化文档帧；它只能观察到接入与路由层级的元数据。
问：跨大陆协作会卡吗？区域 Hub 的意义正在于此：访客按邀请签名区域接入对应 Hub，海外用户通过固定回传通道收敛到同一套区域服务，避免跨区混用端点带来的失败。
✅ 小结
OpenPencil 实时协作把"和谁在哪个网络环境里"抽象成三个选择：局域网就 P2P 直连，跨网络走公共中继，追求稳定就用区域 Hub——而无论走哪条路，加入方式都统一为一个 10 位配对码，文档内容始终受端到端加密保护。对于想在不牺牲设计稿隐私的前提下体验多人协同的设计团队，这是一套协议完全开源、可审查的协作方案。
【免费下载链接】openpencilThe world's first open-source AI-native vector design tool and the first to feature concurrent Agent Teams. Design-as-Code. Turn prompts into UI directly on the live canvas. A modern alternative to Pencil.项目地址: https://gitcode.com/gh_mirrors/op/openpencil
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
