对应 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)
16 KiB
QFT v0.5 增量设计:全平台对等互传
基线 v0.4.7。三项增量需求:
- 电脑 ↔ 电脑互传,跨平台(mac ↔ win ↔ mac,linux ↔ win ↔ mac)
- 手机 ↔ 手机互传
- 全量高速传输,支持目录直传,高速索引 + 稳定连接
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 不好,是它的请求/响应模型表达不了这几件事:
- 接收方主动告知「我已经有哪些」(断点续传的前提)——HTTP 里只能靠客户端逐个 HEAD 探测
- 一个连接上并发多个文件——HTTP/1.1 无多路复用,HTTP/2 会引入大依赖
- 边走目录边传——索引和传输必须重叠,否则大目录要先干等几十秒
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 |
瓶颈按顺序:
- 小文件系统调用(最大)→ 合批解决
- TLS + SHA-256 CPU → 两者都有硬件指令加速(AES-NI / SHA-NI),实测 1~3 GB/s,不是瓶颈;但必须单遍,做两遍就变成瓶颈了
- 磁盘 → 大缓冲(1~4 MiB)、顺序写、批末统一 flush
- 单条 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(已在用) |