Skip to content

PasteFerry (隔空贴): clipboard and file sync across macOS, Windows and Linux. Direct-first, end-to-end encrypted. Optional official access: no server to host. Independent self-hosting remains available.

45.1 KB
Raw Blame

隔空贴:好友——加好友,给好友发文件和图片

定稿 · 2026-10-26 · 决定见第 3 节,尚未实现 · 已按 2.5.3 的代码核对

  • 在 隔空传送(2.5.0)上扩展:以前只能发给自己配对的电脑,这次加上「别人」。
  • 不做聊天。 只发文件和图片,可以附一句备注;备注附在文件上,没有文件就发不了,长度有上限;没有对话窗口,只有传输记录(第 6.5 节)。
  • 插件、插件市场另行讨论,不在本稿范围内。
  • 用词:界面上的「官方服务」一律改叫 「服务」(第 12 节)。本稿里的「服务」就是指它;用户自己部署的叫「自建服务器」。

1. 要做的事

你在用隔空贴,你的朋友也在用,但你们是两个人、各有各的电脑:

  1. 你的一台电脑和他的一台电脑加一次好友,之后互相发文件不用配对。好友按电脑算:在哪台电脑上加的,就只在那台电脑上有效(第 4 节)。
  2. 给好友发文件、图片,可以附一句备注(最多 200 字),比如「合同第 3 页要签字」。备注只能附在文件上,不能单独发。
  3. 能不能发由接收方决定。隔空传送页底部和隔空投送一样有一行「允许这些人给我发文件」:
    • 均不允许:只有自己配对的电脑能发。
    • 仅限好友(默认):好友能发。
    • 所有人:同一局域网里不认识的人也能发,10 分钟后自动回到「仅限好友」。
  4. 好友和陌生人发来的东西,接收方每次都要点「接受」。可以对某个好友设成「自动接收」,陌生人不行。
  5. 怎么连:
    • 在同一局域网,直接连;
    • 不在同一局域网时,开了「服务」就先尝试直连,直连不了再经服务中转;
    • 连不上时,提示双方打开「服务」。
  6. 好友碰不到你的剪贴板、复制记录、收藏,也不会和你的电脑一直连着。

2. 三种关系

我的设备(配对,现有) 好友(新) 附近的人(新,「所有人」模式)
是谁 自己的电脑 别人的一台电脑 同一局域网里不认识的电脑
怎么建立 配对码 / 搜索附近设备,核对指纹 好友码,双方确认(第 5 节) 不用建立
剪贴板同步 ✓ ✗ ✗
发文件、图片 ✓ 自动接收(受现有「接收文件」开关控制) ✓ 接收方选了「仅限好友」或「所有人」;每次确认,可设自动接收 ✓ 接收方选了「所有人」;每次确认
备注 — ✓ 附在文件上 ✗
连接 常连 要发的时候才连,空闲 2 分钟断开 同左,只在局域网
跨网络 ✓ ✓ 双方都打开「服务」,或者用同一台自建服务器(第 9 节) ✗
保存在哪 设备页 本机的好友列表 不保存

「允许这些人给我发文件」只管别人发来的。自己设备之间的发送,仍由设置里现有的「接收文件」开关控制。

3. 已定的决定

# 问题 决定
1 接收设置的默认值 仅限好友。新装和升级的用户都是这一档;升级时还没有好友,所以不会有人突然能给你发文件
2 好友发来的文件是否每次确认 每次确认,可以对单个好友打开「自动接收」;陌生人永远确认
3 「所有人」的范围 只限同一局域网,10 分钟后自动回到「仅限好友」
4 不在同一局域网、又不在同一服务上 只加提示,请双方打开「服务」。不另开「好友通道」,不改服务模式的规则(第 9.2 节)
5 聊天 不做。只发文件和图片,附可选备注:附在文件上、没有文件发不了、最多 200 字;没有对话界面(第 6.5 节)
6 跨网络给好友发 可以,经服务直连或中转,和自己设备之间的隔空传送一样
7 「官方服务」的叫法 界面上改叫 「服务」
8 好友按人还是按电脑 按电脑。配对过的电脑不合并成一个人,好友只在加好友的那台电脑上(第 4 节)
9 加好友时是否强制核对安全码 不强制,提供展开核对;配对设备照旧强制核对指纹
10 图片要不要确认 和文件一样确认。不做「图片直接显示」:那是聊天的做法
11 头像 一期就做:默认头像加自定义头像,按电脑设置(第 4.4 节)
12 名字 简体「好友」、繁体「好友」、英文 "Contacts"、日文「連絡先」

4. 好友按电脑算

4.1 为什么不按人

按人算的话,要把已配对的电脑合并成「同一个人」,再靠互相签发的证明让好友认出你的其他电脑。问题是:

  • 配对不等于同一个人:有人把自己的电脑和家人、同事的电脑配对来共享剪贴板。合并以后,家人的电脑会以你的名义出现在你好友那里。
  • 合并 ID、同人证明、取消配对时的撤销,整套机制复杂,出错时直接影响信任。

按电脑算,以上全部不需要。

4.2 具体规则

  • 好友就是对方的一台电脑:设备 ID 加公钥,和配对设备一样的身份,只是角色不同。
  • 你在 Mac 上加了小明的 MacBook Air,只有这两台之间是好友。你的 Windows 想给他发,要在 Windows 上再加一次;他用台式机也一样。
  • 小明有两台电脑都加了你时,好友列表里显示两条:「小明 · MacBook Air」「小明 · Win 台式机」。
  • 取消配对、重装系统都不影响别的电脑上的好友;重装后设备密钥变了,对方要重新加。
  • 已经配对的电脑不能再加为好友。

4.3 我的名字

  • 好友看到的是显示名加电脑名,比如「光光 · MacBook Air」。
  • 显示名在这台电脑的隔空传送页顶部设置,默认取系统的用户全名(macOS NSFullUserName、Windows 的显示名、Linux GECOS)。每台电脑各自设置,不同步。

4.4 头像

  • 默认头像:圆形色块加显示名的第一个字(英文取首字母大写),颜色由设备 ID 算出,固定不变。没设头像的人、陌生电脑都用它。
  • 自定义头像:
    • 在隔空传送页顶部点自己的头像,弹出菜单「选择图片…」「粘贴图片」「恢复默认头像」;也可以把图片拖到头像上。
    • 选好后进入裁剪:方形取景框,可拖动、缩放,预览显示成圆形。
    • 保存时由后台服务统一处理成 256×256 的 JPEG,最大 64 KB;去掉 EXIF 等元数据,免得把拍摄地点发给别人。
    • 和显示名一样按电脑设置,不同步。
  点自己的头像:
  ┌──────────────────┐
  │ 选择图片…          │
  │ 粘贴图片           │
  │ 恢复默认头像        │
  └──────────────────┘

  选好图片后裁剪:
┌──────────────── 设置头像 ────────────────┐
│   ┌──────────────────────────┐           │
│   │      ╭──────────╮        │           │
│   │      │  (图片)   │ ← 拖动  │   预览     │
│   │      ╰──────────╯        │   (光)     │
│   └──────────────────────────┘           │
│   缩放  ─────●──────                       │
│                     [ 取消 ]  [ 完成 ]     │
└──────────────────────────────────────────┘
  • 怎么给到好友:
    • 名片里只带头像的哈希。对方发现哈希变了,才在 P2P 连接上要一次头像数据(AvatarRequest / AvatarData)。
    • 收到后由后台服务用 Go 重新解码、重新编码,再存进本机;界面只显示重新编码过的文件。
    • 拿到之前、或者头像数据有问题时,显示对方的默认头像。
  • 出现的地方:雷达、好友列表、发送窗口标题、加好友的确认框、接收弹窗、传输记录。系统通知能换图标的平台(Windows 的 toast、Linux 的通知)用对方头像;macOS 的通知图标固定是应用图标,换不了。
  • 陌生人(「所有人」模式)不交换头像,一律显示默认头像,避免被用来发不当图片。

4.5 以后要不要按人

先按电脑做。如果用户普遍有多台电脑、嫌每台都要加一次,二期可以加一个明确的选项:「把这台电脑上的好友同步到我的其他电脑」,由用户在每台电脑上主动打开,而不是根据配对关系自动合并。到时再加一个功能标记(第 10.2 节),不影响一期的数据。

5. 加好友

5.1 好友码

复用现有配对码的通道(服务器的配对码代理加局域网),服务器不用改:

  1. 光光在隔空传送页点「好友 → 添加好友」,界面显示好友码 F-7K3QXM,5 分钟内有效。下面一行说明:「把这个码发给好友,对方在隔空贴里输入后,你们就成为好友」。
  2. 小明点「添加好友」,输入这个码。
  3. 两边交换公钥(和配对完全一样),建立 P2P 连接。这条连接的角色是「待定好友」,只能交换名片、头像和好友请求。
  4. 两边各弹一个确认框:头像加「添加 小明 · MacBook Air 为好友?」,按钮是「添加」「取消」。两边都点「添加」才算加上。
  5. 确认框里有一行可展开的「核对安全码」,显示 6 个数字,面对面时可以对一下,防止服务器调包;不强制。
显示好友码的一方:
┌──────────────── 添加好友 ────────────────┐
│                                          │
│              F - 7K3QXM                  │
│              4:52 后失效                   │
│                                          │
│   把这个码发给好友,对方在隔空贴里输入后,     │
│   你们就成为好友。                          │
│                                          │
│   ─────────── 或者 ───────────            │
│   输入对方的好友码:[            ] [添加]   │
│                                          │
│                                 [ 关闭 ]  │
└──────────────────────────────────────────┘

两边各自确认:
┌──────────────── 添加好友 ────────────────┐
│                                          │
│       (小)  添加 小明 · MacBook Air        │
│             为好友?                       │
│                                          │
│   ▸ 核对安全码(可选)                      │
│       482 917     ← 展开后显示,            │
│                     两边一样就没被调包       │
│                                          │
│                     [ 取消 ]  [ 添加 ]     │
└──────────────────────────────────────────┘

好友码要靠服务器或局域网交换:两边在同一局域网,或者都打开了「服务」(或用同一台自建服务器)。都不满足时,「添加好友」窗口提示:「你们不在同一个局域网,双方都打开『服务』后才能添加」,并给出「打开服务」按钮。

┌──────────────── 添加好友 ────────────────┐
│  ⚠ 你们不在同一个局域网,双方都打开          │
│    「服务」后才能添加。                      │
│                                          │
│                [ 取消 ]  [ 打开服务… ]     │
└──────────────────────────────────────────┘

好友码与配对码互不混淆:

  • 好友码是 F 加上服务器(或局域网)签发的 6 位码,输入时连字符可有可无。
  • 新版本:在「添加设备」里输入了好友码,自动转到加好友的流程;在「添加好友」里输入了 6 位配对码,提示「这是配对码,请到『设备 → 添加设备』」。
  • 旧版本在「添加设备」里输入好友码:7 位码在服务器上查不到,直接报「配对码无效」,不会被误配成自己的设备。
  • 发起方在加密通道里确认对方声明了 friends_v1 才继续,否则提示「对方需要更新到 2.6.0 或更高」(第 10 节)。

5.2 删除与屏蔽

  • 删除好友:双向生效。发一条签名的通知,对方也删掉你;对方不在线就在本机排队,下次连上时补发,最多排 30 天。传输记录保留在本机,可以手动清除。
  • 屏蔽:在「所有人」模式下拒绝过的陌生设备,可以选「屏蔽这台设备」。之后它的请求直接拒绝,不再提示。

5.3 二期

  • 附近添加:「搜索附近设备」的雷达上增加「附近的人」。
  • 好友链接、二维码:长期有效,对方离线时等他上线再把请求送过去。

6. 给好友发文件和图片

6.1 发送

沿用现有的隔空传送:

  • 点雷达上的好友,打开发送窗口(和发给自己设备的是同一个窗口),标题是对方头像和「发送给 小明 · MacBook Air」,下面一行是连接方式。
  • 或者直接把文件拖到好友头像上。
  • 发送窗口里多一个备注输入框(第 6.2 节)。拖到头像上直接发时不带备注;想写备注就点头像,在窗口里发。
  • 支持拖入、「选择文件…」「选择文件夹…」,以及粘贴:在发送窗口里按 ⌘V / Ctrl+V,剪贴板里的图片或文件直接加进来(截图后发给好友最顺手)。剪贴板里只有文字时,粘贴到备注框,不会把文字当成要发送的内容。
  • 发出后进入等待:「等待 小明 接受…」。
    • 对方接受:开始传输,和现在一样。
    • 对方拒绝:「小明 拒绝了」。
    • 60 秒没有回应:「小明 没有回应」,带「再发一次」。
    • 对方设了自动接收你:跳过等待。
  • 对方不在线就不能发,和现在的隔空传送一样,不排队。
点好友头像,打开发送窗口:
┌──────────────────────────────────────────┐
│ (小)  发送给 小明 · MacBook Air             │
│       局域网                               │
├──────────────────────────────────────────┤
│                                          │
│  ┌ ┄ ┄ ┄ ┄ ┄ ┄ ┄ ┄ ┄ ┄ ┄ ┄ ┄ ┄ ┄ ┄ ┐   │
│  ┆                                  ┆   │
│  ┆     把文件或图片拖到这里,或 ⌘V 粘贴   ┆   │
│  ┆                                  ┆   │
│  └ ┄ ┄ ┄ ┄ ┄ ┄ ┄ ┄ ┄ ┄ ┄ ┄ ┄ ┄ ┄ ┄ ┘   │
│     [选择文件…]  [选择文件夹…]              │
│                                          │
│  备注(可选)                               │
│  [ 先选择要发送的文件               ] 0/200 │  ← 没选文件时不能用
│                                          │
│                              [ 发送 ]     │  ← 没选文件时变灰
└──────────────────────────────────────────┘

选好文件后:
┌──────────────────────────────────────────┐
│ (小)  发送给 小明 · MacBook Air             │
│       局域网                               │
├──────────────────────────────────────────┤
│  ▤ 合同扫描件.pdf            2.3 MB    ✕   │
│  [缩略图] 截图 2026-10-26.png  860 KB   ✕   │
│  ▣ 附件                      15.2 MB   ✕   │
│  ┄ 继续拖入或 ⌘V 粘贴 ┄                     │
│                                          │
│  备注(可选)                               │
│  [ 合同第 3 页要签字                ] 9/200 │
│                                          │
│                  共 3 项 · 18.4 MB [ 发送 ] │
└──────────────────────────────────────────┘

发出后:
├──────────────────────────────────────────┤
│  ⏳ 等待 小明 接受…                 [取消]  │
│     合同扫描件.pdf 等 3 项 · 18.4 MB        │
│     备注:合同第 3 页要签字                 │
├──────────────────────────────────────────┤

  对方接受后  →  ━━━━━━━━━━━━░░░░░  64% · 12 MB/s · 剩 1 秒
  对方拒绝    →  ✕ 小明 拒绝了                     [再发一次]
  60 秒没回应 →  小明 没有回应                     [再发一次]

发送窗口里的缩略图由发送方本机生成,只在本机显示。

6.2 备注

  • 可选,最多 200 个字符,单行(不能换行)。
  • 必须附在至少一个文件或图片上:没有选文件时,备注框和「发送」按钮都不能用,不能单独发。
  • 发送前可以编辑;发出后不能修改、不能撤回。
  • 接收方在接收弹窗、系统通知、传输记录里看到它。
  • 没有「回复」:接收方要回话,只能也发一个文件,或者用别的方式联系。这是有意的,见第 6.5 节。
  • 只当纯文本显示,不解析链接、HTML 或 Markdown;网址显示为普通文字,不能点、不抓预览。

6.3 图片

  • 图片就是文件,规则完全相同:接收方确认、存到保存位置、进传输记录。
  • 传完以后,传输记录里图片那一行显示缩略图。缩略图由接收方的后台服务用 Go 的解码器(内存安全)重新编码生成,界面只显示这张缩略图,不直接解码收到的原文件。沿用 internal/imagepreview。HEIC 在 Windows、Linux 上也能显示。
  • 点缩略图用系统默认程序打开原图。

6.4 好友的传输记录

  • 隔空传送页「收到的 / 发出的」列表照常显示好友的传输,行上带对方头像和「小明 · MacBook Air」,有备注时第二行显示备注。
  • 在好友列表里点一个好友,看和他之间的传输记录:按时间倒序的列表,每行一次传输(方向、文件、大小、备注、状态),不排成左右两边的对话样式。
┌───────────── 和 小明 · MacBook Air 的传输 ─────────────┐
│ (小)  小明 · MacBook Air · 局域网             [发送…]   │
├───────────────────────────────────────────────────────┤
│ ↑ 今天 14:02   合同扫描件.pdf 等 3 项 · 18.4 MB   已送达  │
│                备注:合同第 3 页要签字                    │
├───────────────────────────────────────────────────────┤
│ ↓ 今天 11:30   [缩略图] 报价单.png · 640 KB              │
│                备注:看下这个价格         在访达中显示     │
├───────────────────────────────────────────────────────┤
│ ↑ 昨天 18:12   项目资料 · 1.2 GB                 被拒绝   │
├───────────────────────────────────────────────────────┤
│ ↓ 10月23日     演示.mov · 320 MB         在访达中显示     │
└───────────────────────────────────────────────────────┘
  • 记录保留规则和隔空传送的列表一样(30 天或最近 500 条)。

6.5 为什么不做聊天

  • 国内对「即时通讯服务」有实名、内容管理等要求,针对的是提供服务的网络运营者。好友之间如果能自由地一来一回发文字,经过「服务」找人和中转,隔空贴的服务就成了即时通讯服务的一部分。
  • 只发文件、备注附在文件上、没有对话界面,隔空贴仍然是传文件的工具,和自己设备之间的隔空传送性质相近:每次要接收方确认,有额度限制,不公开发布。
  • 要守住的界线,以后改功能时对照:
    • 备注不能单独发,长度有上限,不能有「回复」按钮,不能显示成对话;
    • 不加已读、输入中、表情面板这类聊天才有的东西;
    • 不做群发、群组;
    • 中转始终只在两台互相授权的设备之间转发。
  • 文案口径:写「给好友发文件」,不写「聊天」「端到端加密,谁也看不到」「绝对安全」。
  • 这只是降低风险的产品取舍,不是法律意见。准备收费、做手机版或注册公司前,请律师看一次。

7. 接收

  • 别人要给你发东西时弹窗。主窗口开着时在窗口里弹,没开时用系统通知加按钮:
主窗口开着时:
┌──────────────────────────────────────────┐
│ (光)  光光 · MacBook Air                    │
│       想发给你 3 个文件                      │
│                                          │
│   合同扫描件.pdf 等 · 18.4 MB               │
│   备注:合同第 3 页要签字                    │
│                                          │
│   □ 以后自动接收这台电脑的文件                │  ← 陌生人没有这一行
│                                          │
│                     [ 拒绝 ]  [ 接受 ]     │
│                          59 秒后自动拒绝    │
└──────────────────────────────────────────┘

主窗口没开时,用系统通知:
┌──────────────────────────────────────┐
│ 隔空贴                                 │
│ 光光 想发给你 3 个文件 · 18.4 MB        │
│ 备注:合同第 3 页要签字                  │
│              [ 拒绝 ]  [ 接受 ]        │
└──────────────────────────────────────┘

陌生人(「所有人」模式)发来的弹窗用默认头像。

  • 接受后和现在一样:存到保存位置,进「收到的」列表,收完弹通知(带备注)。
  • 60 秒不处理算拒绝,通知换成「已忽略 光光 发来的文件」。
  • 防打扰:同一台电脑 1 分钟内被拒绝 3 次,之后 10 分钟内它的请求自动拒绝,不再弹出。
  • 接收设置是开关,不是提示:选「均不允许」时,好友的请求直接回 not_allowed,不弹窗;对方雷达上显示「不接收文件」。
  • 在 Mac 上,好友和陌生人发来的文件一律加「来自网络」的隔离标记(com.apple.quarantine),和隔空投送一样,打开可执行文件时系统会提醒。自己设备发来的保持现状。

8. 隔空传送页

┌──────────────────────────────────────────────────────┐
│ (光)  显示为                           好友 3    +   │  ← 好友列表 / 添加好友
│       光光 ✎                                          │
├──────────────────────────────────────────────────────┤
│                                                      │
│            (小)                        (阿)          │  ← 好友在最外圈
│            小明                        阿杰          │     显示头像
│            局域网                      中转          │
│                    (▭)        (▥)                    │  ← 我的设备,不变
│                    MacBook    台式机                  │
│                         (◉)                          │
│                         本机                          │
│                                                      │
│            (王)                                       │
│            王姐                                       │
│            离线                  ← 变淡               │
│                                                      │
├──────────────────────────────────────────────────────┤
│  收到的 · 发出的                          全部清除    │
│  ↓ (小) 合同扫描件.pdf 等 3 项 · 18.4 MB              │
│        小明 · MacBook Air · 14:02                     │
│        备注:合同第 3 页要签字           在访达中显示  │
│  ↓ [缩略图] IMG_2041.HEIC · 2.1 MB                    │
│        阿杰 · Win 台式机 · 昨天           在访达中显示  │
├──────────────────────────────────────────────────────┤
│  允许这些人给我发文件:仅限好友 ⌄                       │
└──────────────────────────────────────────────────────┘
  • 顶部左边是这台电脑的头像和显示名:点名字可以改名,点头像可以换头像(第 4.4 节)。
  • 「所有人」打开时,那一行变成「所有人 · 还剩 8 分钟」。到时间自动回到「仅限好友」,并提示一句。
  • 雷达上的好友:每个好友一个圆,显示头像,名字是「小明」,下面一行小字是状态:
状态 小字 能不能发
在线,开放接收 局域网 / 直连 / 中转 能
在线,对方选了「均不允许」 不接收文件 不能,变淡
不在线 离线 不能,变淡
正在连接、还没拿到对方的功能声明 连接中… 点了先连,连上再判断
对方版本太旧 需要更新 不能
不在同一局域网,也不在同一服务上 需要打开服务 不能,点了显示第 9.2 节的提示
  • 「所有人」模式下,附近开着「所有人」的陌生电脑也出现在雷达上,显示显示名和「附近」,图标用虚线圈,和好友区分开。
  • 好友列表窗口:每行有头像、「显示名 · 电脑名」、在线状态、最近一次传输的时间;行尾是「发送」;右键菜单:发送、查看传输记录、自动接收他的文件、删除好友。不在侧边栏新增入口。
┌─────────────────── 好友 ───────────────────┐
│                               [+ 添加好友] │
├────────────────────────────────────────────┤
│ (小)  小明 · MacBook Air          [发送]    │
│       局域网 · 今天 14:02 传过                │
├────────────────────────────────────────────┤
│ (阿)  阿杰 · Win 台式机            [发送]    │
│       中转 · 昨天传过                        │
├────────────────────────────────────────────┤
│ (王)  王姐 · MacBook Pro           [发送]    │  ← 变淡
│       离线 · 10月20日传过                    │
└────────────────────────────────────────────┘

  右键某一行:
  ┌──────────────────────┐
  │ 发送…                 │
  │ 查看传输记录           │
  │ ✓ 自动接收他的文件      │
  │ ──────────────────── │
  │ 删除好友               │
  └──────────────────────┘

9. 网络:好友怎么连上

9.1 连接顺序

好友之间的连接和自己设备之间的完全一样,只是按需建立:

  1. 同一局域网:靠 mDNS 发现,直接连。好友按现有的当日令牌认出来,算法不变。不需要服务。
  2. 不在同一局域网,双方都打开了服务(或者用同一台自建服务器):经服务器交换信令,先尝试打洞直连。
  3. 直连不了:经服务中转。中转受每天 100 MB、约 0.25 MB/s 的额度限制,大文件会慢;沿用现有的中转确认。
  4. 中转期间打洞成功了,就切到直连。
  • 服务器不用改:客户端把好友的设备 ID 也放进 Hello 的关注列表,服务器就会推送它们的在线状态;转发本来也不查配对关系(server/signal/server.go 的 forward)。自建服务器不用升级。
  • 按需连接:只看在线状态时不建 P2P 连接;打开发送窗口、往头像上拖文件、补发删除通知时才连;连上后交换功能声明、名片,空闲 2 分钟断开。
  • 服务中转的额度:按每台机器各自的组计算。网关只看双方是否互相授权,不看是否配对(实现时要验证)。
  • 「所有人」只在局域网:陌生人不知道你的设备 ID,跨网络本来就找不到你。局域网里沿用「搜索附近设备」的做法,打开期间 mDNS 广播里带上显示名,关掉就撤下。

9.2 连不上时的提示

名片里带着对方用的是哪种服务:服务 / 自建服务器 / 仅局域网。自建服务器只带地址的哈希,不带地址本身,用来判断是不是同一台。名片在每次连上时更新,本机记住最近一次的值。

情况 提示
在同一局域网 不提示
不在同一局域网,双方都开着服务,或者用同一台自建服务器 不提示,正常连接
不在同一局域网,我没开服务 「你和 小明 不在同一个局域网。打开服务后就能给他发文件,直连不了时经服务中转。」按钮「打开服务」
不在同一局域网,我开了,对方没开 「小明 没有打开服务,不在同一个局域网时发不了。请他在隔空贴里打开服务。」
双方用的是不同的自建服务器 「你们用的不是同一台服务器。双方都打开服务,或者改用同一台服务器后就能发。」
  • 提示出现在:点好友或往好友身上拖文件时、雷达上的小字「需要打开服务」、好友码窗口(第 5.1 节)。
┌──────────────────────────────────────────┐
│ ⚠ 你和 阿杰 不在同一个局域网。               │
│   打开服务后就能给他发文件,                  │
│   直连不了时经服务中转。                      │
│                                          │
│                [ 取消 ]  [ 打开服务… ]     │
└──────────────────────────────────────────┘

  对方没开服务时:
  「阿杰 没有打开服务,不在同一个局域网时发不了。
    请他在隔空贴里打开服务。」          [ 知道了 ]
  • 「打开服务」跳到现有的服务设置页,沿用里面的隐私说明和确认,不在这里直接打开。
  • 不在后台偷偷换服务模式,也不额外连服务器:服务模式仍然只由用户自己选。

10. 版本与兼容

10.1 先修现有的「需要更新」误报(2.5.4,独立于好友功能)

现象:对方明明是新版本,雷达上先显示「需要更新」,过一会儿才消失;连不上时会一直显示。

原因:

  • 「在线」由服务器在线通知、局域网可达、P2P 已连通任一成立即算(peers.Manager.isOnlineLocked)。
  • 但功能声明 PeerFeatures 要等 P2P 连通以后才交换(handleP2PState)。
  • 界面只分「支持 / 不支持」(send_page.dart 的 _statusOf),把「还不知道」当成了「不支持」。
  • 后台服务重启后声明清空,又会闪一次。

修法:

  • Device 增加功能声明状态:unknown / known。还不知道时,界面显示「连接中…」,可以点,点了就先去连接。
  • 只有 P2P 已连通、超过 5 秒仍没收到声明,才判定为旧版本,显示「需要更新」。旧版本一直不发声明,所以这个判断是准的。
  • 每台设备最近一次的声明和版本号存进数据库,重启以后立即可用;连上后收到新的声明再更新。
  • 连不上时显示「暂时连不上」,不显示「需要更新」。
  • 测试:在线但 P2P 未连通 → unknown;连通后不发声明 → 不支持;重启后读出上次的声明。

10.2 按功能判断,不比版本号

  • PeerFeatures 里每个功能一个标记,双方都声明了才用:
标记 含义 起始版本
send_files_v1 / send_files_off 能收隔空传送 / 关掉了接收(现有) 2.5.0
send_files_tcp_v1 局域网 TCP 快速通道(现有) 2.5.1
friends_v1 名片、头像、好友请求、删除好友 2.6.0
send_files_ask_v1 发送请求可以等待对方确认(60 秒),带备注,认识新的回绝原因 2.6.0
send_files_recv_v1 真的实现了隔空传送的接收端。2.7.4 及更早的手机端没有这个功能(phone-sync.md 3.1.2),2.7.4 及更早的安卓包却照抄了桌面端的声明,所以手机平台只声明 send_files_v1 不算数,要额外声明这个才认 2.7.5
  • PeerFeatures 增加 app_version,只用来显示,比如「小明 需要更新到 2.6.0 或更高」;不用它做判断,避免 2.5.0 和 2.5.3 这样的版本差被误判。
  • 给好友发文件,必须对方声明了 send_files_ask_v1。旧版本收到发送请求会直接自动接收,绕过确认,所以不能发给旧版本。
  • 手机(android / ios)还要声明 send_files_recv_v1。2.7.4 及更早的安卓 App 用的是同一套 peers.Manager,照抄了桌面端的 send_files_v1 却没有实现隔空传送;只改手机端挡不住已经装出去的包, 所以收文件的判定除了看声明,还要看平台。新版安卓端已经真的实现了(android-send-files.md) 并声明这个标记,电脑端一直声明它。
  • 以后再加的功能照此办理:新标记、双方声明、界面三态(不知道 / 支持 / 不支持并提示版本)。

10.3 全局最低版本

更新清单 updates/latest.json 增加可选的 min_supported。只在设备之间协议不兼容(升 MAJOR)或有安全问题时设置;低于它的客户端提示「必须更新后才能继续同步」。好友功能是只增不改,不需要设置它。

11. 安全

以前连上来的对端都是自己的电脑,现在不是了,这是这次改动里最要紧的部分。

  1. 分开存。 好友存到新表 contacts,不进 devices。剪贴板同步、快捷粘贴、收藏、文件同步都只读 devices,按结构就碰不到好友。
  2. 入口白名单。 每个对端连接带一个角色:self / friend_pending / friend / stranger。peers.Manager 收到 P2P 消息、数据流时按角色放行,其他一律丢弃并记日志:
角色 放行
friend_pending PeerFeatures、名片、头像请求与数据、好友请求与回复
friend 上一行全部,加上 PeerDisplay、LinkInfo、删除好友、Send* 与发送数据流
stranger PeerFeatures、PeerDisplay、LinkInfo、Send* 与发送数据流

要有单测逐条覆盖每种消息类型。以后新加的消息默认不放行。 3. 发出去的也过滤。 剪贴板广播只发给 self。给好友的名片只有显示名、电脑名、系统、服务类型和头像哈希。 4. 签名信令的公钥来源。 signed.Verifier 现在只从已配对设备里找公钥,要扩展成「已配对设备 + 好友 + 本次局域网会话里认识的陌生设备」,并带出角色。陌生设备的公钥只存在内存里,关掉「所有人」就清掉。 5. 接收文件:

  • 路径穿越、指向保存位置以外的符号链接,一律拒绝;
  • 非 self 发来的文件去掉可执行权限;
  • Mac 上加隔离标记;
  • 缩略图和头像只显示后台服务重新编码过的版本。
  1. 备注:长度上限 200 字符、单行,只当纯文本显示;超长、含换行或控制字符的整条请求拒绝;没有文件的请求拒绝。收发两边都检查。
  2. 在线状态:任何人只要知道你的设备 ID,都能在服务器上关注你、看到你在不在线。现在就是这样,好友功能没有让它更糟。但「均不允许」挡不住在线状态被看到,只挡发文件,文案里不写「对方看不到你」。

12. 「官方服务」改叫「服务」

  • 界面上所有「官方服务」改成「服务」:侧边栏、设置、隐私说明、中转确认框、额度提示。
    • 简体「服务」、繁体「服務」、英文 "Service"、日文「サービス」。
    • 涉及 officialService、useOfficialService、officialPrivacy、relayConfirmTitle、relayConfirmBody 等字符串,五种语言一起改。
  • 官网(tools/site/content/*.py)和 README 里的相关说法同步改。
  • 代码里的标识符(Official()、service_mode = official)和设计文档 official-gateway.md 不改:它们是内部名字,改了会牵动配置迁移。
  • 改的是文字,不改行为,可以和 2.5.4 一起发。

13. 协议与数据

设备之间的协议只增不改,旧版本收到新消息会忽略,所以升 MINOR(2.6.0)。

13.1 wire.proto(设备之间)

message FriendCard {
  string display_name = 1;
  string device_name = 2;
  string platform = 3;
  string service = 4;                // official / custom / lan
  bytes  custom_server_hash = 5;     // 自建服务器地址的哈希,判断是否同一台
  bytes  avatar_hash = 6;            // 空表示用默认头像
}
message FriendRequest { bytes nonce = 1; FriendCard card = 2; }
message FriendAnswer  { bytes nonce = 1; bool accepted = 2; FriendCard card = 3; }
message FriendRemove  { int64 at_unix = 1; }
message AvatarRequest { bytes avatar_hash = 1; }
message AvatarData    { bytes avatar_hash = 1; bytes jpeg = 2; }  // ≤ 64 KB
  • SendOffer 增加 string note = 9;(≤ 200 字符,单行;items 为空时不允许带)。发送方是谁由连接的角色决定,不信任消息里自报的身份。
  • 发送请求的「等待确认」:接收方先回 SendAnswer{accepted:false, reason:"pending"},用户点了以后再回最终结果。发送方 60 秒没收到最终结果就按 timeout 处理。
  • SendAnswer.reason 增加 pending、declined、timeout、not_allowed、rate_limited。
  • PeerFeatures 增加 app_version,以及第 10.2 节的新标记。
  • 名片在每次连上时重发一次(显示名、服务类型、头像可能变了)。

13.2 本机存储

CREATE TABLE contacts (
    device_id     TEXT PRIMARY KEY,
    public_key    BLOB NOT NULL,
    display_name  TEXT NOT NULL DEFAULT '',
    device_name   TEXT NOT NULL DEFAULT '',
    platform      TEXT NOT NULL DEFAULT '',
    service       TEXT NOT NULL DEFAULT '',
    server_hash   BLOB,
    avatar_hash   BLOB,
    avatar_path   TEXT NOT NULL DEFAULT '',  -- 本机重新编码后的头像
    features      TEXT NOT NULL DEFAULT '',
    app_version   TEXT NOT NULL DEFAULT '',
    auto_accept   INTEGER NOT NULL DEFAULT 0,
    added_at      INTEGER NOT NULL,
    last_activity INTEGER NOT NULL DEFAULT 0
);
CREATE TABLE contact_addrs (         -- 同 device_addrs
    device_id TEXT NOT NULL REFERENCES contacts(device_id) ON DELETE CASCADE,
    addr      TEXT NOT NULL,
    last_seen INTEGER NOT NULL,
    PRIMARY KEY (device_id, addr)
);
CREATE TABLE pending_notices (       -- 待补发的删除好友通知
    device_id  TEXT PRIMARY KEY,
    public_key BLOB NOT NULL,        -- 好友已从 contacts 删除,补发时仍要验证对方
    created_at INTEGER NOT NULL
);
CREATE TABLE blocked_devices (device_id TEXT PRIMARY KEY, at INTEGER NOT NULL);
  • devices 增加 features、app_version(第 10.1 节)。
  • transfers 增加 peer_role、note、thumb_path。好友的名字和头像从 contacts 取。
  • config 增加:
    • receive_from:off / friends / everyone,默认 friends;
    • everyone_until;
    • display_name、avatar_path。

13.3 本机接口(daemon RPC)

  • 名字与头像:GetProfile、SetDisplayName、SetAvatar(图片路径或剪贴板图片, 裁剪区域)、ResetAvatar、GetAvatar(device_id)
  • 好友:CreateFriendCode、RedeemFriendCode、ConfirmFriend、ListFriends、RemoveFriend、SetFriendAutoAccept、BlockDevice
  • 发送:SendFiles 的目标可以是好友,增加 note;AnswerIncoming(transfer_id, accept, always);ListTransfers 可按好友过滤
  • 设置:SetReceivePolicy(off | friends | everyone)
  • 事件:friend_request、friend_changed、incoming_offer、receive_policy_changed(「所有人」到期自动关闭时)、friend_reachability(第 9.2 节的提示状态)
  • pasteferry-cli:friends、friend add | code | remove、send --to <好友> --note <备注>、accept、decline

14. 分期

2.5.4(先发)

  • 修「需要更新」误报(第 10.1 节)
  • 「官方服务」改叫「服务」(第 12 节)

2.6.0(好友一期)

  • 这台电脑的显示名;默认头像与自定义头像(选择、粘贴、拖入,裁剪)
  • 好友码加好友、删除好友、好友列表
  • 给好友发文件和图片:备注、粘贴图片、等待确认、自动接收、防打扰、隔离标记、图片缩略图
  • 接收设置三档,「所有人」只限局域网、10 分钟到期
  • 连不上时的「打开服务」提示(第 9.2 节)
  • 角色白名单、功能声明与版本提示
  • 五种语言的文案,官网功能页加一节(按第 6.5 节的口径)

二期

  • 附近添加好友、好友链接与二维码
  • 可选:把好友同步到自己的其他电脑(第 4.5 节)
  • 手机端(mobile-clients.md)

15. 测试

  • 单测:
    • 角色白名单逐个消息类型;
    • 接收设置三档 × 三种角色的应答;
    • 60 秒超时、防打扰计数;
    • 备注:超长、多行、控制字符被拒;没有文件时不能发;
    • 图片:损坏的图片不崩溃、HEIC 缩略图;头像不超过 64 KB、去掉 EXIF、坏数据退回默认头像;
    • 路径穿越与符号链接;
    • 好友码与配对码的识别;已配对的电脑不能加为好友;
    • 第 9.2 节的每一种提示情况。
  • 本机端到端(沿用隔空传送的做法:-tags fakeclip、隔离的 -data-dir、receive_dir 在 /tmp)。A1/A2 互相配对,B1 是另一个人:
    • A1 和 B1 加好友后能互相发文件,备注和头像正确显示;A2 和 B1 不是好友,互相发不了;
    • A1 复制文字、图片、文件后,B1 的剪贴板与复制记录都没有变化(最重要的一条);
    • B1 选「均不允许」时,A1 发送得到「不接收文件」;
    • 删除好友后双方都发不了;B1 离线时删除,B1 上线后收到补发的通知;
    • 旧版本(2.5.3)对端:显示「需要更新」,好友码报「配对码无效」,不会被误配。
  • 实机:
    • Mac(A)↔ Linux 虚拟机(B):Linux 用隔离的 HOME,不要用和真 Mac 配对过的那份数据,免得测试内容进真剪贴板。
      • 双方打开服务、关掉局域网:确认跨网络能发,中转确认和额度扣减正常。
      • 一方关掉服务:确认第 9.2 节的提示。
    • Windows 虚拟机:测接收弹窗、通知上的按钮和头像。