Files
QFT/docs/V05_MULTIPEER_PLAN.md
T
zhy200308 376ffba96e feat(desktop): 跨平台桌面端 + 电脑↔电脑互传(v0.5.0-m1)
对应 V05_EXECUTION_PLAN 的 P1。核心改动是把「PC 只能当服务端」
这个写死的角色拆开——此前 TcpStream::connect 只出现在测试里,
桌面端根本无法主动连接另一台桌面端,PC↔PC 因此完全不可用。

跨平台
- windows/ → desktop/,crate 更名 qft-desktop
- 新增 platform.rs 收敛全部平台差异:配置目录(LOCALAPPDATA /
  Application Support / XDG)、下载目录(含 Linux 本地化的 ~/下载)、
  设备名、Direct AP 能力。约定:其余模块不得再出现 #[cfg(target_os)]
- direct_ap.rs 的 Context 导入按平台条件化,非 Windows 上不再告警
- macOS 上已实测编译并链接出可执行文件(65 MB Mach-O arm64),
  这是本仓库首次在非 Windows 平台构建成功

电脑 ↔ 电脑
- 新增 client.rs:桌面端发起侧。手写 HTTP,不引入客户端依赖——
  服务端本来就是手写的,两边同一套解析更容易与 Android/iOS 对齐。
  含并发分块上传(自适应 4/8/16 MiB、最多 8 worker)与 Range 断点续传
- 新增 discovery.rs:UDP 广播 QFTBROWSE3 浏览局域网节点。
  既有的 QFTDISC2 是「已知令牌找机器」,用于扫码之后;
  PC 没有摄像头,必须先能列出附近有谁
- receiver.rs 新增 POST /qft/pair:用 6 位配对码换会话令牌。
  这是唯一不校验令牌的端点。6 位仅约 20 bit 熵,配严格失败计数兜底——
  错 5 次即作废,需重启接收;比较用定长实现,不做短路返回
- 新增「电脑 ↔ 电脑」界面:接收方显示配对码与本机地址;
  发送方搜索/手动输入地址 → 输码连接 → 多选文件 → 带进度发送

验证(macOS,Rust 1.97.1)
- cargo check 0 错误,cargo test 17/17 通过
- 新增端到端用例:真实起接收服务 → 配对(含错误码必须被拒)→
  9 MB 跨多分块并发上传 → 校验落盘内容逐字节一致且 SHA-256 与
  接收端返回值相同。这就是 PC↔PC 的完整链路
- 11 项 Python 自检全部通过

顺带修复
- single_channel_guard_selftest 长期为红:它断言
  DEFAULT_CHUNK_SIZE = 450,而代码早已改为 320。改名前即存在,
  已用 git stash 验证与本次无关。改为范围检查(128~4096)并在
  PASS 信息里打印实际值,既挡住"退回多通道小块"又不会因调参误报

已知限制
- UDP 广播只覆盖同一广播域。跨网段或 AP 隔离的 Wi-Fi 上搜索不到,
  需手动输入对方 IP(界面已说明)。mDNS 留待后续
- 本阶段仍走 v2 明文 HTTP,加密随 QFT-Stream v3 一起做(见 P2)
2026-08-11 16:36:33 +08:00

16 KiB
Raw Blame History

QFT v0.5 增量设计:全平台对等互传

基线 v0.4.7。三项增量需求:

  1. 电脑 ↔ 电脑互传,跨平台(mac ↔ win ↔ mac,linux ↔ win ↔ mac)
  2. 手机 ↔ 手机互传
  3. 全量高速传输,支持目录直传,高速索引 + 稳定连接

0. 现状盘点(实测,非推测)

项 现状 影响
桌面端角色 只有服务端。TcpStream::connect 仅出现在 #[cfg(test)] 里 PC 无法主动连接对方 → PC↔PC 完全不可用
HTTP 连接 每个响应都写 Connection: close(sender.rs:183/188/211、receiver.rs:531) 每个分块新建一次 TCP
上传会话 UploadSession { file_name, size, chunk_size, total_chunks } —— 单文件 无目录概念
Windows 耦合 仅 3 处:direct_ap.rs(已 cfg 隔离)、pairing.rs:148 的 LOCALAPPDATA、protocol.rs:194 的 COMPUTERNAME。read_at_once 已有 unix 分支 跨平台成本比预期低得多
传输加密 无,局域网明文 HTTP 同网段任何人可读文件内容
协议实现 Rust 2845 行 / Kotlin 4423 行 / Swift 2053 行,同一协议三份实现 每加一个特性要写三遍

目录传输在现有协议下的实际代价

每个文件需要 init + chunk + finish 三次 HTTP,且每次都新建 TCP(局域网 RTT 按 2ms 计):

场景 文件数 总量 纯握手 数据传输(1GbE) 合计
代码仓库 node_modules 50 000 0.95 GB 600 s 8 s 608 s
照片目录 3 000 11.7 GB 36 s 102 s 138 s
单个大文件 1 10 GB 0 s 87 s 87 s

小文件场景 98% 的时间花在握手上。 这是本次设计的首要矛盾,不是带宽问题。


1. 核心设计决策:从「角色固定」到「对称节点」

现有架构把角色写死了:PC 是服务端,手机是客户端。三项需求全都被这个假设挡住。

v0.5 引入 QFT Node 模型——每个安装都同时具备:

┌─────────────────── QFT Node ───────────────────┐
│  身份    Ed25519 密钥对(首次运行生成,持久化)      │
│  广播端  mDNS _qft._tcp + UDP 兜底                │
│  服务端  QFT-Stream v3 监听器(接受传入会话)        │
│  客户端  QFT-Stream v3 发起器(主动连接对方)        │← 桌面端当前缺失
│  信任库  已确认过的对端公钥                        │
└────────────────────────────────────────────────┘

一旦对称,三项需求退化成同一件事:任意两个节点之间建立一条 v3 会话。PC↔PC、手机↔手机、PC↔手机走完全相同的代码路径,差别只在链路选择。


2. 需求一:跨平台桌面端

2.1 目录改名与平台抽象

windows/ → desktop/(crate 名 qft-desktop)。eframe/egui、rfd、rayon 本来就跨平台,实际要动的只有三处:

文件 现状 改法
direct_ap.rs Windows WiFi Direct,非 Windows 直接 bail! 抽成 trait LinkProvider,mac/linux 返回 Unsupported,UI 隐藏该入口
pairing.rs:148 LOCALAPPDATA directories crate:win=%LOCALAPPDATA%,mac=~/Library/Application Support,linux=$XDG_CONFIG_HOME
protocol.rs:194 COMPUTERNAME/HOSTNAME hostname crate + 各平台友好名(mac 读 ComputerName)

另需新增:默认保存目录(win=Downloads,mac=~/Downloads,linux=XDG_DOWNLOAD_DIR)、单实例锁、开机自启(可选)。

估算:这部分是整个方案里性价比最高的——三个文件加一层 trait,就拿到 macOS 与 Linux。

2.2 桌面客户端(当前完全缺失)

新增 desktop/src/client.rs,实现 Node 的发起侧。UI 上新增「附近的设备」页:

┌─ 附近的设备 ────────────────────────────┐
│  🖥  MacBook-Pro      macOS 26    ● 已信任 │
│  💻  DESKTOP-M7DEVQO  Windows 11  ○ 未信任 │
│  📱  iPhone 17 Pro    iOS 26      ● 已信任 │
│  🖥  ubuntu-dev       Linux       ○ 未信任 │
├────────────────────────────────────────┤
│  [ 拖拽文件/文件夹到此处发送 ]              │
└────────────────────────────────────────┘

拖拽是桌面端的核心交互——这也是目录直传最自然的入口。

2.3 两台 PC 怎么互相发现(没有摄像头,扫不了码)

手段 适用 说明
mDNS / DNS-SD(主) 同一局域网 服务类型 _qft._tcp,TXT 携带 v/id/name/platform/port/fp。三平台都有成熟实现:桌面 mdns-sd crate、Android NsdManager、iOS NWBrowser(P2P 已在用)
UDP 广播(兜底) mDNS 被交换机/防火墙拦时 沿用现有 QFTDISC2,升级到 v3
6 位配对码(跨网段/兜底) 不同子网、AP 隔离 接收方显示 6 位数字,发送方手输
手动 IP 极端情况 直接输 192.168.1.20:39393

QR 在 PC↔PC 场景不适用(对方没摄像头),所以 6 位配对码是 PC↔PC 的必需品,不是可选项。


3. 需求二:手机 ↔ 手机

组合 链路 状态
iOS ↔ iOS AWDL 点对点(includePeerToPeer)+ TLS-PSK 已实现(PeerLink.swift),并入 v3 即可
Android ↔ Android Wi-Fi Direct(WifiP2pManager)或 Local Only Hotspot,回落同 LAN 需新增:Android 端 v3 服务端
Android ↔ iOS 只能同一局域网 见下

关于 Android ↔ iOS 必须说清楚的限制

无路由器直连做不到,原因是两边的点对点链路互不兼容:

  • AWDL 是苹果私有链路,Android 无法参与
  • Wi-Fi Direct 走 P2P GO 协商,iOS 完全不支持
  • iOS 无法用代码加入指定 Wi-Fi(NEHotspotConfiguration 需付费账号 entitlement),所以「Android 开热点 + iOS 自动加入」这条路走不通;用户手动去设置里连是可行的,但体验很差
  • 反方向「iOS 开个人热点 + Android 自动加入」:Android 侧可以用 WifiNetworkSpecifier 自动加入,但 iOS 个人热点无法由 App 开启,且多数运营商要求蜂窝套餐

结论:Android ↔ iOS 要求两台手机连同一个 Wi-Fi。 UI 上必须直说,不能让用户在没有路由器的场合反复重试。

Android 端要补的东西

当前 Android 只有客户端。需新增:

  • NodeServer.kt:ServerSocket + v3 帧协议(不引入 HTTP 服务器依赖)
  • NsdHelper.kt:NsdManager 注册与发现
  • 前台服务 + WakeLock:长传输不被 Doze 掐断(现在只有 FLAG_KEEP_SCREEN_ON,息屏就危险)
  • 接收侧文件写入走 MediaStore / SAF 目录树(目录传输需要 ACTION_OPEN_DOCUMENT_TREE)

4. 需求三:QFT-Stream v3 —— 目录直传 + 高速索引 + 稳定连接

4.1 为什么必须换掉 HTTP

不是 HTTP 不好,是它的请求/响应模型表达不了这几件事:

  1. 接收方主动告知「我已经有哪些」(断点续传的前提)——HTTP 里只能靠客户端逐个 HEAD 探测
  2. 一个连接上并发多个文件——HTTP/1.1 无多路复用,HTTP/2 会引入大依赖
  3. 边走目录边传——索引和传输必须重叠,否则大目录要先干等几十秒

4.2 帧格式

TLS 1.3 over TCP,每会话开 N 条连接(默认 4,可调 1~8)。

u8 类型 | u32 长度(BE) | payload
类型 方向 说明
HELLO / HELLO_ACK 双向 版本、node id、能力位
SESSION_OPEN 发→收 session_id、根目录名、预估总量
INDEX_ENTRY 发→收 流式:path / size / mtime / mode,边走目录边发
INDEX_END 发→收 总文件数、总字节数(此时才知道准确进度)
HAVE 收→发 已有文件与偏移(断点续传)
FILE_OPEN / FILE_DATA / FILE_END 发→收 大文件流式,FILE_END 带该文件 SHA-256
BATCH 发→收 小文件合批,一帧塞多个完整小文件
ACK 收→发 字节水位,用于流控
PING / PONG 双向 心跳
ERROR / ABORT 双向

4.3 高速索引:流式 + 重叠

不等目录走完就开始传。索引线程用 rayon 并行遍历目录,每发现一个文件就发一条 INDEX_ENTRY,同时数据通道已经在传前面发现的文件。

10 万文件的树,遍历本身 SSD 上要 2~5 秒(Windows FindFirstFile 更慢,机械盘或网络盘可能几十秒)。重叠之后这段时间完全被隐藏。

代价:INDEX_END 之前进度条只能显示「已发现 N 个 / 已传 M 个」,拿不到百分比。这是正确的取舍——先动起来比先算准重要。

4.4 小文件合批:本方案最大的性能杠杆

阈值:< 1 MiB 合批,≥ 1 MiB 走 FILE_* 流式 + 分块并发。

小文件打进 4 MiB 的 BATCH 帧,一帧内多个完整文件,接收端顺序落盘。回到开头那张表:

场景 v2 v3 提升
5 万小文件 0.95 GB 608 s ≈ 8 s 76×
3 千张照片 11.7 GB 138 s ≈ 102 s 1.35×(已接近线速)

大文件场景本来就接近线速,提升有限;小文件场景是数量级的差异。

接收端配套优化:批量创建文件时避免每个文件一次 fsync,改为批末统一 flush;Windows 上关闭 Defender 实时扫描对目标目录的影响无法控制,但可以提示用户。

4.5 稳定连接

  • 心跳:每 5 s PING,20 s 无 PONG 判定断链
  • 自动重连:session_id 存活 10 分钟。重连后发 HAVE,从字节粒度续传,不重传已完成的文件
  • 流控:接收方按 ACK 水位反压,磁盘慢时不会把内存撑爆(现在 Android 侧 worker × chunk 就是内存峰值,没有反压)
  • 每文件独立校验:FILE_END 带 SHA-256,坏文件只重传自己,不会让一个 100 GB 的会话整体作废(现在是整份下完再校验,失败就全丢)
  • 单遍哈希:边读边算,不再像现在 Android 那样下载完再整份读一遍算 SHA-256

4.6 跨平台路径安全(容易被忽略但必须做)

目录传输一旦跨系统,这些全是真会踩的坑:

问题 处理
..、绝对路径、空段、NUL 一律拒绝,整会话中止
Windows 保留名 CON/PRN/AUX/NUL/COM1-9/LPT1-9 自动加后缀重命名,并在报告里列出
Windows 非法字符 <>:"|?*、结尾的点或空格 同上
MAX_PATH 260 Windows 侧统一走 \\?\ 长路径前缀
macOS 的 NFD 归一化 Linux 传 NFC 的「é」,macOS 存成 NFD,回传时路径对不上 → 协议层统一用 NFC,本地存储时记录原始字节
大小写冲突 Linux 目录里的 README.md 与 readme.md 传到 Windows/macOS 会撞 → 检测并加后缀,报告给用户
符号链接 默认不跟随;指向根目录内则作为链接条目传输,指向外部则跳过并警告
权限位 unix 之间保留可执行位;Windows 忽略

4.7 吞吐目标与真实瓶颈

链路 目标
千兆有线 ≥ 110 MB/s(线速 118 MB/s)
Wi-Fi 6 (160MHz) ≥ 40 MB/s
Wi-Fi 5 ≥ 20 MB/s

瓶颈按顺序:

  1. 小文件系统调用(最大)→ 合批解决
  2. TLS + SHA-256 CPU → 两者都有硬件指令加速(AES-NI / SHA-NI),实测 1~3 GB/s,不是瓶颈;但必须单遍,做两遍就变成瓶颈了
  3. 磁盘 → 大缓冲(1~4 MiB)、顺序写、批末统一 flush
  4. 单条 TCP 在 Wi-Fi 上打不满 → 多连接(默认 4)

5. 安全模型

现状是局域网明文 HTTP + 二维码里的会话令牌。二维码作为带外信道是对的,但内容明文——同网段任何人抓包就能拿到文件。

v0.5:

  • 每个节点首次运行生成 Ed25519 身份密钥对,存平台配置目录(后续可迁到 Keychain / Credential Manager / Secret Service)
  • TLS 1.3,自签证书绑定身份公钥,按公钥验证对端(不走 CA 体系)
  • 首次连接的信任建立分两种:
场景 方式
扫码(手机在场) 二维码携带对端指纹 + 一次性 PSK,扫码动作本身即确认,无需弹窗(沿用现有 QFTP2P1 思路)
mDNS 发现 / 6 位码(PC↔PC) 接收方弹「接受来自 <名字> 的传输?」,两端各显示一个由双方公钥派生的 6 位校验码,用户目视比对后确认
  • 确认后写入信任库(TOFU),之后同一对端免确认
  • 绝不自动接受未知对端

6. 代码组织:要不要做共享核心

现状是同一协议三份实现,共 9 321 行。v3 要在三端各写一遍目录传输 + 合批 + 断点续传,是三倍工作量和三倍漂移风险。

方案 优点 代价
A. 三端各写 无新工具链 3× 工作量,协议漂移
B. 共享 Rust core + FFI 一份实现 NDK/cargo-ndk、uniffi、xcframework、CI 全套
C. 桌面共享 + 移动端原生 + 共用一致性测试 桌面三平台几乎零成本共享;移动端不引入 FFI 移动端仍是两份

推荐 C。 理由:桌面三平台本来就是同一份 Rust 代码(实测只有 3 处平台耦合),共享是白拿的;而移动端上 FFI 的投入要等 v3 协议稳定后才划算。

配套:把现有 ios/CoreTests/MockPCServer.py 的做法推广成 conformance/ 一致性套件——一份黄金测试向量 + 一个参考对端,三端实现都必须跑通。这是目前防漂移最有效的手段,已经在 iOS 端验证过。

若后续移动端漂移确实变痛,再切 B,届时 v3 已定型,FFI 的收益也更清楚。


7. 兼容与分期

v2(现有 HTTP)与 v3 并存。节点在 mDNS TXT 和 /qft/ping 里声明支持的版本,双方取交集。老版本 Android/iOS 装机不受影响。

里程碑 内容 产出 依赖
M1 桌面跨平台(windows/→desktop/,3 处平台抽象)+ 桌面客户端 + mDNS + 6 位码 PC↔PC 可用(先走 v2 HTTP) 无
M2 QFT-Stream v3:帧协议、流式索引、小文件合批、断点续传、路径安全 目录直传可用,先在两台 PC 之间验证 M1
M3 移动端接入 v3:Android NodeServer + NsdManager + 前台服务;iOS PeerLink 并入 v3 手机 ↔ 电脑走 v3 M2
M4 手机↔手机:Android Wi-Fi Direct、iOS 沿用 AWDL、跨系统走 LAN 手机↔手机可用 M3
M5 一致性套件 conformance/、性能回归基准 防漂移 M2

M1 最快见效且零协议风险,建议先做完 M1 拿到真实的 PC↔PC 体验,再决定 M2 的细节。


8. 明确不做 / 做不到

  • Android ↔ iOS 无路由器直连:AWDL 与 Wi-Fi Direct 互不兼容,iOS 又不能用代码加入指定 Wi-Fi。只能同一局域网,UI 必须直说
  • Linux 的 Wi-Fi Direct / 热点:各发行版 NetworkManager 行为差异过大,不做,Linux 只支持同 LAN
  • 光学链路:不在本次范围。QFT5 位阵列方案见 OPTICAL_V5_PLAN.md,且必须先做完楔形标定
  • 公网中继 / 打洞:QFT 的定位是本地直传,引入中继会改变整个安全模型,不做

9. 主要风险

风险 影响 对策
mDNS 在企业 Wi-Fi / AP 隔离下被拦 发现不到对端 UDP 广播 + 6 位码 + 手动 IP 三重兜底
大目录索引占内存 10 万文件的清单常驻 流式索引,接收端落盘为 sqlite/紧凑二进制,不全量驻留
Android 后台被杀 长传输中断 前台服务 + WakeLock + 会话可恢复(v3 断点续传)
三端协议漂移 联调地狱 conformance/ 一致性套件,CI 强制
TLS 引入依赖体积 移动端包变大 桌面用 rustls;Android 用系统 SSLSocket;iOS 用 Network.framework(已在用)