Cloudflare Troubleshooting: diagnóstico antes de mudar DNS, TLS ou origem

ANÁLISE EDITORIAL

Cloudflare Troubleshooting é uma Skill para investigar falhas de DNS, TLS, redirecionamento e comunicação com a origem usando evidência antes de mudar configurações. Ela organiza consultas à API da Cloudflare, testes externos e uma sequência de hipóteses para impedir que um erro 525, 526, 502 ou um loop de HTTPS seja tratado por tentativa e erro.

A proposta parece simples, mas existe uma diferença importante entre diagnosticar e operar. A Skill pode orientar chamadas somente leitura, porém também cita alterações de modo SSL, regras, DNS e limpeza de cache. A curadoria do Bastidores mantém esses passos separados, recomenda token mínimo em vez de Global API Key e exige confirmação explícita do domínio, da conta e da zona antes de qualquer efeito remoto.

O que esta Skill faz de verdade

A Skill começa identificando a zona e lendo a configuração que pode explicar o sintoma. Para um loop de redirecionamento, consulta o modo SSL, o uso obrigatório de HTTPS e regras de redirecionamento. Para DNS, lista registros, observa proxy e DNSSEC e compara a resposta da API com resolução pública. Para erros de certificado ou origem, orienta testar o handshake, o endereço real do servidor e as respostas vistas com e sem o proxy.

O valor não está em assumir que Flexible é sempre errado ou que limpar o cache resolve tudo. O valor está em formar uma cadeia verificável: sintoma, camada, estado atual, hipótese, teste que poderia refutar a hipótese, mudança mínima e nova verificação. A documentação oficial de modos de criptografia mostra que a relação entre visitante, edge e origem muda conforme o modo escolhido. A escolha correta depende do certificado e do HTTPS realmente disponível no servidor de origem.

Para quem serve

Serve a administradores de sites, equipes de suporte, desenvolvedores, profissionais de infraestrutura e pequenos negócios que usam Cloudflare e precisam separar falha de DNS, edge, certificado, redirecionamento, firewall ou servidor de origem. Também ajuda na preparação de um chamado técnico, porque incentiva registrar horário, hostname, código, Ray ID quando disponível, resposta externa e estado da configuração.

Ela não substitui acesso ao provedor de hospedagem, logs do servidor, conhecimento do aplicativo, suporte da Cloudflare nem autorização para alterar uma zona. A Cloudflare Platform Skill já publicada no catálogo é uma referência ampla e oficial para Workers, Pages, armazenamento e outros produtos. Cloudflare Troubleshooting tem finalidade distinta: conduzir investigação operacional de entrega web e só propor a menor mudança depois de localizar a camada provável.

Compatibilidade e pré-requisitos

O arquivo SKILL.md fixado foi escrito para Claude Code, mas pode ser lido por Codex e outros clientes que aceitam Agent Skills ou instruções Markdown. O pacote documental funciona sem Python. Os scripts oficiais opcionais usam Python 3 e a biblioteca requests, mas não estão incluídos no ZIP do Bastidores.

• Domínio e hostname exatos do problema.
• Horário, código de erro e comportamento esperado.
• Acesso somente leitura à zona, quando a API for necessária.
• Ferramentas como curl, nslookup, dig ou openssl, conforme o ambiente.
• Acesso separado à origem ou aos logs, se a hipótese chegar ao servidor.
• Janela de mudança e rollback definidos antes de usar permissões de edição.

Instalação recomendada

Comece pelo pacote documental do Bastidores em uma pasta de teste. Ele contém seis arquivos: SKILL.md, licença MIT, ORIGEM.md e três referências Markdown. Não contém scripts Python, bibliotecas, executáveis, dados da zona, chaves, tokens, e-mails, senhas ou configuração real.

Para consultar a unidade completa, abra o diretório oficial fixado. O marketplace do mantenedor declara a versão 1.0.2. Nessa versão, fix_ssl_mode.py opera em dry run por padrão e só grava quando recebe --apply. Ainda assim, não execute o script com um segredo em argumento de linha de comando. Argumentos podem aparecer em histórico, telemetria, captura de terminal ou lista de processos.

git clone https://github.com/daymade/claude-code-skills.git
git -C claude-code-skills checkout 71cdb265213642547af21b04234df57ea95c0d53
# Leia cloudflare-troubleshooting antes de instalar ou executar.

Configuração antes do primeiro uso

Crie um API Token restrito à zona necessária e apenas às permissões de leitura exigidas pelo diagnóstico. A documentação oficial permite escolher recursos, permissões, restrição por IP e validade. O Global API Key é uma credencial legada e ampla. O upstream ainda a usa em exemplos, portanto essa parte não deve ser copiada para produção.

Guarde o token em um gerenciador de segredos ou variável protegida do ambiente. Não cole em chat, prompt, arquivo versionado ou comando que ficará no histórico. Valide o token pelo método oficial e confirme o ID da zona usando a operação de listar zonas. Uma resposta HTTP 200 não basta: a API retorna também success e uma lista de erros que precisam ser examinados.

Defina dois modos de trabalho. O modo diagnóstico permite apenas GET e testes externos. O modo alteração exige aprovação nova, snapshot do valor atual, alvo explícito, rollback e verificação posterior. Um token de leitura não deve ser ampliado silenciosamente só porque a hipótese parece convincente.

Primeiro uso seguro

Faça um piloto sem credenciais e sem mudança. Use um hostname público e peça à Skill para montar a árvore de testes que distingue resolução DNS, conexão ao edge, handshake TLS, cadeia de redirecionamentos e resposta da origem. Depois compare cada passo com a documentação oficial.

Use Cloudflare Troubleshooting somente para diagnóstico.
Alvo: exemplo.com e www.exemplo.com.
Não peça nem use credenciais.
Não altere DNS, SSL, regras ou cache.
Liste hipótese, evidência necessária, comando somente leitura
e o resultado que confirmaria ou refutaria cada hipótese.
Pare antes de qualquer mudança remota.

Se a investigação realmente exigir API, forneça o token fora da conversa, com escopo de leitura e validade curta. A primeira resposta esperada é um inventário, não uma correção automática.

Como o fluxo deve funcionar

1. Registrar domínio, host, horário, região, código e sintoma reproduzível.
2. Verificar o status público da Cloudflare sem presumir que uma página verde exclui falha local.
3. Comparar DNS autoritativo, resolvedores públicos e registros vistos na zona.
4. Observar se o hostname está proxied ou DNS only e qual endereço deveria alcançar.
5. Testar TLS no edge e, quando autorizado, na origem com SNI correto.
6. Seguir a cadeia de redirecionamentos e separar regra da Cloudflare, aplicação e servidor web.
7. Relacionar erros 5xx ao trecho edge para origem, sem apagar evidência com uma limpeza de cache prematura.
8. Consultar apenas configurações relevantes e registrar o valor atual.
9. Escolher o menor teste capaz de refutar a hipótese principal.
10. Se uma mudança for aprovada, aplicar uma por vez, validar e manter rollback.

Para loops, use o guia oficial de redirecionamentos excessivos. Para resolução, consulte o material de troubleshooting de DNS. Esses documentos devem prevalecer sobre valores, prazos e nomes de recursos gravados nas referências do pacote quando houver divergência.

Resultado esperado

A saída útil é um relatório curto, reproduzível e separado em fatos, hipóteses e ações. Um bom diagnóstico diz qual hostname foi testado, quando, de onde, qual resolvedor respondeu, qual certificado foi apresentado, quantos redirecionamentos ocorreram, onde a resposta mudou e qual configuração da API foi lida.

O relatório deve terminar com uma conclusão proporcional à evidência. Se a origem não foi acessada, diga que a camada de origem permanece não verificada. Se o token não permite ler uma configuração, registre a lacuna. Se o erro não foi reproduzido, não declare correção. O resultado esperado é reduzir a área de busca, não produzir certeza artificial.

Permissões, privacidade e riscos

O maior risco é credencial excessiva. O upstream solicita e-mail e Global API Key e mostra segredos em argumentos. A orientação atual da Cloudflare favorece tokens com permissões e recursos delimitados. Nunca publique o token nem o inclua em captura, log, ticket ou arquivo de projeto.

O segundo risco é transformar diagnóstico em mudança. Alterar SSL pode derrubar o acesso à origem. Modificar DNS pode desviar tráfego ou e-mail. Purga total afeta o cache da zona. Desativar proxy ou regras pode expor a origem. --apply precisa de autorização própria, e a presença dessa opção no script não prova que o alvo esteja correto.

Há também risco de documentação envelhecida. A referência upstream cita Page Rules e endpoints de firewall que podem ter sido substituídos ou limitados por produto e plano. Confira sempre a referência atual da API e os detalhes do recurso antes de executar.

Erros comuns

Trocar SSL antes de testar a origem. Os erros 525 e 526 apontam problemas diferentes. Leia a página específica e teste certificado, SNI e handshake.

Confundir propagação com registro errado. Compare autoritativo, TTL e resolvedores antes de esperar ou alterar novamente.

Purgar cache como primeiro passo. A purga é uma operação, não um diagnóstico. Preserve a evidência e escolha escopo mínimo.

Testar a origem sem SNI ou Host correto. O servidor pode apresentar outro site ou certificado.

Concluir pela resposta do navegador. Cache local, HSTS, extensão, rede e resolvedor podem mudar o caminho observado.

Tratar um GET como seguro sem olhar o retorno. Resposta parcial, paginação, erro de permissão e zona errada podem produzir diagnóstico incompleto.

Versão, licença e origem verificadas

A API oficial do GitHub foi consultada em 04/09/2026. O repositório daymade/claude-code-skills registrava 1.377 estrelas, estava público, não arquivado e declarava licença MIT. Estrelas medem atenção relativa, não segurança, atualização de endpoints, compatibilidade ou correção do diagnóstico.

A curadoria fixou o commit 71cdb265213642547af21b04234df57ea95c0d53 e verificou a versão 1.0.2 no marketplace. Foram inspecionados SKILL.md, três referências, dois scripts Python e a licença MIT.

A licença permite redistribuição com preservação do aviso. O ZIP local contém seis documentos, tem 15.009 bytes e SHA-256 7720389c9a9cd40b863ebe6cfe238c300603abe4770264a590b33fa69c95fc5f. Os scripts foram omitidos deliberadamente.

Checklist antes de automatizar

• Fixe commit, versão, zona, host e horário do incidente.
• Use API Token mínimo e mantenha o segredo fora do chat e da linha de comando.
• Comece com GET, DNS público e testes externos.
• Separe fato, hipótese, lacuna e ação proposta.
• Confirme SNI, Host, certificado e endereço da origem.
• Revise endpoints atuais antes de copiar exemplos antigos.
• Autorize cada mudança, registre valor anterior e prepare rollback.
• Prefira purga seletiva quando uma purga for realmente necessária.
• Reproduza o teste depois da mudança e não declare sucesso sem evidência.

Fontes primárias

• Repositório oficial do mantenedor.
• Diretório da Skill no commit auditado.
• Referência de API do upstream.
• Problemas comuns documentados pelo upstream.
• Modos SSL descritos pelo upstream.
• Criação oficial de API Token.
• Como fazer chamadas oficiais à API.
• Modos de criptografia entre edge e origem.
• Guia oficial para loops de redirecionamento.
• Guia oficial de troubleshooting de DNS.
• Documentação oficial de purga de cache.
• Licença MIT.