본문으로 건너뛰기

Blockstudio 사이트 배포

테마 폴더를 서버에 복사하는 것만으로 블록을 배포할 수 있습니다. Blockstudio은 파일 시스템에서 블록을 찾고, 캐시는 변경된 입력을 자동으로 감지합니다. 실제 사이트에는 더 많은 구성 요소가 있습니다. 파일 기반 페이지는 동기화해야 데이터베이스에 반영됩니다. 정적 사전 렌더링은 새로 교체할 때까지 어제의 HTML을 계속 제공합니다. 앞단의 CDN는 캐시해 둔 내용을 계속 제공합니다.

이 가이드에서는 acme이라는 테마를 Composer를 통해 Blockstudio를 번들링하는 배포를 구성합니다. CI에서 실행할 작업, 파일 배포 후 서버에서 실행할 작업, 페이지 동기화 보고서 확인 방법, 릴리스에 포함해야 할 wp bs 명령을 다룹니다.

릴리스 한눈에 보기

  1. 빌드. CI가 프로덕션 Composer 종속 항목을 설치합니다.
  2. 업로드. vendor/을 포함한 테마가 서버에 도착합니다.
  3. 페이지 동기화. wp bs pages sync가 페이지 게시물을 파일과 일치시키고 보고서를 출력합니다.
  4. 원본 캐시 새로 고침. 페이지가 변경되면 저장된 HTML를 삭제한 다음 다시 채웁니다.
  5. CDN 삭제. 마지막으로 수행하여 엣지 캐시가 새 원본에서 다시 채워지도록 합니다.

3단계와 4단계는 서버에 WP-CLI가 필요합니다. 아래 스크립트는 JSON를 읽기 위해 jq도 사용합니다.

1단계: CI에서 Composer

테마에 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는 해당 실행을 전체 동기화로 간주할지 보고합니다. 첫 실행, --full이 있는 경우 또는 동기화 엔진 자체가 변경된 경우에는 true이며, 이전에 성공한 동기화의 식별자가 있으면 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 6개 중 4개가 처리 대상으로 선택되었고, 네 개 모두 렌더링에 실패했습니다:

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 이벤트와 정적 사전 렌더링 상태를 제거하고, 외부 드롭인과 설정 파일은 그대로 두며, 나중에 다시 활성화할 때 깨끗하게 시작하도록 합니다.

다음 단계