Introduction
Un point de terminaison de disponibilité du support fonctionnait jusqu’à ce qu’une nouvelle version commence à renvoyer une erreur 503. Dans cet atelier, vous publiez les deux versions d’un Worker temporaire, identifiez la version active, puis restaurez une version fonctionnelle connue. Vous comparez le comportement HTTP réel aux métadonnées de déploiement Cloudflare au lieu de vous fier à un message indiquant que l’envoi a réussi.
Vous devez déjà comprendre le développement local avec Wrangler, l’autorisation du compte et le déploiement. Commencez dans cette nouvelle VM avec votre propre compte d’apprentissage ; aucune ancienne VM ni aucun ancien Worker ne sera réutilisé. La configuration installe Node.js 22.22.0 ainsi que Wrangler 4.131.1 dans le projet, et fournit deux petits fichiers de test pour les gestionnaires. Aucun domaine, service de stockage ou secret n’est nécessaire. Vous effectuez vous-même chaque opération de déploiement et de nettoyage.
Une version est un instantané immuable du code et de la configuration. Un déploiement détermine la version qui reçoit le trafic. Une restauration crée un nouveau déploiement à partir d’une version existante ; elle ne réécrit pas votre code source local et ne restaure pas les données des ressources liées. Consultez la présentation officielle des versions.
Préparer une version fonctionnelle connue
Dans cette étape, préparez le point d’entrée fonctionnel et vérifiez son comportement en local. Les fichiers de test fournis vous permettent de vous concentrer sur les opérations de gestion des versions. Le gestionnaire fonctionnel renvoie available=true ; le gestionnaire défectueux conserve l’état de santé, mais renvoie 503 pour la route métier.
cd /home/labex/project/release-recovery
cat versions/good.js
diff -u versions/good.js versions/faulty.js
La commande diff se termine avec le code 1, car les fichiers sont différents ; c’est le comportement attendu. Seules la disponibilité et son code d’état HTTP changent. La copie du fichier de test fonctionnel sélectionne le fichier source indiqué par la configuration.
cp versions/good.js src/index.js
Générez un nom unique avec l’API crypto standard de Node. Le délimiteur EOF non placé entre guillemets ci-dessous remplace la variable du shell dans le fichier JSON ; le fichier ne contient aucun commentaire, ce qui permet également aux lecteurs JSON standard de l’inspecter.
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
La liaison de métadonnées de version fournit l’identifiant et le libellé de la version au moment de l’exécution. Le développement local utilise des métadonnées locales ; seules les métadonnées d’un déploiement identifient une version cloud. Cette liaison est documentée ici.
Démarrez le serveur local en arrière-plan avec & et redirigez sa sortie vers dev.log. Attendez l’état Ready avant d’envoyer des requêtes.
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
Les deux routes doivent renvoyer 200 ; la disponibilité doit être true. Les valeurs locales de version et de libellé peuvent être des valeurs fictives de développement. Effectuez la vérification avant d’arrêter le processus de développement à l’étape suivante.
Déployer et enregistrer la version fonctionnelle
Dans cette étape, déployez le code source fonctionnel sur votre compte d’apprentissage et enregistrez sa version réelle. Arrêtez le processus local en remplaçant son numéro par le numéro actuel si nécessaire.
jobs
kill %1
npx wrangler login --device --browser=false --scopes account:read user:read workers_scripts:write workers_tail:read
Ouvrez dans votre navigateur le lien vers l’appareil qui s’affiche, saisissez le code, puis autorisez le compte d’apprentissage souhaité. Conservez vos identifiants dans le flux de connexion. Lisez la sortie standard du compte et confirmez son nom, même si un seul compte est répertorié.
npx wrangler whoami --json
Remplacez YOUR_ACCOUNT_ID ci-dessous par l’identifiant réel de ce compte. Cette commande Node standard met à jour la configuration explicite du projet ; le compte n’est pas sélectionné au moyen d’une variable d’environnement temporaire.
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
Le libellé est un nom lisible ; l’UUID de version constitue l’identité précise. Un déploiement envoie une version et lui achemine le trafic. Le message décrit l’objectif de la version.
npx wrangler deploy --tag good --message "Known-good availability"
Copiez l’URL workers.dev et le Current Version ID affichés dans les commandes suivantes. Il s’agit d’exemples, et non de ressources partagées fixes. Si ce compte ne possède aucun sous-domaine workers.dev, suivez la configuration initiale de la procédure Deploy Your First Cloudflare Worker, puis répétez le déploiement.
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
Vous devez obtenir 200, available=true, tag=good et l’UUID de version enregistré dans la réponse. Le déploiement actif doit lui attribuer 100 % du trafic. Ouvrez ce Worker précis dans le Dashboard et consultez Deployments afin de faire le lien entre la version affichée par la CLI, le déploiement actif et la ressource visible. Si la réponse affiche encore un état précédent juste après un déploiement, attendez cinq secondes, puis répétez les lectures pendant une minute au maximum ; ne modifiez pas le code pour masquer un délai de propagation. Lancez la vérification après concordance des observations.
Observer la version défectueuse
Dans cette étape, reproduisez une régression contrôlée dans ce Worker temporaire. Un point de terminaison de vivacité sain ne garantit pas que la route métier fonctionne. Remplacez le point d’entrée par le fichier de test défectueux et publiez une version portant un libellé différent.
cp versions/faulty.js src/index.js
npx wrangler deploy --tag faulty --message "Demonstrate availability regression"
Enregistrez le nouveau Current Version ID de ce déploiement, et non l’identifiant de la version fonctionnelle. Inspectez les deux routes ainsi que le déploiement actuel.
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
L’état de santé reste 200. La disponibilité renvoie maintenant 503, available=false et tag=faulty. Son UUID d’exécution doit correspondre à la nouvelle version active, qui reçoit 100 % du trafic. Le code 503 est le défaut attendu à cette étape ; ce n’est pas une raison de sauter la vérification. Appliquez la même nouvelle lecture limitée dans le temps si la propagation est toujours en cours. La vérification indépendante exige que le défaut soit observable avant la récupération.
Dans Compute → Workers & Pages, ouvrez votre Worker exact et sélectionnez Deployments. Comparez l’identifiant sous Active deployment à la ligne portant le libellé faulty dans Version History. La capture d’écran utilise des UUID d’exemple abrégés ; utilisez vos UUID complets enregistrés dans les commandes. La version fonctionnelle reste présente dans l’historique, même lorsque la version défectueuse est active. Utilisez wrangler deployments status ci-dessus pour confirmer l’attribution configurée de 100 % du trafic ; les valeurs d’activité égales à zéro dans cette capture silencieuse ne prouvent pas que la route métier fonctionne.
Restaurer la version et synchroniser le code source local
Dans cette étape, restaurez exactement la version fonctionnelle connue. Lisez les identifiants enregistrés et inspectez la version fonctionnelle sélectionnée avant de modifier le trafic. La substitution de commande du shell lit l’UUID dans le fichier ; elle n’envoie pas une nouvelle version.
cat good-version.txt faulty-version.txt
npx wrangler versions view "$(cat good-version.txt)"
Confirmez le libellé fonctionnel, le Worker et le compte souhaités, ainsi que l’UUID. La restauration achemine 100 % du trafic de ce Worker temporaire vers cette version. Le message enregistre la raison de la récupération. N’exécutez la commande qu’après avoir vérifié la cible.
npx wrangler rollback "$(cat good-version.txt)" --message "Restore known-good availability"
Lorsque Wrangler vous demande le message facultatif, appuyez sur Entrée pour accepter Restore known-good availability. Lisez l’UUID fonctionnel affiché ainsi que la cible recevant 100 % du trafic ; lorsque la confirmation correspondante s’affiche, appuyez sur la seule touche y. Attendez le message indiquant que la restauration a réussi avant de continuer.
npx wrangler deployments status
curl -i "$APP_URL/api/availability"
Le nouveau déploiement doit utiliser l’UUID de la version fonctionnelle d’origine ; il n’a pas besoin de reprendre l’identifiant du déploiement d’origine. La disponibilité renvoie de nouveau 200 et true. Actualisez l’onglet Deployments du Dashboard et comparez l’UUID actif. Si nécessaire, effectuez la même nouvelle lecture limitée à une minute.
Dans cet exemple, Active deployment est revenu à 7afe5d31, le même identifiant abrégé que celui de la version good d’origine. Le marqueur actif de Version History s’est déplacé sur cette ligne, et la version défectueuse reste répertoriée. Vérifiez ces relations avec vos propres identifiants ; ne recopiez pas les valeurs de l’exemple. Cette page identifie la version sélectionnée, tandis que la réponse de disponibilité confirme que le comportement est réparé.
La restauration ne modifie pas le code source local. Restaurez le fichier de test fonctionnel en local afin qu’un déploiement ordinaire ultérieur ne puisse pas réintroduire accidentellement le défaut connu. Le mode dry-run regroupe ce code source local sans l’envoyer.
cp versions/good.js src/index.js
npx wrangler deploy --dry-run
Lancez la vérification : elle compare l’UUID et le libellé réels d’exécution au déploiement actuel à 100 %, et vérifie que le précédent déploiement défectueux reste dans l’historique. Un fichier de réussite créé localement ne suffit pas.
Une restauration n’annule pas les écritures effectuées dans une base de données, une file d’attente ou une API externe, et les modifications de ressources liées peuvent rendre d’anciennes versions incompatibles. Cet atelier n’utilise aucune de ces ressources. Dans un incident réel, évaluez ces limites avant la récupération. La documentation sur les restaurations explique les restrictions et la durée de conservation des versions.
Supprimer le Worker utilisé pour le test de version
Dans cette étape, supprimez le Worker temporaire tant que l’autorisation est encore disponible. Confirmez son nom exact et son compte avant la suppression.
cat wrangler.jsonc
npx wrangler delete
Lorsque l’invite affiche le nom correspondant, appuyez sur la seule touche y. La version de Wrangler verrouillée peut signaler une erreur d’authentification lors du nettoyage d’un ancien KV après la suppression du Worker. N’accordez pas d’autorisations supplémentaires et ne supposez pas qu’une erreur prouve que la suppression a réussi. Actualisez le Dashboard et lancez la vérification : un inventaire authentifié réussi doit montrer que ce Worker est absent. Conservez le compte d’apprentissage, le sous-domaine et les ressources sans lien avec cet atelier.
Déconnecter la VM
Dans cette étape, déconnectez cette VM après la confirmation de la suppression. Se déconnecter du compte ne suffit pas à supprimer un Worker déployé.
npx wrangler logout
npx wrangler whoami --json
Vous devez obtenir loggedIn=false ; la commande structurée peut se terminer avec un code différent de zéro, car vous êtes maintenant non authentifié. Lancez la vérification finale. Votre connexion dans le navigateur et votre compte d’apprentissage restent disponibles pour de futurs ateliers indépendants.
Résumé
Vous avez comparé les versions d’un Worker aux déploiements actifs, observé une régression de la route métier malgré une vivacité saine, puis restauré la version fonctionnelle sélectionnée. Les métadonnées d’exécution ont permis de relier les réponses réelles au déploiement à 100 %. Vous avez également restauré le code source local, vérifié le nettoyage cloud et déconnecté la VM.
