Lewati ke konten

Menerapkan Situs Blockstudio

Menyalin folder tema ke server sudah cukup untuk blok: Blockstudio menemukannya di sistem berkas, dan cache-nya mendeteksi sendiri masukan yang berubah. Situs sungguhan memiliki komponen lain. Halaman berbasis berkas baru masuk ke basis data setelah disinkronkan. Prarender statis terus menyajikan HTML kemarin sampai ada yang menggantikannya. CDN di depannya terus menyajikan apa pun yang telah di-cache.

Panduan ini menyusun penerapan untuk tema bernama acme yang menyertakan Blockstudio melalui Composer. Panduan ini mencakup proses yang berjalan di CI, proses yang berjalan di server setelah berkas tiba, cara membaca laporan sinkronisasi halaman, dan perintah wp bs mana yang perlu disertakan dalam rilis.

Gambaran Umum Rilis

  1. Build. CI menginstal dependensi produksi Composer.
  2. Upload. Tema, termasuk vendor/, dikirim ke server.
  3. Rekonsiliasi halaman. wp bs pages sync menyelaraskan posting halaman dengan file dan mencetak laporan.
  4. Segarkan cache origin. HTML yang tersimpan dihapus saat halaman berubah, lalu dihangatkan kembali.
  5. Hapus CDN. Terakhir, agar edge mengisi ulang dari origin yang segar.

Langkah 3 dan 4 memerlukan WP-CLI di server. Skrip di bawah juga menggunakan jq untuk membaca JSON.

Langkah 1: Composer di CI

Bundel Blockstudio di dalam tema dan commit composer.lock, agar CI menginstal versi persis yang Anda uji:

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

Di CI, instal tanpa paket pengembangan:

Shell
composer install --no-dev --optimize-autoloader --no-interaction --prefer-dist

Blockstudio memulai dari autoloader, dan dependensi runtime-nya sendiri sudah dibundel dan diberi namespace di dalam paket. Saat dimuat dari direktori vendor/, updater GitHub bawaannya dinonaktifkan, sehingga Composer tetap menjadi satu-satunya cara untuk mengubah versi.

Langkah 2: Tentukan apa yang harus dapat ditulisi

Blockstudio menulis file yang dihasilkan saat runtime. Ketahui lokasinya sebelum deploy mengganti atau mengunci sebuah direktori:

  • Cache runtime secara default berada di bawah wp-content/blockstudio/cache/. Arahkan cache.path ke volume khusus yang dapat ditulisi jika Anda menginginkannya. Mengubah jalur akan membuat cache kosong.
  • Aset blok yang dikompilasi secara default ditulis ke folder _dist di samping setiap blok. Jika direktori rilis Anda hanya-baca atau diganti pada setiap deploy, atur assets.output ke cache agar aset disimpan di direktori cache sebagai gantinya:
JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "assets": {
    "output": "cache"
  }
}

Anda tidak perlu mengosongkan cache saat deploy. Setiap entri cache menggunakan kunci berdasarkan inputnya, termasuk file blok, pengaturan, tema dan plugin aktif, serta versi WordPress, PHP, dan Blockstudio, jadi rilis yang mengubahnya akan mendapat kunci baru. Di production dan staging, Blockstudio mempercayai snapshot pantauan yang tervalidasi selama 20 detik sebelum memeriksa file lagi, sehingga perubahan dapat memerlukan waktu hingga 20 detik untuk terdeteksi. Filter blockstudio/cache/watch_debounce mengubah rentang waktu tersebut.

Langkah 3: Rekonsiliasi halaman

Posting halaman hanya berubah melalui sinkronisasi eksplisit. Permintaan frontend, admin, Ajax, REST, cron, dan permintaan WP-CLI biasa tidak pernah menemukan sumber halaman atau menulis posting halaman. Deploy harus menjalankan perintah:

Shell
wp bs pages sync --format=json

Di situs yang temanya memiliki dua halaman, about dan contact, proses pertama membuatnya:

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

Cara membacanya:

  • created, updated, unchanged, removed, dan failed menghitung halaman. Halaman yang sidik jari sumbernya tidak berubah tidak menghasilkan penulisan posting atau metadata posting, dan tidak memicu hook pembaruan.
  • Setiap proses membandingkan inventaris halaman secara lengkap. fullReconciliation melaporkan apakah proses tersebut dihitung sebagai rekonsiliasi penuh: true pada proses pertama, dengan --full, atau saat mesin sinkronisasi itu sendiri berubah, dan false saat identitas dari sinkronisasi sebelumnya yang berhasil tersedia. Perangkat hilir dapat menggunakannya untuk menentukan apakah semuanya perlu dibangun ulang.
  • sourceIdentity adalah sidik jari deterministik dari inventaris halaman dan mesin sinkronisasi. Perintah menyimpannya setelah proses berhasil.

Tanpa --format=json, perintah mencetak satu baris ringkasan dan baris keberhasilan. Dalam log CI yang bukan terminal, baris tersebut dipisahkan tab:

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

Proses itu dilakukan setelah pengeditan about/index.php: satu halaman diperbarui, satu halaman tidak berubah.

Saat sinkronisasi gagal

Perintah keluar dengan status 1 saat penemuan atau rekonsiliasi melaporkan kesalahan, sehingga langkah CI gagal. Laporan JSON tetap dicetak, jadi simpanlah di log. page.json yang formatnya salah terlihat seperti ini:

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

Halaman terkelola yang sumbernya hilang hanya dipangkas setelah proses selesai tanpa kesalahan, sehingga rilis yang gagal disinkronkan tidak menghapus halaman aktif. Halaman yang dihapus secara default dipindahkan ke tempat sampah; filter blockstudio/pages/orphan_action dapat mengembalikan trash, delete, atau keep.

Jalankan setiap deploy

Jalankan sinkronisasi meski tidak ada halaman yang berubah. Jika Anda melakukan deploy ke direktori rilis lalu mengganti symlink, halaman yang tidak berubah tetap menunjuk ke jalur templat dan tata letak rilis sebelumnya sampai sinkronisasi berikutnya memperbaruinya. Pembaruan itu tidak menyentuh post_content atau tanggal modifikasi.

--authoritative dan --full

Sinkronisasi biasa mempertahankan konten yang diubah editor di dalam blok berkunci. --authoritative mengganti konten terkelola dengan konten dari file, dan mungkin menghapus kunci Sinkronisasi Halaman. Gunakan saat konten file harus diutamakan: untuk mengatur ulang situs staging, atau situs tempat tidak ada yang mengedit halaman berbasis file di editor. Jangan sertakan ini di setiap deploy situs yang memiliki editor aktif.

--full menandai proses sebagai rekonsiliasi penuh tanpa memedulikan identitas yang tersimpan. Perbandingan halaman sudah lengkap pada setiap proses, jadi flag ini mengubah fullReconciliation dalam laporan, bukan halaman yang diperiksa. Sertakan flag ini jika langkah berikutnya menggunakan nilai tersebut untuk menentukan pembangunan ulang penuh.

Perangkat yang ditulis dalam PHP dapat memanggil Blockstudio\Pages::reconcile() secara langsung. Fungsi ini mengembalikan laporan yang sama, tetapi tidak menyimpan identitas: panggil Blockstudio\Pages::store_successful_source_identity() setelah bagian rilis lainnya, seperti artefak statis yang telah diaktifkan, terverifikasi.

Langkah 4: Segarkan cache statis

Jika situs menggunakan prerendering statis dalam mode signature bawaan, posting halaman yang diperbarui dari WP-CLI tidak menghapus HTML tersimpan dengan sendirinya. Baca laporan dan hapus cache jika ada perubahan, lalu hangatkan:

Shell
#!/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}'

Setiap proses wp bs prerender warm memasukkan URL publik yang sudah usang ke antrean, merender hingga warm.concurrency URL, dan mencetak ringkasan. Dalam proses ini, empat dari enam URL yang diantrekan diklaim dan keempatnya gagal dirender:

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

URL yang gagal dirender tetap usang dan dimasukkan kembali ke antrean pada proses berikutnya, karena itu loop berhenti pada proses pertama yang tidak menghangatkan apa pun, alih-alih menunggu antrean kosong. Item yang tersisa akan diambil oleh penghangat terjadwal atau kunjungan anonim berikutnya.

Dalam mode graph, penghangat per-URL dinonaktifkan dan warm tidak memasukkan apa pun ke antrean. Situs Graph mengganti langkah 2 dan 3 dengan build-nya sendiri, yang merender URL terdampak dan mengaktifkan hasilnya secara atomik. Lihat mode tanda tangan dan graph.

Langkah 5: Alur kerja CI

Alur kerja di bawah ini adalah contoh GitHub Actions. Polanya dapat diterapkan pada sistem CI mana pun: build, upload, jalankan skrip di server, hapus 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 dengan cancel-in-progress: false mengantrekan push kedua di belakang proses deploy yang sedang berjalan, alih-alih membatalkannya di tengah sinkronisasi. PHP 8.2 adalah versi minimum Blockstudio. Ganti langkah terakhir dengan CDN untuk menghapus API.

Perintah pemeliharaan

Perintah ini tidak perlu dijalankan pada setiap rilis, tetapi panduan deploy harus mencantumkannya.

Mengosongkan tumpukan kunci lama. Rilis sebelum 7.6.14 meninggalkan file .build.lock untuk setiap perubahan konten. Setelah peningkatan, WP-Cron menghapusnya dalam batch terbatas. Untuk memeriksa dan mengosongkan seluruh tumpukan sekaligus:

Shell
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 membiarkan kunci yang berumur kurang dari satu jam atau masih dipegang oleh permintaan aktif agar diproses pada putaran berikutnya. Jangan pernah menghapus file kunci secara manual saat situs melayani lalu lintas.

Mengosongkan cache runtime. wp bs cache clear menghapus semua cache untuk situs saat ini, sedangkan wp bs cache clear --scope=runtime menghapus satu cakupan di seluruh namespace. Permintaan berikutnya akan membangun ulang cache dari awal, jadi jalankan saat lalu lintas rendah dan hanya jika ada alasan: perubahan input sudah memperbarui kuncinya.

Menghapus Blockstudio. Instalasi Composer tidak memiliki hook penonaktifan plugin, sehingga tidak ada yang membatalkan penjadwalan peristiwa cron atau menghapus drop-in layanan awal saat paket dihapus. Jalankan ini sebelum menghapus dependensi:

Shell
wp bs teardown

Perintah ini menghapus peristiwa cron dan status prerender statis yang dimiliki instalasi ini, membiarkan drop-in dan file konfigurasi pihak lain apa adanya, serta memastikan pengaktifan kembali nanti bisa dimulai dengan bersih.

Langkah berikutnya