日志与常见问题

出问题时先看日志。本文列出各组件日志位置、最高频的几类故障，以及日常用得到的 make 目标。

日志位置速查

日志	位置	内容
首次启动（create 管线）	<bundle>/setup_logs/boot.log	vm create 全流程输出；AIO 编排另存 setup_logs/runs/<时间戳>/
DFU restore	<bundle>/setup_logs/boot_dfu.log	DFU 引导与刷机过程
vphone-cli（GUI + 子命令）	~/Library/Logs/vphone-cli/vphone-cli.log	VM 起停、vsock 控制、输入注入等 18 个域
Manager / Agent	~/Library/Logs/vphone-manager/vphone-manager.log	GUI 与 standalone agent 共写
Agent（launchd 重定向）	~/Library/Logs/vphone-agent.log	standalone agent stdout/stderr
Agent 审计	~/Library/Logs/vphone-agent-audit.log	单行 JSON 审计事件
guest vphoned	/var/root/vphoned-logs/（guest 内）	守护进程命令分发、更新、服务日志
JB 首启自动收尾	/var/log/vphone_jb_setup.log（guest 内）	symlinks / Sileo / apt / TrollStore 收尾脚本
构建输出	/tmp/vphone_*.log	各 make 构建/测试 target 的全量输出

文件日志 1MB 触发轮转、保留 3 代（.vphone-agent-audit.log 为 10MB 单代）。vphone-cli 与 Manager 的文本日志行格式一致：

2026-07-28 12:34:56.789 [INFO] control: connected to vphoned (VPhoneGuestControl.swift:123)

也可用 Apple unified logging 实时跟踪：subsystem 分别为 com.vphone.cli / com.vphone.manager。

常见问题

1. 单独 swift build 出的二进制一启动 VM 就失败

裸 swift build 产出的是未签名、无私有 entitlements 的二进制，启动 PV=3 VM 需要 com.apple.private.virtualization 和 .security-research 两个私有 entitlement，未签名的二进制会在启动瞬间被系统 SIGKILL。

修复：永远用 make build（release + adhoc 签名 + 注入 entitlements），不要绕过 make。

2. cfw install / vm create 报权限或 helper 错误

cfw install（host-mount 安装 CFW）与 vm create 依赖特权 helper com.vphone.helper 来挂载 Disk.img。一次性安装：

make helper_install

另注意：CFW 安装时 VM 必须处于关机状态（host-mount 需要独占挂载磁盘镜像）。

3. VM 发布/对应硬件该打哪档固件补丁

固件配对表的单一数据源是 config/firmware_catalog.json（Manager 侧栏 Firmware 面板可读）。新增/变更配对只改 JSON，不改代码。

4. 触摸注入了但没反应

先确认 guest 连接状态（窗口标题 [connected]），再经 vphone.sock 发 ping 验证 vphoned 在线：

echo '{"t":"ping"}' | nc -U vm/vphone.sock

若 capability 缺失，多半是 vphoned 版本过旧——make vphoned 后推送更新（详见「guest 守护进程 vphoned」篇）。另：锁屏状态下截屏为黑、触摸无效，正常运行的 VM 已被禁用自动锁屏。

5. 嵌套虚拟化宿主上一票否决

宿主本身跑在 VM 里（sysctl -n kern.hv_vmm_present 为真）无法运行 PV=3 research VM。宿主还要求 macOS 15+ 且 SIP/AMFI 放宽；可用带修复指引的预检查：

vphone-cli preflight

6. 日志/自动化行为异常但对不上代码

vphone-manager.log 是跨进程共享文件（GUI 与 agent 并发写），偶见无时间戳前缀的折行尾巴，属已知现象，过滤时忽略即可。

make 目标速查表

完整列表跑 make help。日常高频项：

类别	目标	说明
构建	make build	release + 签名（跑虚拟化必须用这条）
	make patcher_build	debug 未签名，供 fw_patch* / cfw_* 使用
	make manager_build / manager_bundle	GUI 管理器 / 发布用 VPhone.app
	make agent_build	集群节点 daemon
	make vphoned	guest 守护进程交叉编译 + 签名
	make helper_install	安装特权 helper（一次性，需 sudo）
启动	make boot / boot_dfu	GUI 启动 / DFU 启动
测试	make test	Swift 单测
	make test_integration / test_full	+ 固件补丁门控 / + JB 内核补丁全量
管线	make rebuild_dev	一键走完 fw prepare → patch → DFU restore → CFW
	make fw_patch*、cfw_install*	分阶段补丁与 CFW 安装
独立补丁	make dt_patch / gpu_patch / sensor_patch / sim_patch	不重跑全流程
环境	make setup_tools	一次性装依赖（brew、工具、.venv）

验证顺序约定：patcher 改动至少 make patcher_build && make test（涉及 JB 内核补丁跑 make test_full）；宿主 Swift 改动跑 make build；实际启动效果用 make boot 验证。