# 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.

> 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`.

João Rizzon · 2026-10-24 · WordPress

---

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](https://docs.litespeedtech.com/lscache/lscwp/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 `sudo` ou `--allow-root` em 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 é o `DOCUMENT_ROOT`.

```bash
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):

```bash
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.

```bash
# 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`:

```bash
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.

```bash
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.

```bash
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.

```yaml
---
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:

```bash
#!/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:

```bash
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:

```bash
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ê usa `pipefail` ou `PIPESTATUS`.
- `set -euo pipefail` no topo, exceto em laços onde você quer continuar após erro.
- `--path=` explícito em todo comando `wp`.
- 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-cache` em 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.

