blog
Infraestrutura web

Cache de página no Laravel com LiteSpeed, sem plugin

Sem plugin, o controle fica no seu código: regras por rota, exclusão de sessão autenticada e purge programático por tag, verificados com curl.

JR · · 8 min de leitura · 2 tabelas · 13 blocos de código

Resposta curta: ativar cache de página no Laravel com LiteSpeed exige três peças: `CacheLookup on` no vhost ou .htaccess, um middleware que emite `X-LiteSpeed-Cache-Control` só em rotas GET públicas, e purge por tag via `X-LiteSpeed-Purge` disparado no Observer do model.

Neste artigo
  1. Sem plugin, quem decide o que é cacheável é o seu código
  2. Ligar o CacheLookup no vhost ou no .htaccess
  3. Emitir X-LiteSpeed-Cache-Control só em rotas GET públicas
  4. Purgar por tag no Observer do model em vez de encurtar o TTL
  5. Testar miss contra hit na mesma URL usando GET, não HEAD
  6. Set-Cookie, CSRF, query string e deploy, as armadilhas do Laravel
  7. Checklist de 10 itens antes de liberar em produção

Sem plugin, quem decide o que é cacheável é o seu código

Em WordPress o LSCache resolve sozinho: o plugin decide o que é cacheável, injeta os headers e purga ao salvar um post. No Laravel não existe esse intermediário. O cache de página do LiteSpeed continua sendo o mesmo módulo do servidor, só que quem decide tudo é o seu código.

A divisão de responsabilidade fica assim:

Camada Quem configura O que faz
vhost ou .htaccess administrador do servidor liga o CacheLookup, permitindo que o LiteSpeed sirva a resposta antes do PHP
middleware da aplicação você emite X-LiteSpeed-Cache-Control dizendo se aquela resposta pode ser guardada e por quanto tempo
Event/Observer do model você emite X-LiteSpeed-Purge para invalidar o que ficou velho

Sem a primeira camada, os headers que o Laravel emite são ignorados. Sem a segunda, o LiteSpeed não guarda nada, porque o padrão é não cachear. Sem a terceira, você serve conteúdo desatualizado até o TTL expirar.

A documentação oficial do recurso está em LSCache for Laravel, e é dela que vêm os nomes de header, o pacote e as opções de configuração citados aqui.

As três camadas do cache no LaravelCacheLookup no vhostServidor consulta o cacheMiddleware da aplicaçãoMarca resposta como cacheávelObserver do modelPurga a tag ao salvar
Sem a primeira camada os headers são ignorados; sem a segunda nada é guardado; sem a terceira o conteúdo envelhece até o TTL.

Ligar o CacheLookup no vhost ou no .htaccess

O módulo de cache do LiteSpeed só olha para os headers da aplicação se a busca em cache estiver habilitada para aquele contexto. Em hospedagem compartilhada com LiteSpeed, isso costuma ser feito no .htaccess da raiz pública:

<IfModule LiteSpeed>
    CacheLookup on
</IfModule>

Em LiteSpeed Enterprise ou OpenLiteSpeed com acesso ao painel de administração, a mesma diretiva existe no nível de virtual host. O bloco <IfModule LiteSpeed> é importante: em Apache puro a diretiva não existe e o arquivo quebraria.

Cuidado com a ordem no .htaccess do Laravel. O bloco acima pode ficar antes do RewriteEngine On padrão do framework; ele não interfere no rewrite. O que você não deve fazer é colocar regras de cache dentro do bloco de rewrite esperando que elas sejam avaliadas por rota, porque o controle fino vem dos headers, não do rewrite.

Confirmar com curl se o LiteSpeed está consultando o cache

Depois de salvar o arquivo, uma requisição a qualquer URL pública deve trazer o header x-litespeed-cache. Se ele não aparece nem como miss, a busca em cache não está ligada ou o servidor não é LiteSpeed:

curl -sIk https://seusite.com.br/ | grep -i 'x-litespeed\|server'

Emitir X-LiteSpeed-Cache-Control só em rotas GET públicas

O pacote oficial para Laravel é instalado via Composer e traz um middleware e um helper de tags. Segundo a documentação do LSCache for Laravel, o fluxo é instalar o pacote, publicar a configuração e registrar o middleware:

composer require litespeed/lscache-laravel
php artisan vendor:publish --provider="Litespeed\LSCache\LSCacheServiceProvider"

Sobre versões: o pacote não acompanha o ciclo de release do Laravel, então confira o que de fato entrou antes de subir. composer show litespeed/lscache-laravel mostra a versão instalada e a faixa declarada em require (é lá que está o illuminate/support aceito, e não na documentação). php artisan --version mostra o seu lado. Se a faixa não cobrir seu framework, o header é o mesmo texto: dá para abandonar o pacote e ficar com o middleware próprio mostrado abaixo, que não tem dependência nenhuma.

Do lado do servidor, o módulo de cache existe no LiteSpeed Enterprise e no OpenLiteSpeed. No OLS ele é um módulo que precisa estar carregado e com cache habilitado no contexto do vhost; sem isso o CacheLookup não tem efeito. Confirme a edição e a build com /usr/local/lsws/bin/lshttpd -v (ou o header server na resposta, em compartilhada).

O middleware traduz a configuração em um header X-LiteSpeed-Cache-Control na resposta. Se você prefere não depender do pacote, o header pode ser emitido direto por um middleware seu. O conteúdo é o mesmo:

// app/Http/Middleware/LSCachePublic.php
public function handle($request, Closure $next)
{
    $response = $next($request);

    if ($request->isMethod('GET') && $response->getStatusCode() === 200) {
        $response->headers->set('X-LiteSpeed-Cache-Control', 'public,max-age=300');
    }

    return $response;
}

Aplique esse middleware por grupo de rota, nunca global. O padrão seguro é o oposto do intuitivo: nada é cacheável até você dizer que é.

Route::middleware('lscache.public')->group(function () {
    Route::get('/', [PageController::class, 'home']);
    Route::get('/blog/{slug}', [PostController::class, 'show']);
});

Rotas que nunca podem entrar no grupo cacheável

Um segundo filtro barato evita acidente: se a sessão tem usuário autenticado, não marque como cacheável, mesmo que a rota esteja no grupo.

if (auth()->check()) {
    $response->headers->set('X-LiteSpeed-Cache-Control', 'no-cache');
    return $response;
}

Cache privado por sessão existe no LSCache e é controlado por private no mesmo header, mas ele muda o modelo de invalidação e o consumo de memória. Comece por público e anônimo. É onde está o ganho e onde o risco é menor.

Purgar por tag no Observer do model em vez de encurtar o TTL

TTL curto é um remendo. O jeito correto é marcar a resposta com tags e purgar a tag quando o dado muda.

A tag precisa sair da camada que conhece o model, e não do middleware genérico. No controller, onde o registro já está carregado:

// app/Http/Controllers/PostController.php
public function show(string $slug)
{
    $post = Post::where('slug', $slug)->firstOrFail();

    return response()
        ->view('post.show', ['post' => $post])
        ->header('X-LiteSpeed-Cache-Control', 'public,max-age=300')
        ->header('X-LiteSpeed-Tag', 'post_' . $post->id . ',blog_index');
}

Se você quiser manter a emissão no middleware, derive o identificador do route model binding em vez de supor uma variável no escopo:

// dentro do handle(), depois de $response = $next($request);
$post = $request->route('post'); // instância do model com binding, ou o parâmetro cru

if ($post instanceof \App\Models\Post) {
    $response->headers->set('X-LiteSpeed-Tag', 'post_' . $post->getKey() . ',blog_index');
}

Com rota declarada como /blog/{slug} e sem binding, $request->route('slug') devolve a string, e a tag teria que usar o slug. Escolha um dos dois e mantenha o mesmo formato no purge, porque tag com nome diferente não invalida nada.

No Observer do model, emita o purge. O header X-LiteSpeed-Purge precisa sair em uma resposta HTTP que passe pelo LiteSpeed, então o lugar natural é a própria resposta da ação administrativa que salvou o registro:

// app/Observers/PostObserver.php
public function saved(Post $post)
{
    session()->flash('lscache_purge', 'tag=post_' . $post->id . ',tag=blog_index');
}
// middleware que roda em todas as respostas do painel
if ($purge = session()->pull('lscache_purge')) {
    $response->headers->set('X-LiteSpeed-Purge', $purge);
}

Para jobs em fila e comandos Artisan não há resposta HTTP. Duas saídas: purgar por * em uma rota interna protegida que você chama ao final do job, ou aceitar o TTL como piso de atualização para conteúdo gerado em background. Diga isso em voz alta no seu README, porque é o detalhe que depois vira bug difícil.

Valor de X-LiteSpeed-Purge Efeito
* limpa todo o cache do vhost
tag=blog_index limpa só as respostas marcadas com essa tag
tag=post_42,tag=blog_index limpa as duas tags em uma única resposta

Testar miss contra hit na mesma URL usando GET, não HEAD

A verificação não depende de ferramenta nova. Duas requisições na mesma URL, olhando um header e um tempo.

URL=https://seusite.com.br/blog/meu-post

curl -sk -D - -o /dev/null "$URL" | grep -i x-litespeed-cache
curl -sk -D - -o /dev/null "$URL" | grep -i x-litespeed-cache

Use GET, não HEAD. curl -I envia HEAD, e a entrada de cache que interessa é a do GET: dependendo da configuração, HEAD pode não popular nem consultar a mesma entrada, e você fica olhando miss eterno sem motivo. Por isso -D - com -o /dev/null: faz GET de verdade, imprime os headers e descarta o corpo.

A primeira deve responder x-litespeed-cache: miss e a segunda x-litespeed-cache: hit. Se as duas dão miss, o header de cache-control não está chegando, a rota caiu fora do grupo, ou a resposta sai com Set-Cookie do cookie de sessão: por padrão o LSCache não armazena resposta que carrega Set-Cookie, e o resultado é miss permanente. Confirme com curl -sk -D - -o /dev/null "$URL" | grep -i 'set-cookie'. Se nenhuma traz o header, volte para o CacheLookup.

Para comparar tempo, use -w e meça o mesmo campo nas duas chamadas:

curl -sk -o /dev/null -w 'ttfb=%{time_starttransfer}s total=%{time_total}s\n' "$URL"

O time_starttransfer é o intervalo do início da requisição até o primeiro byte do corpo, incluindo DNS, conexão e TLS. Rode da mesma máquina, na mesma rede, várias vezes, e compare miss contra hit. Os números que você vai ver são seus, da sua conexão e do seu servidor: não existe valor de referência universal, e qualquer tempo citado em artigo serve de ilustração, não de meta.

Para isolar rede do servidor, repita de dentro da máquina contra 127.0.0.1 com --resolve:

curl -sk --resolve seusite.com.br:443:127.0.0.1 \
  -o /dev/null -w '%{time_starttransfer}\n' "$URL"
Diagnóstico quando o hit não apareceDois GET na mesma URLcurl -sk -D - -o /dev/nullNenhum header x-litespeed-cacheCacheLookup desligadoMiss nas duas chamadasVerifique Set-Cookie na respostaAinda miss, sem Set-CookieRota fora do grupo cacheávelMiss e depois hitCache de página funcionando
Rota de diagnóstico a partir de duas requisições GET na mesma URL, sempre com GET e nunca com HEAD.

Cookie de sessão em rota anônima. O Laravel envia Set-Cookie com o cookie de sessão em muitas respostas. Na configuração padrão isso não vira vazamento, vira miss eterno: o LSCache se recusa a armazenar a resposta. O vazamento aparece quando essa proteção é contornada, por exemplo com regra de cache que manda ignorar cookies, ou quando o cookie é emitido por outra camada depois do armazenamento (proxy, CDN ou edge à frente do LiteSpeed). Nos dois casos o sintoma é o mesmo: uma resposta guardada carregando sessão de outra pessoa. Nas rotas cacheáveis, mantenha o middleware StartSession fora do grupo quando a página não precisa de sessão, ou garanta que nada escreva na sessão ali.

CSRF em formulário público. Newsletter, busca e comentário em página cacheada quebram, porque o token servido pertence a outra sessão. Converta esses formulários para envio via JavaScript buscando o token em um endpoint não cacheável, ou deixe a página fora do cache.

Query string. O LSCache diferencia URLs por query string. Parâmetros de campanha multiplicam entradas de cache para o mesmo conteúdo. Vale medir se isso é problema no seu volume antes de criar regra.

Deploy. Depois de um deploy que muda template ou assets, purgue tudo. Uma rota administrativa que devolve 204 com X-LiteSpeed-Purge: *, chamada no final do pipeline, resolve.

Reversão. Se algo der errado em produção, a reversão é comentar o CacheLookup no .htaccess, ou trocar o header do middleware para no-cache e purgar com *. O efeito é imediato na próxima requisição; não há cache a esperar expirar.

Checklist de 10 itens antes de liberar em produção

  1. CacheLookup on presente dentro de <IfModule LiteSpeed>.
  2. Middleware aplicado por grupo de rota, nunca global.
  3. Apenas GET com status 200 marcados como cacheáveis.
  4. auth()->check() força no-cache.
  5. /login, /register, /admin, /cart, /checkout e /api/* fora do grupo.
  6. Nenhuma rota cacheável emite Set-Cookie.
  7. Tags emitidas na resposta e purgadas no Observer do model.
  8. curl -sk -D - -o /dev/null mostra miss seguido de hit na mesma URL.
  9. Purge total no final do deploy.
  10. Teste manual logado e deslogado na mesma URL, confirmando que o conteúdo não vaza entre os dois.

O item 10 é o que mais costuma ser pulado e o único que tem consequência séria. Faça em aba anônima, com a sessão real aberta em outra janela.

Referências

  1. Documentação oficial (litespeed) — LSCache for Laravel. Consultado em 2026-10-03.
Leia também