Introdução
Um endpoint de disponibilidade do suporte funcionava até uma nova release começar a retornar 503. Neste laboratório, você publicará as duas versões de um Worker descartável, identificará a versão ativa e restaurará uma release conhecida como boa. Você comparará o comportamento HTTP real com os metadados de implantação do Cloudflare, em vez de confiar em uma mensagem de upload bem-sucedido.
Você já deve entender o desenvolvimento local com Wrangler, a autorização da conta e a implantação. Comece nesta VM nova com sua própria conta de aprendizagem; nenhuma VM ou Worker anterior será reutilizado. A configuração instala o Node.js 22.22.0 e o Wrangler 4.131.1 local do projeto, além de fornecer dois pequenos fixtures sintéticos de handler. Nenhum domínio, serviço de armazenamento ou segredo é necessário. Você executará todas as ações de implantação e limpeza.
Uma versão é um snapshot imutável do código e da configuração. Uma implantação escolhe qual versão receberá o tráfego. Reverter cria uma nova implantação de uma versão existente; isso não reescreve seu código-fonte local nem restaura dados em recursos associados. Consulte a visão geral oficial sobre versões.
Preparar uma release conhecida como boa
Nesta etapa, prepare um entrypoint conhecido como bom e confirme seu comportamento localmente. Os fixtures fornecidos permitem que você se concentre nas operações de release. O handler bom retorna available=true; o handler com falha mantém a verificação de integridade, mas retorna 503 para a rota de negócio.
cd /home/labex/project/release-recovery
cat versions/good.js
diff -u versions/good.js versions/faulty.js
O diff termina com código 1 porque os arquivos são diferentes; isso é esperado. Somente a disponibilidade e o status HTTP mudam. Copiar o fixture bom seleciona o arquivo de origem indicado pela configuração.
cp versions/good.js src/index.js
Gere um nome exclusivo usando a API padrão crypto do Node. O delimitador EOF sem aspas abaixo expande a variável do shell para JSON; o arquivo não contém comentários, portanto também pode ser lido por leitores JSON padrão.
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
O binding de metadados da versão fornece o ID e a tag da versão em tempo de execução. O desenvolvimento local usa metadados locais; somente os metadados implantados identificam uma versão na nuvem. Este binding está documentado aqui.
Inicie o servidor local em segundo plano com & e redirecione a saída para dev.log. Aguarde a mensagem Ready antes de fazer as requisições.
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
As duas rotas devem retornar 200; a disponibilidade deve ser true. Os valores locais de versão e tag podem ser placeholders de desenvolvimento. Faça a verificação antes de interromper o processo de desenvolvimento na próxima etapa.
Implantar e registrar a versão boa
Nesta etapa, implante o código-fonte conhecido como bom na sua conta de aprendizagem e registre a versão real. Interrompa o processo local, substituindo o número atual se necessário.
jobs
kill %1
npx wrangler login --device --browser=false --scopes account:read user:read workers_scripts:write workers_tail:read
Abra no navegador o link do dispositivo exibido, informe o código e autorize a conta de aprendizagem correta. Mantenha as credenciais no fluxo de login. Leia a saída padrão da conta e confirme o nome, mesmo que apenas uma conta seja listada.
npx wrangler whoami --json
Substitua YOUR_ACCOUNT_ID abaixo pelo ID real dessa conta. Este comando padrão do Node atualiza a configuração explícita do projeto; a conta não é selecionada por meio de uma variável de ambiente temporária.
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
A tag é um rótulo legível; o UUID da versão é a identidade precisa. Uma implantação faz upload de uma versão e direciona o tráfego para ela. A mensagem descreve a finalidade da versão.
npx wrangler deploy --tag good --message "Known-good availability"
Copie a URL workers.dev e o Current Version ID exibidos para os comandos a seguir. Eles são placeholders de exemplo, não recursos compartilhados fixos. Se esta conta não tiver um subdomínio workers.dev, siga a configuração inicial de Deploy Your First Cloudflare Worker e repita a implantação.
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 200, available=true, tag=good e o UUID da versão registrado na resposta. A implantação ativa deve atribuir 100% do tráfego a essa versão. Abra este Worker exato no Dashboard e inspecione Deployments para relacionar a versão exibida pela CLI à implantação ativa no recurso visível. Se a resposta ainda mostrar um estado anterior logo após uma implantação, aguarde cinco segundos e repita as leituras por no máximo um minuto; não altere o código para ocultar um atraso de propagação. Execute a verificação depois que as observações coincidirem.
Observar a release com falha
Nesta etapa, reproduza uma regressão controlada de release neste Worker descartável. Um endpoint de liveness saudável não garante que a rota de negócio funcione. Substitua o entrypoint pelo fixture com falha e publique uma versão com uma tag diferente.
cp versions/faulty.js src/index.js
npx wrangler deploy --tag faulty --message "Demonstrate availability regression"
Salve o novo Current Version ID desta implantação, não o ID da versão boa. Inspecione as duas rotas e a implantação atual.
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
A rota de integridade continua retornando 200. A disponibilidade agora retorna 503, available=false e tag=faulty. O UUID em tempo de execução deve corresponder à nova versão ativa, com 100% do tráfego. O 503 é a falha esperada nesta etapa, não um motivo para pular a verificação. Faça a mesma nova verificação limitada da resposta se a propagação ainda estiver em andamento. A verificação independente exige que a falha seja observável antes da recuperação.
Em Compute → Workers & Pages, abra o Worker exato e selecione Deployments. Compare o ID em Active deployment com a linha marcada como faulty em Version History. A captura de tela usa UUIDs de exemplo abreviados; use seus UUIDs completos salvos nos comandos. A versão boa continua no histórico mesmo enquanto a versão com falha está ativa. Use wrangler deployments status acima para confirmar a alocação configurada de 100% do tráfego; os números de atividade iguais a zero nesta captura silenciosa não comprovam que a rota de negócio esteja saudável.
Reverter e reconciliar o código-fonte local
Nesta etapa, restaure exatamente a versão conhecida como boa. Leia os IDs salvos e inspecione a versão boa selecionada antes de alterar o tráfego. A substituição de comando do shell lê o UUID do arquivo; ela não envia uma nova versão.
cat good-version.txt faulty-version.txt
npx wrangler versions view "$(cat good-version.txt)"
Confirme a tag boa, o Worker e a conta pretendidos e o UUID. A reversão direciona 100% do tráfego deste Worker descartável para essa versão. A mensagem registra o motivo da recuperação. Execute o comando somente depois de verificar o destino.
npx wrangler rollback "$(cat good-version.txt)" --message "Restore known-good availability"
Quando o Wrangler solicitar a mensagem opcional, pressione Enter para aceitar Restore known-good availability. Leia o UUID bom exibido e o destino com 100% do tráfego; na confirmação correspondente, pressione apenas a tecla y. Aguarde a mensagem de reversão concluída com sucesso antes de continuar.
npx wrangler deployments status
curl -i "$APP_URL/api/availability"
A nova implantação deve usar o UUID da versão boa original; ela não precisa ter o ID da implantação original. A disponibilidade deve retornar novamente 200 e true. Atualize a aba Deployments do Dashboard e compare o UUID ativo. Se necessário, faça a mesma nova verificação limitada de até um minuto.
Neste exemplo, Active deployment voltou para 7afe5d31, o mesmo ID abreviado da versão good original. O marcador de atividade em Version History foi movido para essa linha, e a versão com falha continua listada. Compare essas relações usando seus próprios IDs; não copie os valores de exemplo. Esta página identifica a versão selecionada, enquanto a resposta de disponibilidade confirma o comportamento corrigido.
A reversão não altera o código-fonte local. Restaure o fixture bom localmente para que uma implantação comum posterior não reintroduza acidentalmente a falha conhecida. O modo de simulação empacota esse código-fonte local sem fazer upload.
cp versions/good.js src/index.js
npx wrangler deploy --dry-run
Execute a verificação: ela compara o UUID e a tag reais em tempo de execução com a implantação atual de 100% e confirma que a implantação anterior com falha permanece no histórico. Um arquivo de sucesso criado localmente não é suficiente.
A reversão não desfaz gravações em um banco de dados, fila ou API externa, e alterações em recursos associados podem tornar versões antigas incompatíveis. Este laboratório não possui esses recursos. Em um incidente real, avalie esses limites antes da recuperação. A documentação sobre reversão explica as restrições e a janela de retenção de versões.
Remover o Worker usado no teste de release
Nesta etapa, remova o Worker descartável enquanto a autorização ainda estiver disponível. Confirme o nome exato e a conta antes da exclusão.
cat wrangler.jsonc
npx wrangler delete
Quando o nome correspondente for solicitado, pressione apenas a tecla y. O Wrangler fixado pode informar um erro de autenticação na limpeza de KV legado após excluir o Worker. Não conceda escopos mais amplos nem presuma que um erro comprove a exclusão. Atualize o Dashboard e execute a verificação: um inventário autenticado bem-sucedido deve mostrar que este Worker está ausente. Preserve a conta de aprendizagem, o subdomínio e os recursos não relacionados.
Desconectar a VM
Nesta etapa, desconecte esta VM depois que a exclusão for confirmada. Fazer logout sozinho não removeria um Worker implantado.
npx wrangler logout
npx wrangler whoami --json
Espere loggedIn=false; o comando estruturado pode terminar com código diferente de zero porque você agora está sem autenticação. Execute a verificação final. Seu login no navegador e sua conta de aprendizagem continuam disponíveis para laboratórios independentes futuros.
Resumo
Você comparou versões de um Worker com implantações ativas, observou uma regressão na rota de negócio apesar de uma liveness saudável e restaurou a versão boa selecionada. Os metadados em tempo de execução relacionaram as respostas reais à implantação de 100%. Você também restaurou o código-fonte local, verificou a limpeza na nuvem e desconectou a VM.
