Files

T

iOS 计划完成：流式发送 / 后台续传 / APNs / Share Extension / 控制中心控件 + 真机分发预备

- 发送端流式（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 回调

2026-06-27 00:33:35 +08:00

6.0 KiB

Raw Blame History

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 位，记下）。

证书（Apple Development）：本机「钥匙串访问」可能已有（「我的证书」分类里看）。没有就：钥匙串访问菜单 → 证书助理 → 从证书颁发机构请求证书 → 存到磁盘 → 门户 Certificates → ＋ → Apple Development → 传 CSR → 下载 .cer 双击安装。
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
App Group：Identifiers 页类型筛选切到 App Groups → ＋ → group.net.commilitia.cdrop。再回上面 3 个 App ID 各自的 App Groups 能力里 Edit/Configure 关联它（三个都要）。
设备：Devices → ＋ → 填 UDID（插上手机后 just ios-devices 读）。
描述文件 ×3（Profiles → ＋ → iOS App Development，非 Distribution）：每个选对应 App ID + 证书 + 设备，命名清楚（建议 CDrop Dev / CDrop Share Dev / CDrop Widgets Dev）→ 下载 → 双击安装。
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）

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. 服务端前置

引擎可达：真机上引擎 WebView 加载 https://drop.commilitia.net/engine.html——该文件随 cdrop 二进制部署到 prod（//go:embed 进 binary，just docker-image 含最新 dist）。手机要用，prod 须是含本轮改动的最新部署。
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）。缺配置则推送惰性关闭，其余功能照常。
本机联调可选：环境变量 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 选设备发送。
控制中心剪贴板两控件：控制中心加「上传 / 拉取剪贴板」控件 → 锁屏 / 解锁态点按 → 云剪贴板读写。

6.0 KiB Raw Blame History Unescape Escape