Introducción
Un endpoint de disponibilidad del servicio funcionaba correctamente hasta que una nueva versión empezó a devolver 503. En este laboratorio, publicará ambas versiones de un Worker desechable, identificará la versión activa y restaurará una versión conocida como correcta. Comparará el comportamiento HTTP real con los metadatos de implementación de Cloudflare, en lugar de confiar únicamente en un mensaje de carga correcta.
Ya debe comprender el desarrollo local con Wrangler, la autorización de la cuenta y la implementación. Comience en esta VM nueva con su propia cuenta de aprendizaje; no se reutiliza ninguna VM ni ningún Worker anteriores. La configuración instala Node.js 22.22.0 y Wrangler 4.131.1 local del proyecto, además de proporcionar dos pequeños archivos de prueba para los controladores. No se necesita ningún dominio, servicio de almacenamiento ni secreto. Usted realizará todas las acciones de implementación y limpieza.
Una versión es una instantánea inmutable del código y la configuración. Una implementación determina qué versión recibe el tráfico. Revertir crea una nueva implementación de una versión existente; no reescribe el código fuente local ni restaura datos de los recursos vinculados. Consulte la descripción general oficial de las versiones.
Preparar una versión conocida como correcta
En este paso, preparará un punto de entrada conocido como correcto y confirmará localmente su comportamiento. Los archivos de prueba proporcionados le permiten concentrarse en las operaciones de versiones. El controlador correcto devuelve available=true; el controlador defectuoso conserva el estado de salud, pero devuelve 503 para la ruta de negocio.
cd /home/labex/project/release-recovery
cat versions/good.js
diff -u versions/good.js versions/faulty.js
La comparación termina con el código 1 porque los archivos son diferentes; esto es esperado. Solo cambian la disponibilidad y su estado HTTP. Al copiar el archivo de prueba correcto, seleccionará el archivo de código fuente indicado por la configuración.
cp versions/good.js src/index.js
Genere un nombre único mediante la API estándar crypto de Node. El delimitador EOF sin comillas que aparece a continuación sustituye la variable del shell en el JSON; el archivo no contiene comentarios, por lo que los lectores JSON estándar también pueden inspeccionarlo.
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
El binding de metadatos de versión proporciona el ID y la etiqueta de la versión durante el tiempo de ejecución. El desarrollo local utiliza metadatos locales; solo los metadatos de una implementación identifican una versión en la nube. Este binding está documentado aquí.
Inicie el servidor local en segundo plano con & y redirija su salida a dev.log. Espere a que aparezca Ready antes de realizar solicitudes.
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
Ambas rutas deben devolver 200 y availability debe ser true. Los valores locales de versión y etiqueta pueden ser marcadores de posición de desarrollo. Realice la verificación antes de detener el proceso de desarrollo en el paso siguiente.
Implementar y registrar la versión correcta
En este paso, implemente el código fuente conocido como correcto en su cuenta de aprendizaje y registre su versión real. Detenga el proceso local; sustituya su número actual si es necesario.
jobs
kill %1
npx wrangler login --device --browser=false --scopes account:read user:read workers_scripts:write workers_tail:read
Abra en el navegador el enlace del dispositivo que se muestra, introduzca su código y autorice la cuenta de aprendizaje correspondiente. Mantenga las credenciales dentro del flujo de inicio de sesión. Lea la salida estándar de la cuenta y confirme el nombre, aunque solo aparezca una cuenta.
npx wrangler whoami --json
Sustituya YOUR_ACCOUNT_ID a continuación por el ID real de esa cuenta. Este comando estándar de Node actualiza la configuración explícita del proyecto; la cuenta no se selecciona mediante una variable de entorno temporal.
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
La etiqueta es un nombre legible; el UUID de la versión es la identidad precisa. Una implementación carga una versión y le dirige el tráfico. El mensaje describe el propósito de la versión.
npx wrangler deploy --tag good --message "Known-good availability"
Copie la URL de workers.dev y el Current Version ID que se muestran en los comandos siguientes. Son marcadores de posición de ejemplo, no recursos compartidos fijos. Si esta cuenta no tiene un subdominio de workers.dev, siga la configuración inicial de Deploy Your First Cloudflare Worker y repita la implementación.
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
Espere obtener 200, available=true, tag=good y el UUID de versión registrado en la respuesta. La implementación activa debe asignarle el 100 % del tráfico. Abra este Worker exacto en Dashboard e inspeccione Deployments para relacionar la versión de la CLI y la implementación activa con el recurso visible. Si la respuesta sigue mostrando un estado anterior inmediatamente después de una implementación, espere cinco segundos y repita las lecturas durante un máximo de un minuto; no cambie el código para ocultar un retraso de propagación. Ejecute la verificación después de que las observaciones coincidan.
Observar la versión defectuosa
En este paso, reproducirá una regresión controlada de una versión en este Worker desechable. Un endpoint de disponibilidad activo y saludable no garantiza que la ruta de negocio funcione. Sustituya el punto de entrada por el archivo de prueba defectuoso y publique una versión con una etiqueta diferente.
cp versions/faulty.js src/index.js
npx wrangler deploy --tag faulty --message "Demonstrate availability regression"
Guarde el nuevo Current Version ID de esta implementación, no el ID de la versión correcta. Inspeccione ambas rutas y la implementación actual.
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
Health sigue devolviendo 200. Availability ahora devuelve 503, available=false y tag=faulty. Su UUID de tiempo de ejecución debe coincidir con la nueva versión activa, que debe recibir el 100 % del tráfico. El 503 es el defecto previsto para este paso, no un motivo para omitir la verificación. Si la propagación aún está en curso, aplique la misma comprobación limitada de la respuesta. La comprobación independiente requiere que el fallo sea observable antes de la recuperación.
En Compute → Workers & Pages, abra el Worker exacto y seleccione Deployments. Compare el ID de Active deployment con la fila etiquetada como faulty en Version History. La captura de pantalla utiliza UUID abreviados de ejemplo; use sus UUID completos guardados en los comandos. La versión correcta permanece en el historial aunque la versión defectuosa esté activa. Use wrangler deployments status arriba para confirmar la asignación configurada del 100 % del tráfico; las cifras de actividad con valor cero de esta captura silenciosa no demuestran que la ruta de negocio esté saludable.
Revertir y conciliar el código fuente local
En este paso, restaure la versión exacta conocida como correcta. Lea los ID guardados e inspeccione la versión correcta seleccionada antes de cambiar el tráfico. La sustitución de comandos del shell lee el UUID del archivo; no carga una versión nueva.
cat good-version.txt faulty-version.txt
npx wrangler versions view "$(cat good-version.txt)"
Confirme la etiqueta correcta, el Worker y la cuenta previstos, y el UUID. La reversión dirige el 100 % del tráfico de este Worker desechable a esa versión. El mensaje registra el motivo de la recuperación. Ejecute el comando solo después de comprobar el destino.
npx wrangler rollback "$(cat good-version.txt)" --message "Restore known-good availability"
Cuando Wrangler solicite el mensaje opcional, pulse Enter para aceptar Restore known-good availability. Lea el UUID correcto y el destino con el 100 % del tráfico que se muestran; cuando aparezca la confirmación correspondiente, pulse una sola vez la tecla y. Espere el mensaje de reversión correcta antes de continuar.
npx wrangler deployments status
curl -i "$APP_URL/api/availability"
La nueva implementación debe utilizar el UUID de la versión correcta original; no es necesario que tenga el ID de implementación original. Availability vuelve a devolver 200 y true. Actualice la pestaña Deployments de Dashboard y compare el UUID activo. Si es necesario, utilice la misma comprobación limitada de la respuesta durante un máximo de un minuto.
En este ejemplo, Active deployment ha vuelto a 7afe5d31, el mismo ID abreviado de la versión good original. El marcador de actividad de Version History se ha desplazado a esa fila y la versión defectuosa sigue apareciendo. Compare estas relaciones con sus propios ID; no copie los valores del ejemplo. Esta página identifica la versión seleccionada, mientras que la respuesta de disponibilidad confirma que el comportamiento se ha reparado.
La reversión no modifica el código fuente local. Restaure localmente el archivo de prueba correcto para que una implementación normal posterior no vuelva a introducir accidentalmente el fallo conocido. La ejecución en modo de prueba empaqueta ese código fuente local sin cargarlo.
cp versions/good.js src/index.js
npx wrangler deploy --dry-run
Ejecute la verificación: compara el UUID y la etiqueta reales del tiempo de ejecución con la implementación actual al 100 % y comprueba que la implementación defectuosa anterior permanezca en el historial. Un archivo de éxito escrito localmente no es suficiente.
La reversión no deshace escrituras en una base de datos, una cola o una API externa, y los cambios en recursos vinculados pueden hacer que las versiones antiguas sean incompatibles. Este laboratorio no tiene recursos de ese tipo. En un incidente real, evalúe esos límites antes de recuperarse. La documentación sobre reversiones explica las restricciones y el período de conservación de versiones.
Eliminar el Worker de prueba de versiones
En este paso, elimine el Worker desechable mientras la autorización siga disponible. Confirme su nombre exacto y la cuenta antes de eliminarlo.
cat wrangler.jsonc
npx wrangler delete
Cuando aparezca la solicitud con el nombre coincidente, pulse una sola vez la tecla y. El Wrangler fijado puede informar de un error de autenticación durante la limpieza de KV heredado después de eliminar el Worker. No conceda ámbitos más amplios ni suponga que un error demuestra la eliminación. Actualice Dashboard y ejecute la verificación: un inventario autenticado correcto debe mostrar que este Worker está ausente. Conserve la cuenta de aprendizaje, el subdominio y los recursos no relacionados.
Desconectar la VM
En este paso, desconecte esta VM después de confirmar que la eliminación se realizó correctamente. Cerrar la sesión por sí solo no eliminaría un Worker implementado.
npx wrangler logout
npx wrangler whoami --json
Espere loggedIn=false; el comando estructurado puede terminar con un código distinto de cero porque ahora no está autenticado. Ejecute la verificación final. El inicio de sesión del navegador y la cuenta de aprendizaje seguirán disponibles para futuros laboratorios independientes.
Resumen
Comparó las versiones del Worker con las implementaciones activas, observó una regresión de la ruta de negocio a pesar de que la disponibilidad seguía saludable y restauró la versión correcta seleccionada. Los metadatos del tiempo de ejecución relacionaron las respuestas reales con la implementación al 100 %. También restauró el código fuente local, verificó la limpieza en la nube y desconectó la VM.
