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