Commilitia Drop iPhone／iPad 真机分发手册

把 Commilitia Drop 覆盖安装到已登记的 iPhone 与 iPad（开发签名）。本手册走 既有 Apple Development 证书 + ASC API Key provisioning + 全 CLI 路线：签名身份固定为钥匙串内既有证书的 SHA-1；ASC Key 只用于登记设备、更新 App ID／App Group／Push 能力和 profile。构建装机一条命令，全程不碰 Xcode GUI、不新建开发证书、不修改私钥 ACL。

包名与标识

项	值
主 app Bundle ID	`net.commilitia.Commilitia-Drop`
Share Extension	`net.commilitia.Commilitia-Drop.share`
控件扩展	`net.commilitia.Commilitia-Drop.widgets`
App Group	`group.net.commilitia.Commilitia-Drop`
APNs topic（服务端 `CDROP_APNS_TOPIC`）	`net.commilitia.Commilitia-Drop`

前置

付费 Apple Developer Program（$99/年）。
一台 iPhone（iOS 26）+ Mac（Xcode 26 命令行工具）。
一个已登录的 Commilitia Drop（网页 / 桌面）——用来扫码批准本机登录。

A. 既有签名身份 + ASC API Key + .env

先用 CLI 列出当前钥匙串中可用的代码签名身份：

security find-identity -v -p codesigning

找到必须复用的 Apple Development 证书，记录行首 40 位 SHA-1。若身份不存在或私钥不可用，停止构建并解锁当前登录钥匙串；不要让自动签名生成替代证书。

-allowProvisioningUpdates 凭 App Store Connect API Key 自动登记设备、建／改 App ID（含 App Groups + Push 能力）、更新 App Group 与 profile，免去手动 profile 的设备选择问题。签名证书由 CDROP_APPLE_DEVELOPMENT_IDENTITY 固定，不由 provisioning 自行选择。

生成 API Key：appstoreconnect.apple.com → 用户和访问 → 集成 → App Store Connect API → 团队密钥 → 「＋」→ 角色 Admin（要能管设备 / profile / 标识符）→ 命名 → 生成 → 下载 AuthKey_XXXXX.p8（仅一次）。记下三样：

Key ID（密钥行里那串，10 位）
Issuer ID（密钥页顶部，UUID 形）
Team ID（账号 Membership 里，10 位）

配 .env（仓库根目录，已 gitignore，公开仓库不留账号凭据）：

CDROP_TEAM_ID=ABCDE12345
CDROP_ASC_KEY_PATH=/绝对路径/AuthKey_XXXXX.p8
CDROP_ASC_KEY_ID=XXXXXXXXXX
CDROP_ASC_ISSUER_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
CDROP_APPLE_DEVELOPMENT_IDENTITY=<既有证书的40位SHA-1>

.p8 放仓库外即可，CDROP_ASC_KEY_PATH 指它绝对路径（落本目录则被 *.p8 忽略）。

你若已在门户手动建过 App ID / App Group，自动 provisioning 会复用或更新。「手动建 profile 时设备列表只剩 Mac」＝那台 iPhone 在 Devices 里被登记成了 macOS 平台（登记表单 Platform 默认 macOS）；自动 provisioning 按连接的真机登记，绕过此坑。

顺手：APNs Auth Key（发推送用，与上面 ASC Key 是两码事）：门户 Keys → ＋ → 勾 Apple Push Notifications service → 下载 AuthKey_YYYYY.p8（仅一次），记 Key ID + Issuer ID（服务端配，见 C）。

B. 构建装机（全 CLI）

just ios-devices                 # 手机插 USB，读 UDID
just ios-device <你的设备UDID>   # 自动 provisioning 构建 + devicectl 装机

just ios-device 先确认 .env 指定的既有证书仍在钥匙串，再执行 xcodegen generate → xcodebuild -allowProvisioningUpdates（固定该 SHA-1 签名，ASC Key 更新设备与 profile）→ xcrun devicectl device install app。无 Xcode GUI。
首次装机后，iPhone 上首启该开发者 app 即可直接跑（付费 ADP 开发证书，无需手动「信任开发者」）。

若出现 errSecInternalComponent，优先在当前用户的普通 Terminal 解锁登录钥匙串，然后重试原证书。不要创建新证书、修改钥匙串 ACL，或改用 Xcode GUI。

C. 服务端前置

引擎可达：真机上引擎 WebView 加载 https://drop.commilitia.net/engine.html——该文件随 Commilitia Drop 服务端二进制部署到 prod（//go:embed 进 binary，just docker-image 含最新 dist）。手机要用，prod 须是含本轮改动的最新部署。
APNs 真发：把 A 里那把 APNs Auth Key .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 指向可达引擎。

D. 只能真机验的清单

代码已实现，下列是真机才能验的点：

液态玻璃真机渲染（陀螺仪高光 / 动效）。
扫码登录：本机显码 → 已登录 Commilitia Drop 扫码批准 → 进主界面（强制 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 推送：离线设备收「收到文件」通知（需 C2 的 .p8）。
Share Extension：别的 app 分享 → 选 Commilitia Drop → 唤起主 app 选设备发送。
控制中心剪贴板两控件：控制中心加「上传 / 拉取剪贴板」控件 → 锁屏 / 解锁态点按 → 云剪贴板读写。

5.9 KiB Raw Blame History Unescape Escape