Zum Inhalt springen

Eine Blockstudio-Website bereitstellen

Für Blöcke reicht es, einen Theme-Ordner auf einen Server zu kopieren: Blockstudio erkennt sie im Dateisystem, und seine Caches bemerken Änderungen an Eingaben von selbst. Bei einer echten Website gibt es mehr bewegliche Teile. Dateibasierte Seiten gelangen erst nach einer Synchronisierung in die Datenbank. Ein statisches Vorab-Rendering liefert weiterhin das gestrige HTML aus, bis es ersetzt wird. Ein vorgeschaltetes CDN liefert weiter aus, was dort zwischengespeichert wurde.

Diese Anleitung erstellt einen Deploy für ein Theme namens acme, das Blockstudio über Composer einbindet. Sie behandelt die Abläufe in CI und nach dem Übertragen der Dateien auf dem Server, das Lesen des Seitensynchronisierungsberichts und die Wartungsbefehle wp bs, die in einen Release gehören.

Der Release im Überblick

  1. Erstellen. CI installiert die Composer-Abhängigkeiten für den Produktivbetrieb.
  2. Hochladen. Das Theme einschließlich vendor/ wird auf den Server übertragen.
  3. Seiten abgleichen. wp bs pages sync bringt Seitenbeiträge mit den Dateien in Einklang und gibt einen Bericht aus.
  4. Origin-Cache aktualisieren. Der gespeicherte HTML-Cache wird bei geänderten Seiten geleert und anschließend neu befüllt.
  5. CDN leeren. Zuletzt, damit der Edge-Cache wieder frische Inhalte vom Origin abruft.

Für die Schritte 3 und 4 wird WP-CLI auf dem Server benötigt. Das folgende Skript verwendet außerdem jq, um JSON zu lesen.

Schritt 1: Composer in CI

Binde Blockstudio in das Theme ein und committe composer.lock, damit CI genau die Version installiert, die du getestet hast:

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

Installiere in CI ohne Entwicklungspakete:

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

Blockstudio wird über den Autoloader initialisiert. Die Laufzeitabhängigkeiten sind direkt im Paket gebündelt und mit einem eigenen Namensraum versehen. Wird es aus einem vendor/-Verzeichnis geladen, ist der integrierte GitHub-Updater deaktiviert. Composer bleibt damit der einzige Weg, die Version zu ändern.

Schritt 2: Schreibrechte festlegen

Blockstudio schreibt zur Laufzeit generierte Dateien. Lege vor einem Deploy fest, wo sie gespeichert werden, damit kein Verzeichnis ersetzt oder gesperrt wird:

  • Laufzeit-Caches liegen standardmäßig unter wp-content/blockstudio/cache/. Richte cache.path bei Bedarf auf ein separates beschreibbares Volume. Ein geänderter Pfad beginnt mit einem leeren Cache.
  • Kompilierte Block-Assets werden standardmäßig in einem Ordner _dist neben jedem Block abgelegt. Ist dein Release-Verzeichnis schreibgeschützt oder wird es bei jedem Deploy ersetzt, setze assets.output auf cache. Dann werden die Assets stattdessen im Cache-Verzeichnis abgelegt:
JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "assets": {
    "output": "cache"
  }
}

Du musst beim Deploy keine Caches leeren. Jeder Cache-Eintrag richtet sich nach seinen Eingaben, darunter Blockdateien, Einstellungen, aktives Theme und Plugins sowie die Versionen WordPress, PHP und Blockstudio. Ändert ein Release diese Angaben, erhält es neue Schlüssel. In production und staging verlässt sich Blockstudio 20 Sekunden lang auf einen validierten Watch-Snapshot, bevor es Dateien erneut prüft. Änderungen werden daher möglicherweise erst nach bis zu 20 Sekunden erkannt. Der Filter blockstudio/cache/watch_debounce ändert dieses Zeitfenster.

Schritt 3: Seiten abgleichen

Seitenbeiträge ändern sich nur durch eine ausdrücklich angeforderte Synchronisierung. Frontend-, Admin-, Ajax-, REST-, cron- und gewöhnliche WP-CLI-Anfragen suchen nie nach Seitenquellen und schreiben keine Seitenbeiträge. Der Deploy muss den Vorgang ausdrücklich anstoßen:

Shell
wp bs pages sync --format=json

Auf einer Website, deren Theme zwei Seiten enthält, about und contact, werden sie beim ersten Lauf erstellt:

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

So liest du den Bericht:

  • created, updated, unchanged, removed und failed zählen Seiten. Eine Seite, deren Quellfingerabdruck sich nicht geändert hat, erzeugt keine Schreibvorgänge für Beiträge oder Beitragsmetadaten und löst keine Aktualisierungshooks aus.
  • Jeder Durchlauf vergleicht den vollständigen Seitenbestand. fullReconciliation gibt an, ob der Durchlauf als vollständiger Abgleich gilt: true beim ersten Lauf, mit --full oder wenn sich die Sync-Engine selbst geändert hat, und false, wenn eine Identität aus einem vorherigen erfolgreichen Sync vorhanden ist. Nachgelagerte Tools können damit entscheiden, ob alles neu aufgebaut werden muss.
  • sourceIdentity ist ein deterministischer Fingerabdruck des Seitenbestands und der Sync-Engine. Der Befehl speichert ihn nach einem erfolgreichen Durchlauf.

Ohne --format=json gibt der Befehl eine Zusammenfassungszeile und eine Erfolgsmeldung aus. In einem CI-Protokoll, das kein Terminal ist, sind die Spalten der Zeile durch Tabulatoren getrennt:

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

Dieser Lauf folgte auf eine Änderung an about/index.php: Eine Seite wurde aktualisiert, eine blieb unverändert.

Wenn die Synchronisierung fehlschlägt

Der Befehl wird mit Status 1 beendet, wenn die Ermittlung oder der Abgleich einen Fehler meldet. Dadurch schlägt der CI-Schritt fehl. Der Bericht JSON wird trotzdem ausgegeben, also protokolliere ihn. Ein fehlerhaftes page.json sieht so aus:

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

Verwaltete Seiten, deren Quellen nicht mehr vorhanden sind, werden erst entfernt, wenn ein Durchlauf fehlerfrei endet. So löscht ein fehlgeschlagener Sync beim Release keine aktiven Seiten. Standardmäßig wandern entfernte Seiten in den Papierkorb; der Filter blockstudio/pages/orphan_action kann trash, delete oder keep zurückgeben.

Bei jedem Deploy ausführen

Führe den Sync auch aus, wenn sich keine Seite geändert hat. Wenn du in Release-Verzeichnisse deployst und einen Symlink umschaltest, verweist eine unveränderte Seite weiterhin auf die Template- und Layoutpfade des vorherigen Releases, bis der nächste Sync sie aktualisiert. Dabei werden post_content und das Änderungsdatum nicht verändert.

--authoritative und --full

Ein normaler Sync bewahrt Inhalte, die Redakteure innerhalb von Blöcken mit Schlüssel geändert haben. --authoritative ersetzt stattdessen verwaltete Inhalte durch die Dateien und kann eine Page-Sync-Sperre aufheben. Verwende es, wenn die Dateien maßgeblich sein sollen: etwa beim Zurücksetzen einer Staging-Website oder auf einer Website, auf der niemand dateibasierte Seiten im Editor bearbeitet. Führe es nicht bei jedem Deploy einer Website mit aktiven Redakteuren aus.

--full kennzeichnet den Durchlauf unabhängig von der gespeicherten Identität als vollständigen Abgleich. Der Seitenvergleich ist ohnehin bei jedem Durchlauf vollständig, daher ändert die Option den Wert von fullReconciliation im Bericht, nicht die geprüften Seiten. Übergib sie, wenn ein späterer Schritt anhand dieses Werts einen vollständigen Neuaufbau auslösen soll.

In PHP geschriebene Tools können Blockstudio\Pages::reconcile() direkt aufrufen. Die Funktion gibt denselben Bericht zurück, speichert aber die Identität nicht. Rufe Blockstudio\Pages::store_successful_source_identity() auf, sobald der übrige Release geprüft wurde, zum Beispiel nachdem ein statisches Artefakt aktiviert wurde.

Schritt 4: Statischen Cache aktualisieren

Wenn die Website statisches Prerendering im standardmäßigen Modus signature verwendet, löschen aktualisierte Beiträge aus WP-CLI den gespeicherten HTML-Cache nicht selbst. Lies den Bericht und leere den Cache, wenn sich etwas geändert hat. Wärme ihn anschließend auf:

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

Bei jedem Lauf von wp bs prerender warm werden veraltete öffentliche URLs in die Warteschlange gestellt, bis zu warm.concurrency davon gerendert und eine Zusammenfassung ausgegeben. In diesem Durchlauf wurden vier von sechs eingereihten URLs übernommen, aber alle vier konnten nicht gerendert werden:

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

Ein URL, das nicht gerendert werden kann, bleibt veraltet und wird beim nächsten Lauf erneut eingereiht. Deshalb endet die Schleife beim ersten Durchlauf, der nichts aufwärmt, statt auf eine leere Warteschlange zu warten. Alles Übrige übernimmt der geplante Cache-Aufwärmer oder der nächste anonyme Besuch.

Im Modus graph ist der Aufwärmer pro URL deaktiviert, und warm reiht nichts ein. Websites mit Graph ersetzen die Schritte 2 und 3 durch ihren eigenen Build, der die betroffenen URLs rendert und das Ergebnis atomar aktiviert. Siehe Signatur- und Graph-Modi.

Schritt 5: Der CI-Workflow

Der folgende Workflow ist ein Beispiel für GitHub Actions. Der Ablauf lässt sich auf jedes CI-System übertragen: erstellen, hochladen, das Skript auf dem Server ausführen und den CDN-Cache leeren.

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 mit cancel-in-progress: false reiht einen zweiten Push hinter einem laufenden Deploy ein, statt ihn mitten in einem Sync abzubrechen. PHP 8.2 ist die Mindestversion von Blockstudio. Ersetze den letzten Schritt durch den Purge-API deines CDN.

Wartungsbefehle

Diese gehören nicht in jedes Release, sollten aber im Deploy-Handbuch stehen.

Rückstand der alten Sperren abbauen. Releases vor 7.6.14 hinterließen bei jeder Inhaltsänderung eine Datei .build.lock. Nach dem Upgrade entfernt WP-Cron sie in begrenzten Stapeln. So prüfst du den Rückstand und baust ihn auf einmal ab:

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 lässt Sperren, die jünger als eine Stunde sind oder noch von einer laufenden Anfrage gehalten werden, bis zum nächsten Durchlauf bestehen. Lösche niemals manuell Sperrdateien, während die Website Anfragen bedient.

Laufzeitcache leeren. wp bs cache clear leert den gesamten Cache der aktuellen Website, und wp bs cache clear --scope=runtime leert einen Bereich über alle Namensräume hinweg. Die nächste Anfrage baut den Cache von Grund auf neu auf. Führe das bei geringem Traffic und nur bei Bedarf aus: Änderungen an Eingaben rotieren die Schlüssel bereits.

Blockstudio entfernen. Bei einer Composer-Installation gibt es keinen Hook zum Deaktivieren des Plugins. Daher werden cron-Ereignisse nicht aus dem Zeitplan entfernt und das Drop-in für die frühe Auslieferung bleibt bestehen, wenn das Paket entfernt wird. Führe dies aus, bevor du die Abhängigkeit entfernst:

Shell
wp bs teardown

Der Befehl entfernt die cron-Ereignisse und den Status für statisches Prerendering, der dieser Installation gehört. Fremde Drop-ins und Konfigurationsdateien bleiben unangetastet; eine spätere Reaktivierung kann sauber beginnen.

Nächste Schritte