MoonStack — إزاي الريليس والأبديت بيشتغلوا فعلًا + اقتراحات الاستقرار

موثّق من الكود · 2026-06-17 · شرح + اقتراحات

الخلاصة في سطر: الأبديت مش بيسحب من GitHub. الباكدج بيتبني على سيرفر البِلد (moonui) من الفيلات الموجودة فعليًا (base_path() للـ BE + مجلد الفرونت المبني)، بيتوقّع، وبيتنشر في versions.json. العميل بينزّل الباكدج الموقّع ويطبّقه.
للعمل بكذا ديفلوبر: الأنضف نبني الريليس من main (شوف قسم 2.5) — بس انتبه: main فيه السورس بس (مفيش vendor ولا الفرونت المبني public/app)، فبيحتاج خطوة بناء (composer + ng build) — وده بيخلّيه قابل لإعادة الإنتاج.

1) جهة البِلد/الريليس (الديفلوبر) — منين بتتاخد الفيلات

moonstack:build → PackageBuilder::build() بياخد المصدر من $source = base_path() ويحزم:

الكود (config('moonstack.package.include')): app, bootstrap, config, database, Modules, routes + vendor.
الفرونت إند: من MOONSTACK_FRONTEND_DIST (مجلد Angular المبني، فيه index.html) → بينزل في الباكدج تحت public/app.
manifest.json (نسخة + عدد migrations + قايمة الملفات) + sha256 + توقيع (مفتاح خاص جهة البِلد بس).

moonstack:release / ship → بينشر الباكدج في مجلد الريليس + بيحدّث versions.json (المانيفست اللي العميل بيـpoll عليه). ship = build + publish في خطوة، وكمان بينشر ملف الـ updater نفسه موقّع (للـ self-heal).

دِفلوبر → git push (GitHub) ← تعاون/باك أب فقط، مش في مسار الأبديت │ ▼ (لازم تنشر على moonui) moonui: git pull + local-deploy.sh → base_path() (BE) ng build --base-href /app/ → MOONSTACK_FRONTEND_DIST (FE) │ ▼ moonstack:build / ship = لقطة (snapshot) للفيلات دي الآن [ <name>-v<ver>.zip + sha256 + signature ] → release dir + versions.json

⚠️ الـ push لـ GitHub لوحده مايحطّش حاجة في الأبديت — اللي بيتشحن = اللي على moonui وقت الـ build.

2) جهة العميل (الأبديت) — إزاي بيتطبّق بأمان

moonstack-update.php (ملف مستقل) بيعمل بالترتيب:

Self-heal: لو فيه نسخة updater أحدث موقّعة → يستبدل نفسه ويطلب إعادة المحاولة (يمنع updater باظ من تعطيل الأسطول).

يقرا versions.json ويختار أصغر تنزيل: delta (الملفات المتغيّرة بس) لو متاح، وإلا full.

Pre-flight (متطلبات: PHP، صلاحيات…).

تنزيل + تحقق: sha256 لازم يطابق، والتوقيع يتأكد بالمفتاح العام.

Backup (DB + .env + الملفات المتأثرة) + كتابة lock فيه نقطة الرجوع.

Maintenance down.

Apply: delta = نسخ المتغيّر بس · full = تبديل الكود مع الحفاظ على الـ DATA (الفرونت delete-then-copy فمفيش chunks قديمة).

Composer — بس لو composer.lock اتغيّر (تجنّب نسخ 15k ملف vendor).

migrate (timeout-guarded) → جديد 8b sync-reference (يزرع تعريفات الإعدادات، best-effort/non-fatal) → caches.

up + finalize (ختم النسخة).

شبكات الأمان الموجودة دلوقتي قوية

register_shutdown_function: لو حصل fatal/timeout قبل ما يخلص → restore تلقائي للـ backup + خروج من maintenance + فك الـ lock.
stale-lock recovery: لو تحديث قديم كراش وساب lock بـ PID ميت → يرجّع للـ safe point في أول زيارة.
try/catch صريح: أي فشل (تنزيل/apply/migrate) → rollback (كود + DB).
كل exec ملفوف بـ timeout فمفيش خطوة تعلّق للأبد.

2.5) الريليس من GitHub `main` مباشرة — للعمل بكذا ديفلوبر موصى به

بدل ما تجمّع شغل كل الديفلوبرز يدويًا على moonui وتبلد، الأنضف إن الريليس يتبني من main (اللي كله بيعمله merge عليه أصلًا).

تصحيح مهم (متأكد منه من الريموت): main في الريبوهين فيه السورس بس — مفيش vendor ومفيش الفرونت المبني (public/app = 0 ملفات). الفرونت المبني موجود حاليًا في public_html اللي ملوش remote — يعني مش متبوش على GitHub. فالبِلد-من-git لازم يعمل خطوة بناء (composer + ng build)، وده ميزة: ريليس قابل لإعادة الإنتاج 100%.

الـ pipeline المقترح

الديفلوبرز merge لـ main (BE + FE) → نعمل tag للنسخة (v2.3.0) على الاتنين.

build runner (moonui أو CI) ينضّف ويبني من الـ tag:
• BE: git checkout v2.3.0 → composer install --no-dev --optimize-autoloader (ينتج vendor).
• FE: git checkout v2.3.0 → npm ci && ng build --base-href /app/ (ينتج dist).

php artisan moonstack:build v2.3.0 --source=<be-checkout> --frontend=<fe-dist> --sign → باكدج موقّع.

moonstack:release / ship → versions.json → العملاء ينزّلوا.

التغيير الوحيد المطلوب في الكود

PackageBuilder::build() بيقبل opts['source'] أصلًا، لكن أمر moonstack:build مفيهوش --source دلوقتي. نضيف اختيار --source (تعديل بسيط) → نقدر نبني من أي checkout نظيف من غير ما نلمس moonui. (بديل من غير تعديل: نشغّل الأمر من جوه الـ checkout نفسه بعد composer install + .env مؤقت.)

ليه ده أحسن

قابل لإعادة الإنتاج: الريليس = بالظبط الكوميت/الـ tag، مفيش ملفات قديمة أو غير متكوميتة بتتسرّب.
كذا ديفلوبر: كل واحد merge لـ main، الريليس بياخد من main — صفر تجميع يدوي.
مفيش تبويظ من "dirty working copy" على moonui.

التكلفة (مقبولة، مش بتخل بالسرعة/الدقة)

composer install + ng build لكل ريليس — جهة البِلد بس، مش بتأثر على سرعة تحديث العميل ولا دقته إطلاقًا.
انضباط الـ tagging. ولو عايزين كل ريليس تلقائي ومضمون: GitHub Actions يعمل البناء + الـ sign عند الـ tag وينشر.
توقيع الباكدج (المفتاح الخاص) لازم يفضل سرّي — لو CI، يتحط كـ secret، مش في الريبو.

ملاحظة: الخطة إننا نعمل merge لـ main بعد ما نخلّص شغل MoonStack — وده بالظبط نقطة بداية الريليس في الـ pipeline ده.

3) اقتراحاتي للتحسين مقترحات — مش منفّذة

كلها بتزوّد الاستقرار من غير ما تخل بالسرعة ولا الدقة — التأثير موضّح في الجدول.

#	التحسين	المكسب (استقرار)	السرعة	الدقة	الجهد
1	Health-check بعد الأبديت + rollback تلقائي بعد `up` وقبل فك الـ lock: نضرب endpoint صحة (مثلًا `/up` + لوجين/داشبورد). لو رجع خطأ → rollback تلقائي للـ backup.	عالي — بيمسك "migrate نجح بس الأبليكيشن باظ" (اللي دلوقتي بيعدّي)	+ريكوست واحد (مهمل)	محايد	صغير
2	Canary / إطلاق متدرّج (channels) الريليس يروح لعميل تجربة (moontest) الأول؛ بعد ما يثبت سليم نرقّيه لـ `stable` لباقي الأسطول.	عالي — ريليس باظ مايضربش كل العملاء مرة واحدة	محايد (تحديث كل عميل زيه زيه)	محايد	متوسط
3	بِلد قابل لإعادة الإنتاج (من tag نظيف) أو حارس "dirty tree" نبني من `git archive <tag>` في مجلد مؤقت، أو على الأقل نحذّر/نمنع الـ build لو `base_path` فيه تعديلات غير متكوميتة مقابل تاج الريليس.	دقة عالية — مستحيل نشحن ملفات قديمة/غير متكوميتة بالغلط	محايد على العميل (جهة البِلد فقط)	+++	صغير (حارس) / متوسط (archive)
4	تنظيف الـ backups (retention) نحتفظ بآخر N باك أب ونمسح الأقدم — القرص المليان نفسه ممكن يفشّل تحديث.	متوسط — يمنع فشل بسبب امتلاء القرص	محايد	محايد	صغير
5	تحقق سلامة بعد الـ apply بعد النسخ، نطابق checksums الملفات المشحونة من الـ manifest — نكتشف apply ناقص/تالف ونعمل rollback.	متوسط — يمسك تطبيق جزئي/تالف	+هاش للملفات المتغيّرة (بسيط)	+	صغير
6	اختبار idempotency لـ `updater.seeders` اختبار CI يتأكد إن كل seeder في القايمة updateOrCreate ومن غير side-effects (يحمي خطوة الـ seed الجديدة وهي بتكبر).	متوسط — يحافظ على أمان خطوة 8b	محايد (CI بس)	+	صغير

4) الترتيب المقترح للتنفيذ

Health-check + rollback تلقائي — أعلى مكسب أمان بأقل تكلفة. (يكمّل شبكات الأمان الموجودة بإنه يمسك الأعطال اللي بعد نجاح الـ migrate.)

Canary channel (moontest أولًا) — يحمي الأسطول من ريليس باظ.

حارس dirty-tree في الـ build — يضمن إننا بنشحن بالظبط اللي اتكوميت.

الباقي (retention · تحقق ما بعد apply · اختبار idempotency) — تحسينات تدريجية.

ملاحظة: مفيش حاجة فيهم بتبطّأ تحديث العميل — أغلبها جهة البِلد أو ريكوست/هاش بسيط، والـ canary مابيغيّرش سرعة التحديث الفردي.

السياق الكامل في الـ KB: knowledge-base/topics/moonstack-update.md · مرتبط بـ middleware.md.