Перейти к содержимому

Развёртывание сайта на Blockstudio

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

В этом руководстве настраивается развёртывание темы под названием acme, которая включает Blockstudio через Composer. Рассматривается, что выполняется в CI и на сервере после загрузки файлов, как читать отчёт о синхронизации страниц и какие команды wp bs включать в релиз.

Релиз на одной схеме

  1. Сборка. CI устанавливает производственные зависимости Composer.
  2. Загрузка. Тема, включая vendor/, попадает на сервер.
  3. Синхронизация страниц. wp bs pages sync приводит записи страниц в соответствие с файлами и выводит отчет.
  4. Обновление кэша источника. Сохраненный HTML очищается, если страницы изменились, затем кэш заполняется заново.
  5. Очистка CDN. В последнюю очередь, чтобы периферийный узел загрузил данные из обновленного источника.

Для шагов 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 заменяет управляемое содержимое данными из файлов и может снять блокировку синхронизации страниц. Используйте этот параметр, когда приоритет у файлов: например, при сбросе тестового сайта или сайта, где никто не редактирует страницы, созданные из файлов, в редакторе. Не добавляйте его в каждое развертывание сайта, которым активно пользуются редакторы.

--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, он остается устаревшим и снова попадает в очередь при следующем запуске. Поэтому цикл останавливается при первом запуске, который не обновил ни одной записи, а не ждет опустошения очереди. Оставшиеся записи будут обработаны плановым обновлением кэша или при следующем анонимном посещении.

В режиме graph обновление кэша для каждого URL отключено, а warm ничего не ставит в очередь. Для графовых сайтов шаги 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 и не удаляет надстройку ранней отдачи. Перед удалением зависимости выполните:

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

Команда удаляет принадлежащие этой установке события cron и состояние статической предварительной генерации, оставляет посторонние надстройки и файлы конфигурации нетронутыми и обеспечивает чистое повторное включение в будущем.

Следующие шаги