首次构建

本指南会创建、验证、构建并检查一个自定义镜像。已验证的配方是配置检查，不能证明 ISO 已构建，也不能证明每项请求行为都通过了 VM 测试。

开始之前

• 登录，使对话与构建保留在你的账户下。
• 从单一操作系统和少量包或服务开始。
• 明确何种证据能证明请求已满足。包是否存在、服务状态、监听端口与 GUI 行为是不同的 assertion。

首次运行不要在聊天中写入凭据或私有仓库 URL。稍后通过支持的凭据工作流添加密钥，不要烘焙进镜像。

1. 说明目标及其检查项

示例:

Build a Debian 13 server image with OpenSSH and curl.
Create a password-locked deploy user in the sudo group.
Verify that the image boots, the deploy user exists, the ssh service is
enabled, and curl is installed. Do not add Docker or a desktop.

明确排除项有助于区分有意做的最小镜像与 planner 单纯遗漏的请求。

2. 检查配方预览

至少确认:

• base_image 与请求的发行版及版本一致;
• 请求的包出现在 os.packages 下，或由显式 feature 提供;
• 用户、组、服务、网络、installer、desktop 选择与请求一致;
• scenarios 包含你真正需要的检查;
• 未引入未请求的包、desktop、installer、凭据或外部仓库。

在同一对话中要求修改。后续请求会应用到当前活动配方。使用 Validate Recipe 时，后端会保留前一条实质性聊天请求；若仍缺少明确要求则阻止配方；生成的控制句不得抹掉对话意图。

验证仍可能漏掉不可用包、上游故障、发行版特定构建失败或没有测试的行为。将预览视为一份 proposed contract。

3. 只启动一次构建

在已验证预览上选择 Start Build。成功点击会创建 build ID。报告问题时保留该 ID，比百分比或截图更可靠。

构建面板可能显示 queued、planning、configured、building、finalizing、completed、failed 或 cancelled 等状态。queued 的构建可能在等待 worker 容量或启动恢复。显示的百分比是进度估计，不是截止时间；部分打包与文件系统步骤耗时差异很大。

离开原聊天视图后，仍可在 live build panel 中跟踪构建。刷新应通过持久构建状态与 event stream 重新连接。除非 UI 报告未创建 build ID，或先前构建已达 terminal 状态，否则不要重复点击 Start Build。

4. 区分镜像完成与测试完成

镜像可能在所选 VM 验证到达 terminal 状态之前就已完成。请同时查看:

• build status: 是否已组装并 finalize 持久 artifact;
• test status: not_run、running、passed、failed 或 error;
• certification status（如有）: 已配置 evidence 策略的结果，不是通用安全或硬件认证。

打开测试详情。确认每项请求的 assertion 在预期 guest 上运行，并检查失败或跳过的项。通过启动测试不能证明应用会打开；包记录不能证明其服务健康。

5. 检查并下载 artifact

下载前，将最终配方与包/测试证据同请求对照。记录显示的 build ID、artifact 文件名、大小与 checksum。

仅在 artifact finalization 完成后使用构建的下载操作。下载包可能包含 ISO 及相关证据。若下载返回 Failed to create download package、not found 或其他 JSON 错误:

1. 确认以构建所有者身份登录;
2. 打开确切构建，而非旧对话卡片;
3. 确认 artifact finalization 已完成且 ISO 已列出;
4. 重试一次;
5. 报告 build ID、时间戳、显示的 build/test/finalization 状态及完整错误文本。

不要仅为规避所有权或打包错误而重建；那会丢弃有用诊断状态并占用另一个构建槽位。

6. 在预期环境中测试 ISO

在 OpenFactory VM 中启动仅验证已配置的虚拟环境。若需可安装 desktop，还应在 disposable disk 上测试 installer 路径。物理部署时，请在代表性硬件上分别测试 firmware 模式、存储、显卡、网络、休眠、输入设备、更新与 recovery。

常见恢复路径

下一步

• 理解配方
• Recipe Schema
• Custom Assertions
• VNC Console