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.

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
- Por que o purge tem que ser o último passo do deploy
- Os três comandos de purga e quando usar cada um
- Por que `||` não detecta falha dentro de um pipe
- Como escrever o passo de purge no `.cpanel.yml`
- Como o cabeçalho `x-litespeed-cache` prova que o purge funcionou
- 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:
- arquivos no lugar (checkout,
rsync, build de assets); - migrações de banco e
wp core update-db, se houver; - qualquer regeneração de autoload/opcache;
- 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.
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:
- O WP-CLI precisa rodar como o usuário dono dos arquivos. Executar com
sudoou--allow-rootem hospedagem compartilhada tende a criar arquivos de log e cache com dono errado, e o próximo deploy quebra por permissão. - O comando depende do plugin ativo. Se o LiteSpeed Cache estiver desativado naquele site, o WP-CLI devolve erro de comando desconhecido, e isso é bom: o pipeline precisa gritar.
- Use sempre
--path=explícito. Em deploy, o diretório de trabalho raramente é oDOCUMENT_ROOT.
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
Checklist antes de colocar o script em produção
- Shebang é
#!/bin/bash, não#!/bin/sh, se você usapipefailouPIPESTATUS. set -euo pipefailno topo, exceto em laços onde você quer continuar após erro.--path=explícito em todo comandowp.- Purge na última posição, depois de arquivos e migrações.
- Nenhum
--allow-root; o deploy roda como o usuário do site. - Log do purge em arquivo, com
tee, e status capturado corretamente. - Verificação por
x-litespeed-cacheem pelo menos uma URL representativa. - Caminho e existência da sinalização por arquivo confirmados com o provedor, se você usa esse fallback.
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
- Documentação oficial (litespeed) — LSCache for WordPress: CLI | LiteSpeed. Consultado em 2026-10-05.