Todos os produtos
Search
Central de documentação

CDN:Cache troubleshooting

Última atualização: Aug 31, 2026

Este tópico resume métodos de solução de problemas para cenários de cache do CDN organizados por sintoma: cache sem efeito e falhas de cache (cache miss), baixa taxa de acerto de cache e alta taxa de requisição à origem, exceções em cabeçalhos de resposta e CORS, exceções com vídeos e arquivos grandes, além de conteúdo não atualizado e erros de acesso.

Etapas preliminares gerais

Nota

Este tópico aplica-se ao Alibaba Cloud CDN, considerando que o nome de domínio acelerado já foi integrado e a resolução CNAME está ativa. Caso utilize o Dynamic Route for CDN (DCDN), alguns pontos de entrada de configuração e nomes de recursos podem diferir. Consulte a exibição real no console.

Os itens de verificação a seguir aplicam-se à maioria dos problemas de cache. Recomendamos concluí-los um a um antes de iniciar a solução de problemas para evitar conclusões incorretas causadas por interferências ambientais:

Item de verificação

Descrição

Verifique se a resolução CNAME está correta

Execute dig accelerated-domain e confirme se a resolução final aponta para o CNAME atribuído pelo CDN, sem registros A/AAAA residuais apontando para o servidor de origem.

Confirme se a configuração entrou em vigor globalmente

O status da regra no console deve ser Success. A entrega da configuração para os POPs globais geralmente leva de 3 a 5 minutos.

Elimine o cache local do navegador

Teste no modo de navegação privada ou use curl para evitar interferência do cache do navegador.

Limpe o cache existente do CDN

Uma nova configuração aplica-se apenas a novas requisições após entrar em vigor. Para recursos armazenados em cache sob a política anterior, envie uma atualização de URL ou de diretório usando Refresh and prefetch.

Nota

Este tópico utiliza a definição do tempo de expiração de cache para 0 segundos como medida de contingência em vários pontos. Um tempo de expiração de 0 significa que cada requisição dispara uma busca na origem, o que aumenta significativamente a carga no servidor de origem e reduz o efeito de aceleração. Recomendamos usar essa opção apenas para conteúdo dinâmico que exige respostas em tempo real, como endpoints de API. Não configure isso globalmente para recursos estáticos.

Determine se houve acerto de cache

Antes de solucionar problemas de cache, verifique os cabeçalhos de resposta para confirmar o status do cache do recurso:

  • Use uma requisição GET para verificar os cabeçalhos de resposta: Execute curl -v -o /dev/null "http(s)://accelerated-domain/resource-path". Uma requisição curl -I (requisição HEAD) pode não acionar a lógica real de cache para o corpo do recurso no POP em alguns cenários, levando a uma conclusão falsa de falha de cache. Recomendamos usar uma requisição GET para verificação.

  • Verifique o X-Cache para determinar o status de acerto: HIT indica acerto de cache. MISS ou a ausência desse campo indica falha de cache, significando que a requisição disparou uma busca na origem.

  • Analise Age e X-Swift-CacheTime para determinar a duração restante do cache: Age indica o número de segundos que o recurso está armazenado em cache no POP e deve ser interpretado em conjunto com o X-Cache. Se X-Cache for MISS e Age for 0, a requisição disparou uma busca na origem. Se X-Cache for HIT, mas Age for 0, o recurso foi armazenado em cache há menos de 1 segundo. X-Swift-CacheTime indica a duração total permitida para o cache. A duração restante equivale a X-Swift-CacheTime menos Age.

  • Confirme se a requisição passou pelo CDN: Se o cabeçalho de resposta Server mostrar um identificador de origem, como AliyunOSS ou nginx, e os cabeçalhos de resposta do CDN (como X-Cache e X-Swift-CacheTime) estiverem ausentes, a requisição ignorou o POP do CDN e foi diretamente para o servidor de origem. Execute dig accelerated-domain ou nslookup accelerated-domain para confirmar o resultado final da resolução. Mantenha apenas o registro CNAME atribuído pelo CDN e exclua os registros A/AAAA que apontam para o IP do servidor de origem e os registros CNAME que apontam para o nome de domínio do servidor de origem.

Cache sem efeito e falhas de cache

A requisição ainda dispara busca na origem ou falha no cache mesmo após configurar uma regra de cache?

Etapas de solução de problemas:

  1. Confirme se a configuração entrou em vigor: Após adicionar ou modificar uma regra de cache, o status da regra mostra Configuring, indicando que a configuração está sendo entregue aos POPs globais. O status geralmente muda para Success em alguns minutos. Não tente verificar a regra antes que a configuração entre em vigor.

  2. Verifique se a nova regra aplica-se ao recurso de destino: Uma nova regra aplica-se apenas a novas requisições. Recursos já armazenados em cache nos POPs continuam a ser servidos sob a política anterior até expirarem. Para aplicar a regra imediatamente, limpe primeiro o cache anterior usando Refresh and prefetch.

  3. Verifique a prioridade de correspondência da regra: Quando uma requisição corresponde a várias regras, apenas uma entra em vigor. Por padrão, a regra com maior peso tem precedência. Quando os pesos são iguais, a regra criada posteriormente geralmente tem precedência (consulte a descrição real no console). Certifique-se de que a regra correspondente ao caminho de destino tenha o maior peso. Por exemplo, o peso de um diretório específico (/static/) deve ser maior que o do diretório raiz (/).

  4. Verifique se os cabeçalhos de resposta da origem proíbem o cache: Se o servidor de origem retornar Cache-Control: no-cache, no-store, max-age=0 ou Pragma: no-cache, o CDN segue a diretiva da origem por padrão. Para entender o impacto de diferentes diretivas no comportamento de busca na origem, consulte a tabela abaixo. Ative Ignore no-cache headers from the origin server na regra de cache para impor o armazenamento em cache com base nas regras do console ou ajuste a configuração do servidor de origem para remover as diretivas de no-cache para recursos estáticos.

  5. Verifique como os parâmetros de URL são processados: Se a URL contiver parâmetros e Ignore parameters estiver desativado, URLs com parâmetros diferentes são tratadas como recursos distintos, o que reduz a taxa de acerto de cache. Ative Ignore parameters ou Retain specified parameters.

  6. Verifique se o diretório raiz está configurado incorretamente como não armazenável em cache: Se a regra para o diretório raiz / tiver o maior peso e tempo de expiração de 0 segundos, todas as requisições dispararão buscas na origem.

Na etapa 4 acima, diferentes diretivas de no-cache do servidor de origem têm impactos significativamente diferentes no comportamento de busca na origem. Avalie a carga no servidor de origem com base na diretiva real:

Cabeçalho de resposta da origem

Comportamento do CDN

Impacto no servidor de origem

Cache-Control: no-store

O armazenamento em cache é totalmente proibido. Cada requisição busca o recurso completo no servidor de origem.

O servidor de origem suporta toda a pressão de tráfego.

Cache-Control: no-cache ou max-age=0

Os POPs podem armazenar cópias em cache, mas devem revalidar com o servidor de origem antes de cada uso. Quando a validação é aprovada, o servidor de origem retorna 304 (sem corpo de resposta), e a sobrecarga é muito menor do que uma busca completa na origem.

O número de buscas na origem não diminui, mas cada busca é apenas uma pequena requisição condicional; portanto, a pressão na largura de banda é gerenciável.

Pragma: no-cache

Diretiva de compatibilidade HTTP/1.0. O efeito é semelhante ao no-cache.

Igual ao anterior.

O tempo de expiração do cache está definido como 0, mas o conteúdo acessado ainda não é o mais recente?

O objetivo de definir o tempo de expiração como 0 é fazer com que cada requisição busque o conteúdo mais recente no servidor de origem. Se o conteúdo antigo ainda for retornado, siga estas etapas de solução de problemas:

  1. Elimine o cache local do navegador: Limpe o cache do navegador ou use o modo de navegação privada para testar novamente e confirme se é o POP, e não o navegador, que retorna o conteúdo antigo.

  2. Limpe o cache existente antes da alteração de configuração: Recursos armazenados em cache antes da modificação da configuração não são limpos automaticamente. Envie uma tarefa de atualização de URL usando Refresh and prefetch.

  3. Verifique se o servidor de origem possui cache próprio: O servidor de origem (por exemplo, um cache Nginx ou de camada de aplicação) pode retornar conteúdo antigo, fazendo com que o CDN busque dados obsoletos durante a requisição à origem.

  4. Confirme se a configuração entrou em vigor globalmente: O status da regra deve ser Success. A entrega da configuração para todos os POPs leva alguns minutos.

  5. Confirme se a requisição atingiu o POP esperado: Usuários de diferentes ISPs ou regiões podem atingir POPs diferentes. Teste em várias regiões separadamente ou use os logs em tempo real do CDN e o IP do POP na resposta para identificar melhor o problema.

Configurei uma chave de cache personalizada para diferenciar requisições móveis e de PC, mas ela não entrou em vigor?

  1. Verifique a integridade da configuração: Uma chave de cache personalizada geralmente exige a definição de condições de regra com base nas características da requisição (como User-Agent) e a adição de variáveis de chave de cache diferentes para cada regra. Confirme se as características de requisição de clientes móveis e de PC estão corretamente identificadas e se as condições de correspondência das duas regras não se sobrepõem.

  2. Aguarde a configuração entrar em vigor: Após enviar a configuração, aguarde de 5 a 10 minutos para que ela seja sincronizada globalmente.

  3. Atualize o cache anterior: Recursos armazenados em cache sob a chave de cache anterior antes da alteração de configuração não expiram automaticamente. Envie uma tarefa de atualização (recomendamos usar a atualização de diretório).

  4. Verifique no cliente: Limpe o cache do navegador, tente novamente e verifique se X-Cache nos cabeçalhos de resposta é MISS.

  5. Teste com dispositivos reais: Envie requisições usando o User-Agent real de diferentes dispositivos em vez de apenas redimensionar a janela do navegador (o User-Agent emulado por um navegador pode diferir do de um dispositivo real).

Nota

Custom cache key entra em conflito com Ignore parameters: quando ambos estão configurados, o recurso de ignorar parâmetros não entra em vigor. Se você já usa uma chave de cache personalizada, configure a política de tratamento de parâmetros de requisição dentro dela em vez de ativar Ignore parameters separadamente.

A taxa de acerto de cache é 0 porque as respostas contêm Set-Cookie. Como resolver?

Causa: Quando a resposta da origem contém o cabeçalho Set-Cookie, o CDN não armazena a resposta em cache por padrão, resultando em taxa de acerto de cache de 0.

Importante

Remover Set-Cookie é uma operação de alto risco. Este cabeçalho carrega lógica de negócios crítica, como manutenção de sessões de login, autenticação de sessão e rastreamento de comportamento. Removê-lo globalmente pode causar falhas de login, perda de carrinhos de compras e erros de autenticação. Avalie o escopo do impacto antes de prosseguir.

Soluções recomendadas (em ordem de prioridade):

  • Corrija no lado da origem (recomendado): Configure o servidor de origem para parar de retornar Set-Cookie para recursos estáticos, como imagens, CSS, JavaScript e fontes. Esta é a solução fundamental. Ela não afeta o gerenciamento de sessão de endpoints dinâmicos e melhora a taxa de acerto de cache.

  • Remova por caminho no lado do CDN: Se o servidor de origem não puder ser ajustado, remova este cabeçalho no lado do CDN apenas para caminhos de recursos estáticos, como /static/, *.css e *.js, para evitar afetar endpoints dinâmicos.

Etapas para remover o cabeçalho por caminho no lado do CDN:

  1. Faça login no console do CDN. Na página Domain Names, localize o nome de domínio de destino e clique em Manage.

  2. No painel de navegação à esquerda da página de detalhes do domínio, clique em Origin Settings e acesse a aba Modify incoming response headers.

  3. Clique em Add, restrinja a condição da regra aos caminhos de recursos estáticos, selecione Delete para a operação de cabeçalho de resposta e insira Set-Cookie no nome do cabeçalho de resposta.

  4. Após concluir a configuração, use Refresh and prefetch para limpar as respostas anteriores armazenadas em cache, permitindo que a nova regra entre em vigor.

Se a taxa de acerto de cache ainda não melhorar após a configuração, verifique o seguinte: se Ignore no-cache headers from the origin server está ativado nas regras de cache e se Ignore parameters está ativado para evitar que o mesmo recurso seja dividido em vários objetos de cache devido a parâmetros de consulta diferentes. Para as regras de cache padrão do CDN, consulte Configure CDN cache expiration.

Baixa taxa de acerto de cache e alta taxa de requisição à origem

A taxa de acerto de cache está baixa, a taxa de requisição à origem está alta ou a largura de banda da origem está saturada?

Uma baixa taxa de acerto de cache significa que a maioria das requisições dispara buscas na origem. Um caminho de rede pública instável pode degradar o efeito de aceleração e exercer pressão de carga no servidor de origem. Siga estas etapas para solucionar o problema:

  1. Verifique se o servidor de origem retorna diretivas de no-cache: Esta é a causa mais comum de baixa taxa de acerto e largura de banda da origem saturada. Se o servidor de origem retornar Cache-Control: no-cache, no-store, max-age=0 ou Pragma: no-cache, o CDN segue a diretiva da origem e não armazena o recurso em cache, fazendo com que cada requisição dispare uma busca na origem. Ative Ignore no-cache headers from the origin server na configuração de expiração de cache para impor o armazenamento em cache com base nas regras do console ou ajuste a configuração do servidor de origem.

  2. Verifique se as regras de cache estão mal configuradas: Confirme se o tempo de expiração de cache para o diretório raiz / não está definido como 0 segundos com o maior peso. Caso contrário, todas as requisições dispararão buscas na origem.

  3. Verifique se as URLs contêm parâmetros variáveis: Parâmetros alterados após o ponto de interrogação em uma URL fazem com que o mesmo conteúdo seja tratado como recursos diferentes. Ativar Ignore parameters consolida essas requisições em um único objeto de cache. Para mais informações, consulte o próximo item.

  4. Configure recursos estáticos e dinâmicos separadamente: Defina uma longa duração de cache (como 30 dias) para recursos estáticos, como imagens, CSS, JavaScript e fontes, e defina o tempo de expiração como 0 segundos para conteúdo dinâmico, como PHP, JSP e endpoints de API.

  5. Ative a busca por intervalo (range origin fetch) para arquivos grandes: Para arquivos grandes, como vídeos e pacotes de instalação, certifique-se de que a busca por intervalo esteja ativada para que o POP não busque o arquivo inteiro no servidor de origem para cada requisição. Antes de ativar esse recurso, confirme se o servidor de origem suporta requisições de intervalo (ou seja, se pode retornar 206 Partial Content). Ativar esse recurso quando o servidor de origem não suporta requisições de intervalo pode causar falhas na requisição ou conteúdo anormal.

  6. Verifique se o QPS do negócio é muito baixo: O espaço em disco do POP é limitado, e recursos acessados com pouca frequência são substituídos por recursos populares, o que dispara buscas na origem. Para nomes de domínio com apenas algumas dezenas de QPS, recomendamos enviar tarefas de pré-busca usando Refresh and prefetch para que os recursos permaneçam residentes nos POPs.

O X-Cache da requisição da página principal é sempre MISS, resultando em baixa taxa de acerto de cache. Como resolver?

Sintoma: A taxa de acerto geral de uma página é baixa. Os cabeçalhos de resposta mostram que X-Cache é MISS para a requisição principal, mas HIT para arquivos individuais na página.

Causa: A URL contém parâmetros que mudam a cada requisição, como um timestamp. Quando o recurso de ignorar parâmetros está desativado, o CDN trata cada URL com parâmetros diferentes como um recurso independente e não consegue reutilizar o cache. Por exemplo, o valor após ?_t= em http://example.com/movie/res/ArrowScene.ccbi?_t=1699999999 difere para cada requisição.

Solução: Ative Ignore parameters no console do CDN. Após ativar esse recurso, os parâmetros são excluídos do cálculo do objeto de cache, e requisições para o mesmo recurso com parâmetros diferentes atingem o mesmo cache. Se o seu negócio depender de alguns parâmetros, selecione Retain specified parameters para ignorar apenas os irrelevantes.

Quais são as possíveis causas de uma queda repentina na taxa de acerto de cache?

Causas comuns de flutuações de curto prazo ou queda contínua na taxa de acerto:

  • Atualização de cache realizada: Uma atualização manual ou automática limpa o cache nos POPs; portanto, uma diminuição na taxa de acerto dentro de um curto período é esperada. À medida que os recursos são armazenados em cache novamente, a taxa de acerto geralmente se recupera automaticamente em algumas horas.

  • Pico de largura de banda: Um aumento abrupto de tráfego em um curto período traz muitas requisições inéditas, o que aumenta as buscas na origem e diminui a taxa de acerto.

  • Acesso a grande quantidade de novo conteúdo: Quando os POPs solicitam frequentemente recursos acessados pela primeira vez, a busca na origem é inevitável e a taxa de acerto diminui.

  • Ajuste de regras de cache: Modificar a política de cache, especialmente encurtar o tempo de expiração, afeta a taxa de acerto.

  • URLs com parâmetros variáveis: Parâmetros variáveis dividem o mesmo conteúdo em vários objetos de cache.

  • Tempo de expiração do cache inadequado: Se a configuração não diferenciar recursos por frequência de atualização, o cache expira cedo demais.

Exceções em cabeçalhos de resposta e CORS

Configurei Access-Control-Allow-Origin, mas as requisições ainda relatam erros de CORS?

Se você configurou cabeçalhos de resposta CORS no CDN, mas os clientes ainda relatam erros de CORS e os cabeçalhos de resposta não contêm o campo configurado, as possíveis causas e soluções são:

  • A configuração não entrou em vigor: Confirme se a configuração foi salva e se o status da regra é Success.

  • A configuração não foi totalmente entregue: Alterações na configuração de cabeçalhos de resposta de saída geralmente entram em vigor dentro de 5 minutos. Aguarde e tente novamente. Essa configuração afeta apenas as respostas recebidas pelos clientes, não o comportamento de cache dos POPs; portanto, nenhuma atualização ou pré-busca é necessária (a pré-busca não altera os cabeçalhos de resposta de recursos já armazenados em cache).

  • Conflito entre cabeçalhos da origem e configuração do CDN: Se o servidor de origem também retornar cabeçalhos de resposta CORS, eles podem se substituir mutuamente. Recomendamos usar configurações CORS consistentes no servidor de origem e no CDN, ou definir Allow Duplicate como No em Modify outbound response headers para que o valor configurado no CDN substitua o valor retornado pelo servidor de origem.

  • Cache de resposta anterior no navegador: Limpe o cache do navegador ou use o modo de navegação privada para testar.

  • Configuração de domínio curinga não suportada: Após ativar a validação CORS, você pode configurar apenas um único nome de domínio curinga ou vários nomes de domínio exatos separados por vírgulas. Separar vários nomes de domínio curinga com vírgulas não é suportado.

  • Valor de Access-Control-Allow-Origin incompatível com a Origem da requisição: Se o navegador relatar "The 'Access-Control-Allow-Origin' header has a value that is not equal to the supplied origin", a origem permitida retornada não corresponde à origem real da requisição. Você pode resolver isso das seguintes maneiras:

    • Em Modify outbound response headers, reconfigure Access-Control-Allow-Origin e defina Allow Duplicate como No para que o novo valor substitua o valor anterior retornado pelo servidor de origem.

    • Se o seu negócio permitir, configure este cabeçalho de resposta para retornar dinamicamente o valor Origin na requisição, de modo que a origem permitida sempre corresponda à origem da requisição. Após concluir a configuração, aguarde cerca de 5 minutos para que ela entre em vigor. Nenhuma atualização de cache é necessária.

Para saber como configurar o compartilhamento de recursos de origem cruzada, consulte Configure cross-origin resource sharing.

Um cabeçalho de resposta personalizado não entrou em vigor?

  • Confirme se as requisições passam pelos POPs do CDN: Verifique se a resolução DNS mantém apenas o registro CNAME fornecido pelo CDN e se os registros de resolução direta para origens como OSS foram removidos. Se o tráfego for diretamente para o servidor de origem, os cabeçalhos de resposta configurados no CDN não entrarão em vigor.

  • Confirme se você configurou um cabeçalho de resposta de saída e não de entrada: Cabeçalhos de resposta de entrada aplicam-se apenas à comunicação entre o servidor de origem e os POPs do CDN, e os usuários finais não têm ciência deles. Para afetar as respostas que os usuários finais recebem, configure Modify outbound response headers.

  • Confirme se o servidor de origem retorna o cabeçalho de resposta: O CDN repassa os cabeçalhos de resposta da origem por padrão. Se o servidor de origem não retornar o cabeçalho, o CDN também não o retornará. Para forçar a inclusão do cabeçalho de resposta independentemente de o servidor de origem retorná-lo ou não, selecione a operação Add em Modify outbound response headers.

  • Se Content-Type não entrar em vigor, verifique os metadados no servidor de origem: Se o servidor de origem (como OSS) não especificar o Content-Type correto ao carregar um arquivo, os metadados obtidos durante a busca na origem não corresponderão à sua expectativa. Verifique a configuração de Content-Type usada quando o arquivo foi carregado.

  • Confirme se aguardou a configuração entrar em vigor: Alterações na configuração de cabeçalhos de resposta de saída geralmente entram em vigor dentro de 5 minutos e afetam apenas as respostas recebidas pelos clientes, não o comportamento de cache dos POPs; portanto, nenhuma atualização ou pré-busca é necessária (a pré-busca não altera os cabeçalhos de resposta de recursos já armazenados em cache).

Para saber como configurar cabeçalhos de resposta de saída e as descrições dos parâmetros, consulte Modify outbound response headers.

Uma página ficou ilegível após a aceleração do CDN. Como proceder?

Causa: O cabeçalho de resposta Content-Type retornado pelo servidor de origem não especifica corretamente a codificação de caracteres, e o cliente analisa o conteúdo com a codificação errada, causando a ilegibilidade da página.

Solução 1 (recomendada, corrigir na source): Modifique a configuração do servidor de origem para garantir que Content-Type contenha a declaração correta de codificação de caracteres ao retornar HTML.

Solução 2 (reescrever no lado do CDN):

  1. Faça login no console do CDN. Na página Domain Names, localize o nome de domínio de destino e clique em Manage.

  2. Em Modify incoming response headers, adicione uma regra para reescrever o Content-Type do caminho correspondente para text/html; charset=utf-8.

  3. Após concluir a configuração, use Refresh and prefetch para atualizar os recursos armazenados em cache nesse caminho, para que os POPs os armazenem novamente com o tipo correto.

Nota

Reescrever Content-Type com um cabeçalho de resposta de entrada corrige o tipo durante o estágio de busca na origem, e o POP armazena o recurso novamente com o tipo correto. Se você usar um cabeçalho de resposta de saída, o tipo armazenado no cache do POP ainda estará errado e será substituído apenas na entrega, o que é menos eficaz. Além disso, cabeçalhos de resposta de entrada não suportam configuração de domínio curinga.

Configurei um cabeçalho de resposta para controlar download ou visualização de vídeo, mas não funcionou. O que fazer?

Você pode configurar o cabeçalho de resposta Content-Disposition usando o recurso Modify outbound response headers para controlar o comportamento de download ou visualização de vídeos: se definido como attachment; filename='video.mp4', um download é acionado quando um usuário acessa o recurso; se definido como inline, o recurso é visualizado diretamente no navegador.

Se a configuração não entrar em vigor, verifique os seguintes itens:

  1. Condição de correspondência do mecanismo de regras: Certifique-se de que a condição de correspondência da regra tenha como alvo o caminho URI (por exemplo, contém /video-origin/20260414) em vez de corresponder apenas à string de consulta. O mecanismo de regras determina se a configuração entra em vigor identificando as informações de caminho na requisição do usuário.

  2. Cache de cabeçalho anterior no POP: Content-Disposition afeta diretamente o comportamento do navegador. Se a configuração não entrar em vigor 5 minutos após ser salva, elimine primeiro o cache local do navegador (tente novamente no modo de navegação privada) e confirme se o status da regra é Success.

Um arquivo JavaScript está sendo tratado incorretamente como text/html. Como resolver?

Causa: Quando o servidor de origem retorna o arquivo JavaScript pela primeira vez, o cabeçalho de resposta Content-Type está incorretamente definido como text/html. Depois que o CDN armazena o tipo errado em cache, o navegador analisa o arquivo JavaScript como text/html, o que causa exibição ilegível ou erros de execução. Na segunda visita, a página volta ao normal porque o servidor de origem corrigiu o Content-Type ou o CDN buscou o tipo correto no servidor de origem novamente.

Solução:

  1. Em Modify incoming response headers no console do CDN, adicione uma regra para corresponder ao caminho do arquivo JavaScript (como *.js) e substitua forçosamente o Content-Type por application/javascript.

  2. Após concluir a configuração, use Refresh and prefetch para atualizar o cache do arquivo JavaScript, permitindo que a nova regra entre em vigor imediatamente.

Nota

Este problema compartilha a mesma causa raiz da ilegibilidade de página (o servidor de origem retornou o Content-Type errado). Em ambos os casos, recomendamos corrigir primeiro a configuração do servidor de origem e reescrever o cabeçalho com um cabeçalho de resposta de entrada apenas se o servidor de origem não puder ser ajustado.

Exceções com vídeos e arquivos grandes

Ocorre ERR_CONTENT_LENGTH_MISMATCH durante a reprodução de vídeo?

Causa: O tamanho do arquivo armazenado em cache no POP não corresponde ao conteúdo real no servidor de origem, ou o servidor de origem retornou um cabeçalho de resposta Content-Length anormal. Isso ocorre mais comumente quando o servidor de origem atualizou um arquivo de vídeo, mas o CDN ainda retorna a versão anteriormente armazenada em cache.

Solução:

  • Na página Refresh and prefetch, envie uma tarefa de atualização para a URL do vídeo para limpar o cache anterior nos POPs.

  • Se o servidor de origem for OSS, você pode ativar o recurso Automatic CDN cache refresh no console do OSS para que uma atualização de cache do CDN seja acionada automaticamente quando um arquivo no servidor de origem for atualizado.

  • Verifique a estabilidade do servidor de origem para garantir que ele não retorne intermitentemente um valor anormal de Content-Length. Você pode executar curl -I várias vezes diretamente contra o servidor de origem para comparar e verificar.

É normal ver muitos códigos de status 206 ou múltiplas buscas na origem nos logs?

Sim. Reprodutores de vídeo e ferramentas de download geralmente usam requisições de intervalo para carregar recursos em segmentos. Cada requisição recupera apenas parte do conteúdo, e o servidor retorna 206 Partial Content. Mesmo quando uma requisição atinge o cache do CDN, o código de status retornado é 206, o que não é um erro.

Nota sobre faturamento: Desde que um cliente envie uma requisição ao CDN e receba dados, o tráfego é contabilizado como tráfego de saída do CDN, independentemente de a requisição atingir o cache ou não.

Sugestões de otimização: Certifique-se de que a busca por intervalo na origem esteja ativada para que os POPs possam buscar e armazenar segmentos do servidor de origem sob demanda, o que melhora a taxa de acerto para requisições de segmentos subsequentes. Além disso, configure um cabeçalho Cache-Control adequado no servidor de origem (como max-age=86400) para usar o cache local do navegador e reduzir requisições duplicadas.

Exceções de conteúdo e acesso

Recursos estáticos atingem o cache, mas a página inicial ainda carrega lentamente?

Causa: Recursos estáticos, como imagens, arquivos CSS e arquivos JavaScript, atingem o cache e são acelerados normalmente, mas a página inicial (o caminho raiz /) geralmente não possui regra de cache. Cada requisição busca a página inicial no servidor de origem; portanto, a velocidade de carregamento depende inteiramente do tempo de processamento do servidor de origem.

Solução: Adicione uma regra de expiração de cache para o diretório raiz do nome de domínio acelerado para que o conteúdo da página inicial também seja armazenado em cache nos POPs:

Importante

A solução a seguir aplica-se apenas a páginas iniciais puramente estáticas ou pseudoestáticas, como sites oficiais e blogs. Se a página inicial contiver conteúdo dinâmico específico do usuário, como estados de login ou recomendações personalizadas, armazenar o diretório raiz em cache pode fazer com que os usuários vejam o conteúdo de outros usuários, levando ao vazamento de informações. Para páginas iniciais dinâmicas, use ESI (Edge Side Includes) ou uma arquitetura de separação estático-dinâmica.

  1. Na aba Cache Expiration, adicione uma regra, defina o tipo como Directory e defina o endereço como /.

  2. Defina o tempo de expiração com base na frequência de atualização do conteúdo da página inicial, por exemplo, de 30 segundos a vários minutos.

  3. Ajuste o peso da regra para que o peso da regra do diretório raiz seja inferior ao das regras para caminhos específicos (como /static/) para evitar substituir as regras de cache para recursos estáticos.

Depois que a configuração entrar em vigor, os POPs retornarão o conteúdo da página inicial diretamente em vez de buscá-lo no servidor de origem para cada requisição. Para instruções detalhadas de configuração, consulte Configure CDN cache expiration.

O acesso via CDN retorna um resultado diferente do acesso direto ao servidor de origem?

Causa: Quando um POP falha no cache, ele encaminha a requisição do cliente e anexa parâmetros específicos aos cabeçalhos da requisição, como Via e X-Forwarded-For. Alguns servidores de origem retornam respostas diferentes com base nesses parâmetros. Por exemplo, um servidor de origem pode verificar se a requisição contém o cabeçalho Via para identificar requisições de proxy e tratá-las de forma diferente.

Etapas de solução de problemas:

  1. Localize o cabeçalho que causa a diferença: Primeiro, acesse o servidor de origem diretamente e registre a resposta. Em seguida, use curl para acessar o servidor de origem com os cabeçalhos que o CDN anexa, substituindo-os e testando-os um por um até reproduzir o resultado inconsistente.

  2. Ajuste a configuração do servidor de origem: Verifique como o servidor web de origem processa o cabeçalho e modifique a lógica com base nos requisitos do seu negócio.

  3. Ou exclua o cabeçalho no lado do CDN: Se o cabeçalho não for necessário para o seu negócio, você pode excluí-lo no console do CDN.

O arquivo baixado via CDN é inconsistente com o do servidor de origem (atualização com o mesmo nome). Como resolver?

Causa: O servidor de origem realizou uma atualização com o mesmo nome no arquivo (o conteúdo do arquivo foi modificado, mas o nome do arquivo não foi alterado). Antes que o cache expire, o POP do CDN ainda retorna o cache anterior diretamente; portanto, o arquivo baixado é inconsistente com o do servidor de origem.

Solução:

  1. Solução 1: Atualize o cache manualmente. Depois que o servidor de origem realizar uma atualização com o mesmo nome, envie uma atualização de URL na página Refresh and prefetch (adequado para um único recurso e entra em vigor rapidamente) ou uma atualização de diretório (adequado para um diretório inteiro e abrange uma ampla gama, mas aumenta temporariamente a pressão de busca na origem no servidor de origem).

  2. Solução 2: Force uma atualização para ignorar 304. Se o conteúdo do arquivo no servidor de origem mudou, mas o timestamp Last-Modified não foi atualizado, o POP do CDN recebe 304 Not Modified após a validação da requisição condicional (If-Modified-Since), determina que o arquivo não mudou e não atualiza o cache. Nesse caso, uma atualização normal de URL pode não surtir efeito. Você deve chamar a API RefreshObjectCaches e definir o parâmetro Force como true para forçar a busca do arquivo completo no servidor de origem.

  3. Solução 3: Use nomenclatura versionada (recomendado como solução de longo prazo). Recomendamos que o servidor de origem evite atualizações com o mesmo nome. Em vez disso, adicione um número de versão ou um hash ao nome do arquivo (como style.v2.css ou app.abc123.js), ou inclua um identificador de versão em um parâmetro de URL (como ?v=20260828).

  4. Solução 4: Ative a atualização automática para origem OSS. Se o servidor de origem for OSS, você pode ativar Automatic CDN cache refresh no console do OSS. Quando um objeto na origem OSS é atualizado com o mesmo nome, a URL correspondente do CDN é atualizada automaticamente.

Nota

Ao usar parâmetros de versão de URL, não ative Ignore parameters no CDN ao mesmo tempo. Caso contrário, o parâmetro de versão será ignorado e esta solução se tornará ineficaz. Se o seu negócio precisar ignorar outros parâmetros, use Retain specified parameters e mantenha o parâmetro de versão.

Por que uma página 404 personalizada aparece quando acesso um recurso?

Quando um servidor web retorna o código de status HTTP 404, ele redireciona automaticamente para a página 404, indicando que o recurso solicitado não existe no servidor de origem. As causas comuns incluem: mudança na regra de geração de URL, arquivo renomeado ou movido, erro de digitação no link, site inacessível na porta solicitada, ou bloqueio da requisição por política de restrição de extensão de service web ou política de mapeamento MIME.

Se a página que você acessa contém vários recursos e apenas alguns deles estão inacessíveis, a página não redireciona para a página 404 como um todo. Para saber como configurar páginas de erro personalizadas, consulte Configure custom error pages.

Ocorre um redirecionamento de domínio ou loop de redirecionamento após configurar uma página 403 personalizada. Como proceder?

Ao configurar uma página de erro personalizada para o código de status 403, definir o link de redirecionamento diretamente nas configurações da página de erro pode causar um redirecionamento de domínio ou um loop de redirecionamento. Use o seguinte método em vez disso:

  1. Configure o redirecionamento usando o recurso Access URL Rewrite em vez de definir um link de redirecionamento na página de erro personalizada.

  2. Defina o caminho para reescrever como / e aponte o caminho de destino para a página 403 estática correta, por exemplo, /error/403.html.

Importante

Certifique-se de que a própria página de erro 403 esteja acessível e não acione outro redirecionamento 403. Caso contrário, ocorrerá um loop de redirecionamento e a página não poderá ser acessada.

O que fazer se o problema persistir

Antes de abrir um ticket, recomendamos localizar o problema por conta própria das seguintes maneiras:

  • Verifique os logs em tempo real: No console, verifique o status do cache, o status da busca na origem e a distribuição de códigos de resposta da requisição específica para determinar em quais URLs ou períodos de tempo o problema está concentrado.

  • Use a ferramenta de diagnóstico do console: Insira a URL problemática para detecção e obtenha rapidamente informações sobre resolução, busca na origem e cabeçalhos de resposta.

  • Realize testes comparativos: Acesse o mesmo recurso através do CDN e diretamente do servidor de origem, compare as diferenças nos cabeçalhos de resposta e no conteúdo, e determine se o problema está no lado do CDN ou no lado do servidor de origem.

Se o problema persistir após a solução de problemas por conta própria, recomendamos coletar as seguintes informações antes de abrir um ticket para acelerar a identificação:

  • O nome de domínio acelerado e a URL específica da requisição.

  • A saída completa de curl -v que reproduz o problema (incluindo os cabeçalhos de requisição e resposta).

  • O horário aproximado, região e ISP quando o problema ocorreu.

  • O tipo de servidor de origem (OSS, ECS, SLB, servidor de origem de terceiros, etc.) e se o servidor de origem suporta requisições de intervalo.

  • As etapas de solução de problemas que você tentou e o resultado de cada etapa.

  • Se o problema envolver a taxa de acerto de cache, forneça uma captura de tela da taxa de acerto no console e o intervalo de tempo correspondente.