Skip to Content
Reference食譜架構

食譜架構

OpenFactory 配方使用 Snake_case JSON。規範格式有一個小 頂級信封，用於作業系統配置的 os 對象，以及 用於建構後驗證的 scenarios 陣列。

驗證證明已識別的欄位具有可接受的形狀。它不 證明每個包都存在，每個請求的行為都被表示，或者 影像和測試將會成功。向後可能會忽略未知字段 相容性，因此請始終檢查由 產品。

規範信封

{
  "name": "debian-web-check",
  "display_name": "Debian Web Check",
  "description": "Small Debian image with explicit smoke tests.",
  "base_image": "debian-trixie",
  "use_case": "Server evaluation",
  "hardware": {},
  "os": {},
  "scenarios": [],
  "publish_to": ["local"]
}

請勿使用駝峰命名法字段，例如 baseImage 或 startupScripts。的 相容性驗證器接受一些較舊的平面配方，但標準化輸出 將 OS 欄位嵌套在 os 下。新的整合應該發送規範格式。

頂級字段

領域類型必要/預設意義
name字串必要的; 3–100 個字元穩定的內部配方名稱
display_name字串或空白選修的; 1–100 個字元人性化的名字
description字串""預期結果與邊界
base_image字串debian-trixie分發/建置目標；使用目前控制台清單
task字串或空白可選經營目標
executor字串或空可選預計執行任務的技術
use_case字串General主要用例
hardware物件預設值如下所示部署需求
os物件空白/預設物件作業系統套件、使用者、服務、安全性、桌面、安裝程式和腳本
scenarios陣列[]測試拓樸與目標
publish_to字串陣列["local"]請求的輸出目的地
delivery物件{}附加聲明交付配置
community布林false請求社區市場可見性；出版政策仍然適用

存在用於來源 ISO 重新製作、Proxmox guest 的高級目標特定字段 有效負載、策略來源和交付整合。使用編輯器或 API 已部署版本的合同，而不是複製舊範例。

硬體

{
  "hardware": {
    "platform": "pc",
    "architecture": "x86_64",
    "gpu": null,
    "min_cpu_cores": 2,
    "min_memory_gb": 4,
    "min_storage_gb": 16,
    "nic_count": 1
  }
}

platform 是 pc、phone 或 raspberry_pi；支援的設備值為 特定目標。 architecture 是 x86_64 或 aarch64。 GPU 值名稱 a 支援的供應商或供應商組合。這些是聲明的要求，而不是 證明生成的圖像在匹配的物理硬體上進行了測試。

作業系統對象

常見的 os 欄位有：

領域類型目的
features字串陣列註冊功能模組
packages字串陣列請求的原生包
excluded_packages字串陣列功能擴充後必須保留的軟體包
custom_packages數組透過支援的建置路徑打包的來源儲存庫
package_overrides陣列明確新增、刪除或取代操作
extra_repos字串陣列額外的儲存庫；信任和密鑰處理仍需審查
services陣列命名服務啟用與設定
users陣列圖像本機帳戶和群組
security物件聲明的強化、加密、稽核、SELinux 和fail2ban 選擇
networking物件介面與網路意圖
desktop_settings物件桌面外觀與行為
branding物件分配身分和資產
runtime物件初始化/服務/套件管理器身分
boot物件核心參數與 GRUB 選擇
installer物件安裝到磁碟配置
persistence物件即時持久性與區域策略
integrity物件請求的 dm-verity、安全啟動和 IMA/EVM 設定
file_attachments陣列先前上傳的由 file_id 標識的檔案
startup_scripts陣列有界 systemd 一次性腳本
time_zone字串或空白影像時區設定

完整性或安全欄位的存在是配置意圖。它是 沒有證據表明該機制是在運行時產生、執行或合格的 建立合規制度。需要匹配的建置和測試證據。

用戶

{
  "os": {
    "users": [
      {
        "username": "deploy",
        "full_name": "Deployment Operator",
        "groups": ["sudo"],
        "shell": "/bin/bash"
      }
    ]
  }
}

使用者名稱和群組名稱僅限於安全的 Linux 帳戶字元和長度。 不設定 password 會建立一個僅使用金鑰或密碼鎖定的帳戶 部署時憑證工作流程。避免保存明文憑 食譜。

服務

{
  "os": {
    "services": [
      {
        "name": "ssh",
        "enabled": true,
        "config": {
          "port": 22,
          "disable_password_auth": true
        }
      }
    ]
  }
}

config 是特定於服務的。語法上有效的鍵仍然可以被忽略 一個沒有實現它的生成器。驗證生成的標準化配方 配置和訪客行為。

安全性和安裝程序

{
  "os": {
    "security": {
      "hardening_level": "standard",
      "disk_encryption": false,
      "audit_logging": true,
      "selinux": false,
      "fail2ban": true
    },
    "installer": {
      "enabled": false,
      "type": "calamares",
      "desktop_launcher": true,
      "bootloader": "grub",
      "delivery": [],
      "user_setup": "build_time"
    }
  }
}

安裝程式類型取決於目標（calamares、anaconda 或 elster-mobile)。啟用安裝程式後必須使用一次性磁碟 安裝測試；即時桌面中的圖示並不能證明安裝有效。

啟動腳本

{
  "os": {
    "startup_scripts": [
      {
        "name": "write-build-marker",
        "description": "Create a local marker after networking is available.",
        "command": "install -m 0644 /dev/null /var/lib/example-ready",
        "packages": [],
        "run_as": "root",
        "after": "network.target"
      }
    ]
  }
}

最多接受 32 個啟動腳本。命令必須非空且不能 包含 NUL 位元組。將它們視為具有 root 權限的 shell 程式碼，除非 run_as 說 否則；審查冪等性、引用、網路故障和秘密暴露。

場景和斷言

{
  "scenarios": [
    {
      "id": "primary-smoke",
      "name": "Primary image smoke test",
      "enabled": true,
      "tests": ["boot", "login", "packages"],
      "custom_tests": [
        {
          "description": "Confirm SSH is enabled on the configured port.",
          "assertions": [
            {
              "type": "service_enabled",
              "description": "The SSH service starts at boot.",
              "params": {"service": "ssh"}
            },
            {
              "type": "port_listening",
              "description": "The guest listens on TCP port 22.",
              "params": {"port": 22}
            }
          ]
        }
      ]
    }
  ]
}

場景還可以定義具有虛擬機器和網路、基準格式的 topology 測試和 CIS 設定。省略的拓樸預設為正常的單虛擬機 路徑。斷言需要人類可讀的描述和特定於類型的參數。 未知的斷言類型可能會在模式解析中倖存下來，因此請確認運行程式 在將其視為證據之前支持它們。

完整的最小範例

{
  "name": "debian-web-check",
  "display_name": "Debian Web Check",
  "description": "Debian image with SSH, curl, and explicit smoke tests.",
  "base_image": "debian-trixie",
  "use_case": "Server evaluation",
  "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"],
    "users": [
      {
        "username": "deploy",
        "groups": ["sudo"],
        "shell": "/bin/bash"
      }
    ],
    "services": [
      {
        "name": "ssh",
        "enabled": true,
        "config": {"port": 22, "disable_password_auth": true}
      }
    ],
    "security": {
      "hardening_level": "standard",
      "audit_logging": true
    },
    "installer": {"enabled": false}
  },
  "scenarios": [
    {
      "id": "primary-smoke",
      "name": "Primary image smoke test",
      "enabled": true,
      "tests": ["boot", "login", "packages"]
    }
  ],
  "publish_to": ["local"]
}

驗證工作流程

  1. 透過目前配方編輯器、API 或 MCP 驗證 JSON validate_recipe 工具。
  2. 將傳回的規範化配方與原始請求進行比較。
  3. 將遺失的未知欄位視為配方中的缺陷，而不是成功 配置。
  4. 僅在表達了明確的需求後才進行建構。
  5. 檢查產生的證據並對產生的訪客運作斷言。

請參閱 Your First Build 以了解失敗情況並下載 恢復指導。

McpServicenow Integration