Files
zhy200308 eae24000e9 优化IOS
2026-08-19 09:31:21 +08:00

14 KiB
Raw Permalink Blame History

QFT iOS 客户端 v0.5.0

对齐当前 Windows / macOS / Android 三端的能力,四条链路:

方向 链路 说明
电脑 → iPhone(光学) 屏幕 → 摄像头 扫电脑「光学传输」页循环播放的 QFT2 二维码,文件数据完全不经过网络
iPhone ↔ Windows 专用网络(QFT Direct) 扫码后加入电脑开的专用 Wi-Fi,从路由表认出网关即电脑
iPhone ↔ Mac / Linux 局域网 扫二维码,或直接输电脑上的连接码;下发走 8 路并行 Range
iPhone ↔ iPhone 隔空(AWDL 点对点) 多选文件后显示二维码,对方扫一下即可,不需要连同一个 Wi-Fi

本次改动只在 ios/ 目录内,未改动 desktop/(Windows/macOS/Linux)与 android/ 的任何实现。

系统版本与向下兼容

  • 最低系统:iOS 15.0,覆盖 iPhone 6s(2015)及以后,与 Android 端 minSdk 24 (Android 7.0,2016)覆盖的机型年代大致相当。
  • 再往下走不动了:URLSession 的 async 接口是 iOS 15 才有的,低于 15 就要把 全部网络代码改回 completion handler,代价与收益不成比例。
  • 新系统上更好的实现照样用,但一律走 App/Compatibility.swift 分叉,不把整个 App 的部署目标顶上去:
    • NavigationStack / ShareLink / LabeledContent(iOS 16)→ iOS 15 上分别回落 NavigationView / UIActivityViewController / 手写 HStack;
    • 两参数 onChange(iOS 17)→ 统一用 onReceive;
    • videoRotationAngle(iOS 17)→ iOS 15/16 上用 videoOrientation;
    • UnsafeRawPointer.loadUnaligned(Swift 5.7 运行时 / iOS 16)→ 改成手工拼大端 与 memcpy。

打开工程

open ios/QFT.xcodeproj

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

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

python3 ios/tools/generate_xcodeproj.py

Bundle ID:com.qft.transfer(按需改 generate_xcodeproj.py 里的常量)。

光学接收(不用网络的那条)

首页「光学接收」对准电脑的「光学传输」页即可。这条链路上文件数据只经过屏幕和 摄像头——Wi-Fi、蓝牙、局域网、互联网都不参与,因此也是「电脑不允许接任何网络」 场合下唯一可用的路径。

实现与 Android 端同一套状态机,只是解码器换成 Vision:

居中搜索(92% 画面)
   ↓ 解出一帧
按条码外接框建立 ROI(放大 1.22 倍、按像素修成正方形)
   ↓
后续只把 ROI 交给 Vision
   ↓ 轻微移动:平滑跟随(alpha 0.35)
   ↓ 连续 3 帧丢失:逐级放大 ROI
   ↓ 连续 12 帧丢失:回到全画面重新搜索

其它与 Android 对齐的点:

  • 相机格式在「支持 ≥60 FPS 的格式里取分辨率最高的」,锁定固定帧率,关 HDR 与防抖;
  • alwaysDiscardsLateVideoFrames,追不上就丢,不播放过时的相机帧;
  • 锁定后每 2.5 秒在 ROI 中心重新对焦/测光(屏幕是平面光源,连续自动对焦会拉风箱);
  • 屏幕上同一帧会被连续拍到多次,重复帧不会重复送进装配器;UI 同时显示 解码/s 和有效新帧/s——决定传输时间的是后者,据此在电脑端选 30 / 45 / 60 FPS;
  • 每帧 CRC32 + 整份 SHA-256,校验不过就整份丢弃等下一轮重播,绝不把半份文件交给用户。

专用网络(iPhone ↔ Windows)

Windows 进入接收后会用 Wi-Fi Direct Legacy AP 开一张专用网,二维码里按设计不带 任何电脑地址(见 desktop/src/pairing.rs::qr_endpoints):手机必须先加入那张 Wi-Fi,再从路由表里把网关认出来——那就是电脑。

iOS 侧两条路径,取决于签名能力:

情况 行为
有 HotspotConfiguration entitlement NEHotspotConfiguration 自动加入(joinOnce,会话结束不留在系统 Wi-Fi 列表里)
没有(免费账号) 显示 SSID / 密码 + 「打开设置」,用户手动连一次,回 App 点「我已连上」继续

不会假装成功:拿不到能力时直接转手动引导,而不是让用户对着一个永远连不上的 进度条等下去。

entitlement 只有付费账号签得出来,带上它免费账号会直接签名失败,因此工程默认 不引用 QFT/QFT.entitlements。要开启:

Target → Build Settings → QFT_ENTITLEMENTS = QFT/QFT.entitlements

加入之后判据不是「系统说加好了」,而是协议层握手成功——能用正确令牌 ping 通 /qft/ping 才算数。系统接受配置 ≠ 拿到 IPv4 ≠ 电脑那侧的 Wi-Fi Direct 数据通道已建立。

局域网(iPhone ↔ Mac / Linux)

两种入口:

  1. 扫二维码:和 Windows 的 LAN 模式完全一样。
  2. 连接码:电脑上打开 QFT →「电脑 ↔ 电脑」→「我要接收」,屏幕上会显示 K7M2-9X4P-QR3T 这样一串码,地址、端口和配对秘密都编在码里。iPhone 在 「连接附近的电脑」页输入即可,不用扫码、不要求同网段可广播。

「附近的电脑」列表用 QFTBROWSE3 广播(desktop/src/discovery.rs 的客户端实现), 只是帮用户确认「就是这台」;真正建立会话仍然靠连接码换令牌(POST /qft/pair)。 电脑端输错 5 次即作废整个码,所以 App 绝不重试。

边界说清楚:连接码换来的是电脑接收端的会话,因此这条路径只能「把文件发到 电脑」。要让电脑下发文件,请在电脑上选好文件后扫它生成的二维码。

更高效在哪

电脑下发改成 8 路并行 Range 下载:

  • 块大小按文件自适应,落在 64 KiB–16 MiB,目标 8 路并发;
  • 每块最多重试 5 次,403 立即失败不重试;
  • 完成情况写进 .qftpart 旁边的账本(并行块是乱序落盘的,「已落盘长度即断点」 那套在这里不成立),中断后只补没收到的块;
  • 全部收齐后单遍 SHA-256,通过才 rename;
  • 对端返回 200(忽略了 Range)时显式失败并回落单流下载,不会因为遇到老版本 电脑端就直接报错。

隔空(iPhone ↔ iPhone)

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

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

v0.5.0 起支持多文件队列(对齐 Android → Android 的手机互传):

发送方                                   接收方
多选文件 → 逐个算 SHA-256
启动 NWListener(Bonjour: _qft-p2p._tcp)
生成 32 字节 PSK
显示 QFTP2P2 二维码  ──────扫码────→  解析出 PSK + 服务实例名 + 清单摘要
                                        NWBrowser 找到实例
        ←──────── TLS-PSK 握手 ────────→
QUEUE(JSON 清单) ───────────────────→  摘要必须与二维码一致
FILE_BEGIN / DATA×N / FILE_END ─────→  逐个落盘 + 单文件 SHA-256
        (对队列里每个文件重复)
EOF             ────────────────────→
        ←──────── RESULT(JSON) ────────  全部通过才算成功

文件清单不进二维码,只放一个 SHA-256 摘要:十几个文件的元数据会让二维码密到 扫不动。清单在 TLS 建立之后才传,接收端拿摘要比对——扫码这一下依然锁定了 「你看到的就是你收到的」。摘要对的是清单帧的原始字节,不是重新序列化的结果。

QFTP2P1(单文件)已移除。iOS 端从未发布过,保留一个没有用户的线格式只会腐坏。

AWDL 是苹果私有链路,Windows/Android 无法参与,所以与电脑互传仍走局域网/专用网络 HTTP,与 Android 手机互传只能同一个局域网。

已知的平台限制

  1. 没有「下载」文件夹。 收到的文件存在 App 的 Documents/QFT 下,通过 UIFileSharingEnabled + LSSupportsOpeningDocumentsInPlace 暴露到「文件」App, 也可以在 App 内直接分享出去。
  2. 首次访问局域网会弹权限窗。 已在 Info.plist 声明 NSLocalNetworkUsageDescription 与 NSBonjourServices。若用户误点了拒绝,需要去 设置 → 隐私与安全性 → 本地网络 里重新打开。
  3. 上传块固定 4 MiB。 Android 端按文件大小选 4/8/16 MiB,但 iOS 上 worker 数 × 块大小 就是内存峰值,16 MiB × 6 会在旧机型触发 jetsam。 4 MiB × 6 = 24 MiB 峰值,局域网速度下每块的往返开销可以忽略。
  4. 光学链路是单向的,只有「电脑 → iPhone」。iPhone 屏幕小、电脑普遍没有摄像头, 反方向没有意义。

测试

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

./ios/CoreTests/run.sh

也已接入主自检套件(python scripts/run_all_selftests.py)。当前 180 项检查全绿。

测试内容:

  • Base64URL、Base45 与三端一致性(Base45 用的是 desktop/src/base45.rs 里的同一组向量)
  • QFTPAIR2 / QFTSEND2 / QFTP2P2 解析,含各类畸形输入
  • 端点白名单:二维码是不可信输入,只接受字面量私有 IPv4 + 声明端口。 已覆盖域名、公网地址、172.32 边界、非规范八位组、IPv6、带凭据/路径/query 等 11 种拒绝用例
  • 专用网络:只带 Wi-Fi 凭据的二维码被接受,既无地址又无凭据的被拒; 有/无 entitlement 时的决策分支
  • 光学链路:合成 QFT2 播放列表 →「乱序 + 重复」重播 → 落盘校验; CRC 篡改整帧丢弃;清单摘要不符整份丢弃;0 字节文件边界;ROI 状态机的 锁定 / 放大 / 重新搜索 / 越界夹取
  • 连接码:四组向量由 Rust 实现直接产出,任何一边改了编码都会红; Crockford 容错、改一位必须失败、公网地址必须被白名单拒绝
  • 与 MockPCServer.py 的完整传输:该 mock 严格复刻 receiver.rs / sender.rs 的线上语义(路径、header 名、JSON 字段、Range 行为、chunk 长度校验、 /qft/pair 的错 5 次作废),因此这组测试就是 Swift 端与 Rust 端的线格式契约测试
  • 8 路并行 Range 下载与按账本续传
  • 真实 TLS-PSK 握手下的 P2P 多文件端到端传输,含错误密钥与清单摘要不符必须被拒

只有真机能验的部分

以下需要你在设备上跑,这台机器上没有 Xcode(只有 Command Line Tools), App 层(SwiftUI + AVFoundation + Vision + NetworkExtension)无法在此编译:

  • Xcode 打开工程,选模拟器 ⌘B 通过
  • 光学接收的真机吞吐矩阵(电脑 30 / 45 / 60 FPS × 机型),记录有效新帧/s
  • 加入 Windows QFT Direct 专用网(分别验证有/无 entitlement 两条路径)
  • iPhone ↔ iPhone 在关掉 Wi-Fi 路由器的场合走 AWDL
  • iOS 15 / 16 / 17+ 各跑一遍(兼容层分叉都要走到)

目录

ios/
  QFT.xcodeproj/          生成的工程(已提交)
  QFT/
    Info.plist            权限声明、Bonjour 服务、ATS 本地网络例外
    QFT.entitlements      HotspotConfiguration(默认不引用,见上文)
    App/                  SwiftUI 界面(需要 Xcode 才能构建)
      Compatibility.swift     iOS 15/16/17 分叉
      HomeView.swift
      ScannerView.swift       配对码扫描(AVCaptureMetadataOutput)
      OpticalReceiveView.swift 光学接收(AVCaptureVideoDataOutput + Vision + ROI)
      DesktopConnectView.swift 附近的电脑 / 连接码 / 手动加入专用 Wi-Fi
      TransferModel.swift
    Core/                 纯 Foundation/Network,可在 macOS 上编译测试
      Base64URL.swift
      Base45.swift            RFC 9285,光学帧文本层
      Checksums.swift         CRC-32(光学帧)/ CRC-8(连接码)
      PairingProtocol.swift   QFTPAIR2 / QFTSEND2 + 端点白名单
      ConnectCode.swift       桌面端连接码
      HostDiscovery.swift     endpoint → 网关 → UDP 广播 → 子网扫描
      RouteTable.swift        sysctl 路由表 / 定向广播 / 候选地址
      PeerBrowser.swift       QFTBROWSE3 节点浏览 + POST /qft/pair
      DedicatedNetwork.swift  专用 Wi-Fi 加入策略与 NEHotspotConfiguration
      DownloadClient.swift    单流下载(回落路径)
      RangeDownloadClient.swift 8 路并行 Range + 断点账本
      UploadClient.swift      init/chunk/finish 并行上传
      OpticalProtocol.swift   QFT2 / QFT1 帧与清单
      OpticalROI.swift        ROI 状态机(纯几何)
      OpticalAssembler.swift  会话装配、校验、落盘、速率统计
      PeerPairing.swift       QFTP2P2 配对码 + 文件清单
      PeerLink.swift          TLS-PSK + 分帧的点对点链路
  CoreTests/
    run.sh                编译并运行(swiftc,无需 Xcode)
    main.swift            测试用例
    MockPCServer.py       复刻 Windows/macOS 端线上语义的假电脑
  tools/
    generate_xcodeproj.py 工程生成器