blog
WordPress

Purgar o cache do LiteSpeed por CLI sem falha silenciosa no deploy

Onde o purge entra no script, por que o `||` depois de um pipe não detecta a falha e como provar que o cache realmente foi descartado.

JR · · 7 min de leitura · 2 tabelas · 10 blocos de código

Resposta curta: use `wp litespeed-purge all` como último passo do deploy (ou `wp litespeed-purge url <URL>` para uma página), com `set -euo pipefail` para que a falha apareça no pipeline, e confirme com duas requisições: `x-litespeed-cache: miss` seguido de `hit`.

Neste artigo
  1. Por que o purge tem que ser o último passo do deploy
  2. Os três comandos de purga e quando usar cada um
  3. Por que `||` não detecta falha dentro de um pipe
  4. Como escrever o passo de purge no `.cpanel.yml`
  5. Como o cabeçalho `x-litespeed-cache` prova que o purge funcionou
  6. Checklist antes de colocar o script em produção

Deploy que troca CSS, template ou um functions.php e não limpa cache entrega HTML antigo com asset novo. O inverso também acontece: você purga antes de o rsync/git terminar e a primeira visita reaquece o cache com a versão velha. A ordem importa, e o comando precisa falhar de forma visível no pipeline quando falhar.

Por que o purge tem que ser o último passo do deploy

O cache do LiteSpeed é preenchido por demanda. Qualquer requisição não logada a uma URL cacheável gera uma entrada nova com o HTML que o PHP produziu naquele instante. Por isso o purge tem que ser o último passo do deploy, depois de:

  1. arquivos no lugar (checkout, rsync, build de assets);
  2. migrações de banco e wp core update-db, se houver;
  3. qualquer regeneração de autoload/opcache;
  4. só então o purge.

Se você purgar antes das migrações, a janela entre purge e fim da migração é preenchida com páginas renderizadas contra o schema antigo, e elas ficam cacheadas. Em deploy pelo .cpanel.yml, isso significa que o purge vai na última linha de tasks, depois do /bin/cp ou do rsync que copia o repositório para public_html.

O inverso (purgar duas vezes, antes e depois) é barato e resolve o caso de build demorado. Purge não é operação destrutiva: ele só obriga o próximo acesso a renderizar.

Ordem correta das etapas do deployArquivoscheckout, rsync, build de assetsBancomigrações e wp core update-dbOpcacheautoload e opcache regeneradosPurgeúltimo passo, nunca antes
Purgar antes das migrações cacheia HTML renderizado contra o schema antigo.

Os três comandos de purga e quando usar cada um

A documentação oficial do LSCache for WordPress expõe os comandos de purga pelo WP-CLI (LSCache for WordPress: CLI).

Objetivo Comando Quando usar no deploy
Limpar tudo do site wp litespeed-purge all Deploy que mexe em tema, plugin, core ou assets globais
Limpar uma URL específica wp litespeed-purge url <URL> Publicação pontual de uma página ou post
Sinalização por arquivo (não documentada no CLI oficial) touch <cache_root>/.purge_all Ambiente onde o WP-CLI não está disponível e o provedor confirma o recurso

Algumas restrições práticas que valem antes de colar isso no script:

WP_PATH="$HOME/public_html"
wp --path="$WP_PATH" litespeed-purge all

Para uma URL só, passe a URL completa, com esquema e host, igual à que o visitante acessa (inclusive barra final, se o permalink tiver):

wp --path="$WP_PATH" litespeed-purge url "https://exemplo.com.br/blog/post-novo/"

O fallback por arquivo de sinalização, e por que ele não confirma nada

Quando não há WP-CLI (ou o PHP de CLI está bloqueado), sobra tentar sinalizar o purge pelo sistema de arquivos. Alguns ambientes LiteSpeed suportam essa sinalização por um arquivo no diretório raiz do cache, mas isso não está na documentação do LSCWP CLI citada acima, e o comportamento depende da configuração do servidor. Trate como recurso a confirmar: pergunte ao provedor se existe, qual é o caminho do cache root e qual o nome do arquivo esperado. Enquanto não houver essa confirmação, não coloque no script como se fosse purge garantido.

# só use se o provedor confirmar o recurso e o caminho
LSCACHE_ROOT="/home/usuario/lscache"
LSCACHE_FLAG=".purge_all"                 # nome informado pelo provedor
[ -d "$LSCACHE_ROOT" ] && touch "$LSCACHE_ROOT/$LSCACHE_FLAG"

Esse fallback é um sinal, não uma confirmação. Ele não retorna erro útil se o diretório estiver errado: o touch cria o arquivo em qualquer pasta existente e sai com status 0. Por isso, se você depende dele, a verificação por cabeçalho HTTP (última seção) deixa de ser opcional: é ela que prova que algo aconteceu.

Por que `||` não detecta falha dentro de um pipe

O erro mais comum em script de deploy não é o comando de purge: é achar que ele falhou de forma detectável quando não falhou.

Em Bash, o status de saída de um pipeline é o do último comando. Então isto nunca dispara o echo:

wp litespeed-purge all | tee -a deploy.log || echo "falhou"

Se o wp sair com 1 e o tee sair com 0, o pipeline sai com 0. O || só enxerga o tee. Há duas saídas corretas.

`set -o pipefail` faz a falha do purge abortar o script

Com pipefail ativo, o pipeline retorna o status do último comando que falhou, ou 0 se todos tiverem sucesso.

set -euo pipefail

wp --path="$WP_PATH" litespeed-purge all | tee -a "$HOME/deploy.log"

Combinado com set -e, o script aborta ali. set -u evita o clássico rm -rf "$DIR/" com DIR vazio. Esses três juntos são o mínimo para um script de publicação.

`PIPESTATUS` quando o deploy precisa continuar depois do erro

Se o deploy não pode abortar (quer registrar a falha de purge e continuar), use o array PIPESTATUS, que guarda o status de cada elemento do pipe. Copie o array na linha imediatamente seguinte: qualquer comando no meio o sobrescreve.

wp --path="$WP_PATH" litespeed-purge all | tee -a "$HOME/deploy.log"
status=( "${PIPESTATUS[@]}" )

if [ "${status[0]}" -ne 0 ]; then
  echo "purge falhou (exit ${status[0]})" >&2
  PURGE_OK=0
fi

Detalhe de portabilidade: PIPESTATUS é do Bash. Em sh/dash (e é isso que roda quando o shebang é #!/bin/sh) ele não existe, e set -o pipefail pode não existir. Se o script começa com #!/bin/sh, troque para #!/bin/bash antes de contar com qualquer um dos dois.

Como escrever o passo de purge no `.cpanel.yml`

O deploy por Git do cPanel executa as linhas de tasks em sequência. Cada linha é um comando; não há set -e global herdado, então o encadeamento precisa estar explícito.

---
deployment:
  tasks:
    - export DEPLOYPATH=/home/usuario/public_html/
    - /bin/cp -R wp-content/themes/meutema $DEPLOYPATH/wp-content/themes/
    - /bin/bash -lc 'set -euo pipefail; wp --path=/home/usuario/public_html litespeed-purge all'

Duas armadilhas aqui. A primeira: variáveis definidas em uma task não sobrevivem necessariamente para a seguinte em todo ambiente, e dentro de aspas simples a expansão fica a cargo do shell de dentro, que não herdou nada. Por isso o caminho aparece literal no bash -lc acima; se preferir variável, reexporte na mesma task (/bin/bash -lc 'set -euo pipefail; DEPLOYPATH=/home/usuario/public_html; wp --path="$DEPLOYPATH" litespeed-purge all'). A segunda: o WP-CLI precisa estar no PATH do usuário. O -l no bash -lc carrega o perfil de login e costuma resolver; se não resolver, chame o binário pelo caminho absoluto (por exemplo, ~/bin/wp).

Para deploys que publicam uma URL só, vale um script que recebe a lista e purga uma a uma, somando as falhas:

#!/bin/bash
set -uo pipefail
WP_PATH="$HOME/public_html"
fails=0

for url in "$@"; do
  if ! wp --path="$WP_PATH" litespeed-purge url "$url"; then
    echo "purge falhou: $url" >&2
    fails=$((fails + 1))
  fi
done

exit $(( fails > 0 ))

Não use set -e nesse laço: ele abortaria na primeira URL com erro e você perderia as demais. O controle de falha fica no if e no contador.

Como o cabeçalho `x-litespeed-cache` prova que o purge funcionou

Saída 0 do comando significa que o pedido de purga foi aceito, não que a entrada sumiu. A prova está no cabeçalho de resposta.

A sequência esperada depois de um purge, na mesma URL, com duas requisições seguidas:

URL="https://exemplo.com.br/blog/post-novo/"

curl -sS -o /dev/null -D - "$URL" | grep -i '^x-litespeed-cache'
# x-litespeed-cache: miss

curl -sS -o /dev/null -D - "$URL" | grep -i '^x-litespeed-cache'
# x-litespeed-cache: hit
Valor do cabeçalho Leitura
miss Não havia entrada em cache; o PHP renderizou agora
hit Resposta servida do cache
cabeçalho ausente A URL não é cacheável (sessão, exclusão, ou cache desligado)

Se a primeira resposta já vier hit, o purge não alcançou aquela URL. Causas prováveis, nessa ordem: a URL do comando difere da real (http vs https, www, barra final), o purge rodou antes da cópia dos arquivos, ou você está olhando para uma CDN à frente do LiteSpeed, que tem o cache dela.

Dois cuidados ao automatizar essa verificação. Cookie de sessão derruba o cache: use curl limpo, sem -b/-c. E não encadeie as duas chamadas sem pausa se o TTFB do site for alto; um sleep 1 entre elas evita medir uma corrida.

Para incluir isso no pipeline como gate de verdade:

first=$(curl -sS -o /dev/null -D - "$URL" | awk 'tolower($1)=="x-litespeed-cache:"{print tolower($2)}')
if [ "$first" != "miss" ]; then
  echo "esperava miss, veio: ${first:-ausente}" >&2
  exit 1
fi
Verificação do purge pelo cabeçalho de respostaPurge sai com status 0pedido aceito, nada provado aindaPrimeiro curl sem cookiegrep em x-litespeed-cacheVeio misspurge alcançou a URLVeio hitURL divergente ou purge cedo demaisCabeçalho ausenteURL não cacheável ou CDN na frente
Gate de verificação: só o cabeçalho prova que a entrada saiu do cache.

Checklist antes de colocar o script em produção

Se a confirmação por cabeçalho falhar de forma consistente mesmo com o comando saindo 0, o problema quase nunca é o script: é camada de cache adicional (CDN, proxy reverso, plugin de cache em PHP rodando junto) ou URL canônica diferente da testada. Isole desligando a CDN em modo desenvolvimento e repita as duas requisições.

Referências

  1. Documentação oficial (litespeed) — LSCache for WordPress: CLI | LiteSpeed. Consultado em 2026-10-05.
Leia também