Przejdź do treści

Wdrażanie witryny Blockstudio

Aby udostępnić bloki, wystarczy skopiować folder motywu na serwer: Blockstudio wykrywa je w systemie plików, a pamięci podręczne same wykrywają zmienione dane wejściowe. Prawdziwa witryna ma więcej elementów. Strony oparte na plikach trafiają do bazy danych dopiero po synchronizacji. Statyczna prerenderowana strona nadal wyświetla wczorajszy HTML, dopóki coś go nie zastąpi. CDN znajdujący się przed serwerem nadal wyświetla wszystko, co przechowuje w pamięci podręcznej.

Ten przewodnik opisuje wdrożenie motywu o nazwie acme, który udostępnia Blockstudio za pośrednictwem Composer. Omawia działania wykonywane w CI i na serwerze po umieszczeniu plików, sposób odczytywania raportu synchronizacji stron oraz polecenia wp bs, które należy uwzględnić w wydaniu.

Wydanie w skrócie

  1. Budowanie. CI instaluje zależności produkcyjne Composer.
  2. Przesłanie. Motyw, w tym vendor/, trafia na serwer.
  3. Synchronizacja stron. wp bs pages sync dopasowuje wpisy stron do plików i drukuje raport.
  4. Odświeżenie pamięci podręcznej źródła. Zapisana HTML jest czyszczona po zmianie stron, a następnie ponownie zapełniana.
  5. Wyczyszczenie CDN. Na końcu, aby brzeg pobrał dane ze świeżego źródła.

Kroki 3 i 4 wymagają na serwerze WP-CLI. Poniższy skrypt używa również jq do odczytu JSON.

Krok 1: Composer w CI

Dołącz Blockstudio do motywu i zatwierdź composer.lock, aby CI zainstalowało dokładnie tę wersję, którą przetestowano:

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

W CI zainstaluj pakiety bez zależności deweloperskich:

Powłoka
composer install --no-dev --optimize-autoloader --no-interaction --prefer-dist

Blockstudio uruchamia się z autoloadera, a jego własne zależności środowiska wykonawczego są dołączone do pakietu i mają osobne przestrzenie nazw. Gdy jest ładowany z katalogu vendor/, wbudowany mechanizm aktualizacji GitHub jest wyłączony, więc Composer pozostaje jedynym sposobem zmiany wersji.

Krok 2: Ustal, które katalogi muszą być zapisywalne

Blockstudio zapisuje wygenerowane pliki w czasie działania. Zanim wdrożenie zastąpi katalog lub zablokuje do niego dostęp, ustal, gdzie to następuje:

  • Domyślnie pamięci podręczne środowiska wykonawczego znajdują się w wp-content/blockstudio/cache/. Jeśli wolisz, skieruj cache.path do dedykowanego, zapisywalnego woluminu. Zmiana ścieżki oznacza pustą pamięć podręczną.
  • Skompilowane zasoby bloków są domyślnie zapisywane w katalogu _dist obok każdego bloku. Jeśli katalog wydania jest tylko do odczytu albo jest zastępowany przy każdym wdrożeniu, ustaw assets.output na cache, aby zapisywać je w katalogu pamięci podręcznej:
JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "assets": {
    "output": "cache"
  }
}

Nie trzeba czyścić pamięci podręcznych podczas wdrożenia. Każdy wpis pamięci podręcznej jest indeksowany na podstawie danych wejściowych, w tym plików bloków, ustawień, aktywnego motywu i wtyczek oraz wersji WordPress, PHP i Blockstudio, więc wydanie, które je zmienia, otrzymuje nowe klucze. W production i staging Blockstudio przez 20 sekund ufa zwalidowanej migawce obserwowanych zmian, zanim ponownie sprawdzi pliki. Zmiana może więc zostać wykryta z opóźnieniem do 20 sekund. Filtr blockstudio/cache/watch_debounce zmienia ten czas.

Krok 3: Synchronizacja stron

Wpisy stron zmieniają się wyłącznie podczas jawnej synchronizacji. Żądania z frontendu, panelu administracyjnego, Ajax, REST, cron i zwykłe żądania WP-CLI nigdy nie wyszukują źródeł stron ani nie zapisują wpisów stron. Wdrożenie musi uruchomić:

Powłoka
wp bs pages sync --format=json

W witrynie, której motyw zawiera dwie strony: about i contact, pierwsze uruchomienie je utworzy:

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

Jak odczytać raport:

  • created, updated, unchanged, removed i failed to liczby stron. Jeśli odcisk źródła strony się nie zmienił, nie są zapisywane wpis ani metadane wpisu i nie są uruchamiane żadne haki aktualizacji.
  • Każde uruchomienie porównuje pełny wykaz stron. fullReconciliation informuje, czy uruchomienie jest pełną synchronizacją: true przy pierwszym uruchomieniu, po --full lub po zmianie samego mechanizmu synchronizacji, oraz false, gdy istnieje tożsamość z poprzedniej udanej synchronizacji. Inne narzędzia mogą użyć tej informacji, by zdecydować, czy przebudować całość.
  • sourceIdentity to deterministyczny odcisk wykazu stron i mechanizmu synchronizacji. Polecenie zapisuje go po pomyślnym uruchomieniu.

Bez --format=json polecenie drukuje jeden wiersz podsumowania i komunikat o powodzeniu. W dzienniku CI, który nie jest terminalem, wiersz jest rozdzielony tabulatorami:

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

To uruchomienie nastąpiło po edycji about/index.php: jedna strona została zaktualizowana, a druga pozostała bez zmian.

Gdy synchronizacja się nie powiedzie

Polecenie kończy działanie z kodem 1, gdy wykrywanie lub synchronizacja zgłosi błąd, co powoduje niepowodzenie kroku CI. Raport JSON nadal jest drukowany, więc zapisz go w logu. Nieprawidłowy page.json wygląda tak:

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

Zarządzane strony, których źródła zniknęły, są usuwane dopiero po zakończeniu przebiegu bez błędów, więc wdrożenie, którego synchronizacja się nie powiedzie, nie usunie działających stron. Domyślnie usunięte strony trafiają do kosza; filtr blockstudio/pages/orphan_action może zwrócić trash, delete lub keep.

Uruchamiaj przy każdym wdrożeniu

Uruchamiaj synchronizację nawet wtedy, gdy żadna strona się nie zmieniła. Jeśli wdrażasz do katalogów wydań i przełączasz dowiązanie symboliczne, niezmieniona strona nadal wskazuje ścieżki szablonu i układu z poprzedniego wydania, dopóki kolejna synchronizacja ich nie odświeży. To odświeżenie nie zmienia post_content ani daty modyfikacji.

--authoritative i --full

Zwykła synchronizacja zachowuje treść zmienioną przez redaktorów wewnątrz bloków z kluczami. --authoritative zastępuje zarządzaną treść zawartością plików i może usunąć blokadę Page Sync. Użyj tej opcji, gdy pliki mają być nadrzędne, na przykład przy resetowaniu witryny testowej lub witryny, w której nikt nie edytuje w edytorze stron opartych na plikach. Nie dodawaj jej do każdego wdrożenia witryny, nad którą pracują redaktorzy.

--full oznacza przebieg jako pełną synchronizację niezależnie od zapisanej tożsamości. Porównanie stron i tak jest pełne przy każdym przebiegu, więc flaga zmienia wartość fullReconciliation w raporcie, a nie to, które strony są sprawdzane. Przekaż ją, jeśli kolejny krok używa tej wartości do uruchomienia pełnej przebudowy.

Narzędzia napisane w PHP mogą wywołać bezpośrednio Blockstudio\Pages::reconcile(). Zwraca ono ten sam raport, ale nie zapisuje tożsamości: wywołaj Blockstudio\Pages::store_successful_source_identity() po sprawdzeniu pozostałych elementów wydania, takich jak aktywowany artefakt statyczny.

Krok 4: Odświeżenie statycznej pamięci podręcznej

Jeśli witryna korzysta ze statycznego renderowania wstępnego w domyślnym trybie signature, wpisy stron zaktualizowane przez WP-CLI same nie czyszczą zapisanej HTML. Odczytaj raport, wyczyść pamięć podręczną, jeśli cokolwiek się zmieniło, a następnie ją rozgrzej:

Powłoka
#!/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}'

Każde uruchomienie wp bs prerender warm dodaje do kolejki nieaktualne publiczne adresy URL, renderuje maksymalnie warm.concurrency z nich i drukuje podsumowanie. W tym przebiegu przejęto cztery z sześciu adresów URL w kolejce i nie udało się wyrenderować żadnego z nich:

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

URL, którego renderowanie się nie powiedzie, pozostaje nieaktualny i zostaje ponownie dodany do kolejki przy następnym uruchomieniu. Dlatego pętla kończy się przy pierwszym przebiegu, który niczego nie rozgrzeje, zamiast czekać na opróżnienie kolejki. Pozostałe elementy obsłuży zaplanowany mechanizm rozgrzewania lub kolejna anonimowa wizyta.

W trybie graph mechanizm rozgrzewania dla każdego URL jest wyłączony, a warm niczego nie dodaje do kolejki. Witryny Graph zastępują kroki 2 i 3 własnym procesem budowania, który renderuje zmienione adresy URL i atomowo aktywuje wynik. Zobacz tryby sygnatury i Graph.

Krok 5: Przepływ CI

Poniższy przepływ pracy to przykład dla GitHub Actions. Jego schemat można zastosować w dowolnym systemie CI: zbuduj, prześlij, uruchom skrypt na serwerze, wyczyść 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 z cancel-in-progress: false dodaje drugie wdrożenie do kolejki za już trwającym, zamiast anulować je w połowie synchronizacji. PHP 8.2 to minimalna wersja dla Blockstudio. Zastąp ostatni krok poleceniem czyszczenia API dla CDN.

Polecenia konserwacyjne

Nie trzeba ich wykonywać przy każdym wydaniu, ale warto uwzględnić je w instrukcji wdrożenia.

Opróżnianie kolejki zaległych blokad starszego typu. Wydania sprzed 7.6.14 pozostawiały plik .build.lock po każdej zmianie treści. Po aktualizacji WP-Cron usuwa je w ograniczonych partiach. Aby sprawdzić stan i od razu opróżnić kolejkę:

Powłoka
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 pozostawia do następnego przebiegu blokady młodsze niż godzinę lub nadal utrzymywane przez trwające żądanie. Nigdy nie usuwaj ręcznie plików blokad, gdy witryna obsługuje ruch.

Czyszczenie pamięci podręcznej środowiska wykonawczego. wp bs cache clear czyści wszystkie dane bieżącej witryny, a wp bs cache clear --scope=runtime czyści jeden zakres we wszystkich przestrzeniach nazw. Następne żądanie odtworzy pustą pamięć podręczną, dlatego uruchamiaj polecenie przy małym ruchu i tylko wtedy, gdy jest ku temu powód: zmiany danych wejściowych i tak powodują rotację kluczy.

Usuwanie Blockstudio. Instalacja typu Composer nie ma haka dezaktywacji wtyczki, więc po usunięciu pakietu nic nie anuluje zdarzeń cron ani nie usuwa wtyczki typu drop-in, która umożliwia wczesne serwowanie. Uruchom to polecenie przed usunięciem zależności:

Powłoka
wp bs teardown

Usuwa zdarzenia cron i stan statycznego renderowania wstępnego należący do tej instalacji, pozostawia obce wtyczki drop-in i pliki konfiguracyjne bez zmian oraz umożliwia czyste ponowne włączenie.

Następne kroki