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.
隔空贴:好友——加好友,给好友发文件和图片
定稿 · 2026-10-26 · 决定见第 3 节,尚未实现 · 已按 2.5.3 的代码核对
- 在 隔空传送(2.5.0)上扩展:以前只能发给自己配对的电脑,这次加上「别人」。
- 不做聊天。 只发文件和图片,可以附一句备注;备注附在文件上,没有文件就发不了,长度有上限;没有对话窗口,只有传输记录(第 6.5 节)。
- 插件、插件市场另行讨论,不在本稿范围内。
- 用词:界面上的「官方服务」一律改叫 「服务」(第 12 节)。本稿里的「服务」就是指它;用户自己部署的叫「自建服务器」。
1. 要做的事
你在用隔空贴,你的朋友也在用,但你们是两个人、各有各的电脑:
- 你的一台电脑和他的一台电脑加一次好友,之后互相发文件不用配对。好友按电脑算:在哪台电脑上加的,就只在那台电脑上有效(第 4 节)。
- 给好友发文件、图片,可以附一句备注(最多 200 字),比如「合同第 3 页要签字」。备注只能附在文件上,不能单独发。
- 能不能发由接收方决定。隔空传送页底部和隔空投送一样有一行「允许这些人给我发文件」:
- 均不允许:只有自己配对的电脑能发。
- 仅限好友(默认):好友能发。
- 所有人:同一局域网里不认识的人也能发,10 分钟后自动回到「仅限好友」。
- 好友和陌生人发来的东西,接收方每次都要点「接受」。可以对某个好友设成「自动接收」,陌生人不行。
- 怎么连:
- 在同一局域网,直接连;
- 不在同一局域网时,开了「服务」就先尝试直连,直连不了再经服务中转;
- 连不上时,提示双方打开「服务」。
- 好友碰不到你的剪贴板、复制记录、收藏,也不会和你的电脑一直连着。
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 重新解码、重新编码,再存进本机;界面只显示重新编码过的文件。
- 拿到之前、或者头像数据有问题时,显示对方的默认头像。
- 名片里只带头像的哈希。对方发现哈希变了,才在 P2P 连接上要一次头像数据(
- 出现的地方:雷达、好友列表、发送窗口标题、加好友的确认框、接收弹窗、传输记录。系统通知能换图标的平台(Windows 的 toast、Linux 的通知)用对方头像;macOS 的通知图标固定是应用图标,换不了。
- 陌生人(「所有人」模式)不交换头像,一律显示默认头像,避免被用来发不当图片。
4.5 以后要不要按人
先按电脑做。如果用户普遍有多台电脑、嫌每台都要加一次,二期可以加一个明确的选项:「把这台电脑上的好友同步到我的其他电脑」,由用户在每台电脑上主动打开,而不是根据配对关系自动合并。到时再加一个功能标记(第 10.2 节),不影响一期的数据。
5. 加好友
5.1 好友码
复用现有配对码的通道(服务器的配对码代理加局域网),服务器不用改:
- 光光在隔空传送页点「好友 → 添加好友」,界面显示好友码
F-7K3QXM,5 分钟内有效。下面一行说明:「把这个码发给好友,对方在隔空贴里输入后,你们就成为好友」。 - 小明点「添加好友」,输入这个码。
- 两边交换公钥(和配对完全一样),建立 P2P 连接。这条连接的角色是「待定好友」,只能交换名片、头像和好友请求。
- 两边各弹一个确认框:头像加「添加 小明 · MacBook Air 为好友?」,按钮是「添加」「取消」。两边都点「添加」才算加上。
- 确认框里有一行可展开的「核对安全码」,显示 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 连接顺序
好友之间的连接和自己设备之间的完全一样,只是按需建立:
- 同一局域网:靠 mDNS 发现,直接连。好友按现有的当日令牌认出来,算法不变。不需要服务。
- 不在同一局域网,双方都打开了服务(或者用同一台自建服务器):经服务器交换信令,先尝试打洞直连。
- 直连不了:经服务中转。中转受每天 100 MB、约 0.25 MB/s 的额度限制,大文件会慢;沿用现有的中转确认。
- 中转期间打洞成功了,就切到直连。
- 服务器不用改:客户端把好友的设备 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. 安全
以前连上来的对端都是自己的电脑,现在不是了,这是这次改动里最要紧的部分。
- 分开存。 好友存到新表
contacts,不进devices。剪贴板同步、快捷粘贴、收藏、文件同步都只读devices,按结构就碰不到好友。 - 入口白名单。 每个对端连接带一个角色:
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 上加隔离标记;
- 缩略图和头像只显示后台服务重新编码过的版本。
- 备注:长度上限 200 字符、单行,只当纯文本显示;超长、含换行或控制字符的整条请求拒绝;没有文件的请求拒绝。收发两边都检查。
- 在线状态:任何人只要知道你的设备 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 虚拟机:测接收弹窗、通知上的按钮和头像。
- Mac(A)↔ Linux 虚拟机(B):Linux 用隔离的 HOME,不要用和真 Mac 配对过的那份数据,免得测试内容进真剪贴板。