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
- Build. CI menginstal dependensi produksi Composer.
- Upload. Tema, termasuk
vendor/, dikirim ke server. - Rekonsiliasi halaman.
wp bs pages syncmenyelaraskan posting halaman dengan file dan mencetak laporan. - Segarkan cache origin. HTML yang tersimpan dihapus saat halaman berubah, lalu dihangatkan kembali.
- 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:
{
"require": {
"blockstudio/blockstudio": "^7.0"
}
}
<?php
require_once __DIR__ . '/vendor/autoload.php';
Di CI, instal tanpa paket pengembangan:
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/. Arahkancache.pathke volume khusus yang dapat ditulisi jika Anda menginginkannya. Mengubah jalur akan membuat cache kosong. - Aset blok yang dikompilasi secara default ditulis ke folder
_distdi samping setiap blok. Jika direktori rilis Anda hanya-baca atau diganti pada setiap deploy, aturassets.outputkecacheagar aset disimpan di direktori cache sebagai gantinya:
{
"$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:
wp bs pages sync --format=json
Di situs yang temanya memiliki dua halaman, about dan contact, proses pertama
membuatnya:
{
"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, danfailedmenghitung 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.
fullReconciliationmelaporkan apakah proses tersebut dihitung sebagai rekonsiliasi penuh:truepada proses pertama, dengan--full, atau saat mesin sinkronisasi itu sendiri berubah, danfalsesaat identitas dari sinkronisasi sebelumnya yang berhasil tersedia. Perangkat hilir dapat menggunakannya untuk menentukan apakah semuanya perlu dibangun ulang. sourceIdentityadalah 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:
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:
{
"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:
#!/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:
{"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.
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:
wp bs cache status
wp bs cache cleanup
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:
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
- Membangun Halaman Berbasis File: halaman yang direkonsiliasi oleh deploy ini.
- Referensi halaman: perilaku sinkronisasi, PHP rekonsiliasi API, dan kontrak identitas deploy.
- Referensi CLI: setiap perintah
wp bs. - Caching: lokasi cache, identitas, retensi, dan tumpukan kunci.
- Menyajikan WordPress sebagai HTML statis: cache yang disegarkan pada langkah 4.
- Composer: instalasi plugin, must-use, tema, dan bundel plugin.