Actualizaciones

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

Fuente del cliente compartido

CMS incluye el runtime compartido Publisher Client como fuentes sincronizadas en src/Support/Updates/Client; no exige el paquete Composer privado. Los adaptadores CMS gestionan historial, versión persistente, migraciones, reparación de catálogos y copias completas. No edite archivos generados. El repositorio privado es la fuente: composer embed:sync-all actualiza las copias registradas y composer embed:check-all detecta diferencias mediante .publisher-client.json.

Reglas fundamentales

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.

Transición de documentación y licencia (1.89.1–1.89.4)

La documentación canónica está en docs/ del repositorio independiente webblocks-cms-docs, incluidos docs/guides/ y medios. Las páginas /docs y /guides son destinos de publicación. CMS incluye el contrato de autoría resources/contracts/inventory.md, accesible por GET /webadmin/api/inventory. Instalar o actualizar CMS no requiere el repositorio documental. La separación no introdujo un motor de publicación o sincronización.

La transición de licencia usa una versión puente del paquete:

1.89.1: Los ZIP Publisher solo llevan la licencia antigua docs/LICENSE para instalar el puente con clientes existentes. Composer/Git mantienen LICENSE en raíz. El actualizador acepta ambos formatos, prefiere LICENSE en raíz si coexisten e instala la licencia canónica. La documentación sigue excluida.
1.89.2 y posteriores: Los ZIP Publisher llevan LICENSE en raíz sin generar docs/. Los metadatos requieren como mínimo CMS 1.89.1. Las instalaciones antiguas deben instalar 1.89.1 primero y comprobar de nuevo. Composer permite actualizar directamente.
1.89.3: Publisher Client integrado pasa a 1.1.13, valida la compatibilidad del puente y comprueba la siguiente actualización tras instalarlo. El adaptador CMS conserva update_path y rechaza versiones mínimas de producto mal formadas.
1.89.4: Publisher Client integrado pasa a 1.1.14. Las notas incluyen solo versiones posteriores a la instalada y no superiores al destino seleccionado, incluso si es un puente.

Por ejemplo, una instalación antigua puede recibir 1.89.1 antes de 1.89.4. Revise y aplique el puente; luego compruebe y actualice a la versión actual. La pantalla del puente solo debe mostrar notas hasta 1.89.1. Este puente de licencia es distinto del histórico 1.32.33 gestionado desde raíz.

Expectativas operativas

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.
System Updates siempre apunta a la raíz Composer vendor/fklavyenet/webblocks-cms. Las copias fuente se actualizan con git/Composer. El modo retirado desde fuentes y su ajuste WEBBLOCKS_UPDATES_MIGRATION_STRATEGY se ignoran desde 1.41.0.
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.
Solo se registra éxito cuando el runtime informa la versión destino desde WebBlocks\Cms\Support\WebBlocks. Una versión antigua o inesperada causa fallo y restauración automática. Se registra restored si restaura correctamente, o failed con ambos errores si no.

Clientes de actualización coexistentes

Un host puede instalar varios paquetes con Publisher Client en distintos espacios de nombres. La configuración Laravel es global; publisher-client no es estado permanente del producto. Otro proveedor puede escribir sus valores de producto, resolución de versión, destino, validación, migración y posaplicación en el mismo arranque.

Cada entrada de actualización CMS restaura toda la configuración antes de resolver un servicio. Los controladores solo inyectan CmsPublisherClientConfigurator, llaman configure() y resuelven después SystemUpdateInspector, UpdateServerClient, SystemUpdater o AdminUpdateIndicator. Inyectarlos en constructor o método de acción podría resolver dependencias antes de restaurar la configuración y debe evitarse. La prueba de coexistencia sustituye la configuración por otro producto y comprueba la restauración conjunta del resolutor, versión, destino y cliente CMS.

Detalles de la versión

System Updates muestra una tarjeta con dos estados. Si está actualizado, muestra versión y última comprobación. Si hay actualización compatible, muestra el recorrido de versiones, What's new plegado con notas por versión, Update to X en un clic con copia automática y restauración si falla, y un enlace a Copias para respaldar el servidor antes de cambios importantes. Compara el código CMS activo con la última versión publicada; la versión guardada solo sirve para historial y persistencia.

Los superadministradores tienen un indicador asíncrono arriba. Está oculto por defecto, consulta /webadmin/system/updates/indicator en segundo plano y aparece solo si hay una versión nueva confiable. El renderizado normal no espera al servidor de actualizaciones y las instalaciones actuales no muestran acceso permanente.

La comprobación previa valida base de datos, ZIP/sodium, ejecución PHP/Composer/procesos, escritura en raíz/espacio de trabajo y disco libre. Cada prueba aprueba o falla; actualizar exige todas aprobadas y bloqueo libre. El historial aparece plegado y cada registro abre su log en modal; no hay acciones destructivas.

Los registros se podan tras comprobaciones y aplicaciones. Se conservan los últimos cinco y el último fallo hasta un éxito posterior. La pantalla los lista sin controles de borrado. Inspeccione con php artisan webblocks:updates:runs, php artisan webblocks:updates:runs --last, php artisan webblocks:updates:runs --failed; pode de forma controlada con php artisan webblocks:updates:prune-runs --keep=5.

Release presenta metadatos de title, summary, highlights, fixes, compatibility_notes, migration_notes, asset_notes, operator_notes, technical_notes como texto escapado. changelog_entries incluye entradas acumulativas, más recientes primero, posteriores a la instalada y hasta el destino, tomadas de changelog, releases, changelog_entries. Sin lista, usa una entrada del destino; What's new siempre tiene contenido.

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 se preparan con composer release:prepare y publican con composer release:publish-update. El wrapper verifica autenticación GitHub CLI antes de escribir irreversiblemente en Publisher, publica allí y crea/actualiza el GitHub Release como latest. Exige una sección CHANGELOG.md de la versión, usa sus puntos para release_notes y summary/highlights, añade referencia, checksum y versión mínima. Envía campos superiores y anidados: clientes nuevos reciben notas enriquecidas y antiguos texto simple. Se leen campos superiores, details, release_details, meta.release_details/meta.details.

GitHub Actions no genera paquetes ni publica metadatos; .github solo prueba y valida estilo. El wrapper local mantiene GitHub latest alineado con la etiqueta estable. System Updates solo usa Publisher. publisher.webblocksui.com es el servicio canónico: publicar en https://publisher.webblocksui.com/api/updates/publish, consultar en https://publisher.webblocksui.com/api/updates/latest, descargar en https://publisher.webblocksui.com/downloads/.... Los archivos .env normales no configuran servidor/producto/canal; ReleaseDefaults define servidor, producto, canal stable y rutas. El antiguo puente updates.webblocksui.com es histórico, no configuración activa.

Comandos del mantenedor:

composer release:push
composer release:prepare
composer release:publish-update -- --dry-run
composer release:publish-update

release:push envía rama y etiqueta anotada juntas a origin, ejecutando controles pre-push una vez. Solo después replica las mismas referencias en backup con --no-verify; compara rama y commit de etiqueta de ambos remotos con el commit local.

La publicación usa WEBBLOCKS_PUBLISHER_TOKEN y para firmar WEBBLOCKS_PUBLISHER_SIGNING_KEY. Valores: https://publisher.webblocksui.com, producto webblocks-cms, canal stable, lectura /api/updates/latest; publicar usa la misma identidad y /api/updates/publish. El wrapper Composer lee solo esos dos secretos de .env y los exporta al proceso Testbench aislado; la configuración cacheada los refresca de .env. No requiere export manual. Dry-run valida clave y artefacto sin subir. Sin token, la publicación real devuelve estado no publicado y salida fallida; no cuenta como publicación.

Telemetría de adopción anónima

Las comprobaciones incluyen telemetría respetuosa con la privacidad. Publisher distingue descargas de instalaciones anónimas activas. Las descargas cuentan obtenciones del paquete; las instalaciones activas cuentan identificadores únicos que informan a lo largo del tiempo.

La telemetría está activada por defecto; para desactivarla:

WEBBLOCKS_TELEMETRY=false

Con telemetría activa, la primera comprobación que lo necesita genera installation_id aleatorio local y lo guarda en ajustes del sistema. No contiene datos personales ni del sitio, permanece estable y puede cambiar al recrear la instalación o reiniciar almacenamiento/base de datos.

La comprobación solo envía estos campos:

product_key
installed_version
channel
installation_id
telemetry_schema_version

CMS no envía dominios, URL completas, correos admin, rutas, nombres de bases, titulares de licencia, número de usuarios, tokens, secretos ni valores arbitrarios. Con WEBBLOCKS_TELEMETRY=false, sigue consultando metadatos con producto, canal y versión, pero no crea ni envía installation_id.

Flujo de aplicación de la actualización

Una actualización interna se ejecuta en un clic: descarga y verifica el paquete, crea copia previa automática, aplica archivos y después, en este orden:

migraciones de actualización del paquete, si existen
pasos de limpieza de caché
sincronización del catálogo incluido (webblocks:catalog-repair --all)
registro de la ejecución de la actualización
persistencia de la versión instalada

Si falla la aplicación o verificación, restaura automáticamente la copia previa. El estado es restored; si también falla la restauración, es failed con ambos errores en el log. La copia sigue disponible en Copias o por CLI php artisan system:backup:restore para restauración manual.

Tras un éxito se aplica la limpieza configurada y se registran cantidad eliminada y bytes liberados. Un fallo de limpieza no revierte la actualización; se registra para revisión. Por defecto: copias previas 14 días y al menos las últimas cinco exitosas; copias de seguridad de restauración 30 días y puntos de contenido 7. Las de actualizaciones fallidas/restauradas se protegen 90 días. Se excluyen manuales, cargadas o en curso. Configure o previsualice en Maintenance → Cleanup; consulte Operaciones para planificador, CLI y API.

Las actualizaciones aplican paquetes publicados y después de limpiar caché ejecutan webblocks:catalog-repair --all como subproceso del código nuevo. Alinea catálogos de bloques, bloques plugin, slots, diseños e iconos; añade filas como Rating/Comments sin comando manual. El manifiesto reconstruido permite descubrir nuevos comandos. Es idempotente y conserva filas personalizadas.

La sincronización es de mejor esfuerzo: archivos y migraciones ya tuvieron éxito, por lo que su fallo no hace fallar la actualización. El log informa que no terminó y que puede repetirse php artisan webblocks:catalog-repair --all manualmente. Los cambios de esquema pertenecen a migraciones explícitas; el sync solo repara datos del catálogo.

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.

Durante la actualización, un modal no cerrable muestra el recorrido con el indicador WebBlocks UI. Como PHP puede reiniciarse durante la petición, no espera su final: dispara la actualización y consulta el indicador cada 1,5 segundos hasta que responda, con retorno a administración a los 3 minutos. Cualquier respuesta, incluida redirección al login, recarga la pantalla.

System Update nunca ejecuta database/migrations del host; evita colisiones de migraciones Laravel pendientes como 0001_01_01_000000_create_users_table.php con tablas CMS existentes. Aplica paquetes a vendor/fklavyenet/webblocks-cms y ejecuta solo migraciones PHP de vendor/fklavyenet/webblocks-cms/database/migrations/updates. Si no existen, registra que se omitieron y continúa con caché y versión. También allí van reparaciones seguras de esquema, como claves padre para portabilidad de copias completas.

Regla de actualización de esquema nativa de paquete

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

Instalaciones nuevas o de consumidor del paquete: actualice la ruta de migración de esquema normal o de instalación nueva.
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.

Un éxito exige código, esquema, caché y comprobación posterior alineados. Admin/API/runtime dependientes de esquema nuevo deben orientar de forma controlada, no exponer errores crudos. El incidente 1.32.146→1.32.147 sirve de ejemplo: cms_api_tokens solo estaba en migraciones normales; tras actualizar, System -> API Tokens dio error hasta que 1.32.147 añadió migración de paquete y gestión del esquema ausente.

El esquema de interacción sigue el mismo contrato. Las actualizaciones garantizan wbcms_comment_entries/wbcms_content_ratings automáticamente sin exigir artisan migrate del host. La reparación idempotente conserva y renombra tablas antiguas sin prefijo o crea las prefijadas; al revertir conserva intencionalmente los datos.

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.

El vendor antiguo vendor/fklavyenet/webblocks-cms puede tener estructura de repositorio con artisan, app/, bootstrap/, packages/webblocks-cms/, plugins/, tests/. System Update lo reemplaza por el paquete plano: composer.json, LICENSE raíz, src/, routes/, resources/, database/, public/, config/, stubs/ bajo vendor/fklavyenet/webblocks-cms. Normaliza metadatos Composer antes del autoload optimizado y verifica que WebBlocks\Cms\ resuelva desde vendor/fklavyenet/webblocks-cms/src, no vendor/fklavyenet/webblocks-cms/packages/webblocks-cms/src. Rutas antiguas causan fallo, no éxito con administración rota.

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.

Puente retirado desde las actualizaciones gestionadas desde la raíz de 1.31

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.

Reparación del catálogo

System Updates ejecuta webblocks:catalog-repair --all automáticamente después de instalar; véase Flujo de aplicación. Los mismos comandos sirven para reparar catálogos entre versiones o repetir una sincronización incompleta:

php artisan webblocks:catalog-repair --dry-run --all
php artisan webblocks:catalog-repair --all

El comando admite --block-types, --plugin-block-types, --slot-types, --page-layouts, --icons. Ejecute primero --dry-run para ver filas creadas, actualizadas, conservadas u omitidas. Es idempotente, conserva filas personalizadas y no las elimina.

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

php artisan block-types:sync-core

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.

Actualizaciones del sistema a través de la API (1.90.0)

El Internal Content API admite verificaciones de actualizaciones en toda la instalación, ejecución, y resultados de operación duraderos. Estos puntos finales utilizan el mismo cliente publicador. motor como el panel Actualizaciones del sistema. Conservan su automático configurado copia de seguridad, verificación de suma de comprobación y firma, bloqueo de ejecución exclusivo, mantenimiento modo, verificación de versión posterior a la aplicación y recuperación de fallas. Firma la verificación sigue la política de firma existente de la instalación; la API lo hace no convertir una política de firma opcional en obligatoria ni debilitarla.

Método y ruta	Capacidad requerida	Propósito
GET /webadmin/api/system/updates/check	system-updates.read	Lea la versión instalada, el objetivo ofrecido, la suma de comprobación, la compatibilidad y el estado de bloqueo.
POST /webadmin/api/system/updates	system-updates.run	Ejecute una actualización aprobada explícitamente de forma sincrónica.
GET /webadmin/api/system/updates/operations/{operation}	system-updates.read	Lea una operación duradera por UUID y su resultado desinfectado.

Ambas capacidades están habilitadas y ausentes del token predeterminado y heredado permisos. system-updates.run está clasificado como destructivo. Concede ambos capacidades a una herramienta que debe ejecutarse y posteriormente inspeccionar actualizaciones, o otorgar Sólo system-updates.read para monitoreo. El permiso de lectura nunca implica ejecutar permiso.

Solo un token de sistema para toda la instalación, con allowed_site_ids igual a null, propiedad de un usuario activo que actualmente tiene access-system, puede usar estos puntos finales. Se excluyen los tokens personales y los tokens del sistema de alcance del sitio, incluso si su conjunto de capacidades almacenadas se modificó para incluir permisos de actualización. Los usuarios de demostración pública sin acceso al sistema no pueden otorgar ni ejercer la actualización permisos. Revocación, caducidad, desactivación del propietario, eliminación o pérdida del sistema autoridad impide un mayor acceso. La API comprueba la capacidad y la instalación. autoridad en el momento de la solicitud; La emisión de tokens también verifica la autoridad de instalación.

Aprobación y ejecución

Lea el punto final de verificación. Un servidor de actualización inalcanzable o un resultado incompatible no hay permiso para ejecutar una actualización.
Muestre al operador la versión instalada, la versión de destino ofrecida y la suma de comprobación. Obtenga aprobación explícita para esa actualización exacta y su instalación impacto. Una concesión simbólica no sustituye la aprobación de una ejecución en particular.
Genere un idempotency_key estable y envíe los campos aprobados. Mantén eso clave y cuerpo de solicitud para recuperación de pérdida de conexión.

Ejemplo de cuerpo de solicitud, utilizando versiones sintéticas y suma de comprobación:

{
  "idempotency_key": "operator-approval-2026-10-02-1",
  "expected_current_version": "1.90.0",
  "target_version": "1.91.0",
  "checksum_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "confirmed": true
}

confirmed da fe de que la persona que llama obtuvo la aprobación del operador; no lo hace demostrar que un humano aprobó la solicitud. La disciplina de aprobación sigue siendo la responsabilidad de la herramienta de llamada. No lo configures automáticamente en una IA flujo de trabajo que solo ha sido autorizado para editar contenido.

El motor verifica la versión instalada y la nueva versión ofrecida con la versión aprobada/suma de comprobación dentro de su bloqueo de ejecución, antes de crear una copia de seguridad o aplicando archivos. Se devuelve un destino modificado, una suma de comprobación o una versión instalada. system_update_target_changed; verifique nuevamente y obtenga una nueva aprobación. arbitrario Las URL de descarga, los artefactos, los comandos y las anulaciones de firma/copia de seguridad no están disponibles. aceptado. Una versión puente es una actualización aprobada: no autoriza instalación de una versión posterior.

Ejecución, reintentos y resultados

La ejecución es sincrónica, como en el panel. No hay ningún requisito de cola y no Promesa de trabajo en segundo plano 202 Accepted. El POST inicial normalmente devuelve 200 con un objeto operation; la ejecución fallida devuelve 409 con la operación. La operación incluye su UUID, ID de ejecución asociada, versiones, suma de comprobación, estado, código de error, marcas de tiempo y resultado desinfectado. Ubicaciones de respaldo, tokens al portador, Las credenciales del servidor y los seguimientos de la pila sin procesar no se devuelven. Verificar respuestas omitir descargar URL y diagnósticos del servidor sin formato.

Los estados son running, success, success_with_warnings, failed y restored. restored significa que el motor informó una actualización fallida seguida de un restauración exitosa de la copia de seguridad; no es un éxito de actualización. La salida del resultado es acotado y desinfectado nuevamente cuando se presente. Finalización verificada posterior a la solicitud Los fallos utilizan el mismo servicio de conciliación que el panel, por lo que abrir el panel No es necesario obtener success_with_warnings.

Una POST idéntica que utiliza el mismo token y clave de idempotencia devuelve el original operación con replayed: true y nunca ejecuta otra actualización. Reutilizar un La clave con diferentes campos aprobados devuelve system_update_idempotency_conflict. Las claves de idempotencia están limitadas a un token: cambiar tokens o usar una nueva clave es No es un reintento seguro después de un resultado incierto. Inspeccione operation.status y operation.code; La respuesta HTTP exitosa de una repetición significa que el existente Se recuperó la operación, no es que su actualización se haya realizado correctamente.

Una actualización competitiva devuelve system_update_in_progress. Admisión API y el El bloqueo del motor existente evita la ejecución superpuesta, incluidas las carreras de panel/API. Los recibos duraderos se conservan independientemente de la poda ordinaria del historial de ejecución; revocar o eliminar un token no elimina en cascada estos recibos.

Pérdida de conexión y recuperación del operador

An actualización puede reemplazar su propio código en ejecución y habilitar temporalmente el mantenimiento modo. Es posible que se agote el tiempo de espera de una conexión POST y que el sondeo reciba un 503 temporal respuestas. Ninguno de los dos prueba el fracaso. Cuando vuelva el acceso, repita el POST exacto con su clave/cuerpo original para recuperar el UUID de la operación, o consultar el UUID si ya conocido. Nunca envíe automáticamente una clave nueva.

A una interrupción fatal del proceso puede dejar una operación registrada como running. Cuando la operación es lo suficientemente antigua y el motor no tiene bloqueo/latido activo, su resultado informa requires_attention: true. Este es un resultado incierto, no un fracaso, un éxito o un retroceso inventados. Bloque de operaciones API no resuelto nuevas ejecuciones de API con system_update_requires_attention; la misma operacion aún se puede recuperar sin ejecutarlo nuevamente.

El operador de la instalación debe inspeccionar la versión activa, copia de seguridad, mantenimiento estado y ejecutar el historial y completar el procedimiento de recuperación existente. resolver un recibo huérfano a través del mantenimiento controlado de la base de datos del lado del host únicamente después de establecer el resultado real; preservar su clave y registro de auditoría. hacer No elimine los recibos para evitar la protección. La API no proporciona intencionalmente reinicio, cancelación o restauración automática del punto final para operaciones inciertas.

Campos de solicitud no válidos o devolución de confirmación faltante 422; capacidad faltante o la autoridad de instalación devuelve 403 y devuelve una operación desconocida 404. Los errores de autenticación conservan el comportamiento normal de API 401. Descubrir los caminos en vivo y solicitar contrato a través de /webadmin/api y /webadmin/api/openapi.json.

Elegibilidad del token del sistema en el panel (1.90.1)

La creación y edición del token del sistema muestra el tipo de token del sistema fijo y el alcance de toda la instalación. El panel advierte antes de guardar un token que no puede ejecutar actualizaciones del sistema. Un token elegible aún necesita un propietario de administrador de sistema activo, alcance en toda la instalación y system-updates.read o system-updates.run otorgados por separado; Los tokens personales y de ámbito del sitio no pueden realizar actualizaciones de instalación. La edición de un token normaliza los tipos de tokens del sistema heredados sin eliminar las verificaciones de propietario, vencimiento, revocación o alcance.