نشر موقع Blockstudio
يكفي نسخ مجلد القالب إلى الخادم لتوفير الكتل: يكتشفها Blockstudio من نظام الملفات، وتلاحظ ذاكرات التخزين المؤقت تغيّر المدخلات تلقائيًا. لكن الموقع الفعلي يتضمن أجزاء أخرى. لا تصل الصفحات المعتمدة على الملفات إلى قاعدة البيانات إلا عند مزامنتها. ويواصل العرض المسبق الثابت تقديم نسخة الأمس من HTML إلى أن يستبدلها شيء ما. كما يواصل CDN الموجود في الواجهة تقديم المحتوى الذي خزّنه.
يبني هذا الدليل عملية نشر لقالب اسمه acme يضمّ Blockstudio عبر Composer. ويشرح ما يُشغّل في CI، وما يُشغّل على الخادم بعد وصول الملفات، وكيفية قراءة تقرير مزامنة الصفحات، وأوامر wp bs التي ينبغي أن يتضمنها الإصدار.
الإصدار في صورة واحدة
- البناء. يثبّت CI اعتماديات Composer للإنتاج.
- الرفع. يصل القالب، بما فيه
vendor/، إلى الخادم. - التوفيق بين الصفحات. تجعل
wp bs pages syncمنشورات الصفحات متوافقة مع الملفات وتطبع تقريرًا. - تحديث ذاكرة التخزين المؤقت للمصدر. تُمسح HTML المخزّنة عند تغيّر الصفحات، ثم تُملأ من جديد.
- مسح CDN. أخيرًا، لكي يعيد الطرف تحديث محتواه من مصدر محدّث.
تتطلب الخطوتان 3 و4 وجود WP-CLI على الخادم. كما يستخدم البرنامج النصي أدناه jq لقراءة JSON.
الخطوة 1: Composer في CI
ضمّن Blockstudio في القالب وأدرج composer.lock في الالتزام، لكي يثبّت CI الإصدار نفسه الذي اختبرته:
{
"require": {
"blockstudio/blockstudio": "^7.0"
}
}
<?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لتُحفظ الأصول ضمن مجلد ذاكرة التخزين المؤقت بدلًا من ذلك:
{
"$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، ينشئهما التشغيل الأول:
{
"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، الذي لا يكون طرفية، يُفصل بين قيم الصف بعلامات جدولة:
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 مشوّهًا على النحو التالي:
{
"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 في قائمة الانتظار، وفشل عرضها جميعًا:
{"queued":6,"processed":4,"warmed":0,"skipped":0,"failed":4}
يبقى URL الذي يفشل عرضه قديمًا ويُضاف إلى قائمة الانتظار مجددًا في التشغيل التالي؛ لهذا تتوقف الحلقة عند أول دورة لا تُهيئ فيها شيئًا بدلًا من انتظار إفراغ القائمة. وتتولى أداة التهيئة المجدولة أو الزيارة المجهولة التالية معالجة ما تبقى.
في وضع graph، تتوقف أداة التهيئة لكل URL، ولا يضيف warm أي شيء إلى قائمة الانتظار. تستبدل مواقع Graph الخطوتين 2 و3 بعملية بناء خاصة بها، تعرض عناوين URL المتأثرة وتفعّل النتيجة ذريًا. راجع أوضاع التوقيع والرسم البياني.
الخطوة 5: سير عمل CI
سير العمل أدناه مثال على GitHub Actions. وينطبق هذا النهج على أي نظام CI: أنشئ البناء، وارفعه، وشغّل النص البرمجي على الخادم، وامسح 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 مع 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
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 وحالة العرض المسبق الثابت التي يملكها هذا التثبيت، ويترك الإضافات المؤقتة وملفات الإعدادات الخارجية كما هي، ويتيح إعادة التفعيل لاحقًا من دون بقايا.
الخطوات التالية
- إنشاء صفحات قائمة على الملفات: الصفحات التي تسويها عملية النشر هذه.
- مرجع الصفحات: سلوك المزامنة وPHP التسوية وAPI وعقد هوية النشر.
- مرجع CLI: جميع أوامر
wp bs. - التخزين المؤقت: موقع ذاكرة التخزين المؤقت والهوية والاحتفاظ وتراكم الأقفال.
- تقديم WordPress كـHTML ثابت: ذاكرة التخزين المؤقت التي تحدّثها الخطوة 4.
- Composer: عمليات تثبيت الإضافات والإضافات الإلزامية والقوالب والحزم.