Skip to Content
Getting Started理解配方

理解配方

BuildRecipe 是 OpenFactory 送入映像 pipeline 的規範化規格。聊天可協助編寫，但配方、來源快照、產生檔案與測試證據才定義一次建置。

心智模型

規範配方主要有四層:

  1. Identity and target: 名稱、描述、base image 與硬體意圖。
  2. Operating system: os 下的 feature、套件、服務、使用者、安全、desktop、installer、attachment 與 startup script。
  3. Verification: 一個或多個帶內建測試與 custom assertion 的 scenario。
  4. Delivery intent: 請求的 publication 目標與選用 delivery 設定。
{
  "name": "debian-web-check",
  "display_name": "Debian Web Check",
  "description": "Small Debian image with explicit smoke tests.",
  "base_image": "debian-trixie",
  "hardware": {
    "platform": "pc",
    "architecture": "x86_64",
    "min_cpu_cores": 2,
    "min_memory_gb": 4,
    "min_storage_gb": 16,
    "nic_count": 1
  },
  "os": {
    "features": ["ssh"],
    "packages": ["curl"],
    "services": [
      {
        "name": "ssh",
        "enabled": true,
        "config": {"port": 22, "disable_password_auth": true}
      }
    ],
    "security": {
      "hardening_level": "standard",
      "audit_logging": true
    }
  },
  "scenarios": [
    {
      "id": "primary-smoke",
      "name": "Primary image smoke test",
      "enabled": true,
      "tests": ["boot", "login", "packages"]
    }
  ],
  "publish_to": ["local"]
}

使用 snake_case。新整合不應傳送 baseImage、頂層 features 或 startupScripts 等 legacy 形狀。

三種檢查，三種不同答案

Schema 驗證

驗證回答的是:「識別到的資料形狀是否可接受?」 它不能證明套件存在或行為可用。為相容可能忽略未知欄位，因此驗證成功仍可能遺漏重要請求。

始終將回傳的規範化配方與原始聊天及要求對照。缺少 desktop、application、installer、attachment 或測試是配方缺陷，即使驗證顯示 valid。

建置證據

成功建置回答的是:「pipeline 是否產出了 artifact?」 它不能證明每項 intended feature 都進入了映像。請檢查套件 inventory、來源 provenance、警告與建置 stage 證據。

guest 驗證

guest 測試回答狹義的 runtime 問題: VM 是否啟動、服務是否 active、連接埠是否 listen、檔案內容是否符合預期、application 是否啟動。通過的 assertion 只支援它實際觀察到的行為。

安全設定表達的是意圖

可接受的 hardening_level 值為 minimal、standard、strict，但這些標籤不是可移植的 compliance 設定檔。target generator 可能不同解讀。若需要 benchmark，請選擇確切適用的 benchmark 並保留逐 control 結果；不要從 strict 推斷 CIS 符合性。

同樣，disk_encryption、audit_logging、SELinux、fail2ban、Secure Boot、dm-verity 與 installer 設定需要匹配的 artifact 與 runtime 測試。

聊天與配方歸屬

驗證或編輯聊天產生的配方時，現有對話仍是編寫上下文的一部分。驗證應 refine 目前配方，而不是靜默替換為 generic default。即便如此，規範化配方仍是建置前的最終 checkpoint。

對每項 material 要求:

  • 找到對應的規範化欄位;
  • 確認其值與目標 scope;
  • 在可獲 runtime 證明處新增 assertion; 以及
  • 將僅部署的工作保留為 explicit warning，而非假裝在映像建置中已完成。

審查清單

  • base image 與 architecture 是否正確?
  • 請求的 desktop 與 application feature 是否都在?
  • 外部來源是否 pin 且 license 適用於 intended use?
  • 儲存的配方欄位與 script 中是否無 secret?
  • 若請求 installer，是否在 disposable disk 上設定並測試?
  • scenario 是否測試實際 acceptance criteria?
  • 不支援或部署時要求是否已標明?

欄位參考見 Recipe Schema，建置與下載 workflow 見 首次建置。

首次建置建置指南