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.

21.1 KB
Raw Blame

安卓隔空传送:技术方案与实施记录

2026-10-30 · 基于仓库提交 c26db4d(客户端 2.7.4)

状态:P1~P4 已实现并在本机完成端到端验证(见第 8 节)。第 1~7 节是当时定的方案, 实际实现与方案有出入的地方记在第 8 节「实现与方案的差异」。

背景:2.7.4 及更早的安卓 App 在功能声明里说「我能收隔空传送」,但手机端的 Go 核心根本没有隔空传送, 电脑发文件过去会 30 秒后「对方没有应答」,然后每次重连再试一次,永远发不过去(见第 2 节 Q1)。 本文给两件事:把隔空传送真正移植到安卓;以及今天查到的其余问题怎么处理。

1. 结论

能移植,而且 Go 核心几乎不用改。 隔空传送(internal/send)本来就是平台无关的,手机端缺的只是「组装」:

层 现状 移植要做的 难度
Go 核心 手机端 mobile.start 没创建 send.Engine 在 mobile.go 里照桌面 pasteferryd 的方式创建并接线 小,约 120 行
收到文件的落盘 — 存 App 私有目录,配置里把 ReceiveDir 指过去 小
RPC 面 Transfers 为 nil,相关方法返回 隔空传送不可用 把引擎挂上 deps.Transfers 极小
Android 宿主 已有 save / share 通道、前台服务 接收通知(可选)、接收目录的权限说明 小
Flutter 界面 手机端只有「记录 / 发送 / 设备 / 设置」四个标签,SendTab 只能发剪贴板内容给所有设备 新增「隔空传送」页:选设备发文件、收文件进度、接受/拒绝、保存/分享 中,占大头

AppState 里传输相关的接口(transfers、sendFiles、answerIncoming、checkReceiveDir、 传输事件)桌面上已经全都有,手机端界面只是没接;MobileHost.save() / MobileHost.share() 也已经存在,收到的文件直接就能保存到「下载」或分享出去。所以界面虽有工作量,但没有新的底层能力要造。

建议分两期(第 6 节):一期做「局域网内手机 ↔ 电脑互传文件」,二期做陌生人、通知、后台接收。

2. 今天查到的问题

按「要不要修」逐条给结论。Q1 已经改完(未提交),其余待你确认后一起做。

Q1 手机端声明了它没有的能力(必修,已实现)

  • 证据:release/PasteFerry-android-arm64.apk 里 send.(*Engine).handleOffer、send.(*Engine).runOutgoing、 对方没有应答 这三个符号都是 0 处;同一份 APK 里 send_files_v1、send_files_tcp_v1 各 1 处。 桌面 pasteferryd.exe 对照是 5 / 3 / 1 处。
  • 机制:peers.featuresFor 无条件声明这三个能力,发送端 send.SendFiles 只按声明放行 (p.Supported),发送页也只看 receivesFiles。手机收到 SendOffer 后在 sync.(*Engine).HandlePeerMessage 的 switch 里没有分支,静默丢弃,不回绝也不打日志。
  • 现场:本机复现,桌面 → 手机 22 KB 文件,state=direct 之后正好 30.0 秒打 对方没有应答 模块=隔空传送,传输 30.1 秒变 interrupted,与用户日志 (22:37:11.583 direct → 22:37:41.585 对方没有应答)一致。
  • 已改:peers.Options.SendFiles 控制声明;手机端不打开。另加 send_files_recv_v1:手机平台必须额外声明它才算真的能收,挡住已经装出去的 2.7.4 安卓包。 改完后同一脚本:能收文件=false、SendFiles 被拒绝:unsupported,不再挂 30 秒。
  • 和本次移植的关系:send_files_recv_v1 正是「安卓真的能收了」的开关。移植完成后手机端声明它, 电脑就会正常允许发送,不需要再改判定逻辑。

Q2 接收方超时失败是静默的(已修)

  • sync.newReceiveLocked 有 30 秒看门狗,超时走 failReceive,它只改数据库状态,一行日志都不打。
  • 后果:现场日志里 22:11:05、22:14:24 两条 kind=4 status=3 之后再无下文,用户看到 「只有复制记录、没有文件」,而诊断报告里查不到任何原因。
  • 修法:failReceive 加一行 Warn(记录 ID、原因、来源设备)。纯日志,不影响行为。

Q3 自动推送失败后不会重试(已修)

  • pushOrRequeue 推流失败后走 queueMissed,而它要求 cfg.SyncBacklog 为真, 这个开关默认关(「补发离线期间的内容(默认关)」)。
  • 后果:一次网络抖动=这条内容永久丢失,接收端留一个永远完不成的记录(配上 Q2 就是静默失败)。
  • 已修:拆成两个队列。「offer 根本没发出去」(offerToPeers 里 send 失败)仍归 SyncBacklog 管; 「offer 发出去了、推流失败」进新的 pushRetry 队列(internal/sync/backlog.go), PeerReady 时无条件重推,重发的是原样的 offer(不带 backlog 标记), 对端已有这条记录,只会接着收,不会被当成旧内容而跳过自动写入剪贴板。

Q4 诊断报告缺关键字段(已修)

  • diag 的 Devices 段只有「名字 / 平台 / 连接状态」,没有对端版本号和能力声明。 这次定位靠的是猜 + 反编译 APK,如果有这两项,一条报告就能定案。
  • 修法:DiagInput 带上每个 peer 的 app_version、features、receives_files, 报告里加两列。只加字段,不影响替换规则。

Q5 本机复制文件读不到时用户不知道(已修)

  • 现场 22:15:23 有 记录本机复制失败 err=剪贴板中的文件都不可访问,HandleClipboardChange 只写 Warn 就返回,界面上什么都不显示。
  • 典型场景:从压缩包预览、邮件附件、某些网盘客户端复制文件时,剪贴板里是虚拟路径。
  • 已修:新增 Event.notice(只带一个固定代码),桌面端一分钟内最多提示一次,两端界面弹 toast。

Q6 「对方没有应答」时用户只看到「中断」(已修)

  • 目前 30 秒没应答就 interrupt,界面文案是「中断」,用户点「继续」还是同样结果。
  • 已修:新增 interruptWith(t, reason),超时那一路带上 peer_unreachable,界面显示 「{对方} 没有应答」(复用已有的 reasonTimeout 文案,没新增翻译),状态仍是「中断」, 点「继续」照常能接着发。

Q7 陌生设备列表把 receives_files 写死为 true(本次不动)

  • peers.Stranger() 直接返回 ReceivesFiles: true。目前 Flutter 界面不读这个字段 (只有 Device.receivesFiles 和 Friend.receivesFiles 被用在发送判定里),所以不影响用户。
  • 记着,等二期做「陌生人发给我」时一并改成按声明判断。

3. 移植方案

3.1 Go 核心:把引擎组装起来

新增 client-core/mobile/send.go,内容与 cmd/pasteferryd 的组装对应,去掉只有桌面才有的部分:

sender = send.New(send.Options{
    Store:      db,
    LoadConfig: loadCfg,
    Send:       peerMgr.P2P().Send,
    OpenStream: peerMgr.P2P().OpenStream,
    ListenLAN:  listenLAN,   // lantcp,同桌面 lanHooks
    DialLAN:    dialLAN,
    Peer:       func(id string) send.Peer { return sendPeer(peerMgr, id) },
    // Admit 一期留空:只收自己设备发来的,陌生人一律 not_allowed(见 3.6 二期)
    OnChange:  func(t *pb.Transfer) { hub.Publish(rpc.EventTransferChanged(t)) },
    OnRemoved: func(id string) { hub.Publish(rpc.EventTransferRemoved(id)) },
    OnNotice:  func(kind send.NoticeKind, t *pb.Transfer) { notify.transfer(kind, t) },
})

要点:

  • Inhibit、Thumbnail、Delivered、RelayQuotaExhausted、Connect、ListenLAN、DialLAN 全部留空即可, internal/send 里每一处都做了 nil 判断(已核对 send.go:485、ask.go:165、outgoing.go:91、 pipe.go:61、pipe.go:120)。手机端一期只走局域网,没有官方中转,RelayQuotaExhausted 本来也用不上。
  • ListenLAN / DialLAN 直接抄 cmd/pasteferryd/send_lan.go 的 lanHooks(id, peerMgr)。 已实测 GOOS=android GOARCH=arm64 CGO_ENABLED=0 go build ./internal/send ./internal/transport/lantcp ./internal/peers 全部通过:android 同时满足 linux 构建约束,复用 fs_linux.go 的 unix.Statfs,不需要新增平台文件。 (cmd/* 交叉编译只会在链接期因 pion 依赖的 net.zoneCache 报错,出包脚本的 -ldflags=-checklinkname=0 就是为这个;./mobile 本身能编译。)
  • peers.Options 改成:
    • SendFiles: true
    • ShareableStream: send.IsStream(现在是 func(string) bool { return false })
    • InUse: func(id string) bool { return sender != nil && sender.Busy(id) }
    • OnPeerReady 里同时调 engine.PeerReady 和 sender.PeerReady(现在是前者)
  • sendPeer 只在有好友/陌生人的桌面上才需要完整实现;手机端一期只用到 RoleSelf 分支, 照抄桌面 cmd/pasteferryd/friends.go 的同名函数即可(约 20 行)。

3.2 收到文件放哪里

  • 手机端把 cfg.ReceiveDir 固定成 <dataDir>/received(dataDir 是 filesDir/pasteferry,App 私有,不需要任何存储权限)。写法和现在强制 cfg.ServiceMode = "lan" 一样,放在 mobile.start 里,saveCfg 也一并守住。
  • 界面上隐藏「保存位置」设置(send_settings.dart 的那一项在手机端不显示), 用户拿文件走「保存到下载」或「分享」。
  • 现有 MobileHost.save(paths)(MediaStore,Android 10+ 无需权限)和 MobileHost.share(paths) 直接可用,不需要新的平台通道。

3.3 能力声明

移植完成后手机端声明:send_files_v1、send_files_tcp_v1、send_files_ask_v1、send_files_recv_v1。 SendFiles: true 已经在 Q1 的改动里接好这三者;send_files_recv_v1 也一并在同一处声明, 电脑端的平台兜底(Q1)随之放行,不需要再改判定逻辑。

版本兼容(沿用 friends-send.md 10.2 的规矩):

手机 电脑 结果
新版(声明 recv) 2.7.5 及以后 正常隔空传送,局域网直连时走 TCP 快速通道
新版 2.7.4 及以前 走剪贴板同步(旧电脑只认 send_files_v1,而旧电脑没有 Q1 的兜底,行为与今天相同)
2.7.4 及以前 2.7.5 及以后 电脑认为它不能收,发送页显示「需要更新」
2.7.4 及以前 2.7.4 及以前 今天的样子:30 秒「对方没有应答」

3.4 RPC 面

deps.Transfers 挂上引擎即可,SendFiles / CancelTransfer / ResumeTransfer / ListTransfers / DeleteTransfers / MarkTransfersSeen / CheckReceiveDir / AnswerIncoming 自动可用(桌面用的 transfersAPI 包装在 cmd/pasteferryd/friends.go, 手机端只需要 SendFiles 这一层薄包装,或把包装挪到共用位置)。Flutter 侧 AppState 已经在调这些接口。

3.5 Android 宿主

一期(必须):

  • 无新增。保存/分享复用现有通道。

二期(体验,见 6):

  • 新增通知渠道 transfers(IMPORTANCE_DEFAULT),用于「有人要发给你 N 个文件(点开接受)」和 「收到 N 个文件」;点通知打开 App 并切到隔空传送页。
  • 实现方式:mobile.Host 接口加一个 TransferNotice(kind, name, detail string), 由 OnNotice 调用;Kotlin 的 Core.kt 里实现,SyncService 负责发通知。 注意 gomobile 只会用基本类型,参数用字符串拼。
  • 后台接收:现在有前台服务,传输期间不会有问题;系统杀后台的风险与剪贴板同步相同, 文档里已有的「自启动白名单」提示照样适用。

3.6 Flutter 界面

一期(必须):

  1. ui/lib/mobile/ 新增 transfers_tab.dart(或并入设备页):
    • 设备卡片上一个「发送文件」按钮 → file_selector 选文件 → AppState.sendFiles(deviceId, paths)。 手机端选文件已经有现成的 _pickFiles()(send_tab.dart:82)可以抽出来复用。
    • 传输列表:进行中(进度、速度、取消)、已完成(保存 / 分享)、失败(原因 + 继续)。 桌面 send_page.dart 里的条目渲染可以抽成共用 widget,但手机端样式要按触控重做。
  2. 收到请求时的确认:复用 widgets/incoming_dialog.dart(桌面上就是它), 在 MobileShell 里按 state.askingIncoming 弹窗或弹底部面板。
  3. 设置页隐藏「保存位置」(见 3.2)。

二期:陌生人收发、通知、后台。

3.7 不做的事(一期)

  • 手机收「文件夹」原样落地:按文件夹整体接收,导出时逐个文件走 MediaStore(FileSaver 已支持目录)。
  • 手机之间的隔空传送:协议上通,但一期不验收。
  • 官方中转 / 跨网:手机仍然只走局域网。
  • iOS:本文不涉及。

4. 改动清单

文件 改什么
client-core/mobile/mobile.go 创建 send.Engine、挂 deps.Transfers、SendFiles: true、ShareableStream、InUse、PeerReady
client-core/mobile/send.go(新) sendPeer、lanHooks(lantcp)、ReceiveDir 默认值
client-core/internal/peers/{manager,friends}.go 已完成:Options.SendFiles、send_files_recv_v1、ReceivesSendFiles
client-core/internal/sync/receive.go Q2:failReceive 加日志
client-core/internal/sync/backlog.go Q3:推流失败的重试队列
client-core/internal/diag/* Q4:报告加对端版本与能力
client-core/internal/sync/engine.go Q5:本机文件读不到时给界面一次性提示
client-core/internal/send/{outgoing.go,send.go} + ui 文案 Q6:peer_unreachable 错误码与提示
ui/lib/mobile/{transfers_tab.dart, mobile_app.dart, send_tab.dart} 一期界面
ui/lib/mobile/settings_tab.dart 隐藏保存位置
ui/android/.../{Core.kt, SyncService.kt} 二期:传输通知

5. 测试计划

自动测试(必须)

  • mobile:起核心后 ListDevices/GetStatus 正常;SendFiles 不再返回 Unimplemented; 收到的文件落进 <dataDir>/received;AnswerIncoming 能接受和拒绝。
  • peers:已有的 TestFeaturesWithoutSendFiles、TestOldAndroidPackageDoesNotReceiveFiles 保留; 新增「声明了 recv 的手机平台允许发送」。
  • send:不动现有用例;Q3 加「推流失败后连接恢复会重试」、Q6 加错误码断言。
  • diag:Q4 的报告快照。

端到端(本机,用已经搭好的复现脚本)

/tmp/pf-repro 里已经能用真实的 client-core/mobile 组装跑起一台「手机」,与桌面守护进程配对:

  1. 改造前:桌面发 22 KB 文件 → 30.1 秒 interrupted(已复现)。
  2. 改造后:同一命令应当 done,并且文件真的出现在手机的接收目录、SHA-256 一致。
  3. 反向:手机 → 桌面(现在走剪贴板同步已经能通,改成隔空传送后再验一次)。
  4. 断点续传:传输中杀掉手机端进程再起,桌面重连后应自动续传完成。

真机(需要你在手机和电脑上跑)

场景 看什么
电脑 → 手机 单文件 / 多文件 / 文件夹 进度、保存到下载、分享到微信
手机 → 电脑 进度、电脑侧文件完整
手机锁屏、切后台 前台服务是否撑住;被系统杀掉后重连能否续传
同一 WiFi 千兆 是否走 TCP 快速通道(日志 不是局域网直连,用数据通道 不应出现)
手机拒绝 / 取消 两端状态一致,不留半截文件
存储不足 提示 no_space,不给用户写一半的残文件

界面:flutter analyze 加桌面端手点(手机端页面同时会被桌面构建编译,语法/类型错误能在这里挡住)。

6. 分期与工作量

阶段 内容 估计
P1 Go 核心组装 + RPC + 接收目录 + 能力声明 + Q1 收尾 半天
P2 手机端隔空传送页(发文件、列表、进度、保存/分享)+ 收到请求的确认 1~1.5 天
P3 Q2~Q6 的修复 半天
P4 传输通知、陌生人收发 1 天
P5 真机联调、出包抽查(APK 里 send_files_v1 应为 1 处、send.(*Engine).handleOffer 应为 0 处→改为非 0) 半天

建议 P1 与 P3 一起发一版(2.7.5,PATCH:手机端不能收文件属于缺陷),P2 完成后随 2.8.0 发。

7. 待你决定

  1. 分期:按上面 P1→P5 走,还是你希望一次做完(P2 的界面工作量最大,且我这边没有安卓设备, 只能靠 flutter analyze 和桌面端回归,真机效果要你验)。
  2. Q3 的做法:给「已经发出去但没送到」单独做一个重试队列(我倾向),还是把 SyncBacklog 默认打开(会顺带改变「离线补发」的行为,影响面更大)。
  3. 安卓接收目录:固定成 App 私有目录 + 用户点「保存到下载」(我倾向,权限最干净), 还是直接写系统下载目录(Android 10+ 走 MediaStore,需要额外处理重名和用户删改)。
  4. 通知:一期就要传输通知(要多改 Kotlin 与 Host 接口),还是放二期。

8. 实现记录(2026-10-30)

8.1 做完了什么

阶段 内容 状态
P1 Go 核心组装、RPC 面、接收目录、能力声明 完成
P2 手机端隔空传送页(设备发文件、传输列表、保存/分享) 完成
P3 Q2~Q6 完成
P4 陌生人收发、传输状态进常驻通知 完成(通知是折中方案,见 8.3)
P5 真机联调 待你在手机上验

8.2 端到端验证结果(本机,用真实的 client-core/mobile 组装起一台「手机」)

场景 结果
改造前:电脑 → 手机 22 KB state=direct 后 30.0 秒「对方没有应答」,30.1 秒中断,与用户日志一致
改造后:电脑 → 手机 22 KB 0.5 秒 done,接收目录里的文件 SHA-256 与源文件一致
改造后:电脑 → 手机 4.8 MB 文件夹(含子目录) 0.5 秒 done,逐文件 SHA-256 一致,走了局域网快速通道
改造后:电脑 → 手机 2 GB 传输中杀掉手机进程 → interrupted;手机重新启动后自动续传,2 GB 完成后 SHA-256 一致
改造后:手机 → 电脑 4.8 MB 文件夹 0.5 秒 done,电脑侧逐文件 SHA-256 一致
能力声明 电脑看到手机「能收文件=true、版本 2.7.4」;send_files_recv_v1 让平台兜底放行

8.3 实现与方案的差异

  1. 功能声明的开关 用了 peers.Options.SendFiles(手机端打开),而不是在 featuresFor 里按平台判断。 平台兜底只保留给「已经装出去的 2.7.4 安卓包」(send_files_recv_v1)。
  2. 对端状态的映射抽成了共用包 internal/sendpeer(Peer / Admit / LANHooks), 桌面 cmd/pasteferryd 和手机 mobile 用同一份,cmd/pasteferryd/send_lan.go 已删除。 两端的判定不会跑偏。
  3. 接收目录 固定成 <数据目录>/received(App 私有),并且必须由 mobile.start 先建好: internal/send 只建它下面的 partial 目录,保存位置不存在时会直接回绝 dest_unavailable。
  4. 界面没有新增文案:设备组用 navDevices、列表用 friendHistory、发文件按钮用 sendChooseFiles、保存/分享/继续/删除都用现有键。新增的下拉提示用了新键 noticeFilesUnreadable(5 种语言)。
  5. 传输通知是折中方案:手机端没有新增通知渠道,也没有改 mobile.Host 的 gomobile 接口 (改它必须用 Android 工具链重新编译 AAR 才能验证,本机没有 NDK)。 现在收到传输时会把「来自 X 的文件」写进已有的常驻通知,用户拉开通知栏能看到。 单独的传输通知(带「点开接受」动作)留在后面,见 8.5。
  6. 陌生人:手机端把 Admit 接上了 sendpeer.Admit,附近的陌生设备发文件时会弹确认 (复用桌面的 showIncomingDialog)。手机主动发给陌生设备(lan: 实例名)还不支持—— 手机界面上没有陌生设备列表。

8.4 已知的边界

  • 手机在后台被系统杀掉后,正在进行的传输会中断,重连后自动续传(已验证);但用户不会收到提醒, 直到打开 App。
  • spaceReserve(200 MB)是桌面的常量:手机剩余空间不足 200 MB 时会回绝 no_space。 手机上这个余量偏保守,但不会写半截文件,暂不调整。
  • 局域网快速通道需要两端都声明 send_files_tcp_v1(本次都声明了),防火墙/睡眠仍可能退回数据通道。

8.5 还没做的

  • 单独的传输通知渠道 + 点开接受(要改 mobile.Host 接口与 Kotlin,必须在有 NDK 的机器上验证)。
  • 手机端主动给「附近的陌生设备」发文件(需要陌生设备列表界面)。
  • 手机接收文件夹后的「整体导出为 ZIP」(现在逐个文件保存/分享)。
  • Q7(peers.Stranger() 里 ReceivesFiles 写死为 true):界面目前不读这个字段,留到做陌生人界面时一起改。