Implementar un sitio Blockstudio
Para los bloques, basta con copiar la carpeta del tema al servidor: Blockstudio los detecta en el sistema de archivos y sus cachés detectan los cambios en las entradas por sí solas. Un sitio real tiene más componentes. Las páginas basadas en archivos solo llegan a la base de datos cuando se sincronizan. Una renderización previa estática sigue sirviendo el HTML de ayer hasta que algo lo reemplaza. Un CDN delante sigue sirviendo lo que almacenó en caché.
Esta guía configura el despliegue de un tema llamado acme que incluye Blockstudio mediante Composer. Explica qué se ejecuta en CI, qué se ejecuta en el servidor después de copiar los archivos, cómo leer el informe de sincronización de páginas y qué comandos wp bs incluir en una versión.
La versión de un vistazo
- Compilar. CI instala las dependencias de producción Composer.
- Subir. El tema, incluido
vendor/, llega al servidor. - Sincronizar las páginas.
wp bs pages syncpone las entradas de página al día con los archivos e imprime un informe. - Actualizar la caché del origen. Se purga HTML almacenado si las páginas cambiaron, y luego se vuelve a calentar.
- Purgar CDN. Al final, para que el edge vuelva a cargar contenido desde un origen actualizado.
Los pasos 3 y 4 necesitan WP-CLI en el servidor. El script siguiente también usa jq para
leer JSON.
Paso 1: Composer en CI
Incluye Blockstudio en el tema y confirma composer.lock para que CI instale la
versión exacta que probaste:
{
"require": {
"blockstudio/blockstudio": "^7.0"
}
}
<?php
require_once __DIR__ . '/vendor/autoload.php';
En CI, instala sin los paquetes de desarrollo:
composer install --no-dev --optimize-autoloader --no-interaction --prefer-dist
Blockstudio se inicia desde el autocargador y sus propias dependencias de ejecución
están incluidas y con espacio de nombres dentro del paquete. Cuando se carga desde un directorio vendor/,
su actualizador GitHub integrado se desactiva, de modo que Composer sigue siendo la única
forma de cambiar la versión.
Paso 2: Decide qué debe poder escribirse
Blockstudio escribe archivos generados durante la ejecución. Averigua dónde antes de que un despliegue reemplace o bloquee un directorio:
- Las cachés de ejecución están en
wp-content/blockstudio/cache/de forma predeterminada. Si lo prefieres, apuntacache.patha un volumen dedicado con permisos de escritura. Al cambiar la ruta, la caché empieza vacía. - Los recursos compilados de bloques se escriben por defecto en una carpeta
_distjunto a cada bloque. Si el directorio de la versión es de solo lectura o se reemplaza en cada despliegue, estableceassets.outputencachepara guardarlos en el directorio de caché en su lugar:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"assets": {
"output": "cache"
}
}
No hace falta borrar las cachés durante el despliegue. Cada entrada de caché se identifica por sus
entradas, incluidos los archivos de bloques, los ajustes, el tema y los plugins activos, y las
versiones de WordPress, PHP y Blockstudio, así que una versión que los cambie tendrá claves nuevas. En production y staging, Blockstudio confía en una instantánea de vigilancia validada durante 20 segundos antes de volver a comprobar los archivos, por lo que puede tardar hasta 20 segundos en detectar un cambio. El filtro blockstudio/cache/watch_debounce modifica ese intervalo.
Paso 3: Sincronizar las páginas
Las entradas de página solo cambian mediante una sincronización explícita. Las solicitudes del frontend, del administrador, Ajax, REST, cron y las solicitudes normales de WP-CLI nunca descubren fuentes de páginas ni escriben entradas de página. El despliegue debe solicitarlo:
wp bs pages sync --format=json
En un sitio cuyo tema tiene dos páginas, about y contact, la primera ejecución
las crea:
{
"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": []
}
Cómo interpretarlo:
created,updated,unchanged,removedyfailedcuentan las páginas. Si la huella de origen de una página no cambia, no se escriben entradas ni metadatos de entrada y no se activan hooks de actualización.- Cada ejecución compara el inventario completo de páginas.
fullReconciliationindica si la ejecución cuenta como una sincronización completa:trueen la primera ejecución, con--fullo cuando cambia el propio motor de sincronización, yfalsecuando existe una identidad de una sincronización anterior correcta. Las herramientas posteriores pueden usarlo para decidir si deben reconstruirlo todo. sourceIdentityes una huella determinista del inventario de páginas y del motor de sincronización. El comando la guarda tras una ejecución correcta.
Sin --format=json, el comando imprime una fila de resumen y una línea de éxito.
En un registro de CI, que no es una terminal, la fila está separada por tabulaciones:
discovered created updated unchanged removed failed source_id
2 0 1 1 0 0 7bd575b4ee6c0a948f439dd83ce5fa403f8113c9406c3b13b6ade2f2b19f3c2c
Success: File-backed pages synchronized.
Esa ejecución se realizó después de editar about/index.php: una página se actualizó y otra
no cambió.
Si falla la sincronización
El comando termina con el estado 1 si el descubrimiento o la sincronización indican un
error, lo que hace fallar el paso de CI. Aun así, se imprime el informe JSON, así que guárdalo en el registro.
Un page.json mal formado se ve así:
{
"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"
}
}
]
}
Las páginas gestionadas cuyas fuentes han desaparecido solo se eliminan después de que una ejecución termine
sin errores, de modo que un lanzamiento cuyo proceso de sincronización falla no elimina páginas activas. Las páginas eliminadas
van a la papelera de forma predeterminada; el filtro blockstudio/pages/orphan_action puede
devolver trash, delete o keep.
Ejecútala en cada despliegue
Ejecuta la sincronización aunque no haya cambiado ninguna página. Si despliegas en directorios de versiones
y cambias un enlace simbólico, una página sin cambios sigue apuntando a las rutas de plantilla y diseño de la versión
anterior hasta que la siguiente sincronización las actualiza. Esa actualización no modifica post_content ni la fecha de modificación.
--authoritative y --full
Una sincronización normal conserva el contenido que los editores hayan modificado dentro de bloques con clave.
--authoritative sustituye en cambio el contenido gestionado por el de los archivos y puede
eliminar un bloqueo de Page Sync. Úsalo cuando los archivos deban prevalecer: al restablecer un sitio
de pruebas o en uno donde nadie edite en el editor las páginas basadas en archivos.
No lo incluyas en cada despliegue de un sitio con editores activos.
--full marca la ejecución como una sincronización completa independientemente de la identidad guardada.
La comparación de páginas ya se completa en cada ejecución, por lo que la marca
cambia fullReconciliation del informe, no qué páginas se comprueban. Pásala
si un paso posterior usa ese valor para decidir si hace una reconstrucción completa.
Las herramientas escritas en PHP pueden llamar directamente a Blockstudio\Pages::reconcile().
Devuelve el mismo informe, pero no guarda la identidad: llama a
Blockstudio\Pages::store_successful_source_identity() cuando hayas verificado el resto del
lanzamiento, por ejemplo, un artefacto estático activado.
Paso 4: Actualizar la caché estática
Si el sitio usa prerenderizado estático en el
modo signature predeterminado, las entradas de página actualizadas desde WP-CLI no purgan por sí solas la
HTML almacenada. Lee el informe y purga si hubo cambios; después, calienta la caché:
#!/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}'
Cada ejecución de wp bs prerender warm pone en cola las URL públicas obsoletas, renderiza hasta
warm.concurrency de ellas e imprime un resumen. En esta ejecución, se reclamaron cuatro de las seis
URL en cola y no se pudo renderizar ninguna de las cuatro:
{"queued":6,"processed":4,"warmed":0,"skipped":0,"failed":4}
Si una URL no se puede renderizar, sigue obsoleta y vuelve a ponerse en cola en la siguiente ejecución. Por eso el ciclo se detiene tras la primera ejecución que no calienta ninguna, en vez de esperar a que la cola quede vacía. El calentador programado o la siguiente visita anónima se encargarán de lo que quede.
En modo graph, el calentador por URL está desactivado y warm no pone nada en cola. Los sitios Graph
sustituyen los pasos 2 y 3 por su propia compilación, que renderiza las URL afectadas y activa el resultado de forma atómica. Consulta
los modos de firma y gráfico.
Paso 5: El flujo de trabajo de CI
El flujo de trabajo siguiente es un ejemplo de GitHub Actions. La misma estructura sirve para cualquier sistema de CI: compilar, subir, ejecutar el script en el servidor y purgar 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 con cancel-in-progress: false pone una segunda publicación en cola detrás de un
lanzamiento en curso, en vez de cancelarlo a mitad de una sincronización. La versión 8.2 de PHP es la mínima de Blockstudio. Sustituye el último paso por la CDN de purga API.
Comandos de mantenimiento
No forman parte de cada lanzamiento, pero conviene incluirlos en la guía de despliegue.
Vaciar la cola de bloqueos heredados. Las versiones anteriores a 7.6.14 dejaban un
archivo .build.lock por cada cambio de contenido. Después de actualizar, WP-Cron
los elimina en lotes limitados. Para comprobarlos y vaciar toda la cola de una vez:
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 deja para la siguiente ejecución los bloqueos de hace menos de una hora o que sigan activos por una solicitud en curso.
Nunca elimines archivos de bloqueo manualmente mientras el sitio esté atendiendo tráfico.
Borrar la caché de ejecución. wp bs cache clear purga todo para el
sitio actual y wp bs cache clear --scope=runtime purga un ámbito en todos
los espacios de nombres. La siguiente solicitud reconstruirá la caché desde cero, así que ejecútalo cuando haya poco tráfico y
solo si tienes un motivo: los cambios en las entradas ya renuevan las claves.
Eliminar Blockstudio. Una instalación Composer no tiene un hook de desactivación de plugin, por lo que al desaparecer el paquete no se eliminan los eventos cron programados ni el complemento de atención temprana. Ejecuta esto antes de quitar la dependencia:
wp bs teardown
Elimina los eventos cron y el estado de prerenderizado estático que pertenece a esta instalación, deja intactos los complementos y archivos de configuración ajenos, y permite volver a activarla sin residuos.
Pasos siguientes
- Crear páginas basadas en archivos: las páginas que sincroniza este despliegue.
- Referencia de páginas: comportamiento de sincronización, PHP de sincronización API y contrato de identidad del despliegue.
- Referencia de CLI: todos los comandos de
wp bs. - Almacenamiento en caché: ubicación de la caché, identidad, retención y cola de bloqueos.
- Servir WordPress como HTML estático: la caché que actualiza el paso 4.
- Composer: instalaciones como plugin, must-use, de tema y con plugin incluido.