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
200e não trazSet-Cookie; - o servidor não proibiu o cache com
Cache-Control: no-storeouprivate; - 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,jsonexmlno campo Extensoes (mensagem Extensao nao permitida). - Requisições
POSTe qualquer outro método que não sejaGET. - Respostas personalizadas por visitante: com
Set-Cookie, comVary: Cookieou comCache-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

- 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 |
- 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
.jsou.cssantigo 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.csssem 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-Cookieem 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.
- Clique em Ligar.
- 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.