Warum gibt ein Reverse-Proxy nach dem Neubau eines Containers den Fehler 502 zurück?

Eva Wong

IceWhale author

Eva Wong ist die Technische Redakteurin und und leidenschaftliche Tüftlerin bei ZimaSpace. Eine lebenslange Geek mit einer Leidenschaft für Homelabs und Open-Source-Software, sie spezialisiert sich darauf, komplexe technische Konzepte in zugängliche, praktische Anleitungenzu übersetzen. Eva ist der Meinung, dass Self-Hosting Spaß machen und nicht einschüchternd sein sollte. Durch ihre Tutorials befähigt sie die Community, Hardware-Setups zu entmystifizieren, vom Bau ihres ersten NAS bis hin zur Beherrschung von Docker-Containern.

Why Does a Reverse Proxy Return 502 After a Container Rebuild?

Ein Reverse-Proxy gibt nach dem Neuaufbau eines Containers den Status 502 zurück, wenn er keine gültige Verbindung zum neu aufgebauten Upstream mehr herstellen kann.

Beim Neuaufbau kann der Container ersetzt, ihm eine neue Adresse zugewiesen, ein Docker-Netzwerk getrennt oder umbenannt, der bereitgestellte Port geändert, eine unvollständige Konfiguration wiederhergestellt oder der Proxy gestartet werden, bevor die Anwendung bereit ist. Die richtige Diagnose beginnt mit dem Fehlerprotokoll des Proxys und verfolgt die genaue Upstream-Adresse vom Proxy bis zum Container, anstatt beide Dienste so lange neu zu starten, bis der Fehler vorübergehend verschwindet.

Bestätigen, dass der Fehler 502 durch einen Upstream-Verbindungsfehler verursacht wird

Rufen Sie die betroffene Domain einmal auf und notieren Sie den Zeitstempel, den Proxy-Status, die Upstream-Adresse und die vollständige Fehlermeldung. Unterscheiden Sie zwischen „Verbindung abgelehnt“, „Host nicht gefunden“, Zeitüberschreitung, Verbindungszurücksetzung, TLS-Handshake-Fehler und ungültiger Antwort.

Ein 502 bedeutet, dass der Proxy keine verwendbare Upstream-Antwort erhalten hat. Das Fehlerdetail zeigt jedoch, ob das Ziel nicht vorhanden, nicht erreichbar, nicht aktiv oder für das falsche Protokoll konfiguriert war. Ein aktueller Leitfaden zur NGINX-Fehlerbehebung weist darauf hin, dass ein neu aufgebauter Container dazu führen kann, dass der Proxy eine alte Backend-Adresse verwendet, bis die Namensauflösung oder Konfiguration aktualisiert wird.

Testen Sie die Anwendung direkt vom Proxy-Host oder aus dem Proxy-Container mit dem protokollierten Upstream-Namen, der Adresse, dem Port und dem Protokoll. Wenn diese direkte Anfrage auf dieselbe Weise fehlschlägt, sollten Sie die Untersuchung auf den Weg zwischen Proxy und Container beschränken, statt den öffentlichen DNS-Eintrag oder Zertifikate zu ändern.

Upstream-Ziel vor und nach dem Neuaufbau vergleichen

Überprüfen Sie den Namen des neu aufgebauten Containers, den Dienstnamen, die interne IP-Adresse, den bereitgestellten Port, den veröffentlichten Port, Netzwerk-Aliase und Netzwerkanbindungen. Vergleichen Sie diese Angaben mit der Proxy-Konfiguration und dem zuletzt funktionierenden Ziel.

Ein nginx-proxy-Problem beschreibt einen Neuaufbau, bei dem sich die IP-Adresse des Anwendungscontainers änderte, während der Proxy weiterhin Anfragen an den nicht erreichbaren Container-Upstream sendete. Die öffentliche Domain blieb korrekt, während sich nur die Identität des privaten Upstreams änderte.

Bevorzugen Sie einen stabilen Compose-Dienstnamen oder Netzwerkalias gegenüber einer Container-IP. Wenn eine IP-Adresse bewusst fest vergeben wird, überprüfen Sie, ob der neu aufgebaute Dienst sie tatsächlich erhalten hat und kein anderer Container diese Adresse verwendet.

Überprüfen, ob Proxy und Anwendung weiterhin dasselbe Docker-Netzwerk verwenden

Listen Sie die Netzwerke auf, die dem Proxy und der Anwendung zugewiesen sind, und bestätigen Sie, dass beide mindestens ein benutzerdefiniertes Netzwerk gemeinsam verwenden. Ein veröffentlichter Host-Port macht den Containernamen nicht automatisch aus einem anderen isolierten Docker-Netzwerk erreichbar.

In einem Fall zur Docker-Netzwerkverwaltung wurde festgestellt, dass das Verschieben eines abhängigen Dienstes in das geeignete Netzwerk wiederkehrende 502-Antworten sofort beseitigte. Dies zeigt, wie ein nicht erreichbarer Upstream-Pfad entstehen kann, selbst wenn alle Container weiter ausgeführt werden.

Verbinden Sie Dienste über Compose statt über einmalige Befehle, damit diese Beziehung Neuaufbauten übersteht. Testen Sie die DNS-Auflösung und den Upstream-Port nach der Neuerstellung des Stacks innerhalb des Proxy-Containers.

-15% OFF

ZimaBoard 2 – Mini-Heimserver für Ihre große Idee

Single board computer zimaboard2

Internen Listener-Port und Bind-Adresse überprüfen

Bestätigen Sie, dass die Anwendung auf dem vom Proxy verwendeten Port und an einer über das Containernetzwerk erreichbaren Adresse lauscht. Verwechseln Sie einen auf dem Host veröffentlichten Port nicht mit dem internen Listener-Port des Containers.

Ein Proxy kann erst eine Verbindung herstellen, wenn die Anwendung über die Loopback-Schnittstelle hinaus gebunden ist. Ein Dienst, der innerhalb seines eigenen Containers auf 127.0.0.1 lauscht, ist für den Proxy nicht erreichbar, selbst wenn ein lokaler Health-Check erfolgreich ist.

Überprüfen Sie das Anwendungsprotokoll und die Socket-Liste und senden Sie eine direkte Anfrage aus dem Proxy-Container. Wenn der Port Verbindungen ablehnt, beheben Sie zuerst den Listener oder die Konfiguration der Anwendung, bevor Sie Wiederholungsversuche oder längere Proxy-Zeitüberschreitungen hinzufügen.

Auf die Bereitschaft der Anwendung warten statt nur auf den Containerstart

Ein neu aufgebauter Container kann bereits ausgeführt werden, während Migrationen, Datenbankwiederherstellung, Cache-Aufwärmung oder Konfigurationserstellung die Annahme von Anfragen durch die Anwendung noch verhindern. Vergleichen Sie den Zeitpunkt des ersten 502-Fehlers mit den Health- und Startprotokollen.

Eine Grist-Fehlerbehebungsdiskussion zeigt, wie Docker-Architektur, Umgebungsvariablen und die Bereitschaft des Upstreams nach einem Neuaufbau zu anhaltenden 502-Fehlern auf der Containerseite führen können.

Fügen Sie einen aussagekräftigen Health-Check hinzu und sorgen Sie dafür, dass der Proxy oder abhängige Dienste auf den von den Clients benötigten Betriebszustand warten, nicht lediglich auf die Existenz eines Prozesses. Begrenzen Sie Wiederholungsversuche, damit eine dauerhaft ausgefallene Anwendung nicht wie ein langsamer Start wirkt.

Proxy-Auflösung aktualisieren und den stabilen Pfad wiederherstellen

Laden Sie den Proxy neu oder erstellen Sie ihn neu, nachdem Dienstname, Netzwerk, Port und Gesundheitszustand korrekt sind. Wenn der Proxy Namen nur beim Start auflöst, konfigurieren Sie eine unterstützte Laufzeitauflösung oder eine vorhersehbare Neustartreihenfolge.

Der ZimaSpace-Workflow zum Isolieren einer fehlerhaften Container-Abhängigkeit bietet die passende ergänzende Diagnose, wenn der Upstream wiederholt beendet wird, statt dauerhaft fehlerfrei zu laufen.

Die Reparatur ist erst abgeschlossen, wenn der Proxy den Dienstnamen nach einem weiteren Neuaufbau auflöst, den vorgesehenen internen Port erreicht, die Startphase abwartet und die Domain ohne manuelle IP-Änderungen bereitstellt. Entfernen Sie nach der Validierung vorübergehende direkte IP-Ziele und nicht dokumentierte Netzwerkanbindungen.