Actualizaciones

Las actualizaciones en WebBlocks CMS se basan en versiones publicadas y en paquetes.

• La versión instalada refleja la última versión real aplicada a la instalación.
• El desarrollo ordinario del código fuente no cambia la versión instalada.
• El actualizador integrado aplica paquetes de versiones publicadas, no cambios locales del árbol de trabajo.
• Los consumidores nuevos de Composer deben instalar primero con composer require fklavyenet/webblocks-cms y php artisan webblocks:install antes de usar el flujo normal de actualización basado en versiones.
• Las instalaciones actuales nativas de paquete consumen directamente los ZIP de versión con raíz de paquete.
• Las System Updates nativas de paquete aplican el artefacto del paquete a la raíz canónica del paquete de Composer, vendor/fklavyenet/webblocks-cms, de modo que la actualización con Composer y la System Update producen la misma estructura de paquete instalada.
• Históricamente, las instalaciones anteriores a la nativa de paquete, como 1.31.53, no podían consumir directamente los ZIP de versión con raíz de paquete y requerían primero el puente gestionado desde la raíz con el formato antiguo 1.32.33. Esa vía de puente está ahora retirada de la validación de versiones rutinaria porque ya no quedan instalaciones antiguas gestionadas desde la raíz a las que dar soporte en los controles normales.

• Ejecute las actualizaciones únicamente desde versiones publicadas.
• Mantenga los archivos propios de la instalación en rutas preservadas como .env, storage/ y project/.
• Trate por separado los flujos de trabajo de desarrollo y de publicación.
• En las copias de trabajo de mantenimiento gestionadas desde el código fuente, las ediciones locales ya están presentes en el árbol de trabajo. Las System Updates no deben usarse para aplicar esos cambios locales, y la versión del código CMS en ejecución se compara con la última versión publicada para determinar si hay actualizaciones disponibles.
• Los paquetes de versión contienen únicamente código reutilizable del núcleo del CMS y no deben incluir contenido project/ propio de la instalación.
• Las rutas preservadas durante la actualización no cambian el límite del paquete de versión: project/ permanece local a la instalación y fuera del artefacto publicado.
• Las copias de trabajo del CMS instaladas son consumidoras de actualizaciones, no publicadoras upstream. Si una instalación tiene un origin de git, conserve el acceso de fetch si lo necesita, pero deshabilite el push con git remote set-url --push origin DISABLED.
• Una System Update se registra como correcta solo después de que el runtime del paquete aplicado informe de la versión de destino desde la fuente de versión canónica WebBlocks\Cms\Support\WebBlocks. Si el código aplicado sigue informando de una versión antigua o inesperada, la ejecución se registra como fallida y los operadores deben restaurar la copia de seguridad previa a la actualización o inspeccionar el estado del sistema de archivos y de la caché antes de reintentar.

Antes de cambiar el comportamiento de compatibilidad de versiones, actualizaciones, publicación, Publisher, artefactos o migraciones del CMS, consulte a WebBlocks Advisor e incluya la respuesta como nota de implementación en el informe. Si Advisor no tiene la respuesta correcta, actualice primero la fuente de conocimiento o el fragmento correspondiente en lugar de inventar un flujo de trabajo puntual.

La pantalla System Updates muestra detalles de la versión legibles antes de que un administrador inicie una actualización. El flujo principal tiene dos tarjetas: Install Update y Update Details. Install Update explica si hay una actualización disponible, si la versión del código CMS en ejecución está al día, si la versión local o de código fuente es más reciente que el último paquete publicado, si la actualización es incompatible o si no se puede confiar en la respuesta del servidor de actualizaciones. El resumen visible compara la versión del código CMS en ejecución con la última versión publicada. La versión instalada almacenada sigue siendo un valor de historial de instalación y persistencia de actualizaciones y puede consultarse en Update Readiness, pero no se utiliza para habilitar la acción Install Update.

Update Details mantiene las notas de la versión, la preparación para actualizar y la última ejecución de actualización detrás de filas de acordeón de WebBlocks UI. Update Readiness es un resumen de preparación de la instalación y del servicio de actualización, no las notas de la versión de destino. Last Update Run muestra el resumen de la ejecución relevante más reciente y abre los detalles en un modal cuando es necesario. Hay disponible una descarga de informe de soporte para superadministradores destinada a casos de soporte en alojamiento compartido; incluye resúmenes seguros de versión, preparación y ejecuciones, y excluye tokens, secretos, rutas locales absolutas y trazas de pila en bruto.

Los registros de ejecuciones de actualización se depuran automáticamente tras las comprobaciones de actualización y los flujos de aplicación o cancelación. La retención predeterminada conserva las cinco ejecuciones más recientes, mientras que la última ejecución fallida se conserva hasta que exista una ejecución correcta más reciente. La pantalla principal de administración no lista las ejecuciones antiguas. Los operadores con acceso al terminal pueden inspeccionar las ejecuciones conservadas con php artisan webblocks:updates:runs, php artisan webblocks:updates:runs --last y php artisan webblocks:updates:runs --failed; la depuración controlada está disponible con php artisan webblocks:updates:prune-runs --keep=5.

El acordeón compacto Release Notes de Update Details representa metadatos estructurados a partir de campos como title, summary, highlights, fixes, compatibility_notes, migration_notes, asset_notes, operator_notes y technical_notes. El CMS representa esos campos como texto plano escapado y mantiene las comprobaciones de preparación, la versión instalada almacenada y los detalles de respuesta de bajo nivel en Update Readiness.

La cadena heredada release_notes sigue estando admitida para cargas útiles de versiones antiguas. Si no hay notas de versión, la pantalla indica No release notes were provided for this release. El actualizador no deduce cambios a partir de los números de versión.

Los metadatos de la versión se preparan localmente con composer release:prepare y se publican directamente en el servicio Publisher con composer release:publish-update. El publicador nativo envía campos estructurados de detalle de versión en formatos de carga útil de nivel superior y anidados, junto con el valor heredado release_notes, de modo que el servicio de actualización pueda ofrecer notas enriquecidas a las pantallas System Updates compatibles mientras los clientes antiguos siguen recibiendo notas en texto plano. Los clientes compatibles leen los detalles estructurados desde los campos de nivel superior, details, release_details y las cargas útiles del servidor de actualizaciones meta.release_details o meta.details.

GitHub Actions ya no crea paquetes de versión ni publica metadatos de actualización, y los flujos de trabajo de .github están intencionadamente ausentes del repositorio del CMS. Los mantenedores pueden seguir enviando commits y etiquetas de git para el historial del código fuente, pero las System Updates consumen únicamente metadatos del servidor de actualizaciones y artefactos de paquete. publisher.webblocksui.com es el servicio canónico tanto para publicar como para consumir actualizaciones: los mantenedores publican en https://publisher.webblocksui.com/api/updates/publish, los sitios CMS instalados leen los últimos metadatos desde https://publisher.webblocksui.com/api/updates/latest y las URL de artefacto de los metadatos deben apuntar a descargas de paquete en https://publisher.webblocksui.com/downloads/.... Los sitios CMS instalados no configuran claves de entorno de Publisher/servidor de actualizaciones, producto o canal en los archivos .env habituales, porque el código de producto del CMS es propietario del servidor de versiones predeterminado, la clave de producto, el canal estable, la ruta de últimos metadatos y la ruta de publicación a través de ReleaseDefaults. El antiguo puente updates.webblocksui.com es solo histórico y no debe utilizarse como ruta de configuración activa.

Comandos del mantenedor:

La publicación por parte del mantenedor normalmente solo necesita WEBBLOCKS_PUBLISHER_TOKEN. Las comprobaciones de actualización del CMS instalado usan los valores predeterminados del producto para https://publisher.webblocksui.com, producto webblocks-cms, canal stable y ruta de lectura /api/updates/latest; la publicación por parte del mantenedor usa la misma identidad propiedad del producto y la ruta de publicación /api/updates/publish. Las ejecuciones de publicación con configuración en caché refrescan únicamente el token del publicador desde el .env del proyecto, de modo que un token configurado localmente se detecta sin necesidad de exportarlo en el shell. La ejecución en seco valida las entradas sin subir nada. Una publicación real sin token informa de un estado controlado de no publicado, termina de forma no satisfactoria y no debe tratarse como una publicación de versión.

Cuando una System Update integrada se aplica correctamente, WebBlocks CMS ejecuta el flujo posterior a la instalación en este orden:

• gestión de migraciones para la estrategia de instalación actual
• pasos de limpieza de caché
• registro de la ejecución de la actualización
• persistencia de la versión instalada

Las System Updates normales aplican paquetes de versiones publicadas. No ejecutan automáticamente la siembra del catálogo del núcleo, block-types:sync-core, la sincronización de iconos, la reparación de tipos de slot, la reparación de slots del layout de página ni la reparación amplia del catálogo. Si una versión requiere una transformación de esquema o de datos, debe gestionarse como una migración de actualización explícita para esa versión.

Los pasos de limpieza de caché incluyen las limpiezas de configuración, vistas, caché de aplicación y rutas de Laravel, de modo que los layouts y ayudantes Blade propiedad del paquete se recompilen tras la sustitución de archivos. En instalaciones PHP-FPM en producción con OPcache configurado para no validar marcas de tiempo, recargue el servicio PHP-FPM correspondiente tras una actualización correcta para que PHP no siga sirviendo desde memoria clases del paquete anteriores a la actualización.

En las copias de trabajo de mantenimiento gestionadas desde el código fuente, la gestión de migraciones conserva la autoridad histórica de la raíz database/migrations y ejecuta artisan migrate --force. Esta ruta se selecciona únicamente cuando el manifiesto de Composer de la raíz tiene la autoridad de autoload de WebBlocks CMS del repositorio de mantenimiento, incluida WebBlocks\\Cms\\ => packages/webblocks-cms/src/.

Para los consumidores nuevos de Composer nativos de paquete instalados con webblocks:install, la System Update no ejecuta el directorio raíz database/migrations de la aplicación Laravel anfitriona. La mera presencia del directorio del paquete no es una señal de copia del código fuente. Esto evita que migraciones iniciales pendientes de Laravel, como 0001_01_01_000000_create_users_table.php, choquen con las tablas del CMS creadas por el esquema de instalación nueva del paquete. Las actualizaciones de los consumidores del paquete aplican el artefacto de versión a vendor/fklavyenet/webblocks-cms y solo ejecutan migraciones de actualización dedicadas propiedad del paquete desde vendor/fklavyenet/webblocks-cms/database/migrations/updates cuando ese directorio contiene archivos de migración PHP; de lo contrario, el actualizador registra que se omitieron las migraciones del anfitrión y continúa con las limpiezas de caché y la persistencia de la versión instalada. Las migraciones de actualización del paquete son también el lugar adecuado para reparaciones seguras del esquema en instalaciones existentes, como añadir claves padre que faltan y que son necesarias para la portabilidad de la copia de seguridad y restauración completa de la base de datos.

Todo cambio de esquema de WebBlocks CMS que requiera el código en ejecución debe admitir ambas rutas de instalación:

1. Instalaciones nuevas o de consumidor del paquete: actualice la ruta de migración de esquema normal o de instalación nueva.
2. Instalaciones nativas de paquete existentes actualizadas mediante System Updates: añada una migración de actualización del paquete en database/migrations/updates del paquete; los consumidores instalados la ejecutan desde vendor/fklavyenet/webblocks-cms/database/migrations/updates.

El esquema de instalación nueva por sí solo no basta. Si el nuevo código en ejecución espera una tabla o una columna, la versión debe incluir una migración de actualización para las instalaciones existentes, o bien la actualización debe fallar de forma segura antes de que la nueva ruta de código pueda provocar un error 500 en bruto. Las System Updates nativas de paquete no deben obligar a los usuarios normales a conectarse por SSH a un sitio y ejecutar migraciones manuales después de una actualización correcta.

Una System Update nativa de paquete correcta significa que el código aplicado, el esquema requerido, las limpiezas de caché y la preparación de versión y esquema posterior a la aplicación están alineados. Las páginas de administración, de API y de tiempo de ejecución que dependan de un esquema recién añadido deben mostrar indicaciones controladas de configuración o actualización ante un esquema ausente, en lugar de exponer errores en bruto del framework o de la base de datos. El incidente de los tokens de API entre 1.32.146 y 1.32.147 es el caso de fallo de referencia: cms_api_tokens existía solo en la ruta de migración normal, QuizTem, nativo de paquete, actualizó el código y System -> API Tokens devolvió un error 500 en bruto hasta que 1.32.147 añadió una migración de actualización del paquete y una gestión correcta de la preparación.

Los informes de versiones con cambios de esquema deben responder explícitamente a:

• ruta de esquema de instalación nueva actualizada: sí/no
• migración de actualización del paquete añadida: sí/no
• prueba de regresión de la migración de actualización añadida: sí/no
• comportamiento correcto ante esquema ausente necesario/añadido: sí/no

Durante la transición a paquete, algunas instalaciones pueden conservar todavía una copia obsoleta packages/webblocks-cms en la raíz de la instalación o una antigua copia anidada de transición en vendor. Esas rutas son artefactos heredados de la transición, no la fuente de verdad nativa de paquete activa. La System Update nativa de paquete sustituye ahora la raíz canónica del paquete de Composer en vendor/fklavyenet/webblocks-cms y verifica la versión de destino desde esa raíz de paquete. No mantiene packages/webblocks-cms como una segunda copia de ejecución actualizada.

Las instalaciones más antiguas pueden tener un directorio vendor de Composer con forma de repositorio en vendor/fklavyenet/webblocks-cms, con archivos raíz como artisan, app/, bootstrap/, packages/webblocks-cms/, plugins/ o tests/. La System Update normaliza ese directorio vendor sustituyéndolo por el artefacto plano con raíz de paquete. La raíz de paquete resultante contiene archivos del paquete como composer.json, src/, docs/, routes/, resources/, database/, public/, config/ y stubs/ directamente bajo vendor/fklavyenet/webblocks-cms. Las actualizaciones nativas de paquete normalizan los metadatos de paquetes instalados de Composer antes de regenerar los archivos de autoload optimizados y, a continuación, verifican que los metadatos de autoload generados por Composer resuelvan WebBlocks\Cms\ desde vendor/fklavyenet/webblocks-cms/src, y no desde la ruta anidada heredada vendor/fklavyenet/webblocks-cms/packages/webblocks-cms/src. Si quedan rutas anidadas obsoletas, la ejecución de la actualización falla en lugar de informar de éxito con un entorno de administración roto.

Las actualizaciones modernas conservan la separación entre la administración en /webadmin y los recursos estáticos en /cms introducida por la migración de la v1.32.56. /cms es únicamente un espacio de nombres de recursos estáticos, no un prefijo de administración, porque el try_files de Nginx puede resolver /cms/ como el directorio físico public/cms/ antes de que Laravel vea una ruta. Las actualizaciones no deben restaurar alias de administración /cms propiedad del CMS, redirecciones /cms, rutas /admin ni un traspaso public/cms/index.php, ni en la raíz de la instalación ni en los recursos públicos del paquete.

Esta sección es histórica. El actualizador de 1.31.53 validaba el antiguo contrato de archivo gestionado desde la raíz: artisan y composer.json debían existir en la raíz del archivo comprimido o dentro de un único directorio envolvente. Los artefactos con raíz de paquete, como 1.32.31, no contenían intencionadamente un artisan en la raíz, por lo que aquellos clientes antiguos fallaban antes de aplicar con Package validation failed because composer.json and artisan were not found at the archive root.

La estrategia de puente retirada constaba de dos pasos:

• Publicar o volver a publicar un artefacto de versión puente con la antigua forma gestionada desde la raíz, construido a partir de una fuente compatible con el puente que todavía contenía los envoltorios heredados App\Support\System\Updates\* y que ya validaba archivos estrictos con raíz de paquete fklavyenet/webblocks-cms. Para el puente 1.32.33, la referencia de origen fue v1.32.30.
• Publicar versiones con raíz de paquete con minimum_client_version fijado en 1.32.18 o posterior, para que a los clientes antiguos no se les ofreciera el último artefacto con raíz de paquete antes del puente.
• Una vez aplicado el puente, el actualizador instalado podía validar y aplicar la forma estricta de artefacto con raíz de paquete fklavyenet/webblocks-cms que utilizan las versiones modernas.

scripts/build-root-managed-bridge-archive.sh VERSION [OUTPUT_DIR] [GIT_REF] se conserva únicamente como herramienta archivada de recuperación manual para el ZIP puente con la forma antigua; por ejemplo, scripts/build-root-managed-bridge-archive.sh 1.32.33 dist v1.32.30. El constructor excluye intencionadamente rutas propiedad de la instalación como .env, storage/, project/, public/site/, public/storage y el config/ raíz; los valores por defecto propiedad del paquete bajo packages/webblocks-cms/config siguen formando parte del runtime del paquete. La validación rutinaria nativa del paquete no ejecuta esta ruta de puente.

La ruta histórica completada fue 1.31.53 -> 1.32.33 bridge -> 1.32.34+ package-rooted. Las instalaciones que ya eran compatibles con el puente, como 1.32.30, se saltaron el puente y se actualizaron directamente a una versión con raíz de paquete 1.32.34+. Los controles de versión actuales protegen únicamente el artefacto con raíz de paquete y el comportamiento del actualizador nativo del paquete.

La reparación y la sincronización del catálogo son acciones de mantenimiento explícitas, independientes de System Updates. Utilice:

El comando admite mantenimiento acotado con --block-types, --slot-types, --page-layouts e --icons. Ejecútelo primero con --dry-run para ver qué filas se crearían, se actualizarían, quedarían sin cambios o se omitirían. El comando es idempotente, conserva las filas de catálogo personalizadas o específicas de la instalación y no elimina filas personalizadas.

La sincronización de tipos de bloque de nivel inferior sigue disponible por compatibilidad:

La ruta de reparación de tipos de bloque mantiene el catálogo block_types almacenado en la base de datos alineado con el catálogo del núcleo del CMS distribuido en las instalaciones existentes:

• se crean los tipos de bloque del núcleo que faltan
• los tipos de bloque del núcleo existentes se actualizan en su sitio
• se conservan los tipos de bloque personalizados propios de la instalación
• no se crean filas duplicadas del núcleo

Este flujo de mantenimiento cubre el caso en que una instalación necesita refrescar filas del catálogo sin obligar a que cada aplicación de un paquete de versión realice una reparación amplia del catálogo en la base de datos.

Cuando el actualizador se ejecuta dentro de un clon de instalación gestionado con git que todavía apunta al upstream canónico del CMS, el CMS también deshabilita automáticamente el push a origin después de los comandos de posinstalación, de modo que futuros intentos accidentales de git push fallen con claridad mientras el acceso normal de fetch o pull sigue disponible.

• Operaciones
• Instalación
• Flujo de trabajo de desarrollo