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
- Budowanie. CI instaluje zależności produkcyjne Composer.
- Przesłanie. Motyw, w tym
vendor/, trafia na serwer. - Synchronizacja stron.
wp bs pages syncdopasowuje wpisy stron do plików i drukuje raport. - Odświeżenie pamięci podręcznej źródła. Zapisana HTML jest czyszczona po zmianie stron, a następnie ponownie zapełniana.
- 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:
{
"require": {
"blockstudio/blockstudio": "^7.0"
}
}
<?php
require_once __DIR__ . '/vendor/autoload.php';
W CI zainstaluj pakiety bez zależności deweloperskich:
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, skierujcache.pathdo dedykowanego, zapisywalnego woluminu. Zmiana ścieżki oznacza pustą pamięć podręczną. - Skompilowane zasoby bloków są domyślnie zapisywane w katalogu
_distobok każdego bloku. Jeśli katalog wydania jest tylko do odczytu albo jest zastępowany przy każdym wdrożeniu, ustawassets.outputnacache, aby zapisywać je w katalogu pamięci podręcznej:
{
"$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ć:
wp bs pages sync --format=json
W witrynie, której motyw zawiera dwie strony: about i contact, pierwsze uruchomienie je utworzy:
{
"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,removedifailedto 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.
fullReconciliationinformuje, czy uruchomienie jest pełną synchronizacją:trueprzy pierwszym uruchomieniu, po--fulllub po zmianie samego mechanizmu synchronizacji, orazfalse, gdy istnieje tożsamość z poprzedniej udanej synchronizacji. Inne narzędzia mogą użyć tej informacji, by zdecydować, czy przebudować całość. sourceIdentityto 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:
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:
{
"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:
#!/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:
{"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.
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ę:
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 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:
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
- Tworzenie stron na podstawie plików: strony synchronizowane podczas tego wdrożenia.
- Dokumentacja stron: działanie synchronizacji, PHPuzgadnianieAPI oraz zasady dotyczące tożsamości wdrożenia.
- CLIdokumentacja: każde polecenie
wp bs. - Buforowanie: lokalizacja pamięci podręcznej, tożsamość, przechowywanie i kolejka zaległych blokad.
- Serwowanie WordPress jako statycznego HTML: pamięć podręczna odświeżana w kroku 4.
- Composerdokumentacja: instalacje jako wtyczka, must-use, motyw oraz pakiet dołączony do wtyczki.