Files
QFT/ios
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
..

QFT iOS 客户端 v0.4.7

三种传输方式:

方向 链路 说明
电脑 → iPhone 局域网 HTTP 扫 Windows 端的 QFTSEND2 码,自动下载,支持断点续传
iPhone → 电脑 局域网 HTTP 扫 QFTPAIR2 码,选文件后并行分块上传
iPhone ↔ iPhone 点对点直连 发送方显示二维码,接收方扫码,不需要连同一个 Wi-Fi

打开工程

open ios/QFT.xcodeproj

工程已提交到仓库,不需要 XcodeGen 之类的额外工具。首次构建前在 Target → Signing & Capabilities 里选一下你自己的开发者账号(免费账号即可, 生成的描述文件 7 天有效)。

增删源文件后重新生成工程:

python3 ios/tools/generate_xcodeproj.py
  • 最低系统:iOS 17.0
  • Bundle ID:com.qft.transfer(按需改 generate_xcodeproj.py 里的常量)

隔空投送式点对点传输

PeerLink 用 Network.framework 并打开 includePeerToPeer。底层就是 AirDrop 用的那条链路——BLE 发现 + AWDL 点对点 Wi-Fi,两台设备不需要路由器, 也不需要连同一个 Wi-Fi。两端在同一个 Wi-Fi 下时它会自动优先走基础网络。

握手用 TLS-PSK:预共享密钥(32 字节)由发送端随机生成并写进二维码, 扫码这个动作本身就完成了带外密钥交换与双向认证。没扫到码的第三方 连上来也过不了 TLS 握手,因此不需要任何证书体系,也不需要配对弹窗。

发送方                                  接收方
选文件 → 算 SHA-256
启动 NWListener(Bonjour: _qft-p2p._tcp)
生成 32 字节 PSK
显示 QFTP2P1 二维码  ──────扫码────→  解析出 PSK + 服务实例名
                                        NWBrowser 找到实例
        ←──────── TLS-PSK 握手 ────────→
MANIFEST(JSON) ─────────────────────→  校验与二维码是否一致
DATA × N       ─────────────────────→  落盘 + 增量 SHA-256
EOF            ─────────────────────→
        ←──────── RESULT(JSON) ────────  校验通过才 rename

AWDL 是苹果私有链路,Windows 无法参与,所以与电脑互传仍走局域网 HTTP。 如果现场没有路由器,可行的替代是让 iPhone 开个人热点、电脑连上来。

已知的 iOS 平台限制

  1. 无法用代码连接指定 Wi-Fi。 Android 端用 WifiNetworkSpecifier 自动加入 Windows 的 QFT Direct AP,iOS 对应的 NEHotspotConfiguration 需要 HotspotConfiguration entitlement,免费开发者账号拿不到。因此 iOS 端 不实现 Direct AP 流程,PairingProtocol 在二维码不带可用 endpoint 时 会直接拒绝,而不是给用户一个连不上的假成功。
  2. 首次访问局域网会弹权限窗。 已在 Info.plist 声明 NSLocalNetworkUsageDescription 与 NSBonjourServices。 若用户误点了拒绝,需要去 设置 → 隐私与安全性 → 本地网络 里重新打开。
  3. 没有「下载」文件夹。 收到的文件存在 App 的 Documents/QFT 下, 通过 UIFileSharingEnabled + LSSupportsOpeningDocumentsInPlace 暴露到「文件」App,也可以在 App 内直接分享出去。
  4. 上传块固定 4 MiB。 Android 端按文件大小选 4/8/16 MiB,但 iOS 上 worker 数 × 块大小 就是内存峰值,16 MiB × 6 会在旧机型触发 jetsam。 4 MiB × 6 = 24 MiB 峰值,局域网速度下每块的往返开销可以忽略。

测试

核心层(协议、发现、上传、下载、P2P 链路)不依赖 UIKit, 可以直接以 macOS 为目标编译运行,不需要 Xcode,也不需要模拟器:

./ios/CoreTests/run.sh

也已接入主自检套件(python scripts/run_all_selftests.py)。

测试内容:

  • Base64URL 与三端一致性(含 200 组随机字节往返)
  • QFTPAIR2 / QFTSEND2 / QFTP2P1 解析,含各类畸形输入
  • 端点白名单:二维码是不可信输入,只接受字面量私有 IPv4 + 声明端口。 已覆盖域名、公网地址、172.32 边界、非规范八位组、IPv6、带凭据/路径/query 等 11 种拒绝用例
  • 与 MockPCServer.py 的完整传输:该 mock 严格复刻 receiver.rs / sender.rs 的线上语义(路径、header 名、JSON 字段、Range 行为、chunk 长度校验), 因此这组测试就是 Swift 端与 Rust 端的线格式契约测试——任何一边改了协议都会红
  • 真实 TLS-PSK 握手下的 P2P 端到端传输,含错误密钥必须被拒

目录

ios/
  QFT.xcodeproj/          生成的工程(已提交)
  QFT/
    Info.plist            权限声明、Bonjour 服务、ATS 本地网络例外
    App/                  SwiftUI 界面 + 相机扫码(需要 Xcode 才能构建)
    Core/                 纯 Foundation,可在 macOS 上编译测试
      Base64URL.swift
      PairingProtocol.swift   QFTPAIR2 / QFTSEND2 + 端点白名单
      HostDiscovery.swift     endpoint 探测 → UDP 广播 → 子网扫描
      DownloadClient.swift    流式落盘 + 增量 SHA-256 + Range 续传
      UploadClient.swift      init/chunk/finish 并行上传
      PeerPairing.swift       QFTP2P1 配对码
      PeerLink.swift          TLS-PSK + 分帧的点对点链路
  CoreTests/
    run.sh                编译并运行(swiftc,无需 Xcode)
    main.swift            测试用例
    MockPCServer.py       复刻 Windows 端线上语义的假电脑
  tools/
    generate_xcodeproj.py 工程生成器