كل المقالات التقنية

صفحات أخطاء مخصصة ووضع صيانة بالرمز 503 في Nginx

أنشئوا صفحات أخطاء مخصصة في Nginx ووضع صيانة آمناً بالرمز 503 وRetry-After حتى لا تراه محركات البحث موقعاً معطلاً.

صفحات أخطاء مخصصة ووضع صيانة بالرمز 503 في Nginx

عندما يتوقف خادم التطبيق أو تغلقون الموقع لفترة وجيزة للصيانة، يرى الزائر صفحة خطأ خام. بضعة أسطر في Nginx تتيح عرض صفحة منظمة وإبلاغ محركات البحث بأن الوضع مؤقت.

١. صفحة خطأ بسيطة

أنشئوا ملف HTML ثابتاً وسجّلوه لأخطاء جهة الخادم:

error_page 502 503 504 /50x.html;
location = /50x.html {
    root /var/www/errors;
    internal;
}

يجب أن تكون الصفحة ثابتة ومستقلة؛ فإن اعتمدت على التطبيق المعطل فستفشل هي أيضاً.

٢. الأخطاء خلف وكيل

عندما يقف Nginx أمام تطبيق تمر رسائل الخطأ الصادرة من التطبيق نفسه كما هي افتراضياً. ولاستبدالها بـ error_page فعّلوا proxy_intercept_errors on;. وبدونه تستخدم صفحتكم أخطاء Nginx نفسه فقط، مثل تعذر الوصول إلى upstream. راجعوا Nginx كوكيل عكسي لإعداد الوكيل.

٣. وضع الصيانة بالرمز 503

error_page 503 @maintenance;
location @maintenance {
    root /var/www/errors;
    add_header Retry-After 3600 always;
    rewrite ^ /maintenance.html break;
}

if (-f /var/www/maintenance.on) {
    return 503;
}

إنشاء الملف maintenance.on يضع الموقع في الصيانة وحذفه يعيده دون تعديل الإعداد. يخبر الرمز 503 الروبوتات أن الحالة مؤقتة؛ أما عرض 200 لصفحة الصيانة فقد يضر بالفهرسة. وإذا احتاج المديرون إلى الدخول من عنوان IP محدد فأضيفوا ذلك منفصلاً واختبروه.

٤. الاختبار

sudo nginx -t && sudo systemctl reload nginx
touch /var/www/maintenance.on
curl -I https://example.com/

يجب أن ترون 503 وترويسة Retry-After. ثم احذفوا الملف وتأكدوا من عودة 200. ترتيب الكتل مهم، فراجعوا ترتيب مطابقة location.

٥. مثال توضيحي وليس قياساً حقيقياً

لنفترض إنشاء maintenance.on لمدة عشر دقائق أثناء ترقية قاعدة البيانات. يرى الزوار صفحة الصيانة ويُظهر curl الرمز 503 مع Retry-After. هذا سيناريو مختلق للتوضيح وليس قياساً حقيقياً.

٦. أخطاء شائعة

  • إرجاع 200 لصفحة الصيانة.
  • جعل صفحة الخطأ تعتمد على التطبيق المعطل.
  • نسيان proxy_intercept_errors خلف الوكيل.
  • ترك maintenance.on بعد انتهاء العمل.

٧. أسئلة شائعة

ما قيمة Retry-After المناسبة؟ عدد الثواني حتى المحاولة التالية؛ ضعوا تقديراً واقعياً لمدة الصيانة.

هل if آمن في Nginx؟ return داخل if نمط شائع وآمن؛ تجنبوا التعليمات المعقدة داخله.

هل يرى المديرون صفحة الصيانة أيضاً؟ نعم ما لم تضيفوا استثناءً منفصلاً.

٨. قائمة تحقق سريعة

  1. أُنشئت صفحة HTML ثابتة.
  2. ضُبطت error_page وlocation داخلي.
  3. فُعّل الاعتراض للتطبيقات خلف الوكيل.
  4. نُفذ nginx -t وإعادة التحميل.
  5. أظهر curl الرمز 503 مع Retry-After ثم 200 بعد حذف الملف.

إذا احتجتم إلى مساعدة في مراجعة الأداء أو صيانة الخادم، فراجعوا خدمات إدارة الخوادم.

تجدون المزيد من أدلة الخوادم وووردبريس في أرشيف المقالات.

المراجع الرسمية

Nginx error_page directive · Nginx proxy_intercept_errors · Google Search Central: HTTP status codes