Mises à jour

Les mises à jour dans WebBlocks CMS reposent sur les versions publiées et sur les paquets.

Source du client partagé

CMS fournit le runtime partagé Publisher Client sous forme de sources synchronisées dans src/Support/Updates/Client, sans nécessiter le paquet Composer privé. Les adaptateurs CMS gèrent historique, version persistante, migrations, réparation des catalogues et sauvegardes complètes. Ne modifiez pas les fichiers générés. Le dépôt privé fait référence : composer embed:sync-all actualise les copies enregistrées ; composer embed:check-all détecte les écarts via .publisher-client.json.

Règles fondamentales

La version installée reflète la dernière version réelle appliquée à l'installation.
Le développement ordinaire du code source ne change pas la version installée.
L'outil de mise à jour intégré applique des paquets de versions publiées, et non les modifications locales de l'arbre de travail.
Les nouveaux consommateurs Composer doivent d'abord installer avec composer require fklavyenet/webblocks-cms et php artisan webblocks:install avant d'utiliser le flux normal de mise à jour fondé sur les versions publiées.
Les installations natives de paquet actuelles consomment directement les ZIP de version à racine de paquet.
Les System Updates natives de paquet appliquent l'artefact du paquet à la racine canonique du paquet Composer, vendor/fklavyenet/webblocks-cms, de sorte que la mise à jour Composer et la System Update produisent la même arborescence de paquet installée.
Historiquement, les installations antérieures au natif de paquet, telles que 1.31.53, ne pouvaient pas consommer directement les ZIP de version à racine de paquet et exigeaient d'abord le pont géré depuis la racine à l'ancien format 1.32.33. Ce chemin de pont est désormais retiré de la validation de version courante, car il ne reste plus d'anciennes installations gérées depuis la racine à prendre en charge dans les contrôles normaux.

Transition de documentation et licence (1.89.1–1.89.4)

La documentation canonique réside dans docs/ du dépôt indépendant webblocks-cms-docs, avec docs/guides/ et les médias. Les pages /docs et /guides sont des destinations de publication. CMS contient le contrat resources/contracts/inventory.md, toujours accessible via GET /webadmin/api/inventory. Installer ou mettre à jour CMS ne nécessite pas le dépôt documentaire. La séparation n'a introduit aucun moteur de publication ou de synchronisation.

La transition de licence utilise une version intermédiaire du paquet :

1.89.1: Les ZIP Publisher contiennent uniquement l'ancien chemin docs/LICENSE pour que les clients existants installent la transition. Composer/Git conservent LICENSE à la racine. L'outil accepte les deux structures, préfère LICENSE à la racine si les deux existent et installe la licence canonique. La documentation reste exclue.
1.89.2 et suivantes: Les ZIP Publisher contiennent LICENSE à la racine sans générer docs/. Les métadonnées exigent au minimum CMS 1.89.1. Les anciennes installations doivent d'abord installer 1.89.1, puis revérifier. Composer permet une mise à jour directe.
1.89.3: Publisher Client intégré passe à 1.1.13, valide la compatibilité de transition et recherche la prochaine mise à jour après installation réussie. L'adaptateur CMS conserve update_path et refuse les versions minimales mal formées.
1.89.4: Publisher Client intégré passe à 1.1.14. Les notes incluent uniquement les versions ultérieures à l'installée et ne dépassant pas la cible choisie, même si c'est une transition.

Par exemple, une ancienne installation peut recevoir 1.89.1 avant 1.89.4. Vérifiez et appliquez la transition, puis installez la version courante après un nouveau contrôle. L'écran intermédiaire doit afficher les notes jusqu'à 1.89.1 seulement. Cette transition de licence est distincte de l'ancienne transition 1.32.33 gérée à la racine.

Attentes opérationnelles

N'exécutez les mises à jour qu'à partir de versions publiées.
Conservez les fichiers propres à l'installation dans des chemins préservés tels que .env, storage/ et project/.
Traitez séparément les flux de développement et de publication.
System Updates cible toujours la racine Composer vendor/fklavyenet/webblocks-cms. Les copies sources se mettent à jour via git/Composer. Le mode retiré depuis les sources et son paramètre WEBBLOCKS_UPDATES_MIGRATION_STRATEGY sont ignorés depuis 1.41.0.
Les paquets de version ne contiennent que du code réutilisable du cœur du CMS et ne doivent pas embarquer de contenu project/ propre à l'installation.
Les chemins préservés lors de la mise à jour ne modifient pas la frontière du paquet de version : project/ reste local à l'installation et hors de l'artefact publié.
Les copies de travail CMS installées sont consommatrices de mises à jour, non publieuses en amont. Si une installation possède un origin git, conservez l'accès en fetch si nécessaire mais désactivez le push avec git remote set-url --push origin DISABLED.
Le succès est enregistré uniquement si le runtime signale la version cible depuis WebBlocks\Cms\Support\WebBlocks. Une version ancienne ou inattendue provoque un échec et une restauration automatique. Le statut est restored si elle réussit, sinon failed avec les deux traces d'erreur.

Clients de mise à jour coexistants

Un hôte peut installer plusieurs paquets intégrant Publisher Client dans des espaces de noms distincts. La configuration Laravel est globale ; publisher-client n'est pas un état permanent du produit. Un autre fournisseur peut écrire ses valeurs de produit, résolution de version, cible, validation, migration et post-application dans le même cycle d'amorçage.

Chaque point d'entrée CMS restaure toute la configuration avant de résoudre un service. Les contrôleurs injectent seulement CmsPublisherClientConfigurator, appellent configure(), puis résolvent SystemUpdateInspector, UpdateServerClient, SystemUpdater ou AdminUpdateIndicator. L'injection dans le constructeur ou la méthode d'action pourrait résoudre les dépendances trop tôt et doit être évitée. Le test de coexistence remplace la configuration par un produit tiers et vérifie la restauration conjointe du résolveur, de la version, de la cible et du client CMS.

Détails de la version

System Updates affiche une carte à deux états. À jour, elle indique version et dernier contrôle. Sinon, elle montre le parcours de versions, What's new replié avec notes par version, Update to X en un clic avec sauvegarde automatique/restauration en cas d'échec, et un lien vers les sauvegardes complètes avant les mises à jour majeures. Le résumé compare le code CMS actif à la dernière publication ; la version enregistrée sert uniquement à l'historique et à la persistance.

Les superadministrateurs disposent d'un indicateur asynchrone dans la navigation supérieure. Masqué par défaut, il consulte /webadmin/system/updates/indicator en arrière-plan et apparaît seulement pour une nouvelle version fiable. Le rendu normal n'attend pas le serveur de mises à jour ; les installations à jour n'affichent aucun raccourci permanent.

Le contrôle préalable vérifie base, ZIP/sodium, exécution PHP/Composer/processus, écriture racine/espace de travail et disque libre. Chaque test réussit ou échoue ; tous doivent réussir et aucun verrou ne doit être détenu. L'historique est replié, les journaux s'ouvrent en modales ; aucune action destructive n'est affichée.

Les exécutions sont purgées après contrôles et applications. Les cinq dernières restent, et le dernier échec jusqu'à un succès ultérieur. L'écran les liste sans suppression. Inspection CLI : php artisan webblocks:updates:runs, php artisan webblocks:updates:runs --last, php artisan webblocks:updates:runs --failed ; purge contrôlée : php artisan webblocks:updates:prune-runs --keep=5.

Release affiche les métadonnées de title, summary, highlights, fixes, compatibility_notes, migration_notes, asset_notes, operator_notes, technical_notes en texte échappé. changelog_entries contient les entrées cumulées, plus récentes d'abord, après la version installée et jusqu'à la cible, issues de changelog, releases, changelog_entries. Sans liste, seule l'entrée cible est utilisée ; What's new contient toujours du contenu.

La chaîne historique release_notes reste prise en charge pour les charges utiles de versions plus anciennes. En l'absence de notes de version, l'écran affiche No release notes were provided for this release. L'outil de mise à jour ne déduit pas les changements à partir des numéros de version.

Les métadonnées sont préparées avec composer release:prepare et publiées avec composer release:publish-update. L'enveloppe vérifie GitHub CLI avant l'écriture irréversible sur Publisher, publie puis crée/actualise le GitHub Release comme latest. Un chapitre CHANGELOG.md correspondant est requis ; ses points alimentent release_notes et summary/highlights, avec référence, somme de contrôle et version minimale. Les champs sont envoyés au niveau supérieur et imbriqué : notes enrichies pour nouveaux clients, texte simple pour anciens. Lecture via champs supérieurs, details, release_details, meta.release_details/meta.details.

GitHub Actions ne crée ni paquets ni métadonnées publiées ; .github exécute seulement tests/lint. L'enveloppe locale aligne GitHub latest sur le tag stable. System Updates utilise seulement Publisher. publisher.webblocksui.com est le service canonique : publication https://publisher.webblocksui.com/api/updates/publish, lecture https://publisher.webblocksui.com/api/updates/latest, téléchargement https://publisher.webblocksui.com/downloads/.... Les .env habituels ne configurent pas serveur/produit/canal : ReleaseDefaults possède ces valeurs, stable et les chemins. L'ancienne transition updates.webblocksui.com est historique, pas une configuration active.

Commandes du mainteneur :

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

release:push pousse branche et tag annoté ensemble vers origin, avec un seul contrôle pre-push. Ensuite seulement, il reflète les mêmes références vers backup avec --no-verify, puis compare branche et commit résolu du tag sur les deux distants au commit local.

La publication utilise WEBBLOCKS_PUBLISHER_TOKEN et, pour signer, WEBBLOCKS_PUBLISHER_SIGNING_KEY. Valeurs : https://publisher.webblocksui.com, produit webblocks-cms, canal stable, lecture /api/updates/latest ; publication avec même identité et /api/updates/publish. L'enveloppe Composer lit seulement ces deux secrets dans .env et les exporte vers Testbench isolé ; la configuration en cache les actualise depuis .env. Aucun export manuel. Dry-run valide clé et artefact sans envoi. Sans token, la publication réelle reste non publiée et termine en échec ; elle ne compte pas comme publication.

Télémétrie d'adoption anonyme

Les contrôles incluent une télémétrie respectueuse de la vie privée. Publisher distingue téléchargements et installations anonymes actives. Les téléchargements comptent les récupérations d'artefacts ; les installations actives comptent les identifiants uniques signalés au fil du temps.

La télémétrie est activée par défaut ; pour la désactiver :

WEBBLOCKS_TELEMETRY=false

Avec la télémétrie active, le premier contrôle nécessaire génère installation_id aléatoire local et l'enregistre dans les paramètres système. Sans données personnelles ni du site, il reste stable et peut changer après recréation de l'installation ou réinitialisation stockage/base.

Le contrôle envoie uniquement ces champs :

product_key
installed_version
channel
installation_id
telemetry_schema_version

CMS n'envoie ni domaines, URL complètes, courriels admin, chemins, noms de bases, propriétaires de licence, nombres d'utilisateurs, tokens, secrets ni valeurs arbitraires. Avec WEBBLOCKS_TELEMETRY=false, il demande toujours les métadonnées avec produit, canal et version, mais ne crée ni n'envoie installation_id.

Flux d'application de la mise à jour

Une mise à jour interne s'exécute en un clic : téléchargement/vérification, sauvegarde préalable automatique, application des fichiers, puis dans cet ordre :

migrations de mise à jour du paquet, si présentes
étapes de vidage du cache
synchronisation du catalogue fourni (webblocks:catalog-repair --all)
enregistrement de l'exécution de mise à jour
persistance de la version installée

Si l'application ou la vérification échoue, la sauvegarde préalable est restaurée automatiquement. Le statut est restored ; si la restauration échoue aussi, failed avec les deux traces dans le journal. La sauvegarde reste disponible dans Sauvegardes ou via CLI php artisan system:backup:restore pour restauration manuelle.

Après succès, la politique de nettoyage s'applique ; nombre supprimé et octets libérés sont journalisés. Un échec de nettoyage n'annule pas la mise à jour ; il est consigné. Par défaut : sauvegardes préalables 14 jours et au moins les cinq dernières réussies ; sauvegardes de sécurité de restauration 30 jours, points de contenu 7. Celles des mises à jour échouées/restaurées sont protégées 90 jours. Sauvegardes manuelles, importées ou en cours exclues. Configurez/prévisualisez sous Maintenance → Cleanup ; voir Opérations pour planification, CLI et API.

Les mises à jour appliquent les paquets publiés puis, après vidage du cache, exécutent webblocks:catalog-repair --all en sous-processus sur le nouveau code. Catalogues de blocs, blocs plugin, emplacements, mises en page et icônes sont alignés ; Rating/Comments peut être ajouté sans commande manuelle. Le manifeste reconstruit découvre les nouvelles commandes. Le processus est idempotent et conserve les entrées personnalisées.

La synchronisation est au mieux : fichiers et migrations ont déjà réussi, donc son échec ne fait pas échouer la mise à jour. Le journal indique qu'elle est incomplète et que php artisan webblocks:catalog-repair --all peut être relancé manuellement. Le schéma relève de migrations explicites ; la synchronisation répare seulement les données du catalogue.

Les étapes de vidage du cache comprennent les vidages de configuration, de vues, de cache applicatif et de routes de Laravel, afin que les layouts et helpers Blade appartenant au paquet soient recompilés après le remplacement des fichiers. Sur les installations PHP-FPM en production dont l'OPcache est configuré pour ne pas valider les horodatages, rechargez le service PHP-FPM concerné après une mise à jour réussie afin que PHP ne continue pas de servir depuis la mémoire des classes de paquet antérieures à la mise à jour.

Pendant la mise à jour, une modale non fermable montre le parcours avec le chargement WebBlocks UI. PHP pouvant redémarrer durant la requête, elle n'attend pas sa fin : elle déclenche puis interroge l'indicateur toutes les 1,5 secondes, avec retour à l'administration après 3 minutes au maximum. Toute réponse, même une redirection de connexion, recharge l'écran.

System Update n'exécute jamais database/migrations de l'hôte, évitant les conflits de migrations Laravel en attente comme 0001_01_01_000000_create_users_table.php avec les tables CMS. Les paquets sont appliqués à vendor/fklavyenet/webblocks-cms ; seules les migrations PHP de vendor/fklavyenet/webblocks-cms/database/migrations/updates sont exécutées. Sinon, le saut est journalisé et cache/version poursuivent. Les réparations sûres, comme les clés parentes nécessaires aux sauvegardes complètes portables, appartiennent aussi à ces migrations.

Règle de mise à jour de schéma native de paquet

Tout changement de schéma de WebBlocks CMS requis par le code à l'exécution doit prendre en charge les deux chemins d'installation :

Installations neuves ou de consommateur du paquet : mettez à jour le chemin de migration de schéma normal ou d'installation neuve.
Installations natives de paquet existantes mises à jour via les System Updates : ajoutez une migration de mise à jour du paquet sous database/migrations/updates du paquet ; les consommateurs installés l'exécutent depuis vendor/fklavyenet/webblocks-cms/database/migrations/updates.

Le schéma d'installation neuve ne suffit pas à lui seul. Si le nouveau code à l'exécution attend une table ou une colonne, la version doit inclure une migration de mise à jour pour les installations existantes, ou bien la mise à jour doit échouer proprement avant que le nouveau chemin de code ne puisse produire une erreur 500 brute. Les System Updates natives de paquet ne doivent pas obliger les utilisateurs ordinaires à se connecter en SSH à un site et à lancer des migrations manuelles après une mise à jour réussie.

Un succès aligne code, schéma, cache et contrôle final. Les pages admin/API/runtime dépendantes d'un nouveau schéma doivent fournir des consignes contrôlées plutôt que des erreurs brutes. L'incident 1.32.146→1.32.147 est la référence : cms_api_tokens était seulement dans les migrations normales ; après mise à jour, System -> API Tokens échouait jusqu'à l'ajout d'une migration du paquet et d'une gestion contrôlée en 1.32.147.

Le schéma d'interaction suit le même contrat. Les mises à jour assurent wbcms_comment_entries/wbcms_content_ratings automatiquement sans demander artisan migrate sur l'hôte. La réparation idempotente conserve et renomme les anciennes tables sans préfixe ou crée les tables préfixées ; les données sont volontairement conservées au rollback.

Les rapports de version comportant un changement de schéma doivent répondre explicitement à :

chemin de schéma d'installation neuve mis à jour : oui/non
migration de mise à jour du paquet ajoutée : oui/non
test de non-régression de la migration de mise à jour ajouté : oui/non
comportement propre en cas de schéma manquant nécessaire/ajouté : oui/non

Pendant la transition vers le paquet, certaines installations peuvent encore comporter une copie obsolète packages/webblocks-cms à la racine de l'installation ou une ancienne copie de transition imbriquée dans vendor. Ces chemins sont des artefacts hérités de la transition, et non la source de vérité native de paquet active. La System Update native de paquet remplace désormais la racine canonique du paquet Composer à vendor/fklavyenet/webblocks-cms et vérifie la version cible depuis cette racine de paquet. Elle ne conserve pas packages/webblocks-cms comme seconde copie d'exécution mise à jour.

L'ancien vendor vendor/fklavyenet/webblocks-cms peut être structuré comme dépôt avec artisan, app/, bootstrap/, packages/webblocks-cms/, plugins/, tests/. System Update le remplace par le paquet plat : composer.json, LICENSE racine, src/, routes/, resources/, database/, public/, config/, stubs/ sous vendor/fklavyenet/webblocks-cms. Les métadonnées Composer sont normalisées avant autoload optimisé ; WebBlocks\Cms\ doit provenir de vendor/fklavyenet/webblocks-cms/src, pas vendor/fklavyenet/webblocks-cms/packages/webblocks-cms/src. Les chemins anciens font échouer la mise à jour plutôt que déclarer un faux succès.

Les mises à jour modernes préservent la séparation entre l'administration /webadmin et les ressources /cms introduite par la migration de la v1.32.56. /cms est uniquement un espace de noms de ressources statiques, et non un préfixe d'administration, car le try_files de Nginx peut résoudre /cms/ comme le répertoire physique public/cms/ avant que Laravel ne voie une route. Les mises à jour ne doivent pas restaurer d'alias d'administration /cms appartenant au CMS, de redirections /cms, de routes /admin ni de relais public/cms/index.php, que ce soit à la racine de l'installation ou dans les ressources publiques du paquet.

Pont retiré des mises à jour gérées depuis la racine de la 1.31

Cette section est historique. L'outil de mise à jour de la 1.31.53 validait l'ancien contrat d'archive géré depuis la racine : artisan et composer.json devaient exister à la racine de l'archive, ou dans un unique répertoire englobant. Les artefacts à racine de paquet tels que 1.32.31 ne contenaient volontairement pas d'artisan racine, si bien que ces anciens clients échouaient avant l'application avec Package validation failed because composer.json and artisan were not found at the archive root.

La stratégie de pont retirée se déroulait en deux étapes :

Publier ou republier un artefact de version passerelle dans l'ancienne forme gérée depuis la racine, construit à partir d'une source compatible passerelle qui contenait encore les enveloppes héritées App\Support\System\Updates\* et validait déjà les archives strictes à racine de paquet fklavyenet/webblocks-cms. Pour la passerelle 1.32.33, la référence source était v1.32.30.
Publier des versions à racine de paquet avec minimum_client_version fixé à 1.32.18 ou plus récent, afin que les anciens clients ne se voient pas proposer le dernier artefact à racine de paquet avant la passerelle.
Une fois la passerelle appliquée, l'updater installé pouvait valider et appliquer la forme stricte d'artefact à racine de paquet fklavyenet/webblocks-cms utilisée par les versions modernes.

scripts/build-root-managed-bridge-archive.sh VERSION [OUTPUT_DIR] [GIT_REF] n'est conservé que comme outil archivé de récupération manuelle pour le ZIP passerelle à l'ancienne forme ; par exemple scripts/build-root-managed-bridge-archive.sh 1.32.33 dist v1.32.30. Le constructeur exclut délibérément les chemins appartenant à l'installation tels que .env, storage/, project/, public/site/, public/storage et le config/ racine ; les valeurs par défaut appartenant au paquet sous packages/webblocks-cms/config restent partie intégrante du runtime du paquet. La validation courante native du paquet n'emprunte pas ce chemin de passerelle.

Le chemin historique achevé était 1.31.53 -> 1.32.33 bridge -> 1.32.34+ package-rooted. Les installations déjà compatibles passerelle, comme 1.32.30, ont sauté la passerelle et sont passées directement à une version à racine de paquet 1.32.34+. Les garde-fous de version actuels ne protègent que l'artefact à racine de paquet et le comportement de l'updater natif du paquet.

Réparation du catalogue

System Updates exécute webblocks:catalog-repair --all automatiquement après installation ; voir Processus d'application. Les mêmes commandes restent disponibles pour réparations entre versions ou synchronisation incomplète :

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

La commande prend en charge --block-types, --plugin-block-types, --slot-types, --page-layouts, --icons. Exécutez d'abord --dry-run pour voir les lignes créées, modifiées, inchangées ou ignorées. Elle est idempotente, conserve les entrées personnalisées et ne les supprime pas.

La synchronisation de plus bas niveau des types de bloc reste disponible pour des raisons de compatibilité :

php artisan block-types:sync-core

Le chemin de réparation des types de bloc maintient le catalogue block_types stocké en base aligné sur le catalogue du cœur du CMS livré, sur les installations existantes :

les types de bloc du cœur manquants sont créés
les types de bloc du cœur existants sont mis à jour sur place
les types de bloc personnalisés propres à l'installation sont préservés
aucune ligne du cœur en double n'est créée

Ce flux de maintenance couvre le cas où une installation doit rafraîchir des lignes de catalogue sans obliger chaque application d'un paquet de version à effectuer une réparation étendue du catalogue en base.

Lorsque l'updater s'exécute dans un clone d'installation géré par git qui pointe encore vers l'upstream canonique du CMS, le CMS désactive désormais aussi automatiquement le push vers origin après les commandes de post-installation, afin que de futures tentatives accidentelles de git push échouent clairement tandis que l'accès normal en fetch ou pull reste disponible.

Mises à jour du système via l'API (1.90.0)

Le Internal Content API prend en charge les contrôles de mise à jour, l'exécution, et des résultats de fonctionnement durables. Ces points de terminaison utilisent le même client Publisher moteur comme panneau Mises à jour du système. Ils conservent son automatique configuré sauvegarde, vérification de la somme de contrôle et de la signature, verrouillage d'exécution exclusif, maintenance mode, vérification de la version après application et récupération après échec. Signature la vérification suit la politique de signature existante de l'installation ; l'API fait ne pas transformer une politique de signature facultative en politique obligatoire ni l'affaiblir.

Méthode et chemin	Capacité requise	Objectif
GET /webadmin/api/system/updates/check	system-updates.read	Lisez la version installée, la cible proposée, la somme de contrôle, la compatibilité et l'état de verrouillage.
POST /webadmin/api/system/updates	system-updates.run	Exécutez de manière synchrone une mise à jour explicitement approuvée.
GET /webadmin/api/system/updates/operations/{operation}	system-updates.read	Lisez une opération durable par UUID et son résultat aseptisé.

Les deux fonctionnalités sont facultatives et absentes du jeton par défaut et du jeton par défaut hérité. autorisations. system-updates.run est classé comme destructeur. Accorde les deux capacités à un outil qui doit exécuter et ensuite inspecter les mises à jour, ou accorder uniquement system-updates.read pour la surveillance. L'autorisation de lecture n'implique jamais l'exécution autorisation.

Uniquement un jeton système à l'échelle de l'installation, avec allowed_site_ids égal à null, appartenant à un utilisateur actif qui possède actuellement access-system, peut utiliser ces points finaux. Les jetons personnels et les jetons système à l'échelle du site sont exclus, même si leur tableau de capacités stocké a été modifié pour inclure les autorisations de mise à jour. Les utilisateurs de la démo publique sans accès au système ne peuvent pas accorder ou exercer la mise à jour autorisations. Révocation, expiration, désactivation du propriétaire, suppression ou perte du système l’autorité empêche tout accès ultérieur. L'API vérifie la capacité et l'installation autorité au moment de la demande ; l'émission du jeton vérifie également l'autorité d'installation.

Approbation et exécution

Lisez le point de terminaison de contrôle. Un serveur de mise à jour inaccessible ou résultat incompatible n'est pas autorisé à exécuter une mise à jour.
Afficher à l'opérateur la version installée, la version cible proposée et la somme de contrôle. Obtenez une approbation explicite pour cette mise à jour exacte et son installation à l'échelle impact. L'octroi d'un jeton ne remplace pas l'approbation d'une exécution particulière.
Générez un idempotency_key stable et soumettez les champs approuvés. Gardez ça clé et corps de la demande pour la récupération après perte de connexion.

Exemple de corps de requête, utilisant des versions synthétiques et une somme de contrôle :

{
  "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 atteste que l'appelant a obtenu l'approbation de l'opérateur ; ce n'est pas le cas prouver qu'un humain a approuvé la demande. La discipline d'approbation reste la responsabilité de l’outil appelant. Ne le définissez pas automatiquement dans une IA workflow qui a uniquement été autorisé à modifier le contenu.

Le moteur vérifie la version installée et la nouvelle version proposée par rapport à version approuvée/somme de contrôle à l'intérieur de son verrou d'exécution, avant de créer une sauvegarde ou application des fichiers. Une cible modifiée, une somme de contrôle ou une version installée renvoie system_update_target_changed ; vérifiez à nouveau et obtenez une nouvelle approbation. Arbitraire les URL de téléchargement, les artefacts, les commandes et les remplacements de signature/sauvegarde ne sont pas accepté. Une version relais est une mise à jour approuvée : elle n'autorise pas installation d'une version ultérieure.

Exécution, tentatives et résultats

L'exécution est synchrone, comme dans le panneau. Il n'y a aucune exigence de file d'attente et aucun Promesse de travail en arrière-plan 202 Accepted. Le POST initial renvoie normalement 200 avec un objet operation ; l'échec de l'exécution renvoie 409 avec l'opération. L'opération comprend son UUID, l'ID d'exécution associé, les versions, la somme de contrôle, le statut, code d'erreur, horodatages et résultat nettoyé. Emplacements de sauvegarde, jetons de porteur, les informations d'identification du serveur et les traces brutes de la pile ne sont pas renvoyées. Vérifier les réponses omis télécharger les URL et les diagnostics bruts du serveur.

Les statuts sont running, success, success_with_warnings, failed et restored. restored signifie que le moteur a signalé un échec de mise à jour suivi d'un restauration de sauvegarde réussie ; ce n'est pas un succès de mise à jour. Le résultat est délimité et désinfecté à nouveau lorsqu'il est présenté. Finalisation post-candidature vérifiée les échecs utilisent le même service de réconciliation que le panneau, donc l'ouverture du panneau n’est pas requis pour obtenir success_with_warnings.

Un POST identique utilisant le même jeton et la même clé d'idempotence renvoie l'original opération avec replayed: true et n’exécute jamais une autre mise à jour. Réutiliser un la clé avec différents champs approuvés renvoie system_update_idempotency_conflict. Les clés d'idempotence sont limitées à un jeton : changer de jeton ou utiliser une nouvelle clé est ce n’est pas une nouvelle tentative sûre après un résultat incertain. Inspectez le operation.status et operation.code ; la réponse HTTP réussie d'une rediffusion signifie que l'existant l'opération a été récupérée, mais sa mise à jour n'a pas réussi.

Une mise à jour concurrente renvoie system_update_in_progress. L'admission à l'API et le le verrouillage du moteur existant empêche les exécutions qui se chevauchent, y compris les courses de panneaux/API. Les reçus durables sont conservés indépendamment de l'élagage ordinaire de l'historique d'exécution ; la révocation ou la suppression d'un jeton ne supprime pas ces reçus en cascade.

Perte de connexion et récupération de l'opérateur

Une mise à jour peut remplacer son propre code en cours d'exécution et activer temporairement la maintenance mode. Une connexion POST peut expirer et l'interrogation peut recevoir un 503 temporaire. réponses. Ni l’un ni l’autre ne prouve l’échec. Lorsque l'accès revient, répétez le POST exact avec sa clé/corps d'origine pour récupérer l'UUID de l'opération, ou interroger l'UUID si déjà connu. Ne soumettez jamais automatiquement une nouvelle clé.

Une interruption fatale du processus peut laisser une opération enregistrée sous le nom running. Lorsque l'opération est suffisamment ancienne et que le moteur n'a pas de verrouillage/battement de cœur en direct, son résultat indique requires_attention: true. C'est une issue incertaine, il ne s’agit pas d’un échec, d’un succès ou d’un recul fabriqué de toutes pièces. Bloc d'opérations API non résolu nouvelles exécutions d'API avec system_update_requires_attention ; la même opération peut toujours être récupéré sans l’exécuter à nouveau.

L'opérateur d'installation doit inspecter la version active, la sauvegarde, la maintenance état et exécution de l'historique et complétez la procédure de récupération existante. Résoudre un reçu orphelin grâce à la maintenance contrôlée de la base de données côté hôte uniquement après avoir établi le résultat réel ; conserver sa clé et son dossier d'audit. Faire ne supprimez pas les reçus pour contourner la sauvegarde. L'API ne fournit intentionnellement aucun redémarrage, annulation ou restauration automatique du point de terminaison pour les opérations incertaines.

Champs de demande invalides ou retour de confirmation manquant 422 ; capacité manquante ou l'autorité d'installation renvoie 403 et une opération inconnue renvoie 404. Les échecs d’authentification conservent le comportement normal de l’API 401. Découvrez les chemins en direct et la demande de contrat via /webadmin/api et /webadmin/api/openapi.json.

Éligibilité du jeton système dans le panneau (1.90.1)

La création et la modification du jeton système affichent le type de jeton système fixe et la portée à l'échelle de l'installation. Le panneau avertit avant d'enregistrer un jeton qui ne peut pas exécuter les mises à jour du système. Un jeton éligible nécessite toujours un propriétaire administrateur système actif, une portée à l'échelle de l'installation et un system-updates.read ou system-updates.run accordé séparément ; les jetons personnels et à l’échelle du site ne peuvent pas effectuer les mises à jour d’installation. La modification d'un jeton normalise les types de jetons système existants sans supprimer les contrôles de propriétaire, d'expiration, de révocation ou de portée.