Updates

Updates in WebBlocks CMS sind release-basiert und paketbasiert.

• Die installierte Version spiegelt das letzte tatsächlich auf die Installation angewendete Release wider.
• Gewöhnliche Quellcode-Entwicklung ändert die installierte Version nicht.
• Der In-App-Updater wendet veröffentlichte Release-Pakete an, keine lokalen Working-Tree-Änderungen.
• Neue Composer-Konsumenten sollten zuerst mit composer require fklavyenet/webblocks-cms und php artisan webblocks:install installieren, bevor sie den normalen release-basierten Update-Ablauf verwenden.
• Aktuelle paketnative Installationen konsumieren paketbasierte Release-ZIPs direkt.
• Paketnative System Updates wenden das Paket-Artefakt auf das kanonische Composer-Paketstammverzeichnis vendor/fklavyenet/webblocks-cms an, sodass Composer-Update und System Update dasselbe installierte Paketlayout erzeugen.
• Historisch konnten Installationen vor der paketnativen Umstellung wie 1.31.53 paketbasierte Release-ZIPs nicht direkt konsumieren und benötigten zuerst die root-verwaltete Bridge 1.32.33 im alten Format. Dieser Bridge-Pfad ist inzwischen aus der routinemäßigen Release-Validierung ausgemustert, da in normalen Gates keine alten root-verwalteten Installationen mehr zu unterstützen sind.

• Führen Sie Updates nur aus veröffentlichten Releases aus.
• Bewahren Sie installationsspezifische Dateien in geschützten Pfaden wie .env, storage/ und project/ auf.
• Behandeln Sie Entwicklungs- und Release-Workflows getrennt.
• In quellcodeverwalteten Wartungs-Checkouts sind lokale Quellcode-Änderungen bereits im Working Tree vorhanden. System Updates sollten nicht verwendet werden, um diese lokalen Änderungen anzuwenden, und die laufende CMS-Codeversion wird für die Update-Verfügbarkeit mit dem neuesten veröffentlichten Release verglichen.
• Release-Pakete enthalten ausschließlich wiederverwendbaren CMS-Kerncode und dürfen keine installationsspezifischen project/-Inhalte ausliefern.
• Beim Update geschützte Pfade ändern die Release-Paketgrenze nicht: project/ bleibt lokal in der Installation und außerhalb des veröffentlichten Artefakts.
• Installierte CMS-Arbeitskopien sind Update-Konsumenten, keine Upstream-Publisher. Wenn eine Installation ein Git-origin hat, behalten Sie bei Bedarf den Fetch-Zugriff, deaktivieren Sie aber Push mit git remote set-url --push origin DISABLED.
• Ein System Update wird nur dann als erfolgreich verzeichnet, wenn die angewendete Paket-Laufzeit die Zielversion aus der kanonischen Versionsquelle WebBlocks\Cms\Support\WebBlocks meldet. Meldet der angewendete Code weiterhin eine ältere oder unerwartete Version, wird der Lauf als fehlgeschlagen verzeichnet, und Operatoren sollten vor einem erneuten Versuch das Backup von vor dem Update wiederherstellen oder den Dateisystem-/Cache-Zustand prüfen.

Bevor Sie das Verhalten von CMS-Release, Update, Veröffentlichung, Publisher, Artefakt oder Migrationskompatibilität ändern, fragen Sie den WebBlocks Advisor und nehmen Sie die Antwort als Implementierungshinweis in den Bericht auf. Wenn der Advisor keine passende Antwort hat, aktualisieren Sie zuerst die relevante Wissensquelle oder den betreffenden Chunk, statt einen einmaligen Workflow zu erfinden.

Der System-Updates-Bildschirm zeigt menschenlesbare Release-Details, bevor ein Admin ein Update startet. Der Hauptablauf hat zwei Karten: Install Update und Update Details. Install Update erklärt, ob ein Update verfügbar ist, die laufende CMS-Codeversion aktuell ist, die lokale/Quellversion neuer als das neueste veröffentlichte Paket ist, das Update inkompatibel ist oder der Antwort des Update-Servers nicht vertraut werden kann. Die sichtbare Zusammenfassung vergleicht die laufende CMS-Codeversion mit dem neuesten veröffentlichten Release. Die gespeicherte installierte Version bleibt ein Wert für Installationshistorie/Update-Persistenz und kann in Update Readiness eingesehen werden, wird aber nicht verwendet, um die Install-Update-Aktion ausführbar zu machen.

Update Details hält Release Notes, Update-Bereitschaft und den letzten Update-Lauf hinter WebBlocks-UI-Akkordeonzeilen. Update Readiness ist eine Bereitschaftszusammenfassung für Installation und Update-Dienst, keine Release Notes für die Zielversion. Last Update Run zeigt die neueste relevante Laufzusammenfassung und öffnet Details bei Bedarf in einem Modal. Für Support-Fälle auf Shared Hosting steht ein Support-Bericht-Download für Super-Admins zur Verfügung; er enthält sichere Versions-/Bereitschafts-/Laufzusammenfassungen und schließt Tokens, Geheimnisse, absolute lokale Pfade und rohe Stacktraces aus.

Update-Laufaufzeichnungen werden nach Update-Prüfungen und Anwendungs-/Abbruchabläufen automatisch bereinigt. Die Standardaufbewahrung behält die letzten fünf Läufe, während der letzte fehlgeschlagene Lauf erhalten bleibt, bis ein neuerer erfolgreicher Lauf existiert. Der Haupt-Admin-Bildschirm listet keine alten Läufe auf. Terminal-Operatoren können aufbewahrte Läufe mit php artisan webblocks:updates:runs, php artisan webblocks:updates:runs --last und php artisan webblocks:updates:runs --failed einsehen; kontrolliertes Bereinigen ist mit php artisan webblocks:updates:prune-runs --keep=5 möglich.

Das kompakte Release Notes-Akkordeon in Update Details rendert strukturierte Metadaten aus Feldern wie title, summary, highlights, fixes, compatibility_notes, migration_notes, asset_notes, operator_notes und technical_notes. Das CMS rendert diese Felder als escapten Klartext und hält Bereitschaftsprüfungen, die gespeicherte installierte Version und Low-Level-Antwortdetails in Update Readiness.

Der Legacy-String release_notes wird für ältere Release-Payloads weiterhin unterstützt. Sind keine Release Notes vorhanden, zeigt der Bildschirm No release notes were provided for this release. Der Updater leitet keine Änderungen aus Versionsnummern ab.

Release-Metadaten werden lokal mit composer release:prepare vorbereitet und mit composer release:publish-update direkt an den Publisher-Dienst veröffentlicht. Der native Publisher sendet strukturierte Release-Detailfelder in Payload-Formen auf oberster Ebene und in verschachtelten Detailformen zusammen mit dem Legacy-Wert release_notes, damit der Update-Dienst kompatiblen System-Updates-Bildschirmen reichhaltige Notes liefern kann, während ältere Clients weiterhin einfache Notes erhalten. Kompatible Clients lesen strukturierte Details aus Feldern auf oberster Ebene, details, release_details sowie den Update-Server-Payloads meta.release_details oder meta.details.

GitHub Actions erstellt keine Release-Pakete mehr und veröffentlicht keine Update-Metadaten, und .github-Workflows fehlen im CMS-Repository absichtlich. Maintainer dürfen weiterhin Git-Commits und -Tags für die Quellhistorie pushen, aber System Updates konsumieren ausschließlich Update-Server-Metadaten und Paket-Artefakte. publisher.webblocksui.com ist der kanonische Dienst sowohl für die Veröffentlichung als auch für den Update-Konsum: Maintainer veröffentlichen an https://publisher.webblocksui.com/api/updates/publish, installierte CMS-Sites lesen die neuesten Metadaten von https://publisher.webblocksui.com/api/updates/latest, und Metadaten-Artefakt-URLs sollten auf https://publisher.webblocksui.com/downloads/...-Paketdownloads zeigen. Installierte CMS-Sites konfigurieren in normalen .env-Dateien keine Umgebungsschlüssel für Publisher/Update-Server, Produkt oder Kanal, weil der CMS-Produktcode den Standard-Release-Server, den Produktschlüssel, den Stable-Kanal, den Latest-Pfad und den Publish-Pfad über ReleaseDefaults besitzt. Die frühere Bridge updates.webblocksui.com ist nur noch historisch und sollte nicht als aktiver Konfigurationspfad verwendet werden.

Maintainer-Befehle:

Für die Veröffentlichung durch Maintainer wird normalerweise nur WEBBLOCKS_PUBLISHER_TOKEN benötigt. Update-Prüfungen installierter CMS-Instanzen verwenden Produktstandards für https://publisher.webblocksui.com, Produkt webblocks-cms, Kanal stable und Lesepfad /api/updates/latest; die Veröffentlichung durch Maintainer verwendet dieselbe produkteigene Identität und den Publish-Pfad /api/updates/publish. Publish-Läufe mit gecachter Konfiguration aktualisieren nur das Publisher-Token aus der Projekt-.env, sodass ein lokal konfiguriertes Token ohne Shell-Exporte erkannt wird. Ein Dry-Run validiert Eingaben ohne Upload. Eine echte Veröffentlichung ohne Token meldet einen kontrollierten Nicht-veröffentlicht-Zustand, endet mit Fehlerstatus und darf nicht als Release-Veröffentlichung behandelt werden.

Wenn ein In-App-System-Update erfolgreich angewendet wurde, führt WebBlocks CMS den Post-Install-Ablauf in dieser Reihenfolge aus:

• Migrationsbehandlung für die aktuelle Installationsstrategie
• Cache-Leerungsschritte
• Aufzeichnung des Update-Laufs
• Persistierung der installierten Version

Normale System Updates wenden veröffentlichte Release-Pakete an. Sie führen nicht automatisch Core-Katalog-Seeding, block-types:sync-core, Icon-Synchronisation, Slot-Typ-Reparatur, Seitenlayout-Slot-Reparatur oder umfassende Katalogreparatur aus. Erfordert ein Release eine Schema- oder Datentransformation, muss diese als explizite Update-Migration für dieses Release behandelt werden.

Die Cache-Leerungsschritte umfassen das Leeren von Laravel-Config, Views, Anwendungscache und Routen, damit aktualisierte paketeigene Blade-Layouts und -Helfer nach dem Dateiaustausch neu kompiliert werden. Laden Sie auf Live-PHP-FPM-Installationen, bei denen OPcache so konfiguriert ist, dass Zeitstempel nicht validiert werden, nach einem erfolgreichen Update den betreffenden PHP-FPM-Dienst neu, damit PHP keine Paketklassen von vor dem Update weiter aus dem Speicher ausliefern kann.

Für quellcodeverwaltete Wartungs-Checkouts behält die Migrationsbehandlung die historische Root-Autorität database/migrations und führt artisan migrate --force aus. Dieser Pfad wird nur gewählt, wenn das Root-Composer-Manifest die WebBlocks-CMS-Autoload-Autorität des Wartungsrepositorys hat, einschließlich WebBlocks\\Cms\\ => packages/webblocks-cms/src/.

Für paketnative neue Composer-Konsumenten, die mit webblocks:install installiert wurden, führt System Update das Root-Verzeichnis database/migrations der Host-Laravel-Anwendung nicht aus. Das bloße Vorhandensein des Paketverzeichnisses ist kein Signal für einen Quell-Checkout. Das verhindert, dass ausstehende Laravel-Starter-Migrationen wie 0001_01_01_000000_create_users_table.php mit CMS-Tabellen kollidieren, die vom Fresh-Install-Schema des Pakets erstellt wurden. Paket-Konsumenten-Updates wenden das Release-Artefakt auf vendor/fklavyenet/webblocks-cms an und führen nur dann dedizierte paketeigene Update-Migrationen aus vendor/fklavyenet/webblocks-cms/database/migrations/updates aus, wenn dieses Verzeichnis PHP-Migrationsdateien enthält; andernfalls verzeichnet der Updater, dass Host-Migrationen übersprungen wurden, und fährt mit Cache-Leerungen und der Persistierung der installierten Version fort. Paket-Update-Migrationen sind auch der Ort für sichere Schemareparaturen bestehender Installationen, etwa das Ergänzen fehlender Parent-Keys, die für die vollständige Portabilität von Datenbank-Backup/-Restore erforderlich sind.

Jede WebBlocks-CMS-Schemaänderung, die vom Laufzeitcode benötigt wird, muss beide Installationspfade unterstützen:

1. Neue/Paket-Konsumenten-Installationen: Aktualisieren Sie den normalen oder den Fresh-Schema-Migrationspfad.
2. Bestehende paketnative Installationen, die über System Updates aktualisiert werden: Fügen Sie eine Paket-Update-Migration unter dem Paketverzeichnis database/migrations/updates hinzu; installierte Konsumenten führen sie aus vendor/fklavyenet/webblocks-cms/database/migrations/updates aus.

Das Fresh-Schema allein reicht nicht aus. Wenn neuer Laufzeitcode eine Tabelle oder Spalte erwartet, muss das Release eine Update-Migration für bestehende Installationen enthalten, oder das Update muss sicher fehlschlagen, bevor der neue Codepfad einen rohen 500-Fehler auslösen kann. Paketnative System Updates dürfen nicht verlangen, dass gewöhnliche Benutzer sich nach einem erfolgreichen Update per SSH auf einer Site anmelden und Migrationen manuell ausführen.

Ein erfolgreiches paketnatives System Update bedeutet, dass angewendeter Code, benötigtes Schema, Cache-Leerungen und die Versions-/Schemabereitschaft nach dem Anwenden übereinstimmen. Admin-, API- und Laufzeitseiten, die von neu hinzugefügtem Schema abhängen, sollten bei fehlendem Schema kontrollierte Setup-/Update-Hinweise anzeigen, statt rohe Framework-/Datenbankfehler offenzulegen. Der API-Token-Vorfall von 1.32.146 auf 1.32.147 ist der Referenz-Fehlermodus: cms_api_tokens existierte nur im normalen Migrationspfad, das paketnative QuizTem aktualisierte den Code, und System -> API Tokens lieferte rohe 500-Fehler, bis 1.32.147 eine Paket-Update-Migration und eine saubere Bereitschaftsbehandlung ergänzte.

Release-Berichte zu Schemaänderungen müssen explizit beantworten:

• Fresh-Schema-Pfad aktualisiert: ja/nein
• Paket-Update-Migration hinzugefügt: ja/nein
• Regressionstest für die Update-Migration hinzugefügt: ja/nein
• kontrolliertes Verhalten bei fehlendem Schema nötig/hinzugefügt: ja/nein

Während der Paketumstellung können manche Installationen noch eine veraltete Kopie packages/webblocks-cms im Installationsstamm oder eine alte verschachtelte Vendor-Übergangskopie haben. Diese Pfade sind Legacy-Übergangsartefakte, nicht die aktive paketnative Source of Truth. Paketnatives System Update ersetzt nun das kanonische Composer-Paketstammverzeichnis unter vendor/fklavyenet/webblocks-cms und verifiziert die Zielversion aus diesem Paketstamm. Es behält packages/webblocks-cms nicht als zweite aktualisierte Laufzeitkopie.

Ältere Installationen können unter vendor/fklavyenet/webblocks-cms ein repositoryförmiges Composer-Vendor-Verzeichnis mit Root-Dateien wie artisan, app/, bootstrap/, packages/webblocks-cms/, plugins/ oder tests/ haben. System Update normalisiert dieses Vendor-Verzeichnis, indem es durch das flache paketbasierte Artefakt ersetzt wird. Der resultierende Paketstamm enthält Paketdateien wie composer.json, src/, docs/, routes/, resources/, database/, public/, config/ und stubs/ direkt unter vendor/fklavyenet/webblocks-cms. Paketnative Updates normalisieren die installierten Paketmetadaten von Composer, bevor optimierte Autoload-Dateien neu generiert werden, und verifizieren anschließend, dass die generierten Composer-Autoload-Metadaten WebBlocks\Cms\ aus vendor/fklavyenet/webblocks-cms/src auflösen, nicht aus dem alten verschachtelten vendor/fklavyenet/webblocks-cms/packages/webblocks-cms/src. Bleiben veraltete verschachtelte Pfade übrig, schlägt der Update-Lauf fehl, statt mit einer defekten Admin-Laufzeit Erfolg zu melden.

Moderne Updates bewahren die mit der v1.32.56-Migration eingeführte Trennung von /webadmin-Admin und /cms-Assets. /cms ist ausschließlich ein statischer Asset-Namespace und kein Admin-Präfix, weil Nginx-try_files /cms/ als physisches Verzeichnis public/cms/ auflösen kann, bevor Laravel eine Route sieht. Updates dürfen weder im Installationsstamm noch in den öffentlichen Paket-Assets CMS-eigene /cms-Admin-Aliasse, /cms-Weiterleitungen, /admin-Routen oder eine public/cms/index.php-Übergabe wiederherstellen.

Dieser Abschnitt ist historisch. Der Updater von 1.31.53 validierte den alten root-verwalteten Archivvertrag: artisan und composer.json mussten im Archivstamm oder in einem einzelnen Wrapper-Verzeichnis vorhanden sein. Paketbasierte Artefakte wie 1.32.31 enthielten absichtlich kein Root-artisan, daher schlugen diese alten Clients vor dem Anwenden mit Package validation failed because composer.json and artisan were not found at the archive root. fehl.

Die ausgemusterte Bridge-Strategie war zweistufig:

• Ein Bridge-Release-Artefakt im alten root-verwalteten Format veröffentlichen oder erneut veröffentlichen, gebaut aus einer bridge-fähigen Quelle, die noch die Legacy-Wrapper App\Support\System\Updates\* hatte und bereits strikte paketbasierte fklavyenet/webblocks-cms-Archive validierte. Für die Bridge 1.32.33 war v1.32.30 die Quellreferenz.
• Paketbasierte Releases mit minimum_client_version auf 1.32.18 oder neuer veröffentlichen, damit alten Clients das neueste paketbasierte Artefakt nicht vor der Bridge angeboten wurde.
• Nach dem Anwenden der Bridge konnte der installierte Updater das strikte paketbasierte fklavyenet/webblocks-cms-Artefaktformat moderner Releases validieren und anwenden.

scripts/build-root-managed-bridge-archive.sh VERSION [OUTPUT_DIR] [GIT_REF] wird nur als archiviertes/manuelles Wiederherstellungswerkzeug für das Bridge-ZIP im alten Format beibehalten; zum Beispiel scripts/build-root-managed-bridge-archive.sh 1.32.33 dist v1.32.30. Der Builder schließt installationseigene Pfade wie .env, storage/, project/, public/site/, public/storage und Root-config/ absichtlich aus; paketeigene Standardwerte unter packages/webblocks-cms/config bleiben Teil der Paket-Laufzeit. Die routinemäßige paketnative Validierung führt diesen Bridge-Pfad nicht aus.

Der abgeschlossene historische Pfad war 1.31.53 -> 1.32.33 bridge -> 1.32.34+ package-rooted. Bereits bridge-fähige Installationen wie 1.32.30 übersprangen die Bridge und aktualisierten direkt auf ein paketbasiertes 1.32.34+-Release. Aktuelle Release-Gates schützen nur das paketbasierte Artefakt und das paketnative Updater-Verhalten.

Katalogreparatur und -synchronisation sind explizite Wartungsaktionen, getrennt von System Updates. Verwenden Sie:

Der Befehl unterstützt eingegrenzte Wartung mit --block-types, --slot-types, --page-layouts und --icons. Führen Sie ihn zuerst mit --dry-run aus, um zu berichten, welche Zeilen erstellt, aktualisiert, unverändert gelassen oder übersprungen würden. Der Befehl ist idempotent, bewahrt installationsspezifische/benutzerdefinierte Katalogzeilen und löscht keine benutzerdefinierten Zeilen.

Die Low-Level-Blocktyp-Synchronisation bleibt aus Kompatibilitätsgründen verfügbar:

Der Blocktyp-Reparaturpfad hält den datenbankgestützten block_types-Katalog auf bestehenden Installationen mit dem ausgelieferten CMS-Kernkatalog abgeglichen:

• fehlende Kern-Blocktypen werden erstellt
• bestehende Kern-Blocktypen werden an Ort und Stelle aktualisiert
• benutzerdefinierte installationsspezifische Blocktypen bleiben erhalten
• doppelte Kernzeilen werden nicht erstellt

Dieser Wartungs-Workflow schließt die Lücke, dass eine Installation Katalogzeilen auffrischen muss, ohne dass jede Anwendung eines Release-Pakets eine umfassende datenbankgestützte Katalogreparatur durchführt.

Wenn der Updater innerhalb eines git-gestützten Installationsklons läuft, der noch auf das kanonische CMS-Upstream zeigt, deaktiviert das CMS nun nach den Post-Install-Befehlen auch automatisch den origin-Push, sodass künftige versehentliche git push-Versuche klar fehlschlagen, während normaler Fetch- oder Pull-Zugriff verfügbar bleibt.

• Betrieb
• Installation
• Entwicklungsworkflow