Distribuire un sito Blockstudio
Per i blocchi basta copiare una cartella del tema sul server: Blockstudio li rileva dal filesystem e le sue cache rilevano autonomamente le modifiche agli input. Un sito reale ha più componenti. Le pagine basate su file raggiungono il database solo quando le sincronizzate. Una prerenderizzazione statica continua a servire il HTML di ieri finché non viene sostituito. Una CDN davanti al sito continua a servire ciò che ha memorizzato nella cache.
Questa guida crea una distribuzione per un tema chiamato acme che include Blockstudio tramite Composer. Spiega cosa viene eseguito nella CI e sul server dopo il trasferimento dei file, come leggere il report di sincronizzazione delle pagine e quali comandi wp bs includere in un rilascio.
Il rilascio in un’immagine
- Build. La CI installa le dipendenze di produzione Composer.
- Caricamento. Il tema, incluso
vendor/, viene caricato sul server. - Sincronizzazione delle pagine.
wp bs pages syncallinea i post delle pagine ai file e stampa un report. - Aggiornamento della cache di origine. La HTML memorizzata viene eliminata quando le pagine sono cambiate, quindi la cache viene riscaldata.
- Eliminazione della CDN. Per ultima, così il nodo edge la riempie di nuovo da un’origine aggiornata.
I passaggi 3 e 4 richiedono WP-CLI sul server. Lo script qui sotto usa anche jq per
leggere JSON.
Passaggio 1: Composer nella CI
Includete Blockstudio nel tema e sottoponete composer.lock al commit, così la CI installa la
versione esatta che avete testato:
{
"require": {
"blockstudio/blockstudio": "^7.0"
}
}
<?php
require_once __DIR__ . '/vendor/autoload.php';
Nella CI, installate senza i pacchetti di sviluppo:
composer install --no-dev --optimize-autoloader --no-interaction --prefer-dist
Blockstudio si avvia tramite l’autoloader e include le proprie dipendenze di runtime,
bundle e con namespace all’interno del pacchetto. Quando viene caricato da una directory vendor/,
il suo updater GitHub integrato è disabilitato, quindi Composer resta l’unico
modo per cambiare versione.
Passaggio 2: decidere quali directory devono essere scrivibili
Blockstudio scrive file generati durante l’esecuzione. Prima di un deploy che sostituisca o blocchi una directory, verificate dove:
- Le cache di runtime si trovano per impostazione predefinita in
wp-content/blockstudio/cache/. Se preferite, impostatecache.pathsu un volume scrivibile dedicato. Cambiare percorso significa ripartire da una cache vuota. - Gli asset dei blocchi compilati vengono scritti per impostazione predefinita in una cartella
_distaccanto a ciascun blocco. Se la directory della release è di sola lettura o viene sostituita a ogni deploy, impostateassets.outputsucacheper scriverli nella directory della cache invece:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"assets": {
"output": "cache"
}
}
Non è necessario svuotare le cache durante il deploy. Ogni voce della cache è indicizzata in base ai propri input, inclusi i file dei blocchi, le impostazioni, il tema e i plugin attivi e le versioni di WordPress, PHP e Blockstudio, quindi una release che li modifica riceve nuove chiavi. In production e staging, Blockstudio si affida per 20 secondi a uno snapshot di monitoraggio convalidato prima di controllare di nuovo i file, perciò una modifica potrebbe essere rilevata con un ritardo massimo di 20 secondi. Il filtro blockstudio/cache/watch_debounce modifica questo intervallo.
Passaggio 3: sincronizzare le pagine
I post delle pagine cambiano solo tramite una sincronizzazione esplicita. Le richieste del frontend, dell’area di amministrazione, Ajax, REST, cron e le normali richieste WP-CLI non individuano le origini delle pagine né scrivono i relativi post. Il deploy deve eseguire:
wp bs pages sync --format=json
Su un sito il cui tema contiene due pagine, about e contact, la prima esecuzione le crea:
{
"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": []
}
Come leggere il risultato:
created,updated,unchanged,removedefailedindicano il numero di pagine. Se l’impronta digitale dell’origine di una pagina non è cambiata, non vengono scritti né il post né i metadati del post e non vengono eseguiti hook di aggiornamento.- Ogni esecuzione confronta l’inventario completo delle pagine.
fullReconciliationindica se l’esecuzione conta come sincronizzazione completa:truealla prima esecuzione, con--fullo quando cambia il motore di sincronizzazione;falsequando esiste un’identità proveniente da una sincronizzazione precedente riuscita. Gli strumenti a valle possono usarlo per decidere se ricostruire tutto. sourceIdentityè un’impronta digitale deterministica dell’inventario delle pagine e del motore di sincronizzazione. Il comando la memorizza al termine di un’esecuzione riuscita.
Senza --format=json, il comando stampa una riga di riepilogo e una riga di conferma. Nei log della CI, che non è un terminale, la riga usa le tabulazioni come separatori:
discovered created updated unchanged removed failed source_id
2 0 1 1 0 0 7bd575b4ee6c0a948f439dd83ce5fa403f8113c9406c3b13b6ade2f2b19f3c2c
Success: File-backed pages synchronized.
Questa esecuzione è avvenuta dopo una modifica a about/index.php: una pagina è stata aggiornata, una è rimasta invariata.
Quando la sincronizzazione non riesce
Il comando termina con stato 1 quando l’individuazione o la sincronizzazione segnala un errore, facendo fallire il passaggio della CI. Il report JSON viene comunque stampato, quindi registratelo.
Un page.json non valido appare così:
{
"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"
}
}
]
}
Le pagine gestite le cui origini sono scomparse vengono eliminate solo dopo un’esecuzione conclusa senza errori, così una release la cui sincronizzazione non riesce non cancella le pagine attive. Per impostazione predefinita, le pagine rimosse vengono spostate nel cestino; il filtro blockstudio/pages/orphan_action può restituire trash, delete o keep.
Eseguirlo a ogni deploy
Eseguite la sincronizzazione anche se nessuna pagina è cambiata. Se effettuate il deploy in directory di release e cambiate un collegamento simbolico, una pagina invariata continua a puntare ai percorsi dei template e del layout della release precedente finché la sincronizzazione successiva non li aggiorna. Questo aggiornamento non modifica post_content né la data di modifica.
--authoritative e --full
Una sincronizzazione normale conserva i contenuti modificati dagli editor nei blocchi con chiavi. --authoritative sostituisce invece i contenuti gestiti con quelli dei file e potrebbe rimuovere un blocco di Page Sync. Usatelo quando devono prevalere i file, ad esempio per ripristinare un sito di staging o un sito in cui nessuno modifica nell’editor le pagine basate su file.
Non inseritelo in ogni deploy di un sito con editor attivi.
--full contrassegna l’esecuzione come sincronizzazione completa, indipendentemente dall’identità memorizzata. Il confronto delle pagine è già completo a ogni esecuzione, quindi il flag modifica fullReconciliation nel report, non le pagine controllate. Passatelo quando un passaggio successivo usa quel valore per avviare una ricostruzione completa.
Gli strumenti scritti in PHP possono richiamare direttamente Blockstudio\Pages::reconcile().
Restituisce lo stesso report, ma non memorizza l’identità: chiamate Blockstudio\Pages::store_successful_source_identity() dopo aver verificato il resto della release, ad esempio l’attivazione di un artefatto statico.
Passaggio 4: aggiornare la cache statica
Se il sito usa prerendering statico nella modalità predefinita signature, i post delle pagine aggiornati da WP-CLI non eliminano autonomamente la HTML memorizzata. Leggete il report ed eliminate la cache se è cambiato qualcosa, quindi riscaldatela:
#!/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}'
A ogni esecuzione di wp bs prerender warm vengono accodati gli URL pubblici non aggiornati, ne vengono elaborati fino a warm.concurrency e viene stampato un riepilogo. In questa esecuzione sono stati elaborati quattro dei sei URL in coda e tutti e quattro non sono stati renderizzati:
{"queued":6,"processed":4,"warmed":0,"skipped":0,"failed":4}
Un URL che non viene renderizzato rimane obsoleto e viene accodato di nuovo all’esecuzione successiva. Per questo il ciclo si interrompe alla prima esecuzione che non aggiorna nulla, invece di attendere che la coda si svuoti. Gli URL rimanenti verranno elaborati dal processo pianificato di aggiornamento della cache o dalla prossima visita anonima.
In modalità graph l’aggiornamento della cache per URL è disattivato e warm non accoda nulla. I siti graph sostituiscono i passaggi 2 e 3 con una propria build, che renderizza gli URL interessati e attiva il risultato in modo atomico. Consultate modalità firma e graph.
Passaggio 5: il workflow della CI
Il workflow qui sotto è un esempio di GitHub Actions. La struttura si adatta a qualsiasi sistema CI: build, caricamento, esecuzione dello script sul server, eliminazione della CDN.
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 con cancel-in-progress: false accoda un secondo push dietro a un deploy in corso invece di annullarlo a metà sincronizzazione. PHP 8.2 è la versione minima di Blockstudio. Sostituite l’ultimo passaggio con CDN API di eliminazione della cache.
Comandi di manutenzione
Non servono a ogni release, ma una procedura di deploy dovrebbe conoscerli.
Svuotare la coda dei vecchi lock. Le release precedenti a 7.6.14 lasciavano un file .build.lock per ogni modifica ai contenuti. Dopo l’aggiornamento, WP-Cron li rimuove in batch di dimensioni limitate. Per controllare e svuotare tutta la coda:
wp bs cache status
wp bs cache cleanup
0 legacy build lock(s) across 0 cache namespace(s).
Next cleanup batch in 0 second(s).
cleanup lascia per l’esecuzione successiva i lock più recenti di un’ora o ancora mantenuti da una richiesta in corso. Non eliminate mai a mano i file di lock mentre il sito è attivo.
Svuotare la cache di runtime. wp bs cache clear elimina tutto per il sito corrente, mentre wp bs cache clear --scope=runtime elimina un ambito da tutti i namespace. La richiesta successiva ricostruisce la cache da zero, quindi eseguite il comando quando il traffico è basso e solo se necessario: le modifiche agli input aggiornano già le chiavi.
Rimuovere Blockstudio. Un’installazione Composer non ha un hook di disattivazione del plugin, quindi alla rimozione del pacchetto non viene annullata la pianificazione degli eventi cron né rimosso il drop-in di erogazione anticipata. Eseguite questo comando prima di rimuovere la dipendenza:
wp bs teardown
Rimuove gli eventi cron e lo stato di prerendering statico gestiti da questa installazione, lascia intatti i drop-in e i file di configurazione di altri componenti e consente una successiva riattivazione senza residui.
Passaggi successivi
- Creazione di pagine basate su file: le pagine sincronizzate da questo deploy.
- Riferimento alle pagine: comportamento della sincronizzazione, PHPconcetto di sincronizzazioneAPI e contratto dell’identità di deploy.
- CLIriferimento: tutti i comandi
wp bs. - Caching: posizione della cache, identità, conservazione e coda dei lock.
- Erogazione di WordPress come HTMLstatico: la cache aggiornata nel passaggio 4.
- Composer: installazioni come plugin, must-use, tema e incluse nei plugin.