Към съдържанието

Внедряване на сайт Blockstudio

За блоковете е достатъчно да копирате папката на темата на сървър: Blockstudio ги открива от файловата система, а кешовете му сами забелязват промените във входните данни. В един истински сайт има и други компоненти. Страниците, базирани на файлове, попадат в базата данни само когато ги синхронизирате. Статично предварително генерирана страница продължава да показва вчерашния HTML, докато нещо не го замени. Намиращ се отпред CDN продължава да показва всичко, което е кеширал.

Това ръководство описва внедряване на тема acme, която включва Blockstudio чрез Composer. В него се разглежда какво се изпълнява в CI, какво се изпълнява на сървъра след качването на файловете, как да четете отчета за синхронизация на страниците и кои команди wp bs трябва да влязат във версията.

Версията в една схема

  1. Компилация. CI инсталира производствените Composer зависимости.
  2. Качване. Темата, включително vendor/, се качва на сървъра.
  3. Синхронизиране на страниците. wp bs pages sync привежда публикациите на страниците в съответствие с файловете и извежда отчет.
  4. Обновяване на кеша на origin сървъра. Съхраненият HTML се изчиства при промяна на страниците, след което се загрява отново.
  5. Изчистване на CDN. Накрая, за да се зареди кешът на edge от актуален origin.

Стъпки 3 и 4 изискват WP-CLI на сървъра. Скриптът по-долу използва и jq, за да прочете JSON.

Стъпка 1: Composer в CI

Включете Blockstudio в темата и фиксирайте composer.lock, така че CI да инсталира точната версия, която сте тествали:

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

В CI инсталирайте без пакетите за разработка:

Обвивка
composer install --no-dev --optimize-autoloader --no-interaction --prefer-dist

Blockstudio се зарежда чрез autoloader, а собствените му runtime зависимости са включени в пакета и използват собствено пространство от имена. Когато се зарежда от директория vendor/, вграденият му инструмент за актуализация GitHub е деактивиран, така че Composer остава единственият начин за промяна на версията.

Стъпка 2: Определете какво трябва да може да се записва

Blockstudio записва генерирани файлове по време на изпълнение. Уточнете къде, преди внедряване да замени или заключи дадена директория:

  • По подразбиране runtime кешовете се намират в wp-content/blockstudio/cache/. Ако предпочитате, насочете cache.path към специално предназначен за целта том с право на запис. Промяната на пътя започва с празен кеш.
  • Компилираните ресурси на блоковете по подразбиране се записват в папка _dist до всеки блок. Ако директорията на версията е само за четене или се заменя при всяко внедряване, задайте на assets.output стойност cache, за да се записват вместо това в директорията на кеша:
JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "assets": {
    "output": "cache"
  }
}

Не е необходимо да изчиствате кешовете при внедряване. Всеки запис в кеша се индексира по входните си данни, включително файловете на блоковете, настройките, активната тема и добавките, както и версиите на WordPress, PHP и Blockstudio, така че версия, в която те са променени, получава нови ключове. В production и staging Blockstudio разчита на валидирана моментна снимка за наблюдение в продължение на 20 секунди, преди отново да провери файловете, затова може да отнеме до 20 секунди, докато бъде забелязана промяна. Филтърът blockstudio/cache/watch_debounce променя този интервал.

Стъпка 3: Синхронизиране на страниците

Публикациите на страниците се променят само при изрично синхронизиране. Заявките от frontend, администрацията, Ajax, REST, cron и обикновените заявки WP-CLI никога не откриват източници на страници и не записват публикации на страници. При внедряването трябва изрично да се поиска:

Обвивка
wp bs pages sync --format=json

В сайт, чиято тема има две страници, about и contact, първото изпълнение ги създава:

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

Как да разчитате резултата:

  • created, updated, unchanged, removed и failed показват броя на страниците. Ако отпечатъкът на източника на дадена страница не се е променил, не се записват публикация или метаданни на публикацията и не се задействат куки за актуализация.
  • При всяко изпълнение се сравнява пълният списък със страници. fullReconciliation показва дали изпълнението се счита за пълно синхронизиране: true при първото изпълнение, при --full или когато самият механизъм за синхронизиране се е променил, и false, когато съществува идентификатор от предишно успешно синхронизиране. Другите инструменти могат да го използват, за да решат дали да изградят всичко отново.
  • sourceIdentity е детерминистичен отпечатък на списъка със страници и механизма за синхронизиране. Командата го съхранява след успешно изпълнение.

Без --format=json командата извежда един обобщаващ ред и съобщение за успех. В CI журнал, който не е терминал, редът е разделен с табулатори:

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

Това изпълнение последва редакция на about/index.php: една страница беше актуализирана, а една остана непроменена.

При неуспешно синхронизиране

Командата завършва със статус 1, когато при откриването или синхронизирането възникне грешка, което проваля стъпката в CI. Отчетът JSON все пак се извежда, затова го запишете в журнала. Неправилно форматиран page.json изглежда така:

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

Управляваните страници, чиито източници са изчезнали, се премахват само след като изпълнението завърши без грешки, така че неуспешното синхронизиране при внедряване няма да изтрие активни страници. По подразбиране премахнатите страници се преместват в кошчето; филтърът blockstudio/pages/orphan_action може да върне trash, delete или keep.

Изпълнявайте при всяко внедряване

Изпълнявайте синхронизирането дори когато няма променени страници. Ако внедрявате в директории с версии и превключвате символна връзка, непроменената страница продължава да сочи към пътищата за шаблони и оформление от предишната версия, докато следващото синхронизиране не ги обнови. Това обновяване не променя post_content или датата на промяна.

--authoritative и --full

Обикновеното синхронизиране запазва съдържанието, което редакторите са променили в блоковете с ключове. --authoritative вместо това заменя управляваното съдържание с това от файловете и може да изчисти заключване на Page Sync. Използвайте го, когато файловете трябва да имат предимство: например при нулиране на тестов сайт или на сайт, в който никой не редактира страниците, базирани на файлове, в редактора. Не го включвайте при всяко внедряване на сайт с активни редактори.

--full маркира изпълнението като пълно синхронизиране независимо от съхранения идентификатор. Сравнението на страниците така или иначе е пълно при всяко изпълнение, затова флагът променя fullReconciliation в отчета, а не страниците, които се проверяват. Подайте го, ако следваща стъпка използва тази стойност, за да реши дали да изгради всичко отново.

Инструментите, написани на PHP, могат директно да извикат Blockstudio\Pages::reconcile(). Той връща същия отчет, но не съхранява идентификатора: извикайте Blockstudio\Pages::store_successful_source_identity(), след като останалата част от версията, например активиран статичен артефакт, бъде проверена.

Стъпка 4: Обновяване на статичния кеш

Ако сайтът използва статично предварително генериране] в режим signature по подразбиране, публикациите на страници, обновени чрез WP-CLI, сами по себе си не изчистват съхранения HTML. Прочетете отчета и изчистете кеша при всяка промяна, след което го загрейте:

Обвивка
#!/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}'

При всяко изпълнение на wp bs prerender warm се поставят в опашка остарели публични URL адреси, визуализират се до warm.concurrency от тях и се извежда обобщение. При това изпълнение бяха заявени четири от шестте URL адреса в опашката и визуализацията на всичките четири се провали:

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

Ако визуализирането на URL се провали, той остава остарял и се добавя отново в опашката при следващото изпълнение. Затова цикълът спира при първото изпълнение, което не загрее нищо, вместо да чака опашката да се изпразни. Останалите URL адреси ще бъдат обработени от планирания инструмент за загряване или при следващо анонимно посещение.

В режим graph инструментът за загряване за всеки URL е изключен и warm не добавя нищо в опашката. Graph сайтовете заменят стъпки 2 и 3 със собствен процес на изграждане, който визуализира засегнатите URL адреси и атомарно активира резултата. Вижте режими на подписи и графи.

Стъпка 5: Работният процес на CI

Работният процес по-долу е пример за GitHub Actions. Същата структура важи за всяка CI система: изградете, качете, изпълнете скрипта на сървъра и изчистете 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 с cancel-in-progress: false добавя второ изпълнение на опашката зад текущото внедряване, вместо да го прекъсне по средата на синхронизацията. PHP 8.2 е минималната версия за Blockstudio. Заменете последната стъпка с purge API на CDN.

Команди за поддръжка

Те не са нужни при всяко издание, но трябва да са описани в наръчника за внедряване.

Изчистване на натрупаните стари заключвания. Изданията преди 7.6.14 оставяха файл .build.lock след всяка промяна на съдържанието. След надстройването WP-Cron ги премахва на ограничени порции. За да проверите и да изчистите всичко наведнъж:

Обвивка
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 запазва за следващото изпълнение заключванията, създадени преди по-малко от час, или тези, които все още се държат от текуща заявка. Никога не изтривайте файлове за заключване ръчно, докато сайтът обслужва трафик.

Изчистване на runtime кеша. wp bs cache clear изчиства всичко за текущия сайт, а wp bs cache clear --scope=runtime изчиства един обхват във всички пространства от имена. Следващата заявка ще изгради кеша от нулата, затова изпълнявайте при нисък трафик и само при необходимост: промените във входните данни така или иначе сменят ключовете.

Премахване на Blockstudio. При инсталация като Composer няма кука за деактивиране на добавката, затова нищо не отменя планираните събития cron или не премахва drop-in за ранно обслужване, когато пакетът изчезне. Изпълнете това, преди да премахнете зависимостта:

Обвивка
wp bs teardown

Това премахва събитията cron и състоянието на статичното предварително генериране, които принадлежат на тази инсталация. Оставя чуждите drop-in файлове и конфигурационните файлове непокътнати и позволява повторното активиране да започне на чисто.

Следващи стъпки