admin
44096069a7
- 发送端流式（R-iOS-4）：新增 FileSource 抽象（web/src/features/transfer/source.ts），iOS 经 HTTP Range 惰性拉取（原生 WKURLSchemeHandler 认 Range 头 seek 回 206），整文件不进 WebView 内存；web/桌面经 fileSource 包装字节不变。p2p/relay/transfer 改吃 FileSource - 后台续传：iOS 26 BGContinuedProcessingTask（BackgroundTaskManager + AppDelegate 注册 + BGTaskSchedulerPermittedIdentifiers），引擎传输进度驱动系统进度 UI - APNs：后端 internal/apns（ES256 .p8 JWT + HTTP/2，仿 internal/push）+ push_subscriptions.platform 列 + POST /api/push/apns/register + transfer/message 未投递分支分流；原生 PushRegistry 授权 + 设备令牌经引擎桥 registerPush 上报；aps-environment + remote-notification 后台模式 - Share Extension：CDropShare appex 抓文件 → App Group 收件箱 → cdrop://share 深链唤主程序选设备发送（只交接、不跑引擎） - 控制中心剪贴板两控件：CDropWidgets widgetkit appex（ControlWidget + AppIntent + 纯原生 ClipboardClient REST）；用专用 broker 设备会话（主程序经引擎 provisionWidgetSession 代铸独立 device_id 会话存 App Group，控件自刷不与引擎抢 refresh 轮换） - 真机分发预备：committed 签名改 ad-hoc 使模拟器 entitlement 生效；真机手动签名 scaffold（Signing.xcconfig 仅 device SDK 套 Manual + gitignore 的 Local.xcconfig 填 Team/profile）+ just ios-device / ios-devices 全 CLI 装机；包名改 net.commilitia.Commilitia-Drop（含 .share/.widgets，BG task 前缀同改）；REALDEVICE.md 重写为门户 + CLI 装机手册 - I18n.swift 移 Shared/ 供三 target 共用；i18n 加 ios.bg/share/control.* 键 - ultracode 多 agent 审查修复（0 HIGH，2 MED + 7 LOW）：分享 send 后留收件箱致重发→move 私有暂存；WidgetSession 锁屏文件保护→UntilFirstUserAuthentication；outgoing/安全作用域登出释放；控件 device_id 登出清理；并发控件 refresh CAS-before-clear；APNs 读 reason + prune bad token + bust 过期 JWT；APNSEnv 大小写归一；Share-ext completeRequest 挪进 open 回调
89 lines
6.0 KiB
Markdown
89 lines
6.0 KiB
Markdown
# cdrop iOS 真机分发手册
|
||
|
||
把 cdrop 装到你自己的 iPhone（开发签名，1 年 profile）。代码侧全部就绪并经模拟器验证；真机只差**账号 + 门户 + 签名**这一层。本手册走**手动签名 + 全 CLI**路线——门户你手动建（一次），构建装机一条命令，**全程不碰 Xcode GUI**。
|
||
|
||
## 包名与标识（门户里要用的）
|
||
|
||
| 项 | 值 |
|
||
|---|---|
|
||
| 主 app Bundle ID | `net.commilitia.Commilitia-Drop` |
|
||
| Share Extension | `net.commilitia.Commilitia-Drop.share` |
|
||
| 控件扩展 | `net.commilitia.Commilitia-Drop.widgets` |
|
||
| App Group | `group.net.commilitia.cdrop`（与包名相互独立，刻意不同名） |
|
||
| APNs topic（服务端 `CDROP_APNS_TOPIC`） | `net.commilitia.Commilitia-Drop` |
|
||
|
||
## 前置
|
||
- 付费 Apple Developer Program（$99/年）。
|
||
- 一台 iPhone（iOS 26）+ Mac（Xcode 26 命令行工具）。
|
||
- 一个已登录的 cdrop（网页 / 桌面）——用来扫码批准本机登录。
|
||
|
||
---
|
||
|
||
## A. 门户操作（developer.apple.com/account，一次性）
|
||
|
||
> 入口：登录后左侧 **Certificates, Identifiers & Profiles**（证书 / 标识符 / 描述文件总枢纽）——A1–A5 都在这里面；A6 在 **Keys**；Team ID 在 **Membership details**（10 位，记下）。
|
||
|
||
1. **证书**（Apple Development）：本机「钥匙串访问」可能已有（「我的证书」分类里看）。没有就：钥匙串访问菜单 → 证书助理 → 从证书颁发机构请求证书 → 存到磁盘 → 门户 **Certificates** → ＋ → Apple Development → 传 CSR → 下载 `.cer` 双击安装。
|
||
2. **App IDs ×3**（**Identifiers** → ＋ → App IDs → App，Bundle ID 选 **Explicit**）：
|
||
- `net.commilitia.Commilitia-Drop` — 勾 **App Groups** + **Push Notifications**
|
||
- `net.commilitia.Commilitia-Drop.share` — 勾 **App Groups**
|
||
- `net.commilitia.Commilitia-Drop.widgets` — 勾 **App Groups**
|
||
3. **App Group**：**Identifiers** 页类型筛选切到 **App Groups** → ＋ → `group.net.commilitia.cdrop`。再回上面 3 个 App ID 各自的 App Groups 能力里 **Edit/Configure** 关联它（三个都要）。
|
||
4. **设备**：**Devices** → ＋ → 填 UDID（插上手机后 `just ios-devices` 读）。
|
||
5. **描述文件 ×3**（**Profiles** → ＋ → **iOS App Development**，非 Distribution）：每个选对应 App ID + 证书 + 设备，命名清楚（建议 `CDrop Dev` / `CDrop Share Dev` / `CDrop Widgets Dev`）→ 下载 → 双击安装。
|
||
6. **APNs Auth Key**（**Keys** → ＋ → 勾 Apple Push Notifications service）：下载 `AuthKey_XXXXX.p8`（仅一次），记 **Key ID** + **Issuer ID**（服务端发推送用，见 D）。这把 `.p8` 与 A1 的证书是两码事。
|
||
|
||
> 常见坑：Bundle ID 选 **Explicit** 不是 Wildcard；App Group 务必 3 个 App ID 都关联；Profile 选 **Development** 不要 Distribution。
|
||
|
||
---
|
||
|
||
## B. 本地签名配置（gitignore，填一次）
|
||
|
||
在 `ios/CDrop/Local.xcconfig` 写入（此文件已 gitignore，公开仓库不留你的账号标识）：
|
||
|
||
```
|
||
CDROP_TEAM_ID = ABCDE12345
|
||
CDROP_PROFILE_APP = CDrop Dev
|
||
CDROP_PROFILE_SHARE = CDrop Share Dev
|
||
CDROP_PROFILE_WIDGETS = CDrop Widgets Dev
|
||
```
|
||
|
||
- `CDROP_TEAM_ID`＝A0 的 Team ID；三个 `CDROP_PROFILE_*`＝A5 你起的 profile 名（**名字**，不是文件路径）。
|
||
- 机制：`Signing.xcconfig`（已提交）仅对 **device SDK（iphoneos）** 套用手动签名 + 这些值；**模拟器**仍走 `project.yml` 的 ad-hoc（`CODE_SIGN_IDENTITY = "-"`），故缺 `Local.xcconfig` 也不影响模拟器构建。
|
||
|
||
---
|
||
|
||
## C. 构建装机（全 CLI）
|
||
|
||
```sh
|
||
just ios-devices # 手机插 USB，读 UDID（填进门户 A4 + 下行）
|
||
just ios-device <你的设备UDID> # 真机构建（手动签名）+ devicectl 装机
|
||
```
|
||
|
||
- `just ios-device` ＝ `xcodegen generate` → `xcodebuild`（device，手动签名走 `Local.xcconfig`）→ `xcrun devicectl device install app`。无 Xcode GUI。
|
||
- 首次装机后，iPhone 上首启该开发者 app 即可直接跑（付费 ADP 开发证书，无需手动「信任开发者」）。
|
||
|
||
---
|
||
|
||
## D. 服务端前置
|
||
|
||
1. **引擎可达**：真机上引擎 WebView 加载 `https://drop.commilitia.net/engine.html`——**该文件随 cdrop 二进制部署到 prod**（`//go:embed` 进 binary，`just docker-image` 含最新 `dist`）。手机要用，prod 须是含本轮改动的最新部署。
|
||
2. **APNs 真发**：把 A6 的 `.p8` 放到服务器，给后端容器配 `CDROP_APNS_KEY_PATH` / `CDROP_APNS_KEY_ID` / `CDROP_APNS_TEAM_ID` / `CDROP_APNS_TOPIC=net.commilitia.Commilitia-Drop` / `CDROP_APNS_ENV`（Xcode 开发构建的 device token 属 **sandbox**，故联调填 `sandbox`）。缺配置则推送惰性关闭，其余功能照常。
|
||
3. 本机联调可选：环境变量 `CDROP_ENGINE_URL` 指向可达引擎。
|
||
|
||
---
|
||
|
||
## E. 只能真机验的清单
|
||
|
||
代码已实现，下列是真机才能验的点：
|
||
|
||
- [ ] 液态玻璃真机渲染（陀螺仪高光 / 动效）。
|
||
- [ ] 扫码登录：本机显码 → 已登录 cdrop 扫码批准 → 进主界面（强制 full/persist）。
|
||
- [ ] **本地网络权限 + 同内网直连**（R-iOS-6）：首次同内网传输弹 `NSLocalNetworkUsageDescription`；授予后 ICE 收 host 候选、走真直连；拒绝则回退中继仍可传。
|
||
- [ ] 发送 / 接收：选文件 → 选设备 → 对端收到；对端发来落 Files（Documents）。
|
||
- [ ] **大文件流式发送**（R-iOS-4 已实现）：发大文件，WebView 内存应有界（按 Range 块拉取，不整文件入内存）。
|
||
- [ ] **后台续传**（R-iOS-1 / R-iOS-3）：传输中切后台 → `BGContinuedProcessingTask` 系统进度 UI；验 WKWebView JS 是否随之保活（不保活则退化为回前台续传，可接受）。
|
||
- [ ] **APNs 推送**：离线设备收「收到文件」通知（需 D2 的 `.p8`）。
|
||
- [ ] **Share Extension**：别的 app 分享 → 选 Commilitia Drop → 唤起主 app 选设备发送。
|
||
- [ ] **控制中心剪贴板两控件**：控制中心加「上传 / 拉取剪贴板」控件 → 锁屏 / 解锁态点按 → 云剪贴板读写。
|