Pular para o conteúdo

Implantando um site Blockstudio

Para os blocos, basta copiar a pasta do tema para um servidor: Blockstudio os encontra no sistema de arquivos, e os caches detectam sozinhos as alterações nas entradas. Um site real tem mais partes móveis. As páginas baseadas em arquivos só chegam ao banco de dados quando você as sincroniza. Uma pré-renderização estática continua exibindo o HTML de ontem até que algo o substitua. Um CDN na frente continua exibindo o que estiver em cache.

Este guia prepara uma implantação para um tema chamado acme que inclui Blockstudio por meio de Composer. Ele explica o que é executado na CI, o que é executado no servidor depois que os arquivos chegam, como ler o relatório de sincronização de páginas e quais comandos wp bs devem fazer parte de uma versão.

A versão em uma imagem

  1. Compilar. A CI instala as dependências de produção Composer.
  2. Enviar. O tema, incluindo vendor/, chega ao servidor.
  3. Sincronizar páginas. wp bs pages sync alinha as páginas com os arquivos e imprime um relatório.
  4. Atualizar o cache de origem. O HTML armazenado é limpo quando as páginas mudam e, em seguida, aquecido novamente.
  5. Limpar o CDN. Por último, para que a borda recarregue os dados de uma origem atualizada.

As etapas 3 e 4 precisam de WP-CLI no servidor. O script abaixo também usa jq para ler JSON.

Etapa 1: Composer na CI

Inclua Blockstudio no tema e confirme composer.lock, para que a CI instale a versão exata que você testou:

JSON
{
  "require": {
    "blockstudio/blockstudio": "^7.0"
  }
}
PHP
<?php
require_once __DIR__ . '/vendor/autoload.php';

Na CI, instale sem os pacotes de desenvolvimento:

Shell
composer install --no-dev --optimize-autoloader --no-interaction --prefer-dist

Blockstudio inicializa a partir do autoloader, e suas dependências de execução são incluídas e têm os nomes isolados dentro do pacote. Quando é carregado de um diretório vendor/, seu atualizador GitHub integrado fica desativado; assim, Composer continua sendo a única forma de alterar a versão.

Etapa 2: Decida o que precisa ser gravável

Blockstudio grava arquivos gerados durante a execução. Saiba onde antes que uma implantação substitua ou bloqueie um diretório:

  • Os caches de execução ficam em wp-content/blockstudio/cache/ por padrão. Se preferir, aponte cache.path para um volume gravável dedicado. Alterar o caminho inicia com o cache vazio.
  • Os recursos compilados dos blocos são gravados, por padrão, em uma pasta _dist ao lado de cada bloco. Se o diretório da versão for somente leitura ou for substituído a cada implantação, defina assets.output como cache para que sejam gravados no diretório de cache:
JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "assets": {
    "output": "cache"
  }
}

Não é preciso limpar os caches durante a implantação. Cada entrada de cache é indexada pelas entradas que a geram, incluindo arquivos de blocos, configurações, o tema e os plugins ativos, além das versões de WordPress, PHP e Blockstudio. Assim, uma versão que os altera recebe novas chaves. Em production e staging, Blockstudio confia por 20 segundos em um instantâneo validado do monitoramento antes de verificar os arquivos novamente; por isso, pode levar até 20 segundos para detectar uma alteração. O filtro blockstudio/cache/watch_debounce altera esse intervalo.

Etapa 3: Sincronizar páginas

As páginas só são alteradas por meio de uma sincronização explícita. As solicitações do frontend, do admin, do Ajax, de REST, de cron e as solicitações WP-CLI comuns nunca localizam fontes de páginas nem gravam páginas no banco. A implantação precisa solicitar a sincronização:

Shell
wp bs pages sync --format=json

Em um site cujo tema tem duas páginas, about e contact, a primeira execução as cria:

JSON
{
    "discovered": 2,
    "created": 2,
    "updated": 0,
    "unchanged": 0,
    "removed": 0,
    "failed": 0,
    "fullReconciliation": true,
    "sourceId": "f88baddfd5a1deb94eb8c9bbeca10d5a0d47a72f16b50efdb25a7127945af7dd",
    "sourceIdentity": {
        "commit": "",
        "dirtyHash": "",
        "inventoryHash": "aaec5b9dd13d74eea872117b6167caa7a5d5c1abad9572fba22f6ddf6340adfe",
        "engineFingerprint": "2c442442bb49f91e7187560e6db8f3475caa0b62b47708cab95b6ff13aba4469",
        "hash": "f88baddfd5a1deb94eb8c9bbeca10d5a0d47a72f16b50efdb25a7127945af7dd"
    },
    "pages": {
        "about": {
            "status": "created",
            "postId": 545,
            "locked": false
        },
        "contact": {
            "status": "created",
            "postId": 546,
            "locked": false
        }
    },
    "errors": []
}

Como interpretar o resultado:

  • created, updated, unchanged, removed e failed contabilizam páginas. Se a impressão digital da fonte de uma página não mudou, nenhuma publicação nem metadado da publicação é gravado, e nenhum gancho de atualização é acionado.
  • Cada execução compara o inventário completo de páginas. fullReconciliation informa se a execução conta como uma sincronização completa: true na primeira execução, com --full ou quando o próprio mecanismo de sincronização mudou; e false quando existe uma identidade de uma sincronização anterior bem-sucedida. Ferramentas subsequentes podem usar esse valor para decidir se devem reconstruir tudo.
  • sourceIdentity é uma impressão digital determinística do inventário de páginas e do mecanismo de sincronização. O comando a armazena após uma execução bem-sucedida.

Sem --format=json, o comando imprime uma linha de resumo e uma linha de sucesso. Em um registro de CI, que não é um terminal, a linha usa tabulações como separadores:

Text
discovered	created	updated	unchanged	removed	failed	source_id
2	0	1	1	0	0	7bd575b4ee6c0a948f439dd83ce5fa403f8113c9406c3b13b6ade2f2b19f3c2c
Success: File-backed pages synchronized.

Essa execução ocorreu após uma edição em about/index.php: uma página foi atualizada e outra permaneceu inalterada.

Quando a sincronização falha

O comando termina com o status 1 quando a descoberta ou a sincronização informa um erro, fazendo a etapa da CI falhar. O relatório JSON ainda é impresso, portanto, salve-o no registro. Um page.json malformado aparece assim:

JSON
{
    "discovered": 0,
    ...
    "failed": 1,
    ...
    "pages": [],
    "errors": [
        {
            "code": "invalid_page_json",
            "message": "Invalid page.json file.",
            "context": {
                "path": ".../wp-content/themes/acme/pages/pricing/page.json"
            }
        }
    ]
}

As páginas gerenciadas cujas fontes desapareceram só são removidas após uma execução terminar sem erros, para que uma versão cuja sincronização falhou não apague páginas ativas. Por padrão, as páginas removidas vão para a lixeira; o filtro blockstudio/pages/orphan_action pode retornar trash, delete ou keep.

Execute em cada implantação

Execute a sincronização mesmo quando nenhuma página mudar. Se você implanta em diretórios de versões e troca um link simbólico, uma página inalterada continua apontando para os caminhos de modelo e layout da versão anterior até que a próxima sincronização os atualize. Essa atualização não altera post_content nem a data de modificação.

--authoritative e --full

Uma sincronização normal preserva o conteúdo que os editores alteraram dentro de blocos identificados por chave. --authoritative substitui o conteúdo gerenciado pelos arquivos e pode remover um bloqueio do Page Sync. Use essa opção quando os arquivos devem prevalecer: ao redefinir um site de preparação ou em um site cujas páginas baseadas em arquivos não são editadas por ninguém no editor. Não a inclua em todas as implantações de um site com editores ativos.

--full marca a execução como uma sincronização completa, independentemente da identidade armazenada. A comparação de páginas já é completa em todas as execuções, então a opção altera fullReconciliation no relatório, não quais páginas são verificadas. Use-a quando uma etapa posterior depender desse valor para fazer uma reconstrução completa.

Ferramentas escritas em PHP podem chamar Blockstudio\Pages::reconcile() diretamente. O resultado é o mesmo relatório, mas a identidade não é armazenada: chame Blockstudio\Pages::store_successful_source_identity() depois que o restante da versão, como um artefato estático ativado, tiver sido verificado.

Etapa 4: Atualizar o cache estático

Se o site usa pré-renderização estática no modo padrão signature, as páginas atualizadas a partir de WP-CLI não limpam o HTML armazenado por conta própria. Leia o relatório e limpe o cache quando algo mudar; em seguida, aqueça-o:

Shell
#!/usr/bin/env bash
set -euo pipefail

cd /var/www/example.com
report=$(mktemp)

# 1. Reconcile file-backed pages and keep the report.
if ! wp bs pages sync --format=json > "$report"; then
  cat "$report"
  exit 1
fi
jq '{discovered, created, updated, unchanged, removed}' "$report"

# 2. Drop stored HTML when page content changed.
changed=$(jq '.created + .updated + .removed' "$report")
if [ "$changed" -gt 0 ]; then
  wp bs prerender purge
fi

# 3. Re-warm in bounded passes until a pass warms nothing.
for _ in $(seq 1 50); do
  warmed=$(wp bs prerender warm | jq '.warmed')
  [ "$warmed" -gt 0 ] || break
done

wp bs prerender status | jq '{files, queue}'

Cada execução de wp bs prerender warm enfileira URLs públicas desatualizadas, renderiza até warm.concurrency delas e imprime um resumo. Nesta execução, quatro das seis URLs enfileiradas foram assumidas, mas as quatro falharam ao renderizar:

JSON
{"queued":6,"processed":4,"warmed":0,"skipped":0,"failed":4}

Um URL cuja renderização falha continua desatualizado e é enfileirado novamente na próxima execução. Por isso, o loop para na primeira execução que não aquece nenhum URL, em vez de esperar a fila ficar vazia. O que restar será processado pelo aquecedor agendado ou na próxima visita anônima.

No modo graph, o aquecedor por URL fica desativado e warm não enfileira nada. Sites Graph substituem as etapas 2 e 3 por sua própria compilação, que renderiza os URLs afetados e ativa o resultado de forma atômica. Consulte modos de assinatura e Graph.

Etapa 5: O fluxo de trabalho da CI

O fluxo de trabalho abaixo é um exemplo de GitHub Actions. A estrutura se aplica a qualquer sistema de CI: compilar, enviar, executar o script no servidor e limpar o CDN.

YAML
name: Deploy

on:
  push:
    branches: [main]

concurrency:
  group: deploy-production
  cancel-in-progress: false

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v4

      - uses: shivammathur/setup-php@v2
        with:
          php-version: "8.2"
          tools: composer:v2

      - name: Install production dependencies
        run: composer install --no-dev --optimize-autoloader --no-interaction --prefer-dist

      - name: Configure SSH
        run: |
          mkdir -p ~/.ssh
          echo "${{ secrets.DEPLOY_KEY }}" > ~/.ssh/id_ed25519
          chmod 600 ~/.ssh/id_ed25519
          ssh-keyscan example.com >> ~/.ssh/known_hosts

      - name: Upload the theme
        run: |
          rsync -az --delete --exclude ".git" --exclude ".github" \
            ./ deploy@example.com:/var/www/example.com/wp-content/themes/acme/

      - name: Sync pages and refresh the static cache
        run: ssh deploy@example.com 'bash -s' < scripts/post-deploy.sh

      - name: Purge the CDN
        run: curl -fsS -X POST "${{ secrets.CDN_PURGE_URL }}"

concurrency com cancel-in-progress: false enfileira um segundo envio atrás de uma implantação em andamento, em vez de cancelá-la no meio de uma sincronização. O PHP 8.2 é o mínimo exigido por Blockstudio. Substitua a última etapa pela API de limpeza do CDN.

Comandos de manutenção

Eles não fazem parte de todas as versões, mas devem constar no manual de implantação.

Esvaziar a fila de bloqueios legados. Versões anteriores a 7.6.14 deixavam um arquivo .build.lock para cada alteração de conteúdo. Após a atualização, WP-Cron os remove em lotes limitados. Para verificar e esvaziar a fila de uma só vez:

Shell
wp bs cache status
wp bs cache cleanup
Text
0 legacy build lock(s) across 0 cache namespace(s).
Next cleanup batch in 0 second(s).

cleanup mantém para a próxima execução os bloqueios com mais de uma hora ou que ainda estejam em uso por uma solicitação em andamento. Nunca exclua arquivos de bloqueio manualmente enquanto o site estiver atendendo tráfego.

Limpar o cache de execução. wp bs cache clear limpa tudo para o site atual, e wp bs cache clear --scope=runtime limpa um escopo em todos os espaços de nomes. A próxima solicitação reconstrói o cache do zero; portanto, execute esse comando em períodos de pouco tráfego e somente quando houver um motivo: alterações nas entradas já renovam as chaves.

Remover Blockstudio. Uma instalação Composer não tem um gancho de desativação de plugin; por isso, quando o pacote é removido, nenhum processo cancela os eventos cron nem remove o complemento de atendimento antecipado. Execute isto antes de remover a dependência:

Shell
wp bs teardown

Ele remove os eventos cron e o estado de pré-renderização estática pertencentes a esta instalação, deixa intactos os complementos e arquivos de configuração de terceiros e permite uma reativação posterior sem resíduos.

Próximas etapas