vphone-manager 多 VM 管理 GUI

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

vphone-manager 多 VM 管理 GUI

vphone-manager 是 vphone 的图形化管理端（SwiftUI 桌面应用）：把多台虚拟 iPhone 的创建、启动、屏幕、文件、快照与固件下载集中到一个窗口，本地 VM 与远程集群节点上的 VM 在同一套界面中统一呈现和操作。它本身不直接运行虚拟机——VM 的运行由它在后台拉起的无头 vphone-cli 进程承担，因此同样需要「环境准备与安装」中的全部前置条件。

构建与启动

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

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

五种导航模式

窗口顶部工具栏切换五种模式：

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

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

VM 详情页

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

Tab 能做什么
Console 实时屏幕、触控手势、按键与文本注入、截图与屏幕录制
SSH 内嵌终端，直接进 guest 命令行
Guest 连通性与版本、vphoned 一键升级（版本比对徽章）、剪贴板、偏好设置、Open URL
Device 位置模拟（含轨迹回放）、电池、相机、Touch ID
Apps App 清单、启动 / 终止、IPA 安装
Accounts 按 App 的多账号 profile 管理
Files guest 文件浏览器：拖拽互传、Quick Look、权限编辑、钥匙串浏览
Network 网络代理遥测、代理配置编辑与 Port Forwards 端口转发面板
Config CPU / 内存 / SSH 端口 / 显示 / 设备身份编辑，CFW 重装入口
Snapshots 快照保存、恢复、删除（标注 live / cold）
Logs boot.log 与 Manager 自身日志
Performance 运行时性能遥测

远程节点上的 VM 使用同一套界面（无 Performance tab），操作体验与本地一致。

VM 详情页——Console 屏幕流

SSH——内嵌终端直进 guest 命令行

Files——guest 文件浏览器与拖拽互传

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:<本地端口> → <目标>（经 <节点名>） 与实时会话数/流量。

Network——代理遥测与 Port Forwards 端口转发

vphoned 一键热升级（Guest tab）

Guest tab 自动显示 guest 上报的 vphoned build hash，并与 Manager 自身构建比对：一致显绿色 up-to-date 徽章，不一致显琥珀色可更新徽章。「Upgrade vphoned」按钮一键推送 Manager 内置的签名二进制——本地 VM 原子写入 bundle 的 .vphoned.signed，远程 VM 经节点 agent 上传后强制重握手完成热升级，全程无需重启 VM。

变体防护：一键升级仅对 regular 变体 VM 放行（内置二进制以 regular entitlements 签名）；dev / jb / exp / less 与启用了键盘的 regular VM 会被拒绝并提示走各自更新途径（dev 用 make vphoned + Connect 菜单推送，其余重跑 cfw install）。

创建向导（New VM）

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

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

注意两点：

  1. 选择固件配对时，iPhone 与 cloudOS 两份镜像都已下载才能开始——下载请先到 Firmware 面板完成，Manager 不会在建机时隐式下载。
  2. CFW 类变体要求特权 helper 已就绪。Manager 启动时会自动检测 helper，缺失或版本过期会引导你完成一次性安装（macOS 管理员授权）。

如果已配置远程节点，向导 header 可选择目标节点，把建机任务直接下发到远端执行。

Console 与屏幕流

Console tab 提供两种预览模式：

  • Poll（默认）：每秒轮询截图，资源占用低。
  • Stream：持续视频流（默认 H.264 硬编硬解），更流畅；流失败会自动回退 Poll。

支持 1–4× 缩放（触控板捏合）、手势自动识别（点按 / 长按 / 滑动）、截图保存与屏幕录制（导出 .mov）。

可靠性与自愈

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

  • 崩溃自动重启：VM 因 panic 或被信号杀死而自发退出时自动拉起（退避 5 / 15 / 45 秒、最多 3 次；连续运行满 10 分钟视为稳定并重置预算）。主动停止与正常退出不会触发。可在设置中关闭（默认开启）。
  • 崩溃记录：每次异常退出写一条结构化事件到 ~/Library/Logs/vphone-manager/vm-crashes.jsonl，Dashboard 的 Recent crashes 卡片汇总最近 5 条与各 VM 聚合。
  • 远程节点掉线自愈：节点连续约 45 秒不可达即标「离线缓存」（amber 徽标，数据仍是缓存值），约 90 秒仍不可达则清空该节点缓存列表（幽灵 VM 消失）；任一次成功通信即恢复。控制端对幂等读请求自动重试瞬时网络错误，写操作绝不重试。
  • 应用层指标：启动 / 停止 / 崩溃 / 自动重启、节点轮询成败等计数周期性落盘 ~/Library/Logs/vphone-manager/metrics.jsonl，便于事后观测。

快照

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

  • live 快照：运行中保存，同时冻结内存状态；恢复快照后再启动会自动回到保存瞬间的运行现场。
  • cold 快照：关机状态保存的纯磁盘副本。
  • restore：用快照整体替换目标 VM（目标运行中会被拒绝），设备身份保留。

固件下载面板（Firmware）

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

Firmware——固件配对与镜像下载

配套服务能力

在 Settings → Services 中可以开启：

  • 内嵌 agent：让本机成为集群节点，被其他 Manager 远程管理（状态 / 生命周期 / 快照 / 日志 / 固件等 HTTP API）。
  • MCP server：把 VM 操作暴露为 MCP 工具，供 AI agent 直接调用（默认关闭，仅监听本机回环）。

Settings——内嵌 agent 与 MCP server 开关

日志与退出

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