Treci la conținut

Publicarea unui site Blockstudio

Copierea unui dosar de temă pe un server este suficientă pentru blocuri: Blockstudio le descoperă din sistemul de fișiere, iar cache-urile sale detectează singure modificările intrărilor. Un site real are și alte componente. Paginile bazate pe fișiere ajung în baza de date numai când le sincronizați. O pre-randare statică continuă să afișeze HTML de ieri până când ceva o înlocuiește. Un CDN din față continuă să afișeze ceea ce a memorat în cache.

Acest ghid creează o implementare pentru o temă numită acme, care include Blockstudio prin Composer. Acoperă ce rulează în CI, ce rulează pe server după copierea fișierelor, cum se citește raportul de sincronizare a paginilor și ce comenzi wp bs trebuie incluse într-o versiune.

Lansarea, ilustrată

  1. Construire. CI instale les dépendances de production Composer.
  2. Téléverser. Le thème, y compris vendor/, arrive sur le serveur.
  3. Synchroniser les pages. wp bs pages sync met les articles de page en adéquation avec les fichiers et affiche un rapport.
  4. Actualiser le cache d’origine. Les HTML stockés sont purgés lorsque des pages ont changé, puis remis en cache.
  5. Purger le CDN. En dernier, afin que le nœud périphérique recharge le cache depuis une origine à jour.

Les étapes 3 et 4 nécessitent WP-CLI sur le serveur. Le script ci-dessous utilise aussi jq pour lire JSON.

Étape 1 : Composer dans CI

Intégrez Blockstudio au thème et validez composer.lock, afin que CI installe la version exacte que vous avez testée :

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

Dans CI, installez sans les paquets de développement :

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

Blockstudio se lance depuis l’autoloader, et ses propres dépendances d’exécution sont intégrées au paquet et leurs espaces de noms y sont isolés. Lorsqu’il est chargé depuis un répertoire vendor/, son outil de mise à jour GitHub intégré est désactivé ; Composer reste donc le seul moyen de changer de version.

Étape 2 : Déterminer ce qui doit être accessible en écriture

Blockstudio écrit des fichiers générés à l’exécution. Repérez leur emplacement avant qu’un déploiement ne remplace ou ne verrouille un répertoire :

  • Les caches d’exécution se trouvent par défaut sous wp-content/blockstudio/cache/. Vous pouvez définir cache.path sur un volume dédié accessible en écriture. Si vous changez le chemin, le cache sera vide.
  • Les ressources de blocs compilées sont écrites par défaut dans un dossier _dist à côté de chaque bloc. Si votre répertoire de version est en lecture seule ou remplacé à chaque déploiement, définissez assets.output sur cache pour les placer plutôt dans le répertoire de cache :
JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "assets": {
    "output": "cache"
  }
}

Vous n’avez pas besoin de vider les caches lors d’un déploiement. Chaque entrée de cache est indexée par ses données d’entrée, notamment les fichiers de blocs, les réglages, le thème et les extensions actifs, ainsi que les versions de WordPress, PHP et Blockstudio. Une version qui les modifie obtient donc de nouvelles clés. Dans production et staging, Blockstudio fait confiance à un instantané de surveillance validé pendant 20 secondes avant de vérifier à nouveau les fichiers ; un changement peut donc prendre jusqu’à 20 secondes à être détecté. Le filtre blockstudio/cache/watch_debounce modifie cette durée.

Étape 3 : Synchroniser les pages

Les articles de page ne changent qu’à la suite d’une synchronisation explicite. Les requêtes du frontend, de l’interface d’administration, Ajax, REST, cron et les requêtes WP-CLI ordinaires ne recherchent jamais les sources de pages et n’écrivent jamais d’articles de page. Le déploiement doit le demander :

Shell
wp bs pages sync --format=json

Sur un site dont le thème comporte deux pages, about et contact, la première exécution les crée :

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": []
}

Comment lire le résultat :

  • created, updated, unchanged, removed et failed indiquent le nombre de pages. Si l’empreinte de la source d’une page n’a pas changé, aucun article ni métadonnée d’article n’est écrit et aucun hook de mise à jour n’est déclenché.
  • Chaque passage compare l’inventaire complet des pages. fullReconciliation indique si le passage compte comme une synchronisation complète : true lors de la première exécution, avec --full, ou lorsque le moteur de synchronisation lui-même a changé, et false lorsqu’une identité issue d’une synchronisation précédente réussie existe. Les outils en aval peuvent s’en servir pour décider s’il faut tout reconstruire.
  • sourceIdentity est une empreinte déterministe de l’inventaire des pages et du moteur de synchronisation. La commande la stocke après un passage réussi.

Sans --format=json, la commande affiche une ligne récapitulative et une ligne de réussite. Dans un journal CI, qui n’est pas un terminal, les champs de la ligne sont séparés par des tabulations :

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

Cette exécution a suivi une modification de about/index.php : une page a été mise à jour, l’autre est restée inchangée.

En cas d’échec de la synchronisation

La commande se termine avec le statut 1 lorsque la découverte ou la synchronisation signale une erreur, ce qui fait échouer l’étape CI. Le rapport JSON est tout de même affiché : enregistrez-le dans le journal. Un page.json mal formé ressemble à ceci :

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"
            }
        }
    ]
}

Les pages gérées dont les sources ont disparu ne sont supprimées qu’après un passage sans erreur ; ainsi, un échec de synchronisation lors d’un déploiement ne détruit pas les pages en ligne. Par défaut, les pages supprimées sont placées dans la corbeille ; le filtre blockstudio/pages/orphan_action peut renvoyer trash, delete ou keep.

L’exécuter à chaque déploiement

Exécutez la synchronisation même si aucune page n’a changé. Si vous déployez dans des répertoires de version et basculez un lien symbolique, le modèle et les chemins de mise en page de la version précédente resteront associés à une page inchangée jusqu’à leur actualisation lors de la prochaine synchronisation. Cette actualisation ne modifie ni post_content ni la date de modification.

--authoritative et --full

Une synchronisation normale préserve le contenu que les éditeurs ont modifié dans les blocs avec clé. --authoritative remplace plutôt le contenu géré par celui des fichiers et peut supprimer un verrou Page Sync. Utilisez-le lorsque les fichiers doivent prévaloir : pour réinitialiser un site de préproduction ou pour un site où personne ne modifie dans l’éditeur les pages gérées par des fichiers. Ne l’incluez pas dans chaque déploiement d’un site avec des éditeurs actifs.

--full marque le passage comme une synchronisation complète, quelle que soit l’identité stockée. La comparaison des pages est déjà complète à chaque passage ; ce drapeau modifie donc fullReconciliation dans le rapport, et non les pages vérifiées. Transmettez-le si une étape ultérieure déclenche une reconstruction complète en fonction de cette valeur.

Les outils écrits en PHP peuvent appeler directement Blockstudio\Pages::reconcile(). Cette fonction renvoie le même rapport, mais ne stocke pas l’identité : appelez Blockstudio\Pages::store_successful_source_identity() une fois le reste de la version vérifié, par exemple après l’activation d’un artefact statique.

Étape 4 : Actualiser le cache statique

Dacă site-ul folosește pre-randare statică în modul implicit signature, postările actualizate de pagină din WP-CLI nu invalidează automat datele stocate HTML. Citiți raportul și ștergeți datele stocate când s-a schimbat ceva, apoi încălziți cache-ul:

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}'

Chaque exécution wp bs prerender warm met en file d’attente les URL publiques obsolètes, en génère jusqu’à warm.concurrency et affiche un récapitulatif. Lors de ce passage, quatre des six URL en file ont été prises en charge et les quatre ont échoué à la génération :

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

Une URL dont la génération échoue reste obsolète et est remise en file d’attente lors de la prochaine exécution. C’est pourquoi la boucle s’arrête au premier passage qui ne réchauffe rien, au lieu d’attendre une file vide. Les éléments restants seront traités par le réchauffeur planifié ou lors de la prochaine visite anonyme.

En mode graph, le réchauffeur par URL est désactivé et warm ne met rien en file d’attente. Les sites Graph remplacent les étapes 2 et 3 par leur propre compilation, qui génère les URL concernées et active le résultat de manière atomique. Voir les modes signature et graphe.

Étape 5 : Le workflow CI

Le workflow ci-dessous est un exemple GitHub Actions. Le principe s’applique à tout système CI : compiler, téléverser, exécuter le script sur le serveur et purger le 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 avec cancel-in-progress: false met une seconde mise en production en attente derrière celle en cours, au lieu de l’annuler en plein milieu d’une synchronisation. La version 8.2 de PHP est le minimum requis par Blockstudio. Remplacez la dernière étape par l’CDN de purge de votre API.

Commandes de maintenance

Ces commandes n’ont pas leur place dans chaque version, mais le guide de déploiement doit les mentionner.

Vider l’arriéré des anciens verrous. Les versions antérieures à 7.6.14 laissaient un fichier .build.lock pour chaque modification de contenu. Après la mise à niveau, WP-Cron les supprime par lots limités. Pour vérifier, puis vider l’arriéré en une fois :

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 conserve pour le passage suivant les verrous datant de moins d’une heure ou encore détenus par une requête en cours. Ne supprimez jamais les fichiers de verrou à la main pendant que le site reçoit du trafic.

Vider le cache d’exécution. wp bs cache clear purge tout le cache du site actuel, et wp bs cache clear --scope=runtime purge une portée dans tous les espaces de noms. La prochaine requête repartira d’un cache vide : exécutez cette commande en période de faible trafic et uniquement si nécessaire, car les changements des données d’entrée renouvellent déjà les clés.

Supprimer Blockstudio. Une installation Composer n’a pas de hook de désactivation d’extension ; aucun événement cron n’est donc déplanifié et le drop-in de réponse anticipée n’est pas supprimé lorsque le paquet disparaît. Exécutez cette commande avant de supprimer la dépendance :

Shell
wp bs teardown

Cette commande supprime les événements cron et l’état de pré-génération statique appartenant à cette installation, laisse intacts les drop-ins et fichiers de configuration externes et permet une réactivation ultérieure propre.

Pașii următori