Skip to Content
Referenceمخطط الوصفة

مخطط الوصفة

تستخدم وصفات 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"] }

سير التحقق

  1. تحقق من JSON عبر محرر الوصفة الحالي أو واجهة البرمجة أو أداة MCP validate_recipe.
  2. قارن الوصفة المطبّعة المعادة بالطلب الأصلي.
  3. عامل الحقول غير المعروفة الساقطة كعيب في الوصفة لا كإعداد ناجح.
  4. ابنِ فقط بعد تمثيل المتطلبات الصريحة.
  5. افحص الأدلة المولّدة وشغّل التحققات ضد الضيف الناتج.

انظر أول بناء لك لإرشاد الفشل واستعادة التنزيل.