iOS 控制

架构：iOS 主机节点 + 自动化管理

架构：iOS 主机节点 + 自动化管理

截图待补
把截图放到该路径,或把 src 改成实际图片地址
assets/screenshots/cap-ios-control/architecture.png

iOS 设备由 iOS 主机节点（node-ios）驱动，一台物理主机（Mac/Linux/Windows）+ USB 连接多台 iPhone → 运行一个 node-ios 进程 → 自动发现与管理所有设备。

自动化接入流程（无需手工操作）

自动化接入流程

截图待补
把截图放到该路径，或把 src 改成实际图片地址
assets/screenshots/cap-ios-control/workflow.png

1. 设备发现

iOS 主机节点启动后自动枚举所有 USB/WiFi 连接的 iPhone（通过 go-ios），上报到服务端：

• UDID（设备唯一标识）
• 设备名称（用户设置的 iPhone 名称）
• 机型（iPhone 14 Pro / iPhone 15 等）
• 系统版本（iOS 17.2.1 等）
• 连接方式（USB / WiFi）
• 当前状态（未接入 / 已接入 / WDA 状态）

2. 一键接入

用户在「我的工具」→「设备」Tab 操作：

1. 点击「添加设备」→ 选择「iOS」
2. 选择一个在线的 iOS 主机节点
3. 点击「扫描设备」——界面显示该节点发现的所有 iPhone 列表（名称/型号/系统版本/UDID 尾号/连接方式）
4. 点击设备旁的「接入」按钮——服务端自动完成：
   • 签发一次性配对码
   • 通过 NodeConnect 下发 NodeIosClaimDevice 指令（含配对码、UDID、设备标签）
   • 节点收到后调用既有的 devicecontrol.Pair 流程（HTTP 兑换配对码 → 写入 0600 凭据文件）
   • 启动该设备的 device-control WebSocket 连接循环
5. 接入成功后设备显示为在线，但 WDA 状态为「未准备」——需要进行 WDA 准备

3. WDA 自动化准备

用户首次使用前需要准备签名材料与 WDA 产物（一次性操作，后续复用）：

3.1 签名配置管理

点击顶部「签名配置」按钮，上传签名材料：

• ASC p8 API key（推荐）：需要 $99/年付费开发者账号
  • 上传字段：p8 私钥文件内容、Key ID、Issuer ID、Team ID
  • 自动化程度：完全自动（UDID 注册 → 证书创建 → profile 构建 → 签名 → 安装 → 续期，全程无人工介入）
  • 到期周期：1 年
• P12 + mobileprovision（半自动）：手动从 Xcode 导出
  • 上传字段：.p12 证书文件、证书密码、.mobileprovision 文件
  • 自动化程度：首次手动导出，后续自动签名安装
  • 到期周期：取决于证书类型
• 免费 Apple ID（仅手动）：无付费账号
  • 需要在 Mac 上用 Xcode 手工签名 WDA，上传已签名 .ipa
  • 无法自动续期，7 天过期后必须重新手工签名上传

3.2 WDA 产物管理

点击顶部「WDA 产物」按钮，上传预构建的 WebDriverAgent .ipa：

• 一次性上传，全局复用（按 SHA256 去重，避免重复存储）
• 可由管理员上传全局共享产物（owner_user_id 为 NULL），所有用户可见
• 用户自己上传的产物仅自己可见
• 界面显示产物名称、版本、文件大小、SHA256 哈希前缀

3.3 准备 WDA（一键启动 job）

点击设备详情的「准备 WDA」按钮：

1. 选择签名配置（下拉列表）
2. 选择 WDA 产物（下拉列表）
3. 点击「准备 WDA」——服务端下发 job：
   • 签名材料经 TLS NodeConnect 一次性下发（不落日志/UI/GET 响应）
   • 节点执行流水线：下载 .ipa → go-ios 签名（ASC: 注册 UDID + 创建证书 + 构建 profile + 重签；P12: 直接重签）→ zipconduit 安装 → testmanagerd 启动 → 动态端口转发（USE_PORT=8100 设备侧，宿主端口自动分配）→ WebDriver session 验证（GET /status → POST /session → 读 capabilities）
   • 节点上报 job 事件：阶段（queued/downloading/signing/installing/verifying/completed/failed）、进度百分比、阶段消息、错误码
4. 前端 2 秒轮询显示进度条与阶段信息（复用通用 job 轮询组件）
5. 成功后设备 WDA 状态变为「就绪」，显示 mobileprovision 到期时间

4. 自动续期监控

节点监控 mobileprovision 到期时间：

• 14 天前：WDA 状态变为「将过期」，服务端定时扫描自动派发 renew job（无需人工点击）
• Renew job 流程：复用证书 ID（不重新创建证书）→ 仅重建 profile → 重签 → 重装 → 重启 runner → 验证成功才切换（失败保留旧 WDA）
• 过期后：WDA 状态变为「已过期」，扫描器对终端错误发通知（如签名配置被删）；用户仍可手动「立即续期」兜底

5. 多设备管理

一个 iOS 主机节点可管理多台 iPhone：

• 每台设备一条独立的 device-control WebSocket 连接
• 每台设备独立的凭据文件（0600 权限）
• 服务端视角：每台设备是独立的 device_id，与 Android 设备同级
• 节点详情页显示当前主机的所有 iOS 设备列表与 WDA 状态

签名方式对比

签名方式对比

截图待补
把截图放到该路径，或把 src 改成实际图片地址
assets/screenshots/cap-ios-control/signing.png

功能：15 个操控命令（与 Android 相同）

15 个操控命令

截图待补
把截图放到该路径，或把 src 改成实际图片地址
assets/screenshots/cap-ios-control/commands.png

坐标系统

device-control 协议要求整数物理像素（spec §1）。WDA 返回的 rects 是 points（逻辑点），驱动自动乘以设备 scale（2×/3×）后发出 bounds/screen，tap 坐标除以 scale 后发给 WDA。density（Android densityDpi 整数）在 iOS 无对应概念，驱动上报 scale 派生值（2×→320, 3×→480），最佳努力。

部署模式

部署模式

截图待补
把截图放到该路径，或把 src 改成实际图片地址
assets/screenshots/cap-ios-control/deployment.png

推荐：iOS 主机节点（自动化管理）

一台物理主机（Mac/Linux/Windows）+ USB Hub 连接多台 iPhone → 运行 node-ios 进程：

• 自动发现所有设备（插拔热加载）
• 用户界面一键接入、一键准备 WDA、一键续期
• 签名材料与产物服务端托管，节点按需下载
• 多设备并行管理，每设备独立状态

Sidecar 模式（开发/定制集成）

直接导入 Go 包 device-control/ios/devicecontrol，自己管理 WDA 生命周期：

• 适用于已有设备管理基础设施、需要深度定制的场景
• 手动配对、手动提供 WDA runner（需自己签名）
• 参考 device-control/ios/README.md

CLI（仅供协议测试）

device-control-ios CLI 是协议层测试工具，不推荐生产使用（无发现、无 WDA 自动化、手工 flag 管理）。

与 Android 控制的差异

与 Android 控制的差异

截图待补
把截图放到该路径，或把 src 改成实际图片地址
assets/screenshots/cap-ios-control/diff.png

← Android 控制详解 · device token / MCP token 隔离治理 → · 浏览器控制（CDP）详解 →