Cache na CDN
Todo projeto HTTP público passa pela CDN incluída na Zenifra. A CDN guarda cópias de arquivos estáticos perto do visitante. Assim, esses arquivos chegam mais rápido e a instância fica livre para responder ao resto. Quem decide por quanto tempo cada arquivo fica em cache é a sua aplicação, pelo cabeçalho Cache-Control.
O que fica em cache
| Resposta | Fica em cache na CDN? |
|---|---|
| Arquivo estático (lista abaixo) com status 200 | Sim, pelo tempo definido pela aplicação ou pelo padrão |
HTML, API e qualquer caminho sem extensão (/, /produtos, /api/pedidos) | Não. Sempre vai até a aplicação, mesmo com Cache-Control: public |
| Status 404 | Não. Um arquivo que ainda não existe durante um deploy não fica preso |
Resposta com Cache-Control: no-store ou private | Não |
Resposta que envia Set-Cookie | Não |
Requisições POST, PUT, PATCH e DELETE | Não |
Extensões tratadas como arquivo estático: 7z, avi, avif, apk, bin, bmp, bz2, class, css, csv, doc, docx, dmg, ejs, eot, eps, exe, flac, gif, gz, ico, iso, jar, jpg, jpeg, js, mid, midi, mkv, mp3, mp4, ogg, otf, pdf, pict, pls, png, ppt, pptx, ps, rar, svg, svgz, swf, tar, tif, tiff, ttf, webm, webp, woff, woff2, xls, xlsx, zip, zst.
A URL completa, incluindo a query string, identifica a cópia. /app.js?v=1 e /app.js?v=2 são guardados separadamente.
Atenção: a CDN não diferencia usuários. Uma requisição com
Authorizationou cookie de sessão recebe a mesma cópia em cache de um arquivo estático. Não sirva conteúdo privado em caminhos com essas extensões; se precisar, responda comCache-Control: privateouno-store.
Tempo padrão
Quando um arquivo estático não traz Cache-Control, a CDN o guarda por 2 horas. Nesse caso, a Zenifra não envia Cache-Control ao navegador, que segue o comportamento padrão dele.
Como mudar o tempo de cache
Envie o cabeçalho Cache-Control pela aplicação (no framework, middleware ou servidor web). A CDN respeita o valor da aplicação:
| Cabeçalho enviado pela aplicação | Na CDN | No navegador |
|---|---|---|
Cache-Control: public, max-age=31536000, immutable | 1 ano | 1 ano |
Cache-Control: public, max-age=60 | 60 segundos | 60 segundos |
Cache-Control: public, max-age=3600, s-maxage=60 | 60 segundos (s-maxage vale para a CDN) | 1 hora |
Cache-Control: public, max-age=3600 + CDN-Cache-Control: max-age=60 | 60 segundos (o CDN-Cache-Control não chega ao navegador) | 1 hora |
Cache-Control: public, max-age=60, stale-while-revalidate=300 | 60 segundos; depois disso, entrega a cópia antiga na hora e busca a nova em segundo plano | 60 segundos |
Cache-Control: no-cache ou max-age=0 | Guarda, mas consulta a aplicação a cada requisição | Revalida a cada uso |
Cache-Control: no-store ou private | Não guarda | no-store: não guarda; private: só o navegador guarda |
Exemplo em Express:
// Arquivos com hash no nome: cache longo
app.use('/assets', express.static('dist/assets', { maxAge: '1y', immutable: true }))
// Arquivo que muda sem trocar de nome: 5 minutos na CDN e no navegador
app.get('/widget.js', (req, res) => {
res.set('Cache-Control', 'public, max-age=300')
res.sendFile('widget.js', { root: 'public' })
})Exemplo em Nginx:
location /assets/ {
add_header Cache-Control "public, max-age=31536000, immutable";
}Diferença de latência
Uma resposta em cache sai do ponto da CDN mais próximo do visitante. Sem cache, a requisição precisa ir até a aplicação, e o tempo cresce com a distância. Medição do tempo até o primeiro byte de um mesmo projeto, em novembro de 2026:
| Visitante em | Em cache | Sem cache |
|---|---|---|
| São Paulo | ~26 ms | ~51 ms |
| Porto Alegre | ~34 ms | ~68 ms |
| Fortaleza | ~8 ms | ~74 ms |
| Miami (EUA) | ~40 ms | ~510 ms |
| Frankfurt (Alemanha) | ~48 ms | ~900 ms |
Por isso vale usar cache longo nos arquivos estáticos que têm nome versionado.
Publicar uma versão nova e invalidar o cache
Um deploy novo, um reinício ou a troca de imagem não limpam o cache da CDN. Até o tempo de cache acabar, os visitantes podem receber a versão anterior de um arquivo que manteve o mesmo nome. Hoje não há uma ação no console ou na API para limpar o cache. Use uma destas formas:
- Nome com hash (recomendado): ferramentas como Vite, Next.js, webpack e Angular geram nomes como
app.3f9a2c.jsa cada build. Cada versão tem uma URL nova e pode usar cache longo (max-age=31536000, immutable). O HTML, que nunca fica em cache na CDN, aponta sempre para os nomes novos. - Versão na URL: troque
/app.js?v=1por/app.js?v=2. A CDN trata como outro arquivo. - Tempo curto: para arquivos que mudam sem trocar de nome, use um
max-agecurto ouno-cache. A versão nova aparece em, no máximo, esse tempo.
Como conferir
O cabeçalho Age mostra há quantos segundos a cópia está em cache (ele só aparece quando a resposta veio do cache):
curl -sI https://seu-projeto.clients.zenifra.com/assets/app.js | grep -i -E "^(age|cache-control):"FAQ
Posso guardar HTML ou respostas de API na CDN?
Não. Caminhos sem extensão de arquivo estático sempre vão até a aplicação. Para acelerar páginas e APIs, use cache na própria aplicação, como o Cache Valkey gerenciado.
Mudei um arquivo e o visitante ainda vê o antigo. O que faço?
Troque a URL do arquivo (nome com hash ou ?v=) e publique o HTML que aponta para ela. A cópia antiga sai da CDN quando o tempo de cache acabar.
O cache da CDN muda o que a minha aplicação recebe?
Só reduz o número de requisições de arquivos estáticos que chegam à instância. O IP real do visitante e os cabeçalhos das requisições que chegam continuam os mesmos.
Última atualização em
IP real do visitante
Saiba como ler o IP real do visitante que acessa a sua aplicação hospedada na Zenifra com o cabeçalho X-Real-IP, com exemplos em Node.js, Python, PHP e Go.
Domínios personalizados
Aponte seu domínio para uma aplicação na Zenifra: CNAME no subdomínio, registro A no domínio raiz, TXT de validação, Cloudflare sem proxy e HTTPS automático.