Gå til indhold

Udrulning af et Blockstudio-websted

For blokke er det nok at kopiere en temamappe til en server: Blockstudio finder blokkene i filsystemet, og dets cacher registrerer selv ændrede input. Et rigtigt websted har flere dele. Filbaserede sider når først databasen, når du synkroniserer dem. En statisk forhåndsgengivelse fortsætter med at vise gårsdagens HTML, indtil noget erstatter den. En CDN foran fortsætter med at vise det, den har cachet.

Denne vejledning beskriver en udrulning af et tema kaldet acme, der samler Blockstudio via Composer. Den gennemgår, hvad der kører i CI, hvad der kører på serveren, efter filerne er overført, hvordan rapporten om sidesynkronisering læses, og hvilke wp bs– kommandoer der hører til i en release.

Releaseforløbet i ét billede

  1. Byg. CI installerer produktionsafhængighederne Composer.
  2. Upload. Temaet, inklusive vendor/, kommer op på serveren.
  3. Synkroniser sider. wp bs pages sync bringer sideindlæggene på linje med filerne og udskriver en rapport.
  4. Opdater origin-cachen. Gemte HTML ryddes, når siderne er ændret, og caches derefter igen.
  5. Ryd CDN. Til sidst, så edge-cachen fyldes igen fra en frisk origin.

Trin 3 og 4 kræver WP-CLI på serveren. Scriptet nedenfor bruger også jq til at læse JSON.

Trin 1: Composer i CI

Pak Blockstudio i temaet, og commit composer.lock, så CI installerer den præcise version, du har testet:

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

I CI installeres uden udviklingspakker:

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

Blockstudio indlæses fra autoloaderen, og pakkens egne runtime-afhængigheder medfølger og er namespacet. Når det indlæses fra en vendor/-mappe, deaktiveres den indbyggede GitHub-opdatering, så Composer er den eneste måde at ændre versionen på.

Trin 2: Afgør, hvad der skal være skrivbart

Blockstudio skriver genererede filer under kørsel. Find ud af hvor, før en implementering erstatter eller låser en mappe:

  • Runtime-caches ligger som standard under wp-content/blockstudio/cache/. Peg cache.path på et dedikeret skrivbart drev, hvis du foretrækker det. En ændring af stien starter med en tom cache.
  • Kompilerede blokaktiver skrives som standard til en _dist-mappe ved siden af hver blok. Hvis din release-mappe er skrivebeskyttet eller erstattes ved hver implementering, skal du sætte assets.output til cache, så filerne i stedet placeres i cachemappen:
JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "assets": {
    "output": "cache"
  }
}

Du behøver ikke rydde caches ved implementering. Hvert cacheelement er knyttet til sine input, herunder blokfiler, indstillinger, det aktive tema og plugins samt versionerne af WordPress, PHP og Blockstudio, så en release, der ændrer dem, får nye nøgler. I production og staging stoler Blockstudio på et valideret watch- snapshot i 20 sekunder, før filerne kontrolleres igen. Derfor kan der gå op til 20 sekunder, før en ændring opdages. Filteret blockstudio/cache/watch_debounce ændrer dette tidsrum.

Trin 3: Synkroniser sider

Sideindlæg ændres kun ved en eksplicit synkronisering. Frontend-, admin-, Ajax-, REST-, cron- og almindelige WP-CLI-anmodninger finder aldrig sidekilder eller skriver sideindlæg. Implementeringen skal selv starte synkroniseringen:

Shell
wp bs pages sync --format=json

På et websted, hvis tema har to sider, about og contact, opretter den første kørsel dem:

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

Sådan læses rapporten:

  • created, updated, unchanged, removed og failed tæller sider. En side, hvis kildefingeraftryk er uændret, medfører ingen skrivning af indlæg eller indlægsmetadata og udløser ingen opdateringshooks.
  • Hver gennemgang sammenligner hele sideoversigten. fullReconciliation angiver, om gennemgangen tæller som en fuld synkronisering: true ved første kørsel, med --full, eller når selve synkroniseringsmotoren er ændret, og false, når der findes en identitet fra en tidligere vellykket synkronisering. Efterfølgende værktøjer kan bruge værdien til at afgøre, om alt skal genopbygges.
  • sourceIdentity er et deterministisk fingeraftryk af sideoversigten og synkroniseringsmotoren. Kommandoen gemmer det efter en vellykket gennemgang.

Uden --format=json udskriver kommandoen én opsummeringsrække og en succeslinje. I en CI-log, som ikke er en terminal, er rækken tabulatorsepareret:

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

Kørslen fulgte efter en redigering af about/index.php: én side blev opdateret, én var uændret.

Når synkroniseringen mislykkes

Kommandoen afslutter med status 1, når registrering eller synkronisering melder en fejl, hvilket får CI-trinnet til at fejle. Rapporten JSON udskrives stadig, så gem den i loggen. En fejlformateret page.json ser sådan ud:

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

Administrerede sider, hvis kilder er forsvundet, slettes først efter en fejlfri gennemgang, så en release, hvor synkroniseringen mislykkes, ikke ødelægger aktive sider. Fjernede sider flyttes som standard til papirkurven; filteret blockstudio/pages/orphan_action kan returnere trash, delete eller keep.

Kør ved hver implementering

Kør synkroniseringen, også når ingen sider er ændret. Hvis du implementerer i release- mapper og skifter et symlink, peger en uændret side stadig på skabelon- og layoutstierne fra den forrige release, indtil næste synkronisering opdaterer dem. Opdateringen berører ikke post_content eller ændringsdatoen.

--authoritative og --full

En normal synkronisering bevarer indhold, som redaktører har ændret i nøglede blokke. --authoritative erstatter i stedet administreret indhold med indholdet fra filerne og kan fjerne en Page Sync-lås. Brug den, når filerne skal have forrang: ved nulstilling af et staging-websted eller et websted, hvor ingen redigerer filbaserede sider i editoren. Brug den ikke ved hver implementering på et websted med aktive redaktører.

--full markerer gennemgangen som en fuld synkronisering uanset den gemte identitet. Sammenligningen af sider er allerede fuldstændig ved hver gennemgang, så flaget ændrer fullReconciliation i rapporten, ikke hvilke sider der kontrolleres. Angiv flaget, hvis et senere trin bruger værdien til at beslutte, om alt skal genopbygges.

Værktøjer skrevet i PHP kan kalde Blockstudio\Pages::reconcile() direkte. Funktionen returnerer den samme rapport, men gemmer ikke identiteten: Kald Blockstudio\Pages::store_successful_source_identity(), når resten af releasen, f.eks. et aktiveret statisk artefakt, er blevet verificeret.

Trin 4: Opdater den statiske cache

Hvis webstedet bruger statisk prerendering i standardtilstanden signature, sletter sideindlæg, der er opdateret fra WP-CLI, ikke automatisk gemte HTML. Læs rapporten, og ryd cachen, hvis noget er ændret. Opvarm den derefter:

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

Hver kørsel af wp bs prerender warm føjer forældede offentlige URL’er til køen, renderer op til warm.concurrency af dem og udskriver en opsummering. I denne gennemgang blev fire af seks URL’er fra køen hentet, og alle fire kunne ikke renderes:

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

En URL, der ikke kan renderes, forbliver forældet og føjes til køen igen ved næste kørsel. Derfor stopper løkken efter den første gennemgang, hvor intet bliver cachelagret, i stedet for at vente på en tom kø. Resterende URL’er håndteres af den planlagte cacheopvarmer eller ved næste anonyme besøg.

I tilstanden graph er den separate opvarmer for URL deaktiveret, og warm føjer intet til køen. Graph- websteder erstatter trin 2 og 3 med deres eget build, som renderer de berørte URL’er og aktiverer resultatet atomisk. Se signatur- og graph-tilstande.

Trin 5: CI-workflowet

Workflowet nedenfor er et eksempel på GitHub Actions. Fremgangsmåden kan overføres til ethvert CI-system: byg, upload, kør scriptet på serveren, og ryd 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 med cancel-in-progress: false sætter en ny push i kø bag en igangværende implementering i stedet for at afbryde den midt i en synkronisering. PHP 8.2 er minimumskravet til Blockstudio. Erstat det sidste trin med din CDN’s rydning af API.

Vedligeholdelseskommandoer

Disse hører ikke til i hver release, men bør være med i en vejledning til implementering.

Tømning af den gamle låsekø. Releases før 7.6.14 efterlod en .build.lock-fil for hver indholdsændring. Efter opgraderingen fjerner WP-Cron dem i afgrænsede portioner. Sådan kontrolleres og tømmes hele køen på én gang:

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 lader låse, der er nyere end en time eller stadig holdes af en kørende anmodning, ligge til næste gennemgang. Slet aldrig låsefiler manuelt, mens webstedet håndterer trafik.

Rydning af runtime-cachen. wp bs cache clear rydder alt for det aktuelle websted, og wp bs cache clear --scope=runtime rydder ét område på tværs af alle navnerum. Den næste anmodning genopbygger den tomme cache, så gør det uden for travle perioder og kun, når der er en grund: ændringer i input roterer allerede nøglerne.

Fjernelse af Blockstudio. En Composer-installation har ingen hook til deaktivering af plugins, så der bliver hverken afplanlagt cron-hændelser eller fjernet en drop-in til tidlig visning, når pakken forsvinder. Kør dette, før afhængigheden fjernes:

Shell
wp bs teardown

Det fjerner de cron-hændelser og den statiske prerenderingstilstand, som denne installation ejer, lader fremmede drop-ins og konfigurationsfiler være urørte og gør det muligt at aktivere installationen igen uden rester.

Næste trin