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 见 首次构建。

首次构建构建指南