استعادة نشر توثيق من أخطاء Coolify 502 و503

يعني 502 أو 503 أن الطلب وصل إلى طبقة ما، لكنه لم يحصل على خدمة صالحة من الطبقة التالية. لا يخبرك الرمز وحده إن كانت المشكلة في DNS أو proxy أو الحاوية أو readiness أو قاعدة البيانات أو الترحيل. ابدأ بتحديد أول طبقة فاشلة قبل إعادة النشر أو حذف أي شيء.

هذا الدليل للقراءة أولاً. اجمع الهوية والسجلات والمسابير قبل تغيير الحالة، لأن إعادة التشغيل قد تمحو التوقيت الذي يكشف السبب.

ميّز بين الرمزين أولاً

يشير 502 Bad Gateway غالباً إلى أن الوكيل حاول الاتصال بـupstream وفشل أو تلقى استجابة غير صالحة. يشير 503 Service Unavailable غالباً إلى عدم وجود backend جاهز أو إلى drain أو نافذة استبدال. الإعداد الفعلي قد يغير المعنى، لذلك اربط الرمز بسجل الوكيل والحاوية في اللحظة نفسها.

اختبر صفحة صحة ومساراً عاماً معروفاً. قد تنجح health سطحية بينما تفشل الصفحة بسبب قاعدة البيانات، وقد تفشل readiness عمداً حتى تكتمل migration.

أثبت هوية النشر قبل تغيير الحالة

سجّل مشروع Coolify والخدمة وdeployment ID وcommit ووسم الصورة وdigest إن أمكن. قارنها بالهوية التي يعرضها endpoint الصحة أو سجل بدء التطبيق.

لا تفترض أن آخر build هو الذي يخدم الحركة. قد يكون build نجح بينما بقيت الحاوية القديمة، أو بدأت صورة جديدة ثم فشلت readiness. احتفظ بتوقيتات build وpull وstart وhealth والتحويل.

افحص من الخارج والداخل

من جهاز خارج الخادم:

curl -sS -D - -o /dev/null https://docs.example.com/
curl -sS https://docs.example.com/health

ثم من الخادم افحص حالة الحاويات والسجلات والشبكة الداخلية:

docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}'
docker logs --tail=200 <container>
docker inspect <container> --format '{{json .State.Health}}'

لا تنشر tokens أو env في تذكرة عامة. شارك أسماء المتغيرات وحالة وجودها فقط.

الطبقة 1: الوكيل وتوجيه النطاق

تحقق من DNS وTLS وHost والمسار والمنفذ الذي يتوقعه الوكيل. يجب أن تستمع الحاوية على الواجهة والمنفذ المسجلين في Coolify. افحص ما إذا كان health check يستخدم مساراً مختلفاً أو HTTP بينما التطبيق يفرض HTTPS داخلياً.

إذا نجح الاتصال المباشر من شبكة Docker وفشل النطاق، ركز على التوجيه والشهادة. لا تغير قاعدة البيانات في هذه الحالة.

الطبقة 2: دورة حياة الحاوية والأمر

افحص exit code وعدد مرات restart وأمر التشغيل وworking directory. أخطاء "module not found" أو ملف build مفقود تختلف عن out-of-memory. تأكد أن الصورة المبنية تحتوي artifact الإنتاج وأن command لا يشغّل dev server.

راقب حدود الذاكرة والقرص. لا ترفعها عشوائياً قبل معرفة peak والسبب؛ قد يخفي ذلك تسرباً أو build داخل الحاوية.

الطبقة 3: liveness وreadiness

يجب أن تجيب liveness عن صلاحية إعادة التشغيل، وreadiness عن استقبال الحركة. اجعل readiness تفشل إذا كان الاعتماد الحرج غير متاح، لكن لا تجعلها تنفذ عملاً ثقيلاً أو migration.

قارن timeout وinterval وstart period بزمن بدء التطبيق الفعلي. نافذة قصيرة قد تقتل خدمة سليمة قبل أن تبدأ، بينما نافذة طويلة تخفي فشلاً حقيقياً.

الطبقة 4: قاعدة البيانات وترتيب الترحيل

افحص الاتصال وTLS والمستخدم والمخطط وسجل migration. يجب أن تعمل migration كوظيفة منفصلة ناجحة قبل توجيه الحركة إلى كود يحتاج المخطط الجديد.

إذا كانت migration غير متوافقة مع النسخة القديمة، فقد تفشل الحاويتان أثناء الاستبدال. عالج التوافق بخطوات expand/contract أو خطط توقفاً صريحاً. لا تشغل migration نفسها بالتوازي من عدة replicas.

الطبقة 5: cache والطابور وتخزين الكائنات

قد يبدأ web بينما يفشل العامل أو النشر بسبب Redis أو S3. افحص DNS الداخلي وcredentials والصلاحيات وbucket وCORS. جرّب كتابة وقراءة أصل غير حساس عبر المسار نفسه.

حدد ما هو durable. الطابور وcache غالباً قابلان لإعادة البناء، أما قاعدة البيانات والأصول فبحاجة إلى نسخ واستعادة.

الطبقة 6: اكتمال البناء والـartifact

قارن الملفات داخل الصورة مع ما يتوقعه command. في monorepo، قد ينجح package فرعي بينما يغيب dependency أو generated client. احفظ سجل build وlockfile وهوية base image.

لا تجعل CI يبني صور Docker تلقائياً لكل pull request إذا كانت سياسة المستودع تتطلب trigger يدوياً. افصل فحوص المصدر عن بناء ونشر الصورة.

نافذة الاستبدال وادعاءات التوفر

قد تعرض عملية استبدال Compose 503 حقيقية بين إيقاف القديمة وجاهزية الجديدة. لا تسمها zero downtime من دون مجسات خارجية مستمرة وتداخل مثبت بين نسختين جاهزتين على مستوى المزود.

سجّل بداية النافذة ونهايتها وعدد الفشل. إذا كان عدم الانقطاع شرطاً، استخدم بنية توفر overlap وhealth-aware routing بدلاً من الاعتماد على ترتيب أوامر واحد.

تسلسل استعادة آمن

1. جمّد التغييرات وحدد آخر نشر معروف.
2. اجمع حالة الوكيل والحاويات والhealth والسجلات والموارد.
3. اختبر الاتصال الداخلي لكل dependency.
4. أصلح أول طبقة فاشلة بأصغر تغيير قابل للعكس.
5. أعد تشغيل الخدمة المتأثرة فقط عند الإمكان.
6. افحص health ثم الصفحة العامة و404 وsitemap والبحث والصور.
7. قارن revision العامة بالمرشح.
8. وثق السبب وإجراء المنع، لا مجرد أن retry نجح.

أغلق حدود البيانات والدعم

قبل إعادة الحركة، أثبت اكتمال استعادة قاعدة البيانات والأصول واختبر مهام النشر والفهرسة والبريد وwebhook والتصدير الجارية. قرر هل يُستأنف الطابور أو يعاد بمفتاح عدم تكرار أو يُهمل صراحة. حاوية web سليمة بجانب طابور مفقود ليست استعادة كاملة.

سجّل artifact والمخطط ولقطة المحتوى ومدة دعم الإصدار ومسار EOL. المستودع AGPL-3.0، لكن التزام الرخصة واستخدام الاسم أو الشعار مسألتان منفصلتان. استعن بمستشار فيما يهم نشرك؛ هذا الدليل ليس نصيحة قانونية ولا يمنح حقوق علامة تجارية.

متى يكون نموذج نشر آخر أفضل؟

إذا كان الفريق لا يريد تشغيل قاعدة بيانات وطابور وتخزين، قد يكون مولد ثابت على استضافة مُدارة أبسط. وإذا كانت الاستعادة والتوفر مسؤولية لا يستطيع الفريق امتلاكها، استخدم خدمة توثيق مُدارة. Coolify يقلل عبء النشر لكنه لا يلغي تصميم الصحة والنسخ والتوافق.

تطبيق الدليل على Nibleaf

يتضمن Nibleaf app وserver وworker وPostgreSQL وDragonfly وتخزين كائنات ومهمة migration. افحص كل طبقة منفصلة، وسمِّ الصورة وrevision. مسارات /health دليل جزئي؛ يجب أن تكملها صفحة عامة ومسبار نشر وبحث وصورة.

المراجع وتاريخ المراجعة

رُوجعت المراجع في 2026-09-03: توثيق Coolify، فحوص Docker Compose، إرشادات Docker للإنتاج، وRFC 9110.