Heimserver & Self-Hosting

Geplante Wartung mit HTTP 503 - Vorübergehende Ausfallzeit ehrlich kennzeichnen

Geplante Wartung mit HTTP 503 - Vorübergehende Ausfallzeit ehrlich kennzeichnen

Geplante Wartung mit HTTP 503 - Vorübergehende Ausfallzeit ehrlich kennzeichnen

Eine Wartungsseite kann im Browser beruhigend aussehen und zugleich jedem Client, der ihren Text nicht interpretieren kann, etwas Falsches mitteilen. Wenn der angeforderte Artikel durch „Wir sind bald wieder da“ ersetzt wird, die Antwort aber weiterhin 200 OK trägt, besagt die HTTP-Nachricht, dass die Anfrage erfolgreich war und die Wartungsseite die angeforderte Repräsentation ist.

Dieser Widerspruch betrifft mehr als Suchmaschinen-Crawler. API-Clients, Monitoring-Systeme, Caches, Kommandozeilenwerkzeuge und Browser erhalten zuerst einen Status und Header. Der Seiteninhalt ist für den Menschen bestimmt; die HTTP-Metadaten erklären der Software, was geschehen ist.

Bei einer kurzen geplanten Unterbrechung kann 503 Service Unavailable beide Ebenen in Einklang bringen. Es ist ein kleiner Statuscode mit einer begrenzten Aussage: Der Dienst ist im Moment nicht verfügbar, und der Zustand gilt als vorübergehend. Er verspricht keinen exakten Zeitpunkt der Wiederherstellung und ist nicht automatisch die beste Antwort für jede Wartung.

Was 503 aussagt

RFC 9110 definiert 503 für einen Server, der eine Anfrage wegen vorübergehender Überlastung oder geplanter Wartung momentan nicht verarbeiten kann. Der Server darf außerdem Retry-After senden, um anzugeben, wie lange dieser Zustand voraussichtlich anhält.

Das Wort vorübergehend ist entscheidend. Mehrere Antworten können im Browser eine wenig hilfreiche Seite erzeugen, bedeuten aber Unterschiedliches:

  • 200 OK besagt, dass die Anfrage erfolgreich war. Ein Wartungshinweis ist keine erfolgreiche Kopie des angeforderten Artikels, Dashboards oder API-Resources.
  • 404 Not Found besagt, dass der Origin keine aktuelle Repräsentation für das Ziel gefunden hat. Eine geplante Wartung lässt nicht alle Resources verschwinden.
  • 410 Gone vermittelt eine beabsichtigte, wahrscheinlich dauerhafte Nichtverfügbarkeit. Das ist deutlich stärker als „Die Datenbankmigration sollte bald abgeschlossen sein“.
  • 503 Service Unavailable besagt, dass der Server die Anfrage aufgrund eines vorübergehenden Zustands momentan nicht verarbeiten kann.

Zu 503 gehört weiterhin ein verständlicher Body. Er kann erklären, was nicht verfügbar ist, was weiterhin funktioniert, wann die nächste Aktualisierung erwartet wird und wo Besucher Hilfe erhalten. Der Status ersetzt die Kommunikation nicht; er verhindert, dass sie dem Protokoll widerspricht.

Retry-After ist eine Orientierung, kein Termin

Das Feld Retry-After akzeptiert entweder ein HTTP-Datum oder eine Anzahl von Sekunden:

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

Retry-After: 3600

Die erste Form nennt einen Zeitpunkt; die zweite bittet den User Agent, nach Empfang der Antwort entsprechend viele Sekunden zu warten. Delay-seconds können für ein kurzes Zeitfenster einfacher sein, weil kein korrekt formatiertes zukünftiges Datum in die Konfiguration eingetragen werden muss.

Keine der beiden Formen plant automatisch einen neuen Versuch. Der RFC beschreibt, wie lange ein User Agent warten sollte. Ein Browser kann jedoch lediglich die Seite anzeigen, ein Crawler kann seine eigene Richtlinie anwenden und ein individueller Client kann das Feld ignorieren. Eine ehrliche Schätzung ist besser als eine falsche Garantie. Ist das Ende unbekannt, ist eine klare Seite ohne erfundene Genauigkeit sinnvoller als ein selbstbewusster, aber bedeutungsloser Zeitstempel.

Ein kleines Nginx-Muster

Das folgende Muster verwendet eine Flag-Datei als Schalter. Es ist absichtlich klein, muss aber dennoch an die bestehenden Locations, das Document Root, Proxy- oder FastCGI-Regeln und den Deployment-Prozess der Website angepasst werden.

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.
}

Nginx dokumentiert sowohl die Prüfung auf vorhandene Dateien in if als auch return mit einem gewählten Status. Ist die Flag-Datei vorhanden, endet die Verarbeitung mit 503. Die error_page-Direktive führt anschließend einen internen Redirect zur statischen Seite aus. Der Fehlerstatus bleibt erhalten, weil die Konfiguration ihn nicht durch =200 ersetzt.

Die exakte Location für robots.txt wird getrennt von der allgemeinen location / ausgewertet, sodass die Datei erreichbar bleibt. Diese Ausnahme ist keine allgemeine HTTP-Anforderung. Sie folgt den Empfehlungen von Google Search Central für eine vorübergehend deaktivierte Website: Die robots-Datei sollte nicht mit 503 beantwortet werden, weil dies das Crawling durch Google blockiert.

Warum die Wartungs-Location internal ist

Die Direktive internal verhindert, dass Besucher /maintenance.html direkt anfordern. Nginx kann die Seite über den Error-Page-Redirect erreichen, eine gewöhnliche externe Anfrage kann diese URI jedoch nicht wie eine öffentliche Seite verwenden. So bleibt eine nützliche Invariante erhalten: Die Wartungsrepräsentation begleitet eine tatsächliche Wartungsantwort.

Warum die Header always verwenden

Standardmäßig gilt Nginx' add_header-Direktive nur für eine dokumentierte Liste von Response-Codes, in der 503 nicht enthalten ist. Der Parameter always ist hier daher erforderlich.

Ebenso wichtig ist es, diese Header auf die Wartungs-Location zu begrenzen. Ein Retry-After: 3600 auf Server-Ebene könnte nach Ende der Wartung in gesunde Antworten gelangen. Auch die Header-Vererbung von Nginx verdient Beachtung: Eine add_header-Definition auf einer untergeordneten Ebene kann abhängig von Konfiguration und Nginx-Version ändern, welche übergeordneten Header geerbt werden. Fügt der normale Server Sicherheits-Header hinzu, sollte die fertige Wartungsantwort geprüft werden, anstatt ihre Vererbung vorauszusetzen.

Cache-Control: no-store ist eine konservative Wahl für diese statische Fehlerantwort. Sie verringert das Risiko, dass ein Cache nach der Wiederherstellung weiterhin die Wartungsseite vom Vortag ausliefert. MDN weist darauf hin, dass Caching-Header bei einer 503-Antwort besondere Aufmerksamkeit benötigen; dieses Beispiel ist eine betriebliche Empfehlung und keine Regel, nach der jede 503-Antwort dieselbe Cache-Richtlinie verwenden muss.

Die Seite vom betroffenen Stack unabhängig halten

Eine Wartungsseite, die durch dieselbe PHP-Anwendung, Datenbank, Asset-Pipeline und dieselben externen Skripte läuft, an denen gearbeitet wird, kann auf zu viele Arten scheitern. Google empfiehlt bei einer vollständigen Schließung statisches HTML mit möglichst wenigen externen Resources. Eine eigenständige Seite kann so schlicht sein:

<!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>

Die Zeitangabe im Body und im Header sollte dieselbe Geschichte erzählen. Ändert sich die Schätzung, müssen beide aktualisiert werden. Ein JavaScript-Countdown, der unbemerkt null erreicht, während die Störung andauert, ist ungeeignet; gewöhnliche Sprache kann Unsicherheit ehrlicher ausdrücken.

Den Übergang testen, nicht nur die Datei

Ein plausibel aussehendes Nginx-Snippet beweist nicht, dass ein bestimmter Server-Block korrekt funktioniert. Vor dem Reload muss die zusammengesetzte Konfiguration validiert werden:

sudo nginx -t
sudo systemctl reload nginx

Anschließend sollte eine repräsentative öffentliche URL geprüft werden. Status und Header sind die entscheidenden Belege:

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

Während der Wartung sollte die erste Antwort 503, das vorgesehene Retry-After, die Cache-Richtlinie und den statischen Body zeigen. Die robots-Datei sollte ihre normale erfolgreiche Antwort liefern. Akzeptiert die Website Schreibzugriffe, muss außerdem eine POST- oder API-Route getestet werden; die Wartung darf nicht versehentlich hinter der freundlichen Seite eine zustandsändernde Anfrage verarbeiten.

Auch die Wiederherstellung benötigt einen eigenen Test. Nach dem Entfernen der Flag-Datei ist ein Reload nur dann nötig, wenn die umgebende Konfiguration ihn verlangt. Danach werden dieselben URLs erneut abgerufen. Die normale Seite sollte ihren üblichen Status liefern, der Wartungs-Body sollte verschwunden sein und Retry-After darf nicht zurückbleiben. Ist ein CDN- oder Reverse-Proxy-Cache Teil des Pfades, sollte auch außerhalb dieses Caches geprüft werden.

Wann ein websiteweites 503 das falsche Werkzeug ist

Ein Schalter für die gesamte Website ist einfach, doch diese Einfachheit kann unnötige Nachteile verbergen. Wenn Artikel, Dokumentation und Kontoverlauf lesbar bleiben können, während Checkout oder Publishing pausieren, ist diese Read-only-Oberfläche für Besucher meist nützlicher. Auch Google empfiehlt, wenn möglich die Funktionalität einzuschränken, anstatt die gesamte Website zu deaktivieren.

Ein kurzes 503-Zeitfenster sollte zudem nicht zu einem unbestimmten langfristigen Zustand werden. Google warnt, dass die Deaktivierung einer gesamten Website über einen sehr kurzen Zeitraum hinaus ihre Präsenz in Search erheblich beeinträchtigen kann, selbst bei korrekter Umsetzung. Diese Aussage beschreibt Googles Systeme, keinen universellen Ranking-Timer, und garantiert keine folgenlose Dauer.

Schließlich verwenden geplante Wartung und Überlastung zwar denselben Status, aber nicht dasselbe Steuerungssystem. Eine manuell angelegte Flag-Datei kann eine geplante Datenbankmigration abbilden. Sie erkennt keinen CPU-Druck, entscheidet nicht, welcher Traffic abgewiesen wird, und stellt keinen fehlerhaften Upstream wieder her. Automatischer Überlastungsschutz benötigt Monitoring, Schwellenwerte und ein Fehlerverhalten, das über diese Seite hinausgeht.

Fazit

Eine Wartungsseite hat zwei Zielgruppen. Menschen benötigen eine knappe Erklärung und eine realistische nächste Aktualisierung. Software benötigt eine Antwort, deren Status und Header denselben vorübergehenden Fehler beschreiben.

Bei einer kurzen Unterbrechung der gesamten Website können 503 Service Unavailable, ein sorgfältig geschätztes Retry-After und ein statischer, von Nginx ausgelieferter Body beide Zielgruppen in Einklang bringen. Das Muster bleibt unvollständig, bis sowohl Aktivierung als auch Wiederherstellung getestet wurden. Die hilfreichere Frage lautet nicht nur „Wie aktiviere ich den Wartungsmodus?“, sondern „Wie viel von der Website muss tatsächlich überhaupt nicht verfügbar werden?“

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