首次建置

本指南會建立、驗證、建置並檢查一個自訂映像。已驗證的配方是組態檢查，不能證明 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