Einführung
Ein Endpoint zur Prüfung der Verfügbarkeit funktionierte, bis eine neue Version den Status 503 zurückgab. In diesem Lab veröffentlichen Sie beide Versionen eines temporären Workers, ermitteln die aktive Version und stellen ein bekannt funktionierendes Release wieder her. Dabei vergleichen Sie das tatsächliche HTTP-Verhalten mit den Cloudflare-Deployment-Metadaten, statt einer erfolgreichen Upload-Meldung zu vertrauen.
Sie sollten bereits mit der lokalen Wrangler-Entwicklung, der Kontoautorisierung und Deployments vertraut sein. Beginnen Sie in dieser frischen VM mit Ihrem eigenen Lernkonto. Es wird keine frühere VM und kein früherer Worker wiederverwendet. Das Setup installiert Node.js 22.22.0 und den projektspezifischen Wrangler 4.131.1 und stellt zwei kleine synthetische Handler-Fixtures bereit. Sie benötigen weder eine Domain noch einen Speicherdienst oder ein Secret. Alle Deployments und Bereinigungsschritte führen Sie selbst aus.
Eine Version ist ein unveränderlicher Snapshot von Code und Konfiguration. Ein Deployment legt fest, welche Version Datenverkehr erhält. Ein Rollback erstellt ein neues Deployment einer vorhandenen Version. Es schreibt weder Ihren lokalen Quellcode um noch stellt es Daten in gebundenen Ressourcen wieder her. Weitere Informationen finden Sie in der offiziellen Übersicht zu Versionen.
Ein bekannt funktionierendes Release vorbereiten
Bereiten Sie in diesem Schritt den bekannten funktionierenden Einstiegspunkt vor und bestätigen Sie sein lokales Verhalten. Die bereitgestellten Fixtures lenken Ihre Aufmerksamkeit auf die Release-Verwaltung. Der funktionierende Handler gibt available=true zurück. Der fehlerhafte Handler bleibt gesund, gibt aber für die Geschäftsroute den Status 503 zurück.
cd /home/labex/project/release-recovery
cat versions/good.js
diff -u versions/good.js versions/faulty.js
diff beendet sich mit dem Status 1, weil sich die Dateien unterscheiden. Das ist zu erwarten. Geändert werden nur die Verfügbarkeit und der HTTP-Status. Mit dem Kopieren des funktionierenden Fixtures wählen Sie die Quelldatei aus, die in der Konfiguration angegeben ist.
cp versions/good.js src/index.js
Erzeugen Sie mit der standardmäßigen Crypto-API von Node einen eindeutigen Namen. Der nicht in Anführungszeichen gesetzte EOF-Begrenzer im folgenden Befehl ersetzt die Shell-Variable durch ihren Wert in der JSON-Datei. Die Datei enthält keine Kommentare und kann daher auch von Standard-JSON-Lesern verarbeitet werden.
WORKER_NAME="labex-release-$(node -p "require('node:crypto').randomBytes(6).toString('hex')")"
cat > wrangler.jsonc <<EOF
{
"name": "$WORKER_NAME",
"main": "src/index.js",
"compatibility_date": "2026-07-30",
"workers_dev": true,
"preview_urls": false,
"version_metadata": {"binding": "RELEASE"}
}
EOF
Das Binding für die Versionsmetadaten stellt die Laufzeit-Versions-ID und das Tag bereit. Bei der lokalen Entwicklung werden lokale Metadaten verwendet. Nur bereitgestellte Metadaten identifizieren eine Cloud-Version. Dieses Binding wird hier dokumentiert.
Starten Sie den lokalen Server mit & im Hintergrund und leiten Sie seine Ausgabe nach dev.log um. Warten Sie auf Ready, bevor Sie Anfragen senden.
npx wrangler dev --ip 0.0.0.0 --port 8080 > dev.log 2>&1 &
cat dev.log
curl -i http://127.0.0.1:8080/health
curl -i http://127.0.0.1:8080/api/availability
Beide Routen sollten den Status 200 zurückgeben. Die Verfügbarkeit sollte true sein. Lokale Versions- und Tag-Werte können Platzhalter für die Entwicklung sein. Führen Sie die Verifizierung durch, bevor Sie den Entwicklungsprozess im nächsten Schritt beenden.
Die funktionierende Version deployen und dokumentieren
Deployen Sie in diesem Schritt den bekannten funktionierenden Quellcode in Ihr Lernkonto und dokumentieren Sie die tatsächliche Version. Beenden Sie den lokalen Prozess. Ersetzen Sie dessen aktuelle Nummer, falls erforderlich.
jobs
kill %1
npx wrangler login --device --browser=false --scopes account:read user:read workers_scripts:write workers_tail:read
Öffnen Sie den ausgegebenen Geräte-Link in Ihrem Browser, geben Sie den Code ein und autorisieren Sie das gewünschte Lernkonto. Geben Sie Ihre Zugangsdaten nur im Anmeldevorgang ein. Lesen Sie die standardmäßige Kontoausgabe und bestätigen Sie den Namen, auch wenn nur ein Konto aufgeführt ist.
npx wrangler whoami --json
Ersetzen Sie YOUR_ACCOUNT_ID im folgenden Befehl durch die tatsächliche ID dieses Kontos. Dieser standardmäßige Node-Befehl aktualisiert die explizite Projektkonfiguration. Das Konto wird nicht über eine temporäre Umgebungsvariable ausgewählt.
node -e 'const fs=require("node:fs");const p="wrangler.jsonc";const c=JSON.parse(fs.readFileSync(p));c.account_id="YOUR_ACCOUNT_ID";fs.writeFileSync(p,JSON.stringify(c,null,2)+"\n");'
cat wrangler.jsonc
Das Tag ist eine lesbare Bezeichnung. Die UUID der Version ist ihre eindeutige Identität. Ein Deployment lädt eine Version hoch und leitet den Datenverkehr an diese Version weiter. Die Meldung beschreibt den Zweck der Version.
npx wrangler deploy --tag good --message "Known-good availability"
Kopieren Sie die ausgegebene workers.dev-URL und die Current Version ID in die folgenden Befehle. Dies sind Beispielplatzhalter und keine fest vorgegebenen gemeinsamen Ressourcen. Wenn dieses Konto noch keine workers.dev-Subdomain besitzt, führen Sie die Ersteinrichtung aus Deploy Your First Cloudflare Worker, und wiederholen Sie anschließend das Deployment.
APP_URL="https://YOUR_WORKER.YOUR_SUBDOMAIN.workers.dev"
printf '%s\n' "YOUR_GOOD_VERSION_ID" > good-version.txt
curl -i "$APP_URL/api/availability"
npx wrangler deployments status
npx wrangler versions list
Erwarten Sie den Status 200, available=true, das Tag good und die aufgezeichnete Versions-UUID in der Antwort. Das aktive Deployment muss der Version 100 % des Datenverkehrs zuweisen. Öffnen Sie genau diesen Worker im Dashboard und prüfen Sie Deployments, um die CLI-Version und das aktive Deployment mit der sichtbaren Ressource abzugleichen. Wenn die Antwort direkt nach einem Deployment noch einen früheren Zustand zeigt, warten Sie fünf Sekunden und wiederholen Sie die Abfragen höchstens eine Minute lang. Ändern Sie nicht den Code, um eine Verzögerung bei der Verteilung zu verbergen. Führen Sie die Verifizierung durch, sobald die Beobachtungen übereinstimmen.
Die fehlerhafte Version beobachten
Reproduzieren Sie in diesem Schritt eine kontrollierte Regression in diesem temporären Worker. Ein gesunder Liveness-Endpoint garantiert nicht, dass die Geschäftsroute funktioniert. Ersetzen Sie den Einstiegspunkt durch das fehlerhafte Fixture und veröffentlichen Sie eine eigenständige Version mit einem anderen Tag.
cp versions/faulty.js src/index.js
npx wrangler deploy --tag faulty --message "Demonstrate availability regression"
Speichern Sie die neue Current Version ID dieses Deployments, nicht die ID der funktionierenden Version. Prüfen Sie beide Routen und das aktuelle Deployment.
printf '%s\n' "YOUR_FAULTY_VERSION_ID" > faulty-version.txt
curl -i "$APP_URL/health"
curl -i "$APP_URL/api/availability"
npx wrangler deployments status
npx wrangler versions list
Der Health-Endpoint bleibt bei 200. Die Verfügbarkeit gibt jetzt 503, available=false und das Tag faulty zurück. Die Laufzeit-UUID muss mit der neuen aktiven Version übereinstimmen, der 100 % des Datenverkehrs zugewiesen sind. Der Status 503 ist der beabsichtigte Fehler dieses Schritts und kein Grund, die Verifizierung zu überspringen. Falls die Verteilung noch läuft, führen Sie dieselbe begrenzte erneute Prüfung der Antworten durch. Die unabhängige Prüfung setzt voraus, dass der Fehler vor der Wiederherstellung beobachtbar ist.
Öffnen Sie unter Compute → Workers & Pages genau Ihren Worker und wählen Sie Deployments. Vergleichen Sie die ID unter Active deployment mit der Zeile mit dem Tag faulty unter Version History. Der Screenshot verwendet gekürzte Beispiel-UUIDs. Verwenden Sie in den Befehlen Ihre vollständig gespeicherten UUIDs. Die funktionierende Version bleibt im Verlauf erhalten, während die fehlerhafte Version aktiv ist. Bestätigen Sie mit wrangler deployments status aus dem vorherigen Abschnitt die konfigurierte Zuweisung von 100 % des Datenverkehrs. Die Aktivitätswerte 0 im ruhigen Screenshot belegen nicht, dass die Geschäftsroute gesund ist.
Rollback durchführen und den lokalen Quellcode abgleichen
Stellen Sie in diesem Schritt exakt die bekannte funktionierende Version wieder her. Lesen Sie die gespeicherten IDs aus und prüfen Sie die ausgewählte funktionierende Version, bevor Sie den Datenverkehr ändern. Die Befehlssubstitution der Shell liest die UUID aus der Datei. Es wird keine neue Version hochgeladen.
cat good-version.txt faulty-version.txt
npx wrangler versions view "$(cat good-version.txt)"
Bestätigen Sie das Tag good, den vorgesehenen Worker und das vorgesehene Konto sowie die UUID. Das Rollback leitet 100 % des Datenverkehrs dieses temporären Workers an diese Version weiter. Die Meldung dokumentiert den Grund für die Wiederherstellung. Führen Sie den Befehl erst aus, nachdem Sie das Ziel geprüft haben.
npx wrangler rollback "$(cat good-version.txt)" --message "Restore known-good availability"
Wenn Wrangler nach der optionalen Meldung fragt, drücken Sie die Eingabetaste, um Restore known-good availability zu übernehmen. Lesen Sie die angezeigte gute UUID und das Ziel mit 100 % Datenverkehr. Drücken Sie bei der passenden Bestätigung die einzelne Taste y. Warten Sie auf die Erfolgsmeldung des Rollbacks, bevor Sie fortfahren.
npx wrangler deployments status
curl -i "$APP_URL/api/availability"
Das neue Deployment sollte die ursprüngliche UUID der funktionierenden Version verwenden. Es muss nicht die ursprüngliche Deployment-ID besitzen. Die Verfügbarkeit gibt wieder 200 und true zurück. Aktualisieren Sie im Dashboard den Tab Deployments und vergleichen Sie die aktive UUID. Falls erforderlich, führen Sie dieselbe begrenzte erneute Prüfung der Antworten innerhalb einer Minute durch.
In diesem Beispiel ist Active deployment wieder auf 7afe5d31 zurückgekehrt, dieselbe gekürzte ID wie bei der ursprünglichen Version mit dem Tag good. Die Markierung für die aktive Version ist in Version History zu dieser Zeile gewechselt. Die fehlerhafte Version wird weiterhin aufgeführt. Vergleichen Sie diese Beziehungen mit Ihren eigenen IDs und übernehmen Sie nicht die Beispielwerte. Diese Seite identifiziert die ausgewählte Version. Die Verfügbarkeitsantwort bestätigt das reparierte Verhalten.
Ein Rollback ändert den lokalen Quellcode nicht. Stellen Sie das funktionierende Fixture lokal wieder her, damit ein späteres gewöhnliches Deployment den bekannten Fehler nicht versehentlich erneut einführt. --dry-run erstellt ein Bundle aus diesem lokalen Quellcode, ohne es hochzuladen.
cp versions/good.js src/index.js
npx wrangler deploy --dry-run
Führen Sie die Verifizierung aus. Sie vergleicht die tatsächliche Laufzeit-UUID und das Tag mit dem aktuellen Deployment mit 100 % Datenverkehr und prüft, dass das vorherige fehlerhafte Deployment im Verlauf erhalten bleibt. Eine lokal geschriebene Erfolgsdatei reicht nicht aus.
Ein Rollback macht Schreibvorgänge in einer Datenbank, einer Queue oder einer externen API nicht rückgängig. Änderungen an gebundenen Ressourcen können ältere Versionen inkompatibel machen. Dieses Lab verwendet keine solchen Ressourcen. Prüfen Sie in einem echten Vorfall diese Grenzen, bevor Sie eine Wiederherstellung durchführen. Die Rollback-Dokumentation erläutert Einschränkungen und den Zeitraum, in dem Versionen erhalten bleiben.
Den Test-Worker für das Release entfernen
Entfernen Sie in diesem Schritt den temporären Worker, solange die Autorisierung noch verfügbar ist. Bestätigen Sie vor dem Löschen den exakten Namen und das Konto.
cat wrangler.jsonc
npx wrangler delete
Drücken Sie bei der Eingabeaufforderung mit dem passenden Namen die einzelne Taste y. Der festgelegte Wrangler kann nach dem Löschen des Workers einen Authentifizierungsfehler bei der Bereinigung von Legacy-KV melden. Gewähren Sie keine weitergehenden Berechtigungsbereiche und gehen Sie nicht davon aus, dass ein Fehler das Löschen beweist. Aktualisieren Sie das Dashboard und führen Sie die Verifizierung aus. Eine erfolgreiche authentifizierte Inventarprüfung muss zeigen, dass dieser Worker nicht vorhanden ist. Erhalten Sie das Lernkonto, die Subdomain und nicht zugehörige Ressourcen.
Die VM trennen
Trennen Sie in diesem Schritt die VM, nachdem das Löschen erfolgreich abgeschlossen wurde. Nur das Abmelden würde einen deployten Worker nicht entfernen.
npx wrangler logout
npx wrangler whoami --json
Erwarten Sie loggedIn=false. Der strukturierte Befehl kann mit einem Fehlercode enden, weil Sie jetzt nicht mehr authentifiziert sind. Führen Sie die abschließende Verifizierung aus. Ihre Browser-Anmeldung und Ihr Lernkonto bleiben für künftige unabhängige Labs verfügbar.
Zusammenfassung
Sie haben Worker-Versionen mit aktiven Deployments verglichen, eine Regression der Geschäftsroute trotz gesundem Liveness-Status beobachtet und die ausgewählte funktionierende Version wiederhergestellt. Die Laufzeitmetadaten stellten die Verbindung zwischen den tatsächlichen Antworten und dem Deployment mit 100 % Datenverkehr her. Außerdem haben Sie den lokalen Quellcode wiederhergestellt, die Bereinigung in der Cloud überprüft und die VM getrennt.
