优化IOS
This commit is contained in:
+189
-49
@@ -1,12 +1,30 @@
|
||||
# QFT iOS 客户端 v0.4.7
|
||||
# QFT iOS 客户端 v0.5.0
|
||||
|
||||
三种传输方式:
|
||||
对齐当前 Windows / macOS / Android 三端的能力,四条链路:
|
||||
|
||||
| 方向 | 链路 | 说明 |
|
||||
|---|---|---|
|
||||
| 电脑 → iPhone | 局域网 HTTP | 扫 Windows 端的 `QFTSEND2` 码,自动下载,支持断点续传 |
|
||||
| iPhone → 电脑 | 局域网 HTTP | 扫 `QFTPAIR2` 码,选文件后并行分块上传 |
|
||||
| **iPhone ↔ iPhone** | **点对点直连** | 发送方显示二维码,接收方扫码,**不需要连同一个 Wi-Fi** |
|
||||
| 电脑 → 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`。
|
||||
|
||||
## 打开工程
|
||||
|
||||
@@ -24,74 +42,179 @@ Target → Signing & Capabilities 里选一下你自己的开发者账号(免
|
||||
python3 ios/tools/generate_xcodeproj.py
|
||||
```
|
||||
|
||||
- 最低系统:iOS 17.0
|
||||
- Bundle ID:`com.qft.transfer`(按需改 `generate_xcodeproj.py` 里的常量)
|
||||
Bundle ID:`com.qft.transfer`(按需改 `generate_xcodeproj.py` 里的常量)。
|
||||
|
||||
## 隔空投送式点对点传输
|
||||
## 光学接收(不用网络的那条)
|
||||
|
||||
`PeerLink` 用 `Network.framework` 并打开 `includePeerToPeer`。底层就是
|
||||
AirDrop 用的那条链路——BLE 发现 + AWDL 点对点 Wi-Fi,两台设备不需要路由器,
|
||||
也不需要连同一个 Wi-Fi。两端在同一个 Wi-Fi 下时它会自动优先走基础网络。
|
||||
首页「光学接收」对准电脑的「光学传输」页即可。这条链路上文件数据**只经过屏幕和
|
||||
摄像头**——Wi-Fi、蓝牙、局域网、互联网都不参与,因此也是「电脑不允许接任何网络」
|
||||
场合下唯一可用的路径。
|
||||
|
||||
握手用 **TLS-PSK**:预共享密钥(32 字节)由发送端随机生成并写进二维码,
|
||||
扫码这个动作本身就完成了带外密钥交换与双向认证。没扫到码的第三方
|
||||
连上来也过不了 TLS 握手,因此不需要任何证书体系,也不需要配对弹窗。
|
||||
实现与 Android 端同一套状态机,只是解码器换成 Vision:
|
||||
|
||||
```text
|
||||
居中搜索(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`。要开启:
|
||||
|
||||
```
|
||||
发送方 接收方
|
||||
选文件 → 算 SHA-256
|
||||
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
|
||||
显示 QFTP2P1 二维码 ──────扫码────→ 解析出 PSK + 服务实例名
|
||||
显示 QFTP2P2 二维码 ──────扫码────→ 解析出 PSK + 服务实例名 + 清单摘要
|
||||
NWBrowser 找到实例
|
||||
←──────── TLS-PSK 握手 ────────→
|
||||
MANIFEST(JSON) ─────────────────────→ 校验与二维码是否一致
|
||||
DATA × N ─────────────────────→ 落盘 + 增量 SHA-256
|
||||
EOF ─────────────────────→
|
||||
←──────── RESULT(JSON) ──────── 校验通过才 rename
|
||||
QUEUE(JSON 清单) ───────────────────→ 摘要必须与二维码一致
|
||||
FILE_BEGIN / DATA×N / FILE_END ─────→ 逐个落盘 + 单文件 SHA-256
|
||||
(对队列里每个文件重复)
|
||||
EOF ────────────────────→
|
||||
←──────── RESULT(JSON) ──────── 全部通过才算成功
|
||||
```
|
||||
|
||||
**AWDL 是苹果私有链路,Windows 无法参与**,所以与电脑互传仍走局域网 HTTP。
|
||||
如果现场没有路由器,可行的替代是让 iPhone 开个人热点、电脑连上来。
|
||||
**文件清单不进二维码**,只放一个 SHA-256 摘要:十几个文件的元数据会让二维码密到
|
||||
扫不动。清单在 TLS 建立之后才传,接收端拿摘要比对——扫码这一下依然锁定了
|
||||
「你看到的就是你收到的」。摘要对的是**清单帧的原始字节**,不是重新序列化的结果。
|
||||
|
||||
## 已知的 iOS 平台限制
|
||||
> QFTP2P1(单文件)已移除。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 上
|
||||
**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,
|
||||
核心层(协议、发现、上传/下载、光学解码、P2P 链路)不依赖 UIKit/AVFoundation,
|
||||
可以直接以 macOS 为目标编译运行,**不需要 Xcode,也不需要模拟器**:
|
||||
|
||||
```bash
|
||||
./ios/CoreTests/run.sh
|
||||
```
|
||||
|
||||
也已接入主自检套件(`python scripts/run_all_selftests.py`)。
|
||||
也已接入主自检套件(`python scripts/run_all_selftests.py`)。当前 180 项检查全绿。
|
||||
|
||||
测试内容:
|
||||
|
||||
- `Base64URL` 与三端一致性(含 200 组随机字节往返)
|
||||
- `QFTPAIR2` / `QFTSEND2` / `QFTP2P1` 解析,含各类畸形输入
|
||||
- `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 长度校验),
|
||||
因此这组测试就是 Swift 端与 Rust 端的**线格式契约测试**——任何一边改了协议都会红
|
||||
- **真实 TLS-PSK 握手**下的 P2P 端到端传输,含错误密钥必须被拒
|
||||
的线上语义(路径、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+ 各跑一遍(兼容层分叉都要走到)
|
||||
|
||||
## 目录
|
||||
|
||||
@@ -100,19 +223,36 @@ ios/
|
||||
QFT.xcodeproj/ 生成的工程(已提交)
|
||||
QFT/
|
||||
Info.plist 权限声明、Bonjour 服务、ATS 本地网络例外
|
||||
App/ SwiftUI 界面 + 相机扫码(需要 Xcode 才能构建)
|
||||
Core/ 纯 Foundation,可在 macOS 上编译测试
|
||||
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 + 端点白名单
|
||||
HostDiscovery.swift endpoint 探测 → UDP 广播 → 子网扫描
|
||||
DownloadClient.swift 流式落盘 + 增量 SHA-256 + Range 续传
|
||||
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 并行上传
|
||||
PeerPairing.swift QFTP2P1 配对码
|
||||
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 端线上语义的假电脑
|
||||
MockPCServer.py 复刻 Windows/macOS 端线上语义的假电脑
|
||||
tools/
|
||||
generate_xcodeproj.py 工程生成器
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user