Pular para o conteúdo
Documentação

Cache e persistência

Ligue o cache de arquivos estáticos do HAProxy por domínio ou em todos os domínios, acompanhe os acertos e mantenha as tabelas de proteção entre reloads.

R Regis Manze 20/11/2026 10 min de leitura

A tela Cache e persistencia reúne os recursos que deixam os sites mais rápidos e o proxy mais estável: o cache de arquivos estáticos na memória do HAProxy, a persistência das tabelas de contadores quando o HAProxy recarrega e um atalho para o health-check passivo dos backends. Todos os recursos vêm desligados por padrão.

Para abrir, vá em Infraestrutura > Cache e persistencia no menu lateral.

Cache de arquivos estáticos

O cartão Cache de arquivos estaticos guarda na memória do HAProxy as respostas de CSS, JavaScript, imagens e fontes e as entrega direto ao visitante, sem consultar o servidor do site. Isso diminui a carga do backend e o tempo de carregamento das páginas. A etiqueta no canto mostra LIGADO ou DESLIGADO.

O que entra no cache

Uma resposta só é guardada quando todas as condições abaixo valem:

  • a requisição é HTTPS e usa o método GET;
  • o domínio está com cache ligado;
  • o endereço termina numa das Extensoes configuradas (por padrão css js png jpg jpeg gif webp avif svg ico woff woff2 ttf otf eot map);
  • a requisição não traz login (cabeçalho Authorization);
  • a resposta do servidor tem status 200 e não traz Set-Cookie;
  • o servidor não proibiu o cache com Cache-Control: no-store ou private;
  • o arquivo cabe no Arquivo maximo (KB).

O que nunca entra no cache

  • Páginas HTML, PHP, respostas de API, JSON e XML. O painel recusa as extensões html, htm, php, json e xml no campo Extensoes (mensagem Extensao nao permitida).
  • Requisições POST e qualquer outro método que não seja GET.
  • Respostas personalizadas por visitante: com Set-Cookie, com Vary: Cookie ou com Cache-Control: private.
  • Requisições barradas pelas regras de segurança: o cache é consultado depois dos bloqueios, então quem é bloqueado não recebe nada do cache.

Vary: User-Agent

Muitos servidores (comum em CWP e Apache) mandam o cabeçalho Vary: User-Agent nos arquivos estáticos, dizendo que a resposta muda conforme o navegador. O cache do HAProxy só sabe separar versões por Accept-Encoding, Referer e Origin, e não guarda nada com outro Vary. O resultado seria um cache ligado com zero acertos.

Para resolver, nas respostas que entram no cache o miniProxy troca Vary: User-Agent por Vary: Accept-Encoding. CSS, JS e imagens não mudam conforme o navegador, e o Accept-Encoding mantém separadas a versão comprimida e a não comprimida do mesmo arquivo. Respostas fora do cache (páginas, APIs) não são alteradas.

Ligar o cache

Ligar o cache de arquivos estáticos para um domínio

  1. No formulário do cartão Cache de arquivos estaticos, preencha:
Campo O que informar
Estado Ligado ou Desligado
Tamanho (RAM) Memória reservada para o cache: 64, 128, 256 (padrão), 512, 1024 ou 2048 MB
Validade maxima Tempo máximo que um arquivo fica no cache: 5 min, 15 min, 1 h (padrão), 6 h ou 1 dia. Se o servidor pedir menos com Cache-Control, vale o do servidor
Arquivo maximo (KB) Maior arquivo aceito, de 16 a 32768 KB (padrão 2048). Precisa ser menor que metade do Tamanho (RAM)
Extensoes Extensões de arquivo cacheáveis, separadas por espaço
Dominios So os marcados abaixo (marque cada domínio na lista; use filtrar dominios... para achar) ou Todos os dominios
  1. Clique em Salvar e aplicar. O HAProxy é recarregado e a mensagem informa quantos hosts estão usando cache.

Atenção: Todos os dominios inclui os domínios criados depois, mas não inclui o domínio que publica o próprio painel deste servidor (a tela mostra qual é). O painel muda a cada atualização e um .js ou .css antigo guardado em cache quebraria a tela.

Dica: também dá para ligar ou desligar o cache de um domínio só, na tela do domínio, na linha Cache de estaticos, botão Ligar / Desligar. Ligar por lá liga o cache geral, se ele estiver desligado.

Atenção: se o site atualizar um arquivo mantendo o mesmo nome (por exemplo style.css sem número de versão), os visitantes podem receber a versão antiga até a Validade maxima vencer. Nesse caso, limpe o cache do domínio (veja abaixo).

Limpar o cache

Há três formas:

Forma Onde Efeito
Esvaziar cache Cartão Cache de arquivos estaticos Recarrega o HAProxy com o cache vazio, para todos os domínios
Limpar agora Tela do domínio, linha Limpar cache Limpa só aquele domínio, na hora, sem reload
URL de limpeza Chamada HTTP, por exemplo no deploy do site Limpa só o domínio chamado, na hora, sem reload

A URL de limpeza aparece no bloco URL de limpeza por dominio quando o cache está ligado. Ela funciona em qualquer domínio com cache, enviando o token do servidor no cabeçalho X-Purge-Token:

curl -X POST -H 'X-Purge-Token: <token>' https://loja.exemplo.com.br/__mp-cache-purge

A resposta é 200 cache limpo ou 403 token invalido. Também é aceito ?token=<token> no endereço, mas assim o token fica gravado no log. A chamada limpa todos os hosts do domínio (por exemplo, com e sem www). A tela de cada domínio mostra o comando pronto para copiar.

O token é único por servidor e vale para todos os domínios. Para invalidá-lo, clique em Trocar token: o antigo para de funcionar na hora em todos os domínios.

Atenção: Esvaziar cache recarrega o HAProxy. Se a persistência das tabelas (abaixo) estiver desligada, o reload também zera contadores de rate-limit e bloqueios temporários.

Como saber se o cache está funcionando

Cabeçalho X-MP-Cache

Toda resposta cacheável de um domínio com cache leva o cabeçalho X-MP-Cache: HIT quando veio da memória do HAProxy e MISS quando foi buscada no servidor. Para testar, peça o mesmo arquivo duas vezes:

curl -sI https://loja.exemplo.com.br/assets/style.css | grep -i x-mp-cache
X-MP-Cache: MISS
curl -sI https://loja.exemplo.com.br/assets/style.css | grep -i x-mp-cache
X-MP-Cache: HIT

No log do HAProxy, as respostas servidas do cache aparecem com o backend terminado em /<CACHE>.

Contadores ao vivo

Com o cache ligado, o cartão mostra a taxa de acerto desde o reload e quantos arquivos vieram do cache, contando desde o último reload do HAProxy.

Uso do cache

O cartão Uso do cache, mais abaixo, mostra o histórico (escolha 24h, 7d ou 30d):

Indicador O que significa
taxa de acerto Porcentagem dos arquivos cacheáveis que vieram do cache
arquivos servidos do cache Quantos foram entregues pela memória, sobre o total cacheável
que nao sairam do servidor Volume de dados entregue pelo cache, que o backend deixou de enviar
de servidor poupado Estimativa de tempo de processamento economizado: acertos multiplicados pelo tempo médio de resposta do servidor
resposta media do servidor (MISS) Quanto o backend demora, em média, para entregar esses arquivos quando não estão no cache

O gráfico de barras compara do cache (HIT) e do servidor (MISS) ao longo do período. A tabela por domínio repete esses números para cada site (Cacheaveis, Do cache, Acerto, Banda poupada, Servidor poupado, MISS medio).

Duas listas ajudam a ajustar o cache:

  • Mais servidos do cache: arquivos com mais acertos.
  • Cacheaveis que sempre vao ao servidor: arquivos que deram MISS repetido. Normalmente o site manda Cache-Control: no-store/private, Set-Cookie, ou o arquivo é maior que o Arquivo maximo (KB).

As estatísticas são lidas do log a cada 15 segundos. A tela do domínio também mostra o acerto das últimas 24 horas, com o link detalhes para este cartão.

Dica: se um backend com um servidor só manda Set-Cookie em todas as respostas, verifique se o site (ou um plugin) não está criando sessão para arquivos estáticos. O miniProxy já remove automaticamente o cookie de afinidade do HAProxy (SERVERID) em backends com um único servidor, justamente para não atrapalhar o cache.

Manter as tabelas no reload

Todo reload do HAProxy (salvar um domínio, uma regra, um certificado...) inicia um processo novo. Sem persistência, as tabelas de contadores (stick-tables) começam zeradas: rate-limit, regras com limite e bloqueios temporários recomeçam do zero. Só os IPs presos por isca ou comportamento são copiados e recolocados pelo painel, e voltam com o tempo de bloqueio cheio.

O cartão Manter as tabelas no reload liga o mecanismo nativo peers do HAProxy, só local (em 127.0.0.1:50999): o processo antigo passa as tabelas inteiras para o novo, com o tempo restante intacto. O cartão mostra quantas tabelas existem na configuração.

  1. Clique em Ligar.
  2. A etiqueta muda para LIGADO.

Atenção: o reload que liga o recurso ainda zera as tabelas uma última vez. A partir do reload seguinte elas passam a ser mantidas.

Para desligar, clique em Desligar: volta o comportamento anterior (só os presos são copiados e recolocados). Se a configuração já tiver um localpeer próprio, feito à mão, o painel não mexe e avisa.

Health-check passivo

O cartão Health-check passivo é informativo. O recurso é configurado por backend, na tela do backend, em Protecao passiva: o HAProxy tira de rotação o servidor que começa a responder erros 5xx em tráfego real, sem esperar a próxima checagem, e o traz de volta com subida gradual de carga.

O cartão lista os backends com 2 ou mais servidores ativos, com link para cada um. Com um servidor só a opção fica bloqueada, porque tirá-lo do ar derrubaria o site inteiro.

Sessão fixa (persistência de sessão)

A persistência de sessão, que mantém o visitante sempre no mesmo servidor, não fica nesta tela: ela é configurada por backend, na tela do backend, em Sessao fixa (cookie) — o visitante fica sempre no mesmo servidor. Ligada, o HAProxy grava um cookie SERVERID no navegador do visitante e envia as próximas requisições ao mesmo servidor, útil para sites que guardam a sessão de login ou o carrinho na memória de um servidor específico.

O cookie só é mantido em backends com 2 ou mais servidores. Em backend com um único servidor ele não traz benefício e atrapalha o cache (a primeira resposta de cada visitante sairia com Set-Cookie e Cache-Control: private), por isso o painel o remove automaticamente e o recoloca quando o backend volta a ter 2 ou mais servidores.

Veja também

Copiar para usar com IA

Este artigo foi útil?

Que bom! O que ajudou mais? O que faltou nesta página?

Opcional — seu voto já foi registrado.

Obrigado pelo seu feedback!