# Por que a primeira visita continua lenta com LSCache ligado

Como configurar o crawler a partir do mapa gerado pelo plugin (ou de um sitemap customizado, quando você quiser controlar o conjunto), calcular Delay e Run Duration contra o teto de processos da conta, e confirmar o resultado com curl em uma URL de cauda longa.

> o MISS da primeira visita é estrutural no LSCache, porque cada URL só é armazenada depois que alguém paga a renderização. O crawler do LiteSpeed (LSCWP e server-level) percorre o mapa de URLs do site (gerado pelo plugin ou por um sitemap que você indicar) e pré-aquece essas URLs antes do visitante chegar.

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

---

## O MISS da primeira visita não é bug, é o modelo de cache

O LSCache guarda a resposta renderizada por URL. Enquanto ninguém pedir `/produto/cadeira-ergonomica-azul-p`, não existe cópia dela em cache. A primeira pessoa que chega paga PHP, paga as queries do catálogo, paga a montagem do template, e só então o LiteSpeed grava a entrada e devolve `x-litespeed-cache: miss`.

Em site de poucas dezenas de URLs isso é invisível: o tráfego preenche o cache em minutos e quase todo mundo pega `hit`. Em catálogo grande o problema inverte. Se o TTL público é de 1 semana e a URL recebe visita a cada dez dias, ela expira antes da segunda visita. O cache existe, está ligado, e ainda assim a quase totalidade dos acessos de cauda longa continua pagando renderização completa.

É por isso que "ativei o LSCache e o site continua lento" costuma ser verdade e falso ao mesmo tempo. O cache funciona. O que falta é alguém pagar a primeira renderização antes do visitante.

## O que o crawler do LiteSpeed faz, segundo a documentação

O crawler é esse "alguém". Ele percorre uma lista de URLs do site e faz requisições que o servidor atende e armazena, deixando as páginas pré-aquecidas antes do tráfego real. A [documentação oficial do LSCWP Crawler](https://docs.litespeedtech.com/lscache/lscwp/crawler/) descreve o recurso em duas camadas:

- **Server level**: o crawler precisa estar habilitado na configuração do LiteSpeed Web Server. Em hospedagem compartilhada, essa decisão é do provedor, não do plugin. Se o recurso estiver desabilitado no servidor, a aba do plugin mostra o estado e nada roda.
- **Site level (LSCWP)**: no WordPress, em `LiteSpeed Cache > Crawler`, você define a lista de URLs (o *Map*), os intervalos e as regras de execução.

A mecânica importante para quem vai operar: o crawler não é um robô que "descobre" o site navegando. Ele trabalha a partir de um mapa gerado pelo próprio plugin, que monta a lista a partir do conteúdo do site (posts, páginas, termos e demais tipos públicos). Indicar um sitemap é opcional: o campo *Custom Sitemap* serve para substituir essa geração automática por uma lista que você controla. O plugin percorre o mapa em lotes, guarda a posição e retoma de onde parou na execução seguinte.

### Por que uma URL some do aquecimento sem dar erro

O comportamento que mais confunde na primeira vez: URLs que respondem como não cacheáveis entram automaticamente na blacklist do crawler. A documentação é explícita quanto a isso. Se a página devolve cabeçalho indicando `no-cache`, o crawler marca a URL e deixa de gastar requisição com ela nas próximas passadas.

Isso é desejável. Carrinho, checkout, área logada e qualquer rota excluída do cache não têm por que consumir slot de crawl. O efeito colateral é que uma exclusão mal escrita (um padrão amplo demais em *Do Not Cache URIs*) faz a URL sumir do aquecimento sem erro visível. Antes de culpar o crawler, olhe a blacklist: ela é a lista das páginas que o seu próprio site declarou não cacheáveis.

## De onde sai a lista de URLs que o crawler percorre

A ordem de trabalho é sempre a mesma: primeiro o mapa, depois o ritmo.

### Quando o sitemap customizado ajuda e quando atrapalha

Por padrão não precisa: o mapa sai da geração automática do plugin. Informe um *Custom Sitemap* quando quiser controlar o conjunto (por exemplo, apontar o sitemap de produtos da loja em vez do índice, ou excluir seções inteiras). Lembre que, nesse caso, o crawler passa a aquecer só o que está naquele sitemap: se ele exclui produtos fora de estoque ou posts antigos, a cauda longa fica de fora.

### Inspecionar o Map antes de mexer em qualquer parâmetro

A aba `Crawler > Map` mostra a lista materializada, com o estado de cada URL. É aqui que você confere três coisas: se o total de URLs bate com o que você espera do catálogo, se as rotas que importam estão presentes, e quais entradas foram para a blacklist.

Se o mapa tem 200 URLs e o catálogo tem alguns milhares, investigue nesta ordem: sitemap customizado restritivo, tipos de post não incluídos na geração do mapa, filtros de exclusão do próprio crawler e URLs já na blacklist. O sitemap é um dos casos, não o único.

### Ajustar os tempos só depois que o mapa estiver correto

Com o mapa correto, os parâmetros de ritmo passam a ter significado. Antes disso, acelerar o crawler só aumenta carga sem aumentar cobertura.

## Threads, Delay e Run Duration: a conta de URLs por execução

Os dois parâmetros que decidem o comportamento do crawler são **Delay Between Requests** (intervalo entre requisições, em microssegundos) e **Run Duration** (quanto tempo uma execução dura antes de pausar). Eles existem porque o crawler consome os mesmos recursos que o visitante: processos PHP, memória, I/O.

A aritmética é direta, e depende de três parâmetros, não dois: **Threads** (requisições em paralelo) multiplica a taxa. A fórmula é req/s ≈ threads / delay em segundos. Com 1 thread e delay de 500.000 microssegundos (0,5 s), você faz cerca de 2 requisições por segundo; com 4 threads e o mesmo delay, cerca de 8. Em uma execução de 400 segundos, 2 req/s dão por volta de 800 URLs por rodada. A tabela abaixo assume **1 thread**: multiplique a última coluna pelo número de threads configurado. Os números são **exemplos de cálculo**, não medição: servem para você fazer a conta com os seus próprios valores.

| Delay entre requisições | Req/s aproximado | Run Duration | URLs por execução (estimativa) |
|---|---|---|---||
| 1.000.000 µs (1 s) | 1 | 300 s | ~300 |
| 500.000 µs (0,5 s) | 2 | 400 s | ~800 |
| 250.000 µs (0,25 s) | 4 | 400 s | ~1.600 |
| 100.000 µs (0,1 s) | 10 | 600 s | ~6.000 |

Essa estimativa só vale se o tempo de resposta da página for pequeno diante do delay. Quando a renderização de um produto leva 1,2 s e o delay é 0,25 s, quem dita o ritmo é a renderização, não o parâmetro.

### O limite real é o teto de processos, não o delay

Em conta compartilhada, dois tetos valem mais que a sua conta de requisições por segundo:

- **Entry processes / LSWS Child Processes**: número máximo de processos que a conta (ou o servidor) pode manter atendendo requisições. O crawler disputa esse mesmo pool com os visitantes.
- **cgroup da conta**: limites de CPU e memória aplicados ao conjunto de processos do usuário. Estourar o cgroup não gera mensagem na tela do plugin, gera throttling.

A regra prática: dimensione o crawler para usar uma fração do teto, nunca o teto. Se o visitante real e o crawler competem pelo mesmo pool, o crawler agressivo transforma pré-aquecimento em lentidão para quem está navegando agora. Se precisar escolher, delay maior e execução mais frequente é melhor que delay mínimo em rajada.

## Por que o crawler simplesmente não roda

O ponto que gera mais tempo perdido: o crawler pode ser **descartado silenciosamente**. Não há erro vermelho, não há exceção no log do PHP. Ele apenas não executa ou interrompe a passada.

Segundo a documentação do recurso, o crawler depende de estar habilitado no nível do servidor, respeita o **Server Load Limit** (acima dele, a passada para) e blacklista URLs que respondem como não cacheáveis. A tabela abaixo junta essas condições documentadas com limites que vêm da hospedagem, não da fonte citada, e estão marcados como tal:

| Sintoma | Causa provável | Onde olhar |
|---|---|---||
| Crawler desabilitado na interface | Recurso desligado no nível do servidor (documentado) | Configuração do LSWS / provedor |
| Passadas param em horário de pico | Server Load Limit excedido (documentado) | Carga do servidor no momento |
| URL nunca aquece | URL na blacklist por responder no-cache (documentado) | `Crawler > Map` |
| Execução termina logo após iniciar | Teto de processos da conta atingido (contexto de hospedagem compartilhada, não da doc) | Entry processes / LSWS Child Processes, com o provedor |
| Passada lenta sem erro aparente | Throttling de CPU ou memória no cgroup da conta (contexto de hospedagem compartilhada, não da doc) | Painel da conta / provedor |
| Mapa menor que o catálogo | Sitemap customizado restritivo, tipo de post fora da geração do mapa ou exclusão no crawler | Opções do crawler |

Os dois primeiros limites, child processes e carga do servidor, são proteção, não defeito: o crawler é a carga sacrificável quando o servidor está apertado. Em host compartilhado, aceite isso como projeto. Se o crawler do seu site só completa o mapa de madrugada, está funcionando como desenhado.

Uma consequência prática: não espere que o crawler termine o mapa inteiro em uma execução. Ele guarda a posição. Catálogo grande é aquecido ao longo de várias rodadas, e a métrica de sucesso é a posição avançando entre execuções, não um ciclo completo.

## Confirmar com curl que o miss virou hit

Medir isso é simples e não depende de nenhuma ferramenta do plugin. Escolha uma URL de **cauda longa** de verdade: um produto que ninguém acessa há semanas, não a home.

Primeiro, confirme que ela está fria:

```bash
curl -sSI -o /dev/null \
  -w 'cache=%header{x-litespeed-cache} ttfb=%{time_starttransfer}\n' \
  https://exemplo.com.br/produto/url-de-cauda-longa/
```

O `-w` com `%header{...}` requer curl 7.84 ou superior (verifique com `curl --version`). Em versão mais antiga, use a forma sem formatação e leia o cabeçalho direto:

```bash
curl -sSI https://exemplo.com.br/produto/url-de-cauda-longa/ | grep -i x-litespeed-cache
curl -sS -o /dev/null -w 'ttfb=%{time_starttransfer}\n' https://exemplo.com.br/produto/url-de-cauda-longa/
```

Dois cuidados para o número não mentir:

- `time_starttransfer` inclui DNS, TCP e TLS. Para comparar só a aplicação, rode a partir da mesma máquina e na mesma rede nos dois momentos, ou acrescente `%{time_connect}` e `%{time_appconnect}` ao `-w` e subtraia.
- `curl -I` faz HEAD. Algumas aplicações tratam HEAD de forma diferente de GET. Se o resultado parecer estranho, repita com `curl -sS -D - -o /dev/null` para ver os cabeçalhos de uma requisição GET real.

Depois, deixe o crawler passar pelo mapa e repita o mesmo comando na mesma URL. O que você quer ver: `x-litespeed-cache` saindo de `miss` para `hit` e `time_starttransfer` caindo para a faixa de entrega estática. A Napoleon não mediu esse delta em laboratório, então não publique nem assuma um valor "esperado": meça no seu site, com o seu tema e o seu banco, porque o ganho depende inteiramente de quanto a sua renderização custava.

Para varrer uma lista em vez de uma URL, um loop simples basta:

```bash
while read -r url; do
  st=$(curl -sSI "$url" | tr -d '\r' | awk 'tolower($1)=="x-litespeed-cache:"{print $2}')
  printf '%s %s\n' "${st:-sem-header}" "$url"
done < urls.txt
```

Guarde a saída antes e depois. Essa é a sua evidência, e ela vale mais que a barra de progresso da interface.

## O que o crawler não resolve

Seja honesto com o escopo antes de investir tempo nisso.

- **Página não cacheável continua não cacheável.** Se a rota responde `no-cache`, o crawler vai blacklistar e acabou. O ganho tem que vir de otimizar a renderização.
- **TTL curto demais anula o esforço.** Se o cache expira em uma hora e o crawler leva três horas para dar uma volta no mapa, você aquece páginas que já esfriaram. Ajuste TTL e ritmo juntos.
- **Conteúdo variável por usuário** (preço por cliente, estoque por região) precisa de ESI ou de exclusão, não de crawl.
- **Servidor no limite** não ganha nada com crawler: ele será descartado justamente quando mais precisaria rodar. Nesse caso o problema é capacidade ou consulta lenta, e olhar o log de slow query resolve mais que qualquer parâmetro do plugin.

O crawler é bom em uma coisa específica: transferir o custo da primeira renderização do visitante para um horário em que o servidor está ocioso. Quando o diagnóstico é esse, ele é a ferramenta certa. Quando não é, ele só adiciona carga.

