# Cache no CS-Cart: LSCache e as 4 rotas excluídas

Instalação do complemento oficial de cache pelo painel, as rotas que precisam ficar de fora e como ler o cabeçalho da resposta para confirmar que funcionou.

> Quatro rotas precisam ficar fora do cache público de uma loja CS-Cart: checkout, carrinho, login e minha conta. Com o complemento oficial LSCache ativado pelo painel, a prova de que a categoria passou a sair do cache é o cabeçalho `x-litespeed-cache: hit` na segunda requisição.

João Rizzon · 2026-10-14 · Infraestrutura web

---

## O que muda na vitrine quando o cache de servidor entra

Sem cache de servidor, cada visita a uma página de categoria faz o mesmo trabalho: o PHP sobe, o CS-Cart consulta o banco, monta o bloco de filtros, calcula preço, renderiza o template e devolve o HTML. Dez visitantes na mesma categoria, dez vezes o mesmo trabalho.

Com o cache de servidor ligado, a primeira visita monta o HTML e guarda uma cópia. As visitas seguintes recebem essa cópia direto do servidor web, sem passar pelo PHP nem pelo banco. É o mesmo princípio do LSCache em WordPress ou Magento, com a diferença de que o CS-Cart tem complemento próprio, mantido pela LiteSpeed, documentado em [LSCache for CS-Cart: FAQ](https://docs.litespeedtech.com/lscache/lsccsc/faq/).

O que o cache **não** faz: não corrige consulta lenta no checkout, não acelera o painel de administração e não resolve imagem de 4 MB na home. Se a sua loja está lenta no carrinho e rápida na vitrine, o cache de página não é o seu problema. Olhe primeiro o tamanho das imagens e os add-ons de terceiros ativos.

## Backup e verificação de servidor LiteSpeed antes de instalar

Ativar cache é uma mudança de baixo risco em termos de dado (nada é apagado), mas de risco alto em termos de experiência: uma rota cacheada por engano mostra o carrinho de um cliente para outro. Por isso, a ordem importa.

- Faça backup do banco e dos arquivos. No CS-Cart, em **Administração > Backup/Restauração**, gere um backup do banco antes de instalar o complemento.
- Confirme que o servidor roda LiteSpeed. O complemento de cache do LiteSpeed depende do servidor web para funcionar; em Apache ou Nginx puro, ele instala mas não entrega página do cache.
- Escolha um horário de movimento baixo. Se algo sair errado, a correção é desativar o complemento, e isso é mais tranquilo fora do pico.

Para checar o servidor, abra o terminal do seu computador e rode:

```
curl -sI https://sualoja.com.br/ | grep -i '^server:'
```

Resultado esperado em servidor compatível: uma linha começando com `server: LiteSpeed`. Se vier `nginx` ou `Apache`, o complemento não vai gerar acerto de cache e o resto deste guia não se aplica.

## Como instalar o complemento LSCache pelo painel do CS-Cart

O complemento oficial é distribuído em arquivo, não aparece sozinho na lista de add-ons do CS-Cart.

### Baixar o pacote .zip sem descompactar

Abra o [FAQ oficial do LSCache for CS-Cart](https://docs.litespeedtech.com/lscache/lsccsc/faq/) e siga o link de download do add-on indicado ali. Baixe o pacote e guarde o arquivo `.zip` sem descompactar: o painel do CS-Cart espera o zip inteiro. Antes de subir, confira que o arquivo abre como zip válido e que dentro dele existe uma pasta com o nome do add-on. Se o navegador tiver salvo um `.zip` de poucos KB ou um arquivo HTML renomeado, o download falhou e a instalação vai dar erro de pacote inválido.

### Subir o arquivo em Gerenciar complementos

No painel do CS-Cart, vá em **Complementos > Gerenciar complementos**. No canto superior direito, clique no botão **+** e escolha a opção de carregar um arquivo de complemento. Selecione o `.zip` baixado e confirme.

O CS-Cart instala e já deixa o complemento na lista. Se aparecer erro de permissão de escrita, o problema é dono/permissão da pasta `app/addons` no servidor, não o pacote.

### Ativar o complemento e definir um TTL conservador

Ainda em **Gerenciar complementos**, localize o LiteSpeed Cache na lista, mude o status para **Ativo** e clique no nome do complemento para abrir a tela de configurações. É nessa tela que ficam o liga/desliga do cache público, o tempo de vida (TTL) e a lista de rotas excluídas.

Comece com o TTL conservador. Um valor de poucas horas para páginas públicas já tira a maior parte do trabalho repetido do PHP e limita o estrago caso alguma purga automática falhe.

## Checkout, carrinho, login e minha conta nunca entram no cache público

Esta é a parte que separa uma loja rápida de uma loja com pedido errado. Página pública é igual para todo mundo. Página de sessão é diferente para cada visitante. Se uma página de sessão entrar no cache público, o próximo visitante recebe o conteúdo do anterior.

As quatro rotas de sessão de qualquer loja CS-Cart:

| Rota | Controlador CS-Cart | O que quebra se for cacheada |
|---|---|---||
| Checkout | `checkout` | Endereço, frete e total de outro cliente aparecem na tela |
| Carrinho | `checkout.cart` | Carrinho misturado entre visitantes |
| Login e cadastro | `auth` | Visitante vê sessão logada que não é dele |
| Minha conta e pedidos | `profiles`, `orders` | Dados pessoais e histórico de pedido expostos |

Na tela de configuração do complemento existe um campo para listar URLs ou controladores que não devem ser cacheados. Inclua os quatro acima antes de abrir a loja ao público com o cache ligado.

Um quinto cuidado, específico de loja: **preço por grupo de cliente**. Se a sua loja mostra preço diferente para atacado e varejo na mesma URL de categoria, uma página pública cacheada vai servir o preço de quem a gerou primeiro. Nesse cenário, ou você separa os grupos por URL/loja distinta, ou usa o recurso de cache privado em vez do público para as páginas com preço variável. Trate preço por grupo como caso especial, não como padrão.

## Provar pelo cabeçalho que a categoria saiu do cache

O complemento responde com o cabeçalho `x-litespeed-cache`, documentado no [FAQ oficial](https://docs.litespeedtech.com/lscache/lsccsc/faq/). Ele vale `miss` quando a página foi montada na hora e `hit` quando veio do cache.

Escolha uma URL de categoria pública e rode duas vezes:

```
curl -sI https://sualoja.com.br/sua-categoria/ | grep -i x-litespeed-cache
```

O que esperar:

- Primeira execução: `x-litespeed-cache: miss`. O servidor montou a página e guardou a cópia.
- Segunda execução, em seguida: `x-litespeed-cache: hit`. A resposta veio do cache.

Se preferir não usar terminal, dá para ver o mesmo no navegador. Abra a categoria, pressione F12, vá na aba **Rede** (Network), recarregue a página, clique na primeira linha (o documento HTML) e procure `x-litespeed-cache` na lista de cabeçalhos da resposta.

O tempo total da requisição aparece ali ao lado. Vale comparar o `miss` com o `hit` na sua própria loja e anotar os dois valores. Qualquer número que você leia na sua tela é a sua loja, no seu servidor, naquele momento. Não é um valor universal, e aqui não publicamos benchmark de CS-Cart: este guia é documental.

### Teste obrigatório das rotas excluídas

Repita o mesmo comando nas quatro rotas de sessão. As aspas simples em volta da URL são obrigatórias: sem elas, o zsh (padrão no macOS) tenta interpretar o `?` como curinga de arquivo e devolve erro antes de chamar o curl.

```
curl -sI 'https://sualoja.com.br/index.php?dispatch=checkout.cart' | grep -i x-litespeed-cache
```

O resultado correto aqui é `miss` sempre, em toda execução, ou nenhum cabeçalho de acerto. Se o carrinho devolver `hit`, pare: a exclusão não foi aplicada. Desative o complemento, revise a lista de rotas e só religue depois de ver `miss` consistente.

## Quando o cabeçalho nunca vira hit

Sequência de checagem, da causa mais comum para a mais rara:

- **Servidor não é LiteSpeed.** Confirme com o `curl` do cabeçalho `server` mostrado acima.
- **Cache público desligado na tela do complemento.** Instalar e ativar não é o mesmo que ligar o cache.
- **Você está logado.** Sessão de administrador ou de cliente normalmente não recebe cache público. Teste em janela anônima ou com `curl`, que não carrega cookie.
- **A URL tem parâmetro de rastreamento.** `?utm_source=...` pode gerar uma variação nova a cada visita. Teste a URL limpa.
- **Um add-on de terceiros envia `no-cache`.** Desative temporariamente add-ons de personalização ou de preço dinâmico e teste de novo.
- **CDN na frente.** Se existe um proxy intermediário, o cabeçalho que você lê pode ser o dele. Teste direto no IP de origem ou olhe os cabeçalhos próprios do CDN.

## Purga: quando o cliente vê preço antigo

Cache guarda HTML. Se você muda o preço de um produto e a página de categoria continua mostrando o valor antigo, é purga pendente.

O complemento limpa automaticamente o que foi alterado nas operações normais do CS-Cart (editar produto, mudar estoque, publicar categoria). Importação em massa por CSV, alteração direta no banco e script externo costumam passar por fora dessa automação.

Regra prática:

- Mudou pelo painel do CS-Cart: confie na purga automática e confira uma página.
- Importou CSV, rodou script ou alterou o banco na mão: purgue tudo manualmente na tela do complemento, logo depois.
- Trocou tema ou template: purgue tudo. Sempre.

Depois de qualquer purga, rode o `curl` duas vezes na categoria afetada. O par `miss` seguido de `hit` confirma que o cache foi reconstruído com o conteúdo novo.

## Checklist de validação antes de considerar pronto

| Verificação | Comando ou tela | Resultado aceitável |
|---|---|---||
| Servidor compatível | `curl -sI` cabeçalho `server` | `LiteSpeed` |
| Categoria cacheada | `curl -sI` duas vezes na categoria | `miss` depois `hit` |
| Carrinho fora do cache | `curl -sI` no `checkout.cart` | `miss` em toda execução |
| Checkout fora do cache | `curl -sI` no `checkout` | `miss` em toda execução |
| Login fora do cache | `curl -sI` no `auth` | `miss` em toda execução |
| Minha conta fora do cache | `curl -sI` em `profiles` | `miss` em toda execução |
| Pedido real completo | Compra de teste do início ao fim | Pedido correto, total correto |
| Purga funcionando | Alterar preço e recarregar categoria | Preço novo na vitrine |

O último item da lista é o único que não tem atalho: faça um pedido de teste de verdade, com produto real, até a tela de confirmação. Cabeçalho correto em todas as rotas com um checkout quebrado continua sendo uma loja quebrada.

Se depois de tudo isso a vitrine devolve `hit` e ainda assim a loja parece lenta, o gargalo mudou de lugar. Olhe peso de imagem, número de requisições na página e add-ons de terceiros antes de pensar em trocar de plano. Cache de página resolve PHP repetido, não resolve página pesada.

