Introdução
Um serviço de suporte precisa de um local seguro para visualizar alterações de configuração. Você executará o mesmo código nos ambientes de preview e live, manterá separados os rótulos públicos e os segredos de cada ambiente e protegerá um endpoint de manutenção sintético, mantendo os health checks públicos.
Use sua própria conta de aprendizado da Cloudflare e os conhecimentos sobre autorização do dispositivo, implantação e logs adquiridos nos laboratórios anteriores. Este laboratório começa de forma independente em /home/labex/project/worker-config, com Node.js 22.22.0, Wrangler 4.131.1 instalado localmente no projeto e um pequeno fixture de rota de health check. Nenhuma VM ou recurso de nuvem anterior será reutilizado. Ambas as implantações são descartáveis, e a operação de manutenção é um dry run. Use apenas tokens sintéticos gerados para este laboratório. Workers Free e workers.dev são suficientes para este pequeno exercício; as solicitações contam para o uso da sua conta. Não é necessário comprar um domínio, usar um banco de dados ou fazer upgrade para um plano pago.
Você removerá ambas as implantações na nuvem e os arquivos de token locais e, depois, fará logout antes de encerrar a VM. Mantenha o mesmo terminal aberto durante todo o laboratório.
Separar a configuração de preview e live
Nesta etapa, você usará o mesmo handler de health fornecido com dois ambientes nomeados. Aqui, live ainda é uma implantação de aprendizado descartável; nenhum dos ambientes processa dados reais de produção. O nome preview é um ambiente do Wrangler, não uma URL de preview de versão.
Entre no projeto preparado e inspecione o fixture da rota de health. O Node e o Wrangler instalado localmente no projeto já estão disponíveis.
cd /home/labex/project/worker-config
node --version
npx wrangler --version
cat src/index.js
Você deve ver Node v22.22.0 e Wrangler 4.131.1. O handler lê de env os valores de exibição que não são segredos. Na sua própria máquina, instale o Node e adicione wrangler@4.131.1 como dependência de desenvolvimento do projeto; reproduza as dependências existentes com npm ci.
Gere um nome base descartável. A substituição de comando insere uma saída hexadecimal aleatória na variável do shell. Mantenha este terminal aberto para os comandos posteriores.
WORKER_NAME="labex-config-$(openssl rand -hex 6)"
Escreva a configuração usando um heredoc; o marcador de fechamento sem aspas permite a substituição de $WORKER_NAME. main seleciona o código compartilhado, e compatibility_date seleciona o comportamento do runtime. Os objetos env substituem a configuração para --env preview e --env live. Defina cada valor de vars em cada ambiente, porque esses bindings não são herdados. Não há recurso de banco de dados nem de fila: QUEUE_LABEL é apenas um rótulo público de exibição.
cat > wrangler.jsonc <<CONFIG
{
"name": "$WORKER_NAME",
"main": "src/index.js",
"compatibility_date": "2026-09-14",
"workers_dev": true,
"preview_urls": false,
"env": {
"preview": {"vars": {"ENVIRONMENT": "preview", "QUEUE_LABEL": "sandbox"}},
"live": {"vars": {"ENVIRONMENT": "live", "QUEUE_LABEL": "primary"}}
}
}
CONFIG
Inicie os dois runtimes locais. > redireciona a saída, 2>&1 inclui os erros e & executa o processo em segundo plano. As portas HTTP e do inspector são diferentes para evitar conflitos.
npx wrangler dev --env preview --port 8080 > preview.log 2>&1 &
npx wrangler dev --env live --port 8081 --inspector-port 9230 > live.log 2>&1 &
cat preview.log
cat live.log
Aguarde os dois logs informarem que os servidores estão prontos; se necessário, repita o cat correspondente. Depois, compare as respostas:
curl -i http://127.0.0.1:8080/health
curl -i http://127.0.0.1:8081/health
Ambos retornam 200. O preview retorna {"status":"ok","environment":"preview","queue":"sandbox"}; o live retorna {"status":"ok","environment":"live","queue":"primary"}. curl -i inclui o status e os cabeçalhos. Use o botão de verificação com os dois servidores em execução.
A documentação de ambientes explica a herança de ambientes e os nomes implantados padrão <name>-<environment>.
Proteger uma rota de manutenção com segredos locais
Nesta etapa, você protegerá uma operação de manutenção sintética com um token diferente em cada ambiente. Um segredo é uma configuração privada disponibilizada por env; ele não deve aparecer em vars públicos, no JSON retornado nem nos logs da aplicação. Este pequeno exemplo de bearer token ensina o limite do lado do servidor, não um sistema completo de autenticação de usuários.
Pare os dois processos locais antes de adicionar os arquivos de segredo. Inspecione os números reais dos jobs; os exemplos pressupõem que o preview seja o 1 e o live seja o 2.
jobs
kill %1 %2
Gere dois tokens aleatórios destinados apenas aos testes, sem exibi-los. umask 077 faz com que os novos arquivos possam ser lidos apenas pelo usuário da sua VM. printf grava uma atribuição dotenv em cada arquivo específico do ambiente. Nunca use aqui um token de API de uma conta real.
umask 077
PREVIEW_TOKEN=$(openssl rand -hex 24)
LIVE_TOKEN=$(openssl rand -hex 24)
printf 'MAINTENANCE_TOKEN=%s\n' "$PREVIEW_TOKEN" > .dev.vars.preview
printf 'MAINTENANCE_TOKEN=%s\n' "$LIVE_TOKEN" > .dev.vars.live
cat .gitignore
Confirme que .dev.vars* e .env* estão excluídos. Não exiba nem faça commit dos arquivos de segredo. O Wrangler carrega .dev.vars.preview para --env preview e o arquivo live separado para --env live; um arquivo .dev.vars específico do ambiente substitui o arquivo genérico. Esses arquivos não enviam segredos automaticamente para a Cloudflare. Consulte segredos locais e implantados.
Substitua o handler. O heredoc entre aspas preserva o JavaScript literalmente. Um segredo configurado ausente retorna 503; uma credencial ausente ou incorreta na solicitação retorna 401. Compare o cabeçalho Authorization no servidor antes de retornar sucesso. Apenas um nome de evento fixo, o ambiente público e o status numérico são registrados. A operação aceita é um dry run sem efeito persistente.
cat > src/index.js <<'JS'
export default {
async fetch(request, env) {
const path = new URL(request.url).pathname;
if (path === '/health' && request.method === 'GET') {
return Response.json({status: 'ok', environment: env.ENVIRONMENT, queue: env.QUEUE_LABEL});
}
if (path !== '/maintenance') return Response.json({error: 'not_found'}, {status: 404});
if (request.method !== 'POST') {
return Response.json({error: 'method_not_allowed'}, {status: 405, headers: {Allow: 'POST'}});
}
// Fail closed if this environment has no configured secret.
if (!env.MAINTENANCE_TOKEN) {
return Response.json({error: 'maintenance_unconfigured'}, {status: 503});
}
const authorized = request.headers.get('Authorization') === `Bearer ${env.MAINTENANCE_TOKEN}`;
const status = authorized ? 200 : 401;
console.log(JSON.stringify({event: 'maintenance', environment: env.ENVIRONMENT, status}));
if (!authorized) return Response.json({error: 'unauthorized'}, {status});
return Response.json({operation: 'dry-run', environment: env.ENVIRONMENT});
}
};
JS
npx wrangler dev --env preview --port 8080 > preview.log 2>&1 &
npx wrangler dev --env live --port 8081 --inspector-port 9230 > live.log 2>&1 &
cat preview.log
cat live.log
Depois que os dois servidores informarem que estão prontos, teste esse limite. -X POST seleciona o método, e -H fornece o cabeçalho bearer. Não use a saída detalhada do curl com credenciais reais.
curl -i -X POST http://127.0.0.1:8080/maintenance
curl -i -X POST http://127.0.0.1:8080/maintenance -H "Authorization: Bearer incorrect-token"
curl -i -X POST http://127.0.0.1:8080/maintenance -H "Authorization: Bearer $LIVE_TOKEN"
curl -i -X POST http://127.0.0.1:8080/maintenance -H "Authorization: Bearer $PREVIEW_TOKEN"
curl -i -X POST http://127.0.0.1:8081/maintenance -H "Authorization: Bearer $LIVE_TOKEN"
curl -i http://127.0.0.1:8080/health
curl -i http://127.0.0.1:8081/health
As três primeiras solicitações retornam 401 unauthorized, incluindo o token válido do outro ambiente. As duas seguintes retornam 200 com operation: dry-run e o ambiente correspondente. O health continua público. Use a verificação para conferir o isolamento dos tokens nos dois sentidos, os métodos, a configuração pública e a ausência dos valores dos tokens nos logs locais.
Implantar cada ambiente e enviar seu segredo
Nesta etapa, você autorizará esta VM nova, implantará cada ambiente nomeado e enviará explicitamente seu segredo. Primeiro, pare os processos locais; use os números reais exibidos por jobs.
jobs
kill %1 %2
npx wrangler login --device --browser=false --scopes account:read user:read workers_scripts:write workers_tail:read
Use o link exibido e o código atual no navegador em que você está conectado. Revise as permissões do Wrangler e o Background Access exigido, selecione apenas sua conta de aprendizado e autorize conforme ensinado no laboratório de conexão. Aguarde a conclusão no terminal.
npx wrangler whoami --json
Confirme loggedIn: true, o nome e o ID da conta. Substitua YOUR_ACCOUNT_ID abaixo pelo ID real; mantenha o nome original do recurso.
cat > wrangler.jsonc <<CONFIG
{
"name": "$WORKER_NAME",
"main": "src/index.js",
"compatibility_date": "2026-09-14",
"account_id": "YOUR_ACCOUNT_ID",
"workers_dev": true,
"preview_urls": false,
"env": {
"preview": {"vars": {"ENVIRONMENT": "preview", "QUEUE_LABEL": "sandbox"}},
"live": {"vars": {"ENVIRONMENT": "live", "QUEUE_LABEL": "primary"}}
}
}
CONFIG
Sempre inclua --env neste projeto. Caso contrário, o Wrangler usará o ambiente de nível superior sem nome, que não faz parte do plano de implantação deste laboratório.
npx wrangler deploy --env preview
npx wrangler deploy --env live
Copie o endereço exato de cada workers.dev exibido na saída da implantação. Reutilize o subdomínio existente da sua conta de aprendizado. Usuários de primeira viagem devem seguir o prompt de subdomínio disponível do Wrangler, sem alterar um subdomínio existente.
PREVIEW_URL="https://YOUR_BASE-preview.YOUR_SUBDOMAIN.workers.dev"
LIVE_URL="https://YOUR_BASE-live.YOUR_SUBDOMAIN.workers.dev"
curl -i -X POST "$PREVIEW_URL/maintenance"
curl -i -X POST "$LIVE_URL/maintenance"
Ambos retornam 503 maintenance_unconfigured: os arquivos de segredo locais não foram enviados por uma implantação comum. O health é independente da autorização de manutenção.
Use o comando bulk padrão para enviar o arquivo dotenv ao ambiente correspondente. Mesmo um único segredo pode usar essa operação baseada em arquivo; a saída identifica o nome do segredo, não seu valor. Uma atualização de segredo cria e implanta uma versão imediatamente.
npx wrangler secret bulk .dev.vars.preview --env preview
npx wrangler secret bulk .dev.vars.live --env live
npx wrangler secret list --env preview
npx wrangler secret list --env live
Cada lista deve conter MAINTENANCE_TOKEN com o tipo secret_text. Compare os valores públicos e o comportamento da autorização:
curl -i "$PREVIEW_URL/health"
curl -i "$LIVE_URL/health"
curl -i -X POST "$PREVIEW_URL/maintenance"
curl -i -X POST "$PREVIEW_URL/maintenance" -H "Authorization: Bearer $LIVE_TOKEN"
curl -i -X POST "$PREVIEW_URL/maintenance" -H "Authorization: Bearer $PREVIEW_TOKEN"
curl -i -X POST "$LIVE_URL/maintenance" -H "Authorization: Bearer $LIVE_TOKEN"
O health mantém preview/sandbox e live/primary. Credenciais ausentes e de outro ambiente retornam 401; tokens correspondentes retornam 200. Aguarde a propagação inicial do hostname antes de tentar novamente em caso de erros de conexão. Na mesma conta do Dashboard, abra Compute → Workers & Pages. Localize os dois Workers que terminam em -preview e -live e compare seus nomes completos e URLs com a saída da implantação. Cada ambiente nomeado do Wrangler tem seu próprio Worker implantado neste exemplo; não crie outra aplicação no Dashboard.
Abra seu Worker -preview e selecione Settings. Em Runtime variables and secrets (a seção Variables and secrets), compare as colunas Type, Name e Value. ENVIRONMENT deve ser preview, e QUEUE_LABEL deve ser sandbox. MAINTENANCE_TOKEN deve ter o tipo Secret, com Value encrypted em vez de um valor legível.
Volte para Workers & Pages, abra seu Worker -live e inspecione a mesma seção. Seus valores públicos devem ser live e primary, enquanto o segredo enviado independentemente usa o mesmo nome de binding. Verifique o nome do Worker no breadcrumb superior antes de comparar a tabela.
O sufixo do nome aleatório e o subdomínio exibidos nas imagens são valores de exemplo. A exibição criptografada confirma a presença e o tipo do binding do segredo, mas não indica que os dois ambientes tenham valores de segredo diferentes; as verificações HTTP correspondentes e entre ambientes acima estabelecem esse comportamento. Mantenha este checkpoint somente para leitura: não edite variáveis nem revele, substitua ou copie credenciais no Dashboard. Use a verificação: ela confere a propriedade real, os tipos dos bindings implantados e o comportamento público dos dois ambientes.
Inspecionar logs da aplicação sem expor segredos
Nesta etapa, você inspecionará uma solicitação rejeitada e uma aceita no ambiente de preview implantado. Os logs da aplicação devem explicar o resultado sem copiar credenciais ou cabeçalhos da solicitação.
Inicie um fluxo de logs com o comando tail ensinado anteriormente. A saída formatada exibe as mensagens da aplicação; salve-a para inspecionar o teste limitado depois de interromper o fluxo.
npx wrangler tail --env preview --format pretty > preview-tail.log 2>&1 &
cat preview-tail.log
Aguarde até que o fluxo informe que está conectado; repita cat enquanto a conexão é estabelecida. Depois, envie novas solicitações sintéticas:
curl -i -X POST "$PREVIEW_URL/maintenance" -H "Authorization: Bearer incorrect-token"
curl -i -X POST "$PREVIEW_URL/maintenance" -H "Authorization: Bearer $PREVIEW_TOKEN"
Use grep para exibir apenas as linhas que contêm o nome fixo do evento da aplicação:
grep 'maintenance' preview-tail.log
Aguarde eventos com status 401 e 200. O ambiente público deles é preview. Nenhum valor de token deve aparecer em qualquer uma das mensagens. A entrega dos eventos pode atrasar em relação à resposta HTTP; repita o grep por até um minuto. Se faltar um evento, inspecione o console.log correspondente no código-fonte.
jobs
kill %1
Interrompa o job real do tail assim que os dois eventos estiverem presentes; o exemplo pressupõe que ele seja o job 1. Use a verificação para conferir o log capturado e verificar novamente, de forma independente, os contratos de autorização remota. Este teste usa apenas solicitações sintéticas e não estabelece segurança para futuras alterações arbitrárias nos logs.
Remover as implantações dos dois ambientes
Nesta etapa, você excluirá os dois Workers de ambiente descartáveis enquanto ainda estiver autorizado. Confirme o nome base e a conta de aprendizado na configuração:
cat wrangler.jsonc
Exclua apenas as implantações de preview e live deste laboratório. Em cada prompt, confira o nome exato <base>-preview ou <base>-live e pressione a única tecla y.
npx wrangler delete --env preview
npx wrangler delete --env live
A exclusão desses Workers também remove os bindings de segredo associados. O Wrangler 4.131.1 pode então informar o erro de autenticação do Workers Sites KV legado documentado anteriormente. Não amplie as permissões nem interprete esse erro como prova de exclusão. Atualize Workers & Pages e use a verificação: um inventário autorizado bem-sucedido deve mostrar os dois nomes como ausentes. Um erro de autenticação ou de rede é inconclusivo. Preserve os Workers não relacionados, sua conta de aprendizado e o subdomínio existente.
Remover os segredos locais e desconectar
Nesta etapa, você removerá as cópias locais dos segredos deste laboratório depois de verificar a limpeza na nuvem e, em seguida, desconectará a VM. rm remove apenas os dois arquivos nomeados abaixo, e unset remove as duas variáveis temporárias do shell.
rm .dev.vars.preview .dev.vars.live
unset PREVIEW_TOKEN LIVE_TOKEN
npx wrangler logout
npx wrangler whoami --json
Você deve ver explicitamente "loggedIn": false; o comando não autenticado retornar um código de saída diferente de zero é esperado quando esse resultado estruturado está presente. Use a verificação e, depois, encerre a VM. O login do navegador é separado e pode continuar disponível para o próximo laboratório. Nem o logout nem o encerramento da VM substituem a exclusão prévia dos recursos na nuvem.
Resumo
Você separou a configuração pública por ambiente do Wrangler, carregou segredos locais específicos de cada ambiente, enviou bindings de segredo criptografados e verificou credenciais correspondentes, ausentes e de outro ambiente. A rota pública de health manteve a identidade do ambiente, enquanto o servidor protegeu uma rota de manutenção em dry run. Você inspecionou logs limitados da aplicação sem imprimir tokens e, depois, verificou a exclusão antes de remover as credenciais locais e fazer logout.
A mesma disciplina de configuração ajudará você a diagnosticar posteriormente desvios de configuração no preview ao longo deste curso.
