# Acelerar o Flarum com cache sem vazar sessão

A instalação da extensão de cache é a parte fácil. O que separa um fórum rápido de um vazamento de sessão é a lista de rotas excluídas e a conferência com curl.

> seis grupos de rota do Flarum precisam ficar fora do cache de servidor (/api, autenticação, /confirm e /reset, /settings, /notifications e /admin), senão a página de um usuário logado é entregue a outro. Depois disso, confirme com curl o cabeçalho x-litespeed-cache: hit.

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

---

## O que o cache de servidor faz num Flarum, e onde ele erra

Cache de página em servidor guarda o HTML pronto de uma URL e devolve esse mesmo HTML para a próxima pessoa que pedir a mesma URL. Para uma discussão pública, aberta por quem não fez login, isso é excelente: o PHP não roda, o banco não é consultado, a resposta sai do disco ou da memória.

O problema do Flarum é que ele não separa visitante e usuário logado por URL. A mesma rota `/d/42-titulo-da-discussao` devolve conteúdo diferente conforme quem pede: o seu avatar no canto, o contador de notificações, a marcação de qual post você já leu. Além disso, a interface é uma aplicação JavaScript que conversa com o backend por `/api`, e é nessa rota que trafegam dados de sessão.

Se o cache for ligado sem exclusões, dois acidentes acontecem, nessa ordem de gravidade:

- Uma resposta de `/api` gerada para o usuário A fica guardada e é entregue ao usuário B. Isso é vazamento de sessão, não é lentidão.
- A marcação de leitura e o sino de notificações congelam, porque a página servida é a versão salva, não a sua.

A regra prática: **cache só para quem não tem cookie de sessão, e nunca para rotas de API ou de conta**.

## Backup e pré-requisitos antes de ligar qualquer coisa

Cache de página mexe no que o visitante recebe, não nos seus dados. Ainda assim, instalar extensão no Flarum altera `composer.json`, `composer.lock` e a tabela de extensões no banco. Faça o backup antes:

- Arquivos: a pasta inteira do Flarum, incluindo `config.php`, `.htaccess` e `storage/`.
- Banco de dados: dump completo via phpMyAdmin (aba Exportar, método rápido, formato SQL) ou pelo backup do painel de hospedagem.

Para voltar atrás, o caminho é desabilitar a extensão no painel administrativo, limpar o cache do Flarum e restaurar os arquivos. Guarde essa ordem antes de começar.

Dois pré-requisitos do lado do servidor, segundo a [documentação do LiteSpeed Cache for Flarum](https://docs.litespeedtech.com/lscache/lscflarem/):

- O site precisa rodar em LiteSpeed Enterprise ou OpenLiteSpeed com o módulo de cache habilitado. Em Apache ou Nginx puro a extensão não tem o que controlar.
- O cache precisa estar habilitado para o domínio no nível do servidor. Em hospedagem compartilhada isso costuma vir ligado; se você não tem certeza, pergunte ao suporte se o LiteSpeed Cache está ativo no seu domínio antes de instalar a extensão.

## Instalar a extensão de cache no Flarum

### Acessar o servidor por SSH e encontrar a raiz do Flarum

O Flarum instala extensões por Composer, não por upload de ZIP no painel. Não existe caminho só por clique aqui.

```
cd /home/usuario/public_html
ls composer.json
```

Se `composer.json` aparecer, você está na pasta certa.

### Instalar o pacote com o identificador da documentação oficial

Abra a [página da extensão na documentação da LiteSpeed](https://docs.litespeedtech.com/lscache/lscflarem/) e copie de lá o identificador exato do pacote, no formato `vendor/pacote`. Não copie esse identificador deste texto nem de outro blog: a documentação é a única fonte confiável do nome atual. Na raiz do Flarum, rode:

```
composer require VENDOR/PACOTE
```

Troque `VENDOR/PACOTE` pelo identificador que você copiou, e confira também a restrição de versão indicada na documentação. O nome e a versão mudam conforme a linha do Flarum (1.x e posteriores), e um identificador desatualizado faz o Composer responder `could not be found` sem instalar nada.

Se o Composer reclamar de memória, rode com `php -d memory_limit=-1` antes do comando. Se reclamar de versão de PHP, confira a versão do PHP da conta no painel de hospedagem.

### Limpar o cache do Flarum para o painel enxergar a extensão

```
php flarum cache:clear
```

Saída esperada: uma linha confirmando que o cache foi limpo. Esse passo evita que o painel administrativo continue mostrando a lista antiga de extensões.

### Habilitar a extensão e abrir o TTL e a lista de exclusões

Entre no fórum como administrador, clique no seu avatar, escolha **Administração** e vá em **Extensões**. Procure a extensão de cache na lista e ligue o botão. O Flarum recarrega. Abra as configurações dela (ícone de engrenagem no card da extensão): é ali que ficam o TTL e a lista de exclusões. Os nomes exatos dos campos mudam conforme a versão; se a sua tela estiver diferente da descrita aqui, a [documentação oficial](https://docs.litespeedtech.com/lscache/lscflarem/) é a referência do que cada campo faz.

## As seis rotas que precisam ficar fora do cache

A extensão já traz exclusões próprias, e a referência do que vem configurado de fábrica na sua versão está na [documentação da LiteSpeed](https://docs.litespeedtech.com/lscache/lscflarem/): confira lá antes de sair cadastrando coisa repetida. A tabela abaixo não é transcrição da documentação, é a nossa lista de conferência, montada a partir de como o Flarum se comporta. `/api` e as rotas de autenticação são o caso óbvio; `/settings`, `/notifications` e `/admin` entram porque o conteúdo delas depende de quem está logado, e é verificação que recomendamos fazer a cada instalação. Cadastre na área de exclusão da extensão o que faltar, e confira depois um a um.

| Rota | Por que excluir | Sintoma se cachear |
|---|---|---||
| `/api` e tudo abaixo dela | Carrega dados de sessão, rascunho e permissão | Resposta de um usuário entregue a outro |
| `/login`, `/logout`, `/register` | Fluxo de autenticação e token CSRF | Login que não completa, erro de token |
| `/confirm`, `/reset` | Links de e-mail com token de uso único | Link expirado ou confirmando a conta errada |
| `/settings` | Página de conta do usuário | Dados de uma conta exibidos em outra |
| `/notifications` | Contador e lista pessoal | Sino congelado no número antigo |
| `/admin` | Painel administrativo inteiro | Configuração servida de versão antiga |

E a regra que vale para o fórum todo: **nenhuma requisição com cookie de sessão do Flarum pode ser servida do cache**. Não afirme que isso já vem resolvido: trate como verificação obrigatória sua, feita a cada instalação e a cada atualização da extensão. A verificação está na seção de conferência mais abaixo.

Sobre o TTL, aqui é recomendação nossa e não valor tirado da documentação: comece baixo, algo como 5 minutos, e observe. Fórum ativo tem página de listagem que muda a cada minuto; um TTL alto demais faz a home parecer parada. Quem não participa das discussões não nota, quem participa reclama na hora.

## Medir o tempo de resposta com curl como visitante anônimo

A comparação só faz sentido como **visitante anônimo**, porque é esse o único tráfego que vai sair do cache. Abra o terminal da sua máquina, não do servidor, para que a latência de rede entre no número.

Tempo total de uma discussão pública:

```
curl -sS -o /dev/null -w "%{time_total}\n" https://forum.exemplo.com/d/42
```

- `-sS` esconde a barra de progresso mas mostra erro.
- `-o /dev/null` descarta o HTML.
- `-w "%{time_total}\n"` imprime só o tempo total em segundos.

Rode cinco vezes seguidas e anote. A primeira costuma ser a mais lenta porque abre conexão TLS.

Agora os cabeçalhos, que dizem se o cache respondeu:

```
curl -sS -D - -o /dev/null https://forum.exemplo.com/d/42 | grep -i litespeed
```

O `-D -` imprime os cabeçalhos na tela. Você procura a linha `x-litespeed-cache`. Na primeira requisição depois de uma limpeza ela tende a vir como `miss`; na segunda, `hit`. Enquanto você não vir `hit`, o cache não está servindo nada e qualquer comparação de tempo é ruído.

Um exemplo ilustrativo de como o resultado costuma ser lido, com números inventados só para mostrar o formato da anotação, não medição nossa:

```
antes  (sem cache): 0.812 0.790 0.835 0.801 0.788
depois (hit):       0.114 0.108 0.121 0.110 0.107
```

O que interessa não é bater um número específico e sim duas coisas: o tempo depois ficar estável entre as rodadas (cache entrega sempre o mesmo trabalho) e o cabeçalho confirmar `hit`.

## Conferir em dois minutos se o cache vazou sessão

Este teste leva dois minutos e evita o pior erro possível.

- Em uma janela normal do navegador, faça login no fórum com uma conta comum de teste.
- Em uma janela anônima, abra a mesma discussão.
- Na janela anônima, confira se aparece o botão de login no topo, e não o avatar da conta de teste.

Depois, no terminal:

```
curl -sS -D - -o /dev/null https://forum.exemplo.com/api/forum | grep -i litespeed
```

Se aparecer `x-litespeed-cache: hit` nessa rota, a exclusão de `/api` não foi aplicada. Desligue a extensão imediatamente: avatar, **Administração**, **Extensões**, botão da extensão de cache em desligado. Isso impede que novas respostas sejam marcadas como cacheáveis, mas o que já está guardado continua sendo servido até o TTL expirar. Purgue também:

- No painel da hospedagem (cPanel), procure o ícone **LiteSpeed Web Cache Manager** e use a opção de flush do cache do domínio (**Flush All** ou **Purge All**, conforme a versão).
- Se o seu painel não tiver esse ícone, veja se há um botão de purge nas configurações da extensão dentro do Flarum. Não havendo nenhum dos dois, peça ao suporte da hospedagem um flush do cache LiteSpeed do seu domínio.
- Rode de novo o `curl` em `/api/forum`. Enquanto o cabeçalho não voltar como `miss`, ainda existe resposta guardada circulando.

Só depois disso revise a lista de exclusões e ligue a extensão de novo.

## Quando o cache não resolve e quando ele mascara o problema

Vale dizer antes que você gaste a tarde nisso. O cache de página acelera quem chega de busca e lê sem logar. Ele não acelera:

- Quem está logado e participa, porque essas requisições passam direto para o PHP.
- O envio de post, a busca interna e o upload de anexo.

Caso em que o cache mascara o problema: fórum cuja lentidão vem de consulta ao banco mal indexada ou de extensão pesada. Com `hit` o HTML sai do cache, o PHP não roda e o tempo cai do mesmo jeito, então parece resolvido. O sintoma continua ali, só mudou de lugar: a página demora quando o cabeçalho vem `miss`, ou seja, para quem está logado e no primeiro acesso depois de cada expiração do TTL. O cache compra tempo, não conserta a causa.

Se o `hit` aparece e o tempo não cai, o gargalo está na rede, no TLS ou na transferência, não no processamento. Repita o `curl` com `-w "%{time_namelookup} %{time_connect} %{time_starttransfer} %{time_total}\n"` para ver em qual etapa o tempo é gasto.

## Checklist final

- Backup de arquivos e banco feito e testado.
- Servidor LiteSpeed com cache habilitado para o domínio.
- Extensão instalada com o identificador copiado da documentação oficial e habilitada no painel.
- As seis linhas da tabela de exclusão cadastradas e conferidas.
- TTL começando baixo.
- `x-litespeed-cache: hit` confirmado em discussão pública.
- `/api` confirmado fora do cache.
- Janela anônima mostrando botão de login, nunca o avatar de outra conta.

Fonte do procedimento e dos pré-requisitos: [LiteSpeed Cache for Flarum](https://docs.litespeedtech.com/lscache/lscflarem/), documentação oficial da LiteSpeed Technologies, consultada em 15 de outubro de 2026. Os valores de tempo mostrados neste texto são exemplo de formato, não medição nossa.

