همه مقالات تخصصی

صفحهٔ خطای سفارشی و حالت تعمیر با کد 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 به‌عنوان reverse proxy ببینید.

۳. حالت تعمیر با 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 الگوی امن و رایج است؛ از دستورهای پیچیده درون if پرهیز کنید.

صفحهٔ تعمیر برای مدیر هم نمایش داده می‌شود؟ بله مگر استثنای جداگانه بگذارید.

۸. چک‌لیست سریع

  1. صفحهٔ HTML ثابت ساخته شد.
  2. error_page و location داخلی تنظیم شد.
  3. برای پروکسی intercept فعال شد.
  4. nginx -t و reload انجام شد.
  5. curl کد 503 و Retry-After نشان داد و بعد از حذف فایل 200 شد.

اگر برای بررسی عملکرد یا نگهداری سرور به همکاری نیاز دارید، محدودهٔ خدمات مدیریت سرور را ببینید.

راهنماهای بیشتر سرور و وردپرس در آرشیو مقالات جمع شده‌اند.

منابع رسمی

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