Server Rumahan & Self-Hosting

Maintenance Terencana dengan HTTP 503 - Jujur tentang Downtime Sementara

Maintenance Terencana dengan HTTP 503 - Jujur tentang Downtime Sementara

Maintenance Terencana dengan HTTP 503 - Jujur tentang Downtime Sementara

Halaman maintenance bisa terlihat menenangkan di browser sambil menyampaikan hal yang keliru kepada setiap client yang tidak dapat memahami prosanya. Jika artikel yang diminta diganti dengan “Kami akan segera kembali” tetapi response masih membawa 200 OK, pesan HTTP menyatakan bahwa request berhasil dan halaman maintenance adalah representasi yang diminta.

Ketidaksesuaian itu berpengaruh bukan hanya pada crawler mesin pencari. API client, monitor, cache, command-line tool, dan browser pertama-tama menerima status dan header. Isi halaman ditujukan bagi orang yang membacanya; metadata HTTP menjelaskan kepada software apa yang terjadi.

Untuk gangguan terencana yang singkat, 503 Service Unavailable dapat membuat kedua lapisan tersebut selaras. Ini status code kecil dengan janji yang sempit: layanan sedang tidak tersedia, dan kondisinya diperkirakan sementara. Status ini tidak menjanjikan waktu pemulihan yang pasti, dan bukan otomatis jawaban terbaik untuk setiap jenis maintenance.

Apa yang Dinyatakan 503?

RFC 9110 mendefinisikan 503 untuk server yang saat ini tidak mampu menangani request karena kelebihan beban sementara atau maintenance terjadwal. Server juga dapat mengirim Retry-After untuk menyarankan berapa lama kondisi tersebut diperkirakan berlangsung.

Kata sementara punya peran penting. Bandingkan beberapa response yang semuanya dapat menghasilkan halaman yang tidak membantu di browser:

  • 200 OK menyatakan request berhasil. Pemberitahuan maintenance bukan salinan artikel, dashboard, atau resource API yang berhasil diminta.
  • 404 Not Found menyatakan origin tidak menemukan representasi terkini untuk target tersebut. Maintenance terencana tidak membuat semua resource menghilang.
  • 410 Gone menyampaikan ketidaktersediaan yang disengaja dan kemungkinan permanen. Makna ini jauh lebih kuat daripada “migrasi database seharusnya segera selesai.”
  • 503 Service Unavailable menyatakan server tidak mampu menangani request sekarang karena kondisi sementara.

Body yang ramah tetap perlu menyertai 503. Isinya dapat menjelaskan apa yang tidak tersedia, apa yang masih tersedia, kapan pembaruan status berikutnya diharapkan, dan ke mana pengunjung dapat mencari bantuan. Status bukan pengganti komunikasi; status mencegah komunikasi tersebut bertentangan dengan protokol.

Retry-After Adalah Panduan, Bukan Janji Waktu

Field Retry-After menerima HTTP date atau jumlah detik:

Retry-After: Tue, 17 Nov 2026 02:00:00 GMT

Retry-After: 3600

Bentuk pertama menunjukkan waktu; bentuk kedua meminta user agent menunggu selama jumlah detik tersebut setelah menerima response. Delay-seconds dapat lebih mudah untuk jendela singkat karena tidak bergantung pada penulisan tanggal mendatang dengan format yang benar ke dalam konfigurasi.

Kedua bentuk itu tidak menjadwalkan retry. RFC menjelaskan berapa lama user agent sebaiknya menunggu, tetapi browser mungkin hanya menampilkan halaman, crawler mungkin menerapkan kebijakannya sendiri, dan custom client mungkin mengabaikan field tersebut. Pilih perkiraan yang jujur, bukan jaminan palsu. Jika waktu selesai belum diketahui, halaman yang jelas tanpa presisi buatan lebih baik daripada timestamp penuh keyakinan tetapi tanpa arti.

Pola Nginx yang Ringkas

Pola berikut memakai flag file sebagai sakelar. Pola ini sengaja dibuat ringkas, tetapi tetap perlu disesuaikan dengan location, document root, aturan proxy atau FastCGI, dan proses deployment milik situs.

server {
    server_name example.com;
    root /var/www/example.com/public;

    error_page 503 /maintenance.html;

    location = /robots.txt {
        try_files /robots.txt =404;
    }

    location / {
        if (-f /var/www/example.com/maintenance.flag) {
            return 503;
        }

        try_files $uri $uri/ /index.php?$query_string;
    }

    location = /maintenance.html {
        internal;
        add_header Retry-After "3600" always;
        add_header Cache-Control "no-store" always;
    }

    # The site's existing PHP location belongs here.
}

Dokumentasi Nginx menjelaskan pengujian keberadaan file dalam if dan return dengan status yang dipilih. Saat flag tersedia, pemrosesan request berhenti dengan 503. Directive error_page kemudian melakukan internal redirect ke halaman statis sambil mempertahankan status error karena konfigurasi tidak menggantinya dengan =200.

Location tepat untuk robots.txt dievaluasi terpisah dari location / yang umum, sehingga file tersebut tetap tersedia. Pengecualian ini bukan persyaratan HTTP universal. Ini mengikuti panduan Google Search Central untuk situs yang dinonaktifkan sementara: jangan menjawab file robots dengan 503 karena hal itu memblokir crawling Google.

Mengapa Location Maintenance Bersifat Internal?

Directive internal mencegah pengunjung meminta /maintenance.html secara langsung. Nginx dapat mencapainya melalui redirect error page, tetapi request eksternal biasa tidak dapat memakai URI itu seolah-olah merupakan halaman publik. Ini menjaga satu invariant yang berguna: representasi maintenance menyertai response maintenance yang nyata.

Mengapa Header Menggunakan always?

Secara default, directive add_header milik Nginx hanya berlaku pada daftar response code yang terdokumentasi, dan 503 tidak termasuk di dalamnya. Karena itu, parameter always diperlukan di sini.

Membatasi header tersebut ke location maintenance sama pentingnya. Retry-After: 3600 pada level server dapat bocor ke response sehat setelah maintenance selesai. Pewarisan header Nginx juga perlu diperhatikan: mendefinisikan add_header pada level anak dapat mengubah header induk mana yang diwarisi, tergantung konfigurasi dan versi Nginx. Jika server normal menambahkan security header, uji response maintenance akhirnya alih-alih berasumsi header tersebut tetap ada.

Cache-Control: no-store adalah pilihan konservatif untuk response error statis ini. Ini mengurangi risiko cache terus menyajikan halaman maintenance kemarin setelah layanan pulih. MDN mengingatkan bahwa caching header pada 503 memerlukan perhatian khusus; contoh ini adalah panduan operasional, bukan aturan bahwa setiap response 503 harus menggunakan kebijakan cache yang sama.

Buat Halaman Tidak Bergantung pada Stack yang Sedang Bermasalah

Halaman maintenance yang dirutekan melalui aplikasi PHP, database, asset pipeline, dan script pihak ketiga yang sama-sama sedang dirawat memiliki terlalu banyak cara untuk gagal. Google merekomendasikan HTML statis dengan resource eksternal sesedikit mungkin untuk penutupan seluruh situs. Halaman mandiri bisa sesederhana ini:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Short maintenance window</title>
  <style>
    body { max-width: 42rem; margin: 12vh auto; padding: 1rem;
           font: 1.1rem/1.6 system-ui, sans-serif; }
  </style>
</head>
<body>
  <h1>Short maintenance window</h1>
  <p>This service is temporarily unavailable.</p>
  <p>The next status update is expected by 02:00 UTC.</p>
</body>
</html>

Waktu di body dan header harus menyampaikan cerita yang konsisten. Jika perkiraan berubah, perbarui keduanya. Hindari countdown JavaScript yang diam-diam mencapai nol saat gangguan masih berlangsung; bahasa biasa dapat mengakui ketidakpastian dengan lebih jujur.

Uji Transisinya, Bukan Hanya Filenya

Snippet Nginx yang tampak valid bukan bukti bahwa server block tertentu berperilaku benar. Validasi konfigurasi yang sudah dirangkai sebelum melakukan reload:

sudo nginx -t
sudo systemctl reload nginx

Kemudian periksa URL publik yang mewakili. Status dan header adalah bukti utamanya:

curl -i https://example.com/an-existing-page
curl -i https://example.com/robots.txt

Selama maintenance, response pertama seharusnya menunjukkan 503, Retry-After yang dimaksud, kebijakan cache, dan body statis. File robots seharusnya menunjukkan response sukses normalnya. Uji juga route POST atau API jika situs menerima write; maintenance tidak boleh tanpa sengaja memproses request yang mengubah state di balik halaman ramah tersebut.

Pemulihan memerlukan pengujiannya sendiri. Hapus flag, lakukan reload hanya jika setup di sekitarnya membutuhkannya, lalu minta URL yang sama lagi. Halaman normal seharusnya mengembalikan status normal, body maintenance seharusnya hilang, dan Retry-After tidak boleh tertinggal. Periksa juga dari luar cache CDN atau reverse proxy jika lapisan tersebut menjadi bagian dari rute.

Kapan 503 untuk Seluruh Situs Bukan Alat yang Tepat?

Sakelar maintenance untuk seluruh situs memang sederhana, tetapi kesederhanaan dapat menyembunyikan dampak yang tidak perlu. Jika artikel, dokumentasi, dan riwayat akun dapat tetap dibaca sementara checkout atau publishing dihentikan, mempertahankan permukaan read-only tersebut biasanya lebih berguna bagi pengunjung. Google juga merekomendasikan pembatasan fungsi alih-alih menonaktifkan seluruh situs jika memungkinkan.

Jendela 503 yang singkat juga tidak seharusnya berubah menjadi kondisi sementara jangka panjang yang tidak jelas. Google memperingatkan bahwa menonaktifkan seluruh situs lebih dari waktu yang sangat singkat dapat berdampak besar pada keberadaannya di Search, bahkan saat diterapkan dengan benar. Pernyataan itu menjelaskan sistem Google, bukan timer ranking universal, dan tidak menawarkan durasi aman yang dijamin.

Terakhir, maintenance terencana dan overload memakai status yang sama tetapi bukan sistem kendali yang sama. Flag yang dibuat manual dapat mewakili migrasi database terjadwal. Flag tersebut tidak mendeteksi tekanan CPU, memilih traffic yang perlu dikurangi, atau memulihkan upstream yang tidak sehat. Perlindungan overload otomatis memerlukan monitoring, threshold, dan perilaku kegagalan di luar halaman ini.

Kesimpulan

Halaman maintenance memiliki dua audiens. Orang membutuhkan penjelasan ringkas dan pembaruan berikutnya yang realistis. Software membutuhkan response dengan status dan header yang menjelaskan kegagalan sementara yang sama.

Untuk gangguan singkat pada seluruh situs, 503 Service Unavailable, Retry-After yang diperkirakan dengan hati-hati, dan body statis yang dilayani Nginx dapat menyelaraskan kedua audiens tersebut. Pola ini tetap belum lengkap sebelum proses masuk dan pemulihannya sama-sama diuji. Pertanyaan yang lebih berguna bukan sekadar “bagaimana cara mengaktifkan maintenance mode?” melainkan “seberapa banyak bagian situs yang benar-benar perlu dibuat tidak tersedia?”

References

  1. 503 Service Unavailable, RFC 9110 - RFC Editor
  2. Retry-After, RFC 9110 - RFC Editor
  3. ngx_http_core_module: error_page and internal - Nginx
  4. ngx_http_rewrite_module: if and return - Nginx
  5. ngx_http_headers_module: add_header - Nginx
  6. Temporarily Pause or Disable a Website - Google Search Central
  7. 503 Service Unavailable - MDN Web Docs