vphone-manager 多 VM 管理 GUI

图形化管理多台虚拟 iPhone：创建向导、实时屏幕、快照、文件与固件下载，本地与远程节点统一操作。

vphone-manager 多 VM 管理 GUI

vphone-manager 是 vphone 的图形化管理端（SwiftUI 桌面应用）：把多台虚拟 iPhone 的创建、启动、屏幕、文件、快照、固件下载与自动化集中到一个窗口，本地 VM 与远程集群节点上的 VM 在同一套界面中统一呈现和操作。它本身不直接运行虚拟机——VM 的运行由它在后台拉起的无头 vphone-cli 进程承担，控制经 HostControl Unix socket，创建管线在进程内驱动。

构建与启动

make manager_build     # 构建 release 版 GUI：.build/release/vphone-manager
make manager_bundle    # 打包完整 App：.build/VPhone.app
make manager_zip       # 集群推送源：.build/VPhone.app.zip
方式 说明
make manager_build 日常开发用，直接运行 .build/release/vphone-manager
make manager_bundle 产出发布用 VPhone.app：内嵌已签名的 vphone-cli、特权 helper、agent、guest 守护进程与全部运行资源，可经 Finder 双击启动
make manager_zip 依赖 manager_bundle，产物作为集群 Sync Apps… 的推送源

打包 VPhone.app 前需先完成 make setup_tools（内嵌工具是打包内容的一部分）。

六种导航模式

窗口顶部工具栏切换六种模式；侧栏仅 library 模式可见，其余模式 detail pane 占满窗口。

模式 内容
Library 侧栏 VM 列表（按节点分节，本机恒在最上）+ 选中 VM 的详情页
Gallery 总览网格：所有节点 VM 的实时屏幕缩略图，一键 Start/Stop
Dashboard 宿主机 CPU / 内存 / 磁盘 / 网络监控 + 最近崩溃记录卡片（Recent crashes）
Firmware 固件镜像缓存与下载面板（Manager 唯一的镜像下载入口）
Cluster 集群节点管理：节点卡片、mDNS 自动发现、配对
Audit 审计面板：MCP server 与内嵌 agent 连接状态、远程会话、端口总表（含冲突检测）、统一审计事件流

侧栏实时显示每台 VM 的运行状态；启动失败的 VM 标出红色「boot panic」徽标。行右键菜单提供 Start / Stop / Suspend、在 Finder 中显示、重命名 / 克隆 / 删除等操作。

Gallery 按节点分节显示 LazyVGrid，tile header 有状态点/名称，顶部全局 poll/stream 切换（选择持久化跨重启），单 tile 流失败只回退该 tile 到 poll。

审计面板（Audit）

统一观察所有外部可达面：

  • 连接：MCP server 与内嵌 agent 的状态徽标、endpoint（mono 可复制）、MCP 实时连接数与累计请求数；下方列出当前被外部 controller 拉屏幕流的 VM 会话。
  • 端口总表：每 VM 一行——运行态、SSH bridge 端口、HostControl 通道；对已停止 VM 的 SSH 端口跑 lsof 检测冲突，被占则标红显示占用 PID。
  • 审计流：事件流（newest first，上限 1000 条内存 ring），按来源（全部/MCP/GUI/Agent）与"仅失败"过滤，行内含结果圆点、时间、来源徽标、actor、动作、资源、耗时。事件同时落 JSONL 到 ~/Library/Logs/vphone-manager/vphone-manager-audit.log（10 MB 轮转）。

VM 详情页

选中一台 VM 后进入详情页，本地 VM 有 14 个功能 tab（首次访问才加载，切换后状态保留）；远程 VM 13 个（无 Performance tab）：

Tab 能做什么
Console 实时屏幕预览（poll/stream 双模式，H.264 硬编硬解）、触控手势、按键与文本注入、截图与屏幕录制；输入录制停止后经 OCR 增强锚点自动进入 flow 编辑器审阅
SSH 内嵌 SwiftTerm 交互式终端，直进 guest 命令行
Guest 连通性与版本、vphoned 一键升级（字节级 SHA-256 比对徽章）、剪贴板、CFPreferences、Open URL、PVFS 文件视图规则管理（仅 dev/jb/exp 变体，双编辑模式：文本/结构化）
Device 位置模拟（含轨迹回放）、电池、相机、Touch ID
Apps App 清单、启动 / 终止 / 前台切换、IPA 安装；右键 Reveal in Files 跨 tab 跳转到文件浏览器
Automation flow 库 + 编辑器 + 运行面板 + run 历史（见下节）
Accounts 多账号 profile 管理（create/switch/rename/delete/recover）
Files guest 文件浏览器：导航历史/面包屑/书签、拖拽互传、Quick Look、权限编辑、钥匙串浏览；目录与大文件自动路由 SCP 回退
Network sidecar 遥测、代理配置编辑、Port Forwards 端口转发面板（本地/远程 VM 同构）
Config CPU / 内存 / SSH 端口 / 显示 / 设备身份编辑，CFW 重装入口（Maintenance 区块）
Snapshots 快照保存、恢复、删除（live / cold 徽标）
Logs boot.log 与 Manager 自身日志
Performance 本地 VM 运行时遥测：客户机系统指标 KPI（CPU%/内存/进程数/uptime） + 宿主 boot 进程统计 + guest 进程表
Services Service Profile 区块：catalog 15 个分组勾选（预勾选已全禁的组），Disable Selected / Restore All，状态行提示 needs_reboot；Reboot Guest 按钮（存在已禁用但仍在运行的托管服务时显示）——一键用户态重启，有界轮询等 vphoned 回归后自动刷新全页；下方 launchd 服务列表（行内 start/restart/stop/kill）+ guest 进程列表（term/kill）

屏幕流与 Console

Console tab 提供两种预览模式：

  • Poll（默认）：每秒轮询截图，资源占用低。
  • Stream：持续视频帧（默认 H.264 硬编硬解），旧服务端自动降级 mjpeg；流失败自动回退 Poll。

画质档位可选自动/高清/流畅，自动模式（ABR）按实际帧到达间隔动态调档。缩放 1–4×（触控板捏合），stream 模式下 zoom ≥1.6 自动切全分辨率档。实时触摸流逐相位下发（down→move→up），断线自动回退手势分类器。远程 controller 拉屏幕流时本地预览自动停帧并显示"Remote session active"徽标，会话结束自动恢复。

vphoned 一键热升级（Guest tab）

Guest tab 自动显示 guest 上报的 vphoned build hash，与 Manager 内置二进制做字节级 SHA-256 比对：一致显绿色 up-to-date 徽章，不一致显琥珀色可更新徽章。老 guest 无 bin_sha256 字段时回退 git hash 前缀比对。「Upgrade vphoned」一键推送 Manager 内置的签名二进制——本地 VM 原子写入 bundle 的 .vphoned.signed，远程 VM 经节点 agent 上传后强制重握手完成热升级，全程无需重启 VM。一键升级对所有变体放行（内置二进制以完整 regular entitlements 合并键盘 App Group 签名），less 变体除外。

远程 SSH 持久转发（Network tab）

Port Forwards 面板把 VM 内的服务映射到本机回环：

  • 本地 VM：使用与 CLI 相同的 spec 语法（如 tcp:8080->tcp:80、socks5:1080），列表显示监听状态、会话数与收发流量。
  • 远程 VM：填 guest 目标（tcp:80、unix 路径或 socks5）与本地端口——本地端口默认取 guest 同号端口（SOCKS5 默认 1080），绑定冲突时自动改用临时端口。转发经节点 agent 中继，行内显示 127.0.0.1:<本地端口> → <target>（经 <节点名>） 与实时会话数/流量。

Automation tab（Flow 编排）

Flow 编排的 GUI 入口，flow 库与 run 历史与 Python CLI 双端共享 ~/.vphone/flows/：

  • Flow Library：扫描 flows 目录，步骤数/断言数/参数徽章；New Flow 从零创作，Import 导入 JSON/JSONL 录制文件，行内 Edit 复用编辑器。
  • Flow 编辑器：名称/描述/参数 + 步骤列表（拖拽重排、增删、内联展开编辑）。14 个 action 模板（tap/swipe/long_press/key/type/app_launch/app_terminate/delay + 断言 wait_text/wait_stable/wait_app/find_and_tap + 控制流 exists/jump_if），每步参数表单 + retry/on_failure/anchor。
  • 模板锚点：截图取点器的框选模式——在实时截图上拖出矩形选区，命名后保存为该 flow 的模板图；运行时 Swift TemplateMatcher（NCC 多尺度匹配）定位区域经九宫格点位选择器换算点击坐标，图标/图片按钮等 OCR 定位不到的元素由此可锚定。
  • Run 参数覆盖：声明了 params 的 flow 点 Run 先弹参数表单，同一 flow 换参重跑不用改文档。
  • 运行面板：逐步骤行——pending/进行中/完成徽章，attempts、anchor hit/miss、每步耗时；失败截图留证；Cancel 协作取消。
  • Recent Runs：~/.vphone/flow-runs/history.jsonl，flow/VM/通过率/耗时一行一条。

快照

快照是普通 VM 目录的整盘副本，本地与远程 VM 都可用：

  • live 快照：运行中保存，冻结内存状态写入 .vz-state，恢复后自动回到保存瞬间的运行现场。复制失败有 resume 兜底。
  • cold 快照：关机状态保存的纯磁盘副本。
  • restore：用快照整体替换目标 VM（目标运行中拒绝），设备身份保留。

导入导出

.tgz 归档（export 可选 --include-ipsw），经 NS Save/Open panel。Clone 为 APFS 同身份克隆：nvram/machineIdentifier/shsh/SEPStorage 保留，丢弃 .vz-state 冷启动。

创建向导（New VM）

侧栏 New VM 向导有两种模式：

  • Empty bundle：只创建空白 VM 目录，适合手工折腾。
  • Full pipeline：在应用内驱动完整的 vm create 建机流程，可选五档变体（less / regular / dev / jb / exp），带阶段流水线图与实时日志，运行中可取消。
  • Apps 区（full pipeline 模式，less 变体隐藏）：键盘安装开关（默认开）与附加 IPA 多选列表。附加 IPA 在建机时随 CFW 阶段写入 guest，首启由 vphoned 自动安装；远程目标会先把 IPA 上传到节点暂存区再建机。

注意：选择固件配对时，iPhone 与 cloudOS 两份镜像都已下载才能开始——下载请先到 Firmware 面板完成。CFW 类变体要求特权 helper 已就绪。如果已配置远程节点，向导 header 可选择目标节点，把建机任务直接下发到远端执行。

固件下载面板（Firmware）

Firmware 模式集中管理 IPSW 缓存：按固件配对表列出全部可用配对，显示每份镜像的下载状态，支持并发分段下载与断点续传。缓存目录与 CLI 共享（~/.vphone/ipsws）。

配套服务能力

在 Settings → Services 中可以开启：

  • 内嵌 agent：让本机成为集群节点，被其他 Manager 远程管理（状态/生命周期/快照/日志/固件等 HTTP API）。transport 与路由表和 standalone vphone-agent 共享。
  • MCP server：把 VM 操作暴露为 streamable HTTP MCP 工具，供 AI agent 调用（默认关闭，仅监听本机回环）。工具覆盖 vm 列表/生命周期/截图/apps/文件/位置/电池/快照/SSH 命令执行（vm_ssh_exec：guest 内跑 shell 命令返回 exitCode/stdout/stderr，本地直连 SSH 桥、远程经节点 agent 自动建本地中继）。

可靠性与自愈

Manager 面向无人值守场景内置了一组自愈能力：

  • 崩溃自动重启：VM 因 panic 或信号死亡时自动拉起，退避 5/15/45 秒最多 3 次；连续运行满 10 分钟视为稳定并重置预算。主动停止与干净退出不触发。可在设置中关闭（默认开启）。
  • 崩溃记录：每次异常退出写一条结构化事件到 ~/Library/Logs/vphone-manager/vm-crashes.jsonl（1 MB 轮转），Dashboard 的 Recent crashes 卡片汇总最近 5 条与各 VM 聚合。
  • 远程节点掉线自愈：节点约 45 秒不可达标「离线缓存」，约 90 秒仍不可达清空缓存列表；任一次成功通信即恢复。读操作自动重试瞬时网络错误，写操作绝不重试。
  • Guest 无响应看门狗：vphoned 周期性连通性检查，连续超时判定 guest 无响应，在 UI 中反映状态。

日志与退出

  • Manager 自身日志：~/Library/Logs/vphone-manager/vphone-manager.log（1 MB 轮转）。
  • VM 启动日志：各 VM 目录下的 setup_logs/boot.log，Logs tab 内可直接查看。
  • 退出时如有 VM 仍在运行，Manager 会询问：保持运行（默认，下次启动自动重新识别）/ 全部停止 / 取消退出。