مخطط الوصفة
تستخدم وصفات OpenFactory JSON بـ snake_case. للشكل القانوني غلاف صغير في المستوى
الأعلى، وكائن 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"]
}لا تستخدم حقول camelCase مثل baseImage أو startupScripts. يقبل محقق التوافق بعض
الوصفات المسطحة الأقدم، لكن المخرج المطبّع يعشّش حقول نظام التشغيل تحت os. يجب أن
ترسل التكاملات الجديدة الشكل القانوني.
حقول المستوى الأعلى
| الحقل | النوع | مطلوب/افتراضي | المعنى |
|---|---|---|---|
name | سلسلة | مطلوب؛ 3–100 حرف | اسم وصفة داخلي مستقر |
display_name | سلسلة أو null | اختياري؛ 1–100 حرف | اسم للعرض |
description | سلسلة | "" | النتيجة المقصودة والحد |
base_image | سلسلة | debian-trixie | هدف التوزيعة/البناء؛ استخدم قائمة اللوحة الحالية |
task | سلسلة أو null | اختياري | هدف تشغيلي |
executor | سلسلة أو null | اختياري | التقنية المتوقعة لأداء المهمة |
use_case | سلسلة | General | حالة الاستخدام الأساسية |
hardware | كائن | الافتراضيات أدناه | متطلبات النشر |
os | كائن | كائن فارغ/افتراضي | حزم نظام التشغيل والمستخدمون والخدمات والأمان وسطح المكتب والمثبت والسكربتات |
scenarios | مصفوفة | [] | طوبولوجيا الاختبار وأهدافه |
publish_to | مصفوفة سلاسل | ["local"] | وجهات المخرج المطلوبة |
delivery | كائن | {} | إعداد تسليم معلن إضافي |
community | منطقي | false | طلب ظهور سوق المجتمع؛ سياسة النشر ما زالت تنطبق |
توجد حقول متقدمة خاصة بالهدف لإعادة تجهيز ISO المصدر وحمولات ضيف Proxmox وأصل السياسة وتكاملات التسليم. استخدم المحرر أو عقد واجهة الإصدار المنشور بدل نسخ مثال قديم.
العتاد
{
"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 مورّدا مدعوما أو تركيبة مورّدين.
هذه متطلبات معلنة وليست دليلا على اختبار الصورة الناتجة على عتاد فعلي مطابق.
كائن نظام التشغيل
حقول os الشائعة:
| الحقل | النوع | الغرض |
|---|---|---|
features | مصفوفة سلاسل | وحدات ميزة مسجلة |
packages | مصفوفة سلاسل | حزم أصلية للطلب |
excluded_packages | مصفوفة سلاسل | حزم يجب أن تبقى غائبة بعد توسيع الميزة |
custom_packages | مصفوفة | مستودعات مصدر لتعبئتها عبر مسار البناء المدعوم |
package_overrides | مصفوفة | عمليات إضافة أو إزالة أو استبدال صريحة |
extra_repos | مصفوفة سلاسل | مستودعات إضافية؛ ما زال التعامل مع الثقة والمفاتيح يتطلب مراجعة |
services | مصفوفة | تمكين الخدمة المسماة وإعدادها |
users | مصفوفة | حسابات ومجموعات محلية على الصورة |
security | كائن | اختيارات التقوية والتشفير والتدقيق وSELinux وfail2ban المعلنة |
networking | كائن | قصد الواجهة والشبكة |
desktop_settings | كائن | مظهر سطح المكتب وسلوكه |
branding | كائن | هوية التوزيعة والأصول |
runtime | كائن | هوية init/الخدمة/مدير الحزم |
boot | كائن | وسائط النواة واختيارات GRUB |
installer | كائن | إعداد التثبيت على القرص |
persistence | كائن | الاستمرار الحي وسياسة المنطقة |
integrity | كائن | إعدادات dm-verity والإقلاع الآمن وIMA/EVM المطلوبة |
file_attachments | مصفوفة | ملفات مرفوعة سابقا معرّفة بـ file_id |
startup_scripts | مصفوفة | سكربتات systemd لمرة واحدة محدودة |
time_zone | سلسلة أو null | إعداد المنطقة الزمنية للصورة |
وجود حقل سلامة أو أمان قصد إعداد. ليس دليلا على إنتاج الآلية أو فرضها وقت التشغيل أو تأهيلها لنظام امتثال. اطلب أدلة بناء واختبار مطابقة.
المستخدمون
{
"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. عاملها كشفرة صدفة قادرة على الجذر ما لم يقل 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"]
}سير التحقق
- تحقق من JSON عبر محرر الوصفة الحالي أو واجهة البرمجة أو أداة MCP
validate_recipe. - قارن الوصفة المطبّعة المعادة بالطلب الأصلي.
- عامل الحقول غير المعروفة الساقطة كعيب في الوصفة لا كإعداد ناجح.
- ابنِ فقط بعد تمثيل المتطلبات الصريحة.
- افحص الأدلة المولّدة وشغّل التحققات ضد الضيف الناتج.
انظر أول بناء لك لإرشاد الفشل واستعادة التنزيل.