Перейти до вмісту

Розгортання сайту Blockstudio

Для блоків достатньо скопіювати папку теми на сервер: Blockstudio знаходить їх у файловій системі, а його кеші самостійно виявляють змінені дані. У реального сайту є й інші складові. Сторінки на основі файлів потрапляють до бази даних лише після синхронізації. Статично попередньо згенерована сторінка й далі показує вчорашній HTML, доки його не замінять. Розташований попереду CDN продовжує показувати те, що зберіг у кеші.

У цьому посібнику налаштовується розгортання теми acme, яка містить Blockstudio, зібраний за допомогою Composer. Розглянуто, що виконується в CI та на сервері після завантаження файлів, як читати звіт про синхронізацію сторінок і які команди wp bs мають входити до випуску.

Випуск в одній схемі

  1. Збірка. CI встановлює Composer залежності для production.
  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 завантажується через автозавантажувач, а його власні залежності середовища виконання вбудовані в пакет і мають окремий простір імен. Коли він завантажується з каталогу vendor/, вбудований засіб оновлення GitHub вимкнений, тож Composer залишається єдиним способом змінити версію.

Крок 2: Визначте, що має бути доступним для запису

Blockstudio створює файли під час виконання. Заздалегідь визначте, де саме, перш ніж розгортання замінить каталог або заблокує його:

  • Кеші середовища виконання за замовчуванням зберігаються в 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: Синхронізація сторінок

Записи сторінок змінюються лише під час явної синхронізації. Запити з фронтенду, адмінпанелі, 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. Замініть останній крок очищенням CDN за допомогою API.

Команди обслуговування

Ці команди не потрібні під час кожного релізу, але їх слід знати для інструкцій із розгортання.

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

Очищення кешу середовища виконання. wp bs cache clear очищує весь кеш поточного сайту, а wp bs cache clear --scope=runtime — одну область у всіх просторах імен. Після цього наступний запит заново створить кеш, тому запускайте команду за низького трафіку й лише за потреби: зміни вхідних даних і так оновлюють ключі.

Видалення Blockstudio. Установлення як Composer не має хуку деактивації плагіна, тож після зникнення пакета ніщо не скасовує заплановані події cron і не видаляє drop-in для раннього обслуговування. Запустіть цю команду перед видаленням залежності:

Командна оболонка
wp bs teardown

Команда видаляє події cron і стан статичного попереднього рендерингу, створений цією інсталяцією, не зачіпає сторонні drop-in-файли та файли конфігурації й дає змогу чисто ввімкнути її знову пізніше.

Наступні кроки