Aggiornamenti

Gli aggiornamenti in WebBlocks CMS sono basati sulle release e sui pacchetti.

• La versione installata riflette l'ultima release reale applicata all'installazione.
• Il normale sviluppo del codice sorgente non modifica la versione installata.
• L'updater integrato applica pacchetti di release pubblicati, non le modifiche locali dell'albero di lavoro.
• I nuovi consumatori Composer devono installare prima con composer require fklavyenet/webblocks-cms e php artisan webblocks:install prima di usare il normale flusso di aggiornamento basato sulle release.
• Le attuali installazioni native di pacchetto consumano direttamente gli ZIP di release con radice di pacchetto.
• Le System Updates native di pacchetto applicano l'artefatto del pacchetto alla radice canonica del pacchetto Composer, vendor/fklavyenet/webblocks-cms, così che l'aggiornamento con Composer e la System Update producano la stessa struttura di pacchetto installata.
• Storicamente, le installazioni precedenti al modello nativo di pacchetto, come 1.31.53, non potevano consumare direttamente gli ZIP di release con radice di pacchetto e richiedevano prima il ponte gestito dalla radice nel vecchio formato 1.32.33. Quel percorso ponte è ora ritirato dalla validazione di release ordinaria perché non restano vecchie installazioni gestite dalla radice da supportare nei controlli normali.

• Eseguite gli aggiornamenti solo da release pubblicate.
• Mantenete i file specifici dell'installazione nei percorsi preservati come .env, storage/ e project/.
• Trattate separatamente i flussi di lavoro di sviluppo e di release.
• Nelle copie di lavoro di manutenzione gestite da sorgente, le modifiche locali sono già presenti nell'albero di lavoro. Le System Updates non devono essere usate per applicare quelle modifiche locali, e la versione del codice CMS in esecuzione viene confrontata con l'ultima release pubblicata per verificare la disponibilità di aggiornamenti.
• I pacchetti di release contengono solo codice riutilizzabile del core del CMS e non devono includere contenuti project/ specifici dell'installazione.
• I percorsi preservati durante l'aggiornamento non modificano il confine del pacchetto di release: project/ resta locale all'installazione e fuori dall'artefatto pubblicato.
• Le copie di lavoro CMS installate sono consumatrici di aggiornamenti, non publisher upstream. Se un'installazione ha un origin git, mantenete l'accesso in fetch se necessario ma disabilitate il push con git remote set-url --push origin DISABLED.
• Una System Update viene registrata come riuscita solo dopo che il runtime del pacchetto applicato riporta la versione di destinazione dalla fonte di versione canonica WebBlocks\Cms\Support\WebBlocks. Se il codice applicato riporta ancora una versione più vecchia o inattesa, l'esecuzione viene registrata come fallita e gli operatori devono ripristinare il backup precedente all'aggiornamento oppure ispezionare lo stato del filesystem e della cache prima di riprovare.

Prima di modificare il comportamento di compatibilità di release, aggiornamento, pubblicazione, Publisher, artefatti o migrazioni del CMS, consultate WebBlocks Advisor e includete la risposta come nota di implementazione nel report. Se Advisor non ha la risposta corretta, aggiornate prima la fonte di conoscenza o il chunk pertinente invece di inventare un flusso di lavoro estemporaneo.

La schermata System Updates mostra dettagli di release leggibili prima che un amministratore avvii un aggiornamento. Il flusso principale ha due card: Install Update e Update Details. Install Update spiega se è disponibile un aggiornamento, se la versione del codice CMS in esecuzione è aggiornata, se la versione locale o da sorgente è più recente dell'ultimo pacchetto pubblicato, se l'aggiornamento è incompatibile oppure se la risposta del server di aggiornamento non è affidabile. Il riepilogo visibile confronta la versione del codice CMS in esecuzione con l'ultima release pubblicata. La versione installata memorizzata resta un valore di cronologia dell'installazione e di persistenza degli aggiornamenti e può essere ispezionata in Update Readiness, ma non viene usata per rendere attiva l'azione Install Update.

Update Details mantiene le note di release, la prontezza all'aggiornamento e l'ultima esecuzione di aggiornamento dietro righe di accordion WebBlocks UI. Update Readiness è un riepilogo di prontezza dell'installazione e del servizio di aggiornamento, non le note di release della versione di destinazione. Last Update Run mostra il riepilogo dell'esecuzione rilevante più recente e apre i dettagli in una modale quando serve. È disponibile il download di un report di supporto per super-amministratori destinato ai casi di supporto su hosting condiviso; include riepiloghi sicuri di versione, prontezza ed esecuzioni ed esclude token, segreti, percorsi locali assoluti e stack trace grezzi.

I record delle esecuzioni di aggiornamento vengono ripuliti automaticamente dopo i controlli di aggiornamento e i flussi di applicazione o annullamento. La conservazione predefinita mantiene le ultime cinque esecuzioni, mentre l'ultima esecuzione fallita viene preservata finché non esiste un'esecuzione riuscita più recente. La schermata principale di amministrazione non elenca le esecuzioni vecchie. Gli operatori da terminale possono ispezionare le esecuzioni conservate con php artisan webblocks:updates:runs, php artisan webblocks:updates:runs --last e php artisan webblocks:updates:runs --failed; la pulizia controllata è disponibile con php artisan webblocks:updates:prune-runs --keep=5.

L'accordion compatto Release Notes in Update Details rende metadati strutturati a partire da campi come title, summary, highlights, fixes, compatibility_notes, migration_notes, asset_notes, operator_notes e technical_notes. Il CMS rende quei campi come testo semplice con escape e mantiene i controlli di prontezza, la versione installata memorizzata e i dettagli di risposta di basso livello in Update Readiness.

La stringa legacy release_notes resta supportata per i payload di release più vecchi. Se non sono presenti note di release, la schermata indica No release notes were provided for this release. L'updater non deduce le modifiche dai numeri di versione.

I metadati di release vengono preparati localmente con composer release:prepare e pubblicati direttamente sul servizio Publisher con composer release:publish-update. Il publisher nativo invia campi strutturati di dettaglio della release in payload di primo livello e annidati, insieme al valore legacy release_notes, così che il servizio di aggiornamento possa fornire note complete alle schermate System Updates compatibili mentre i client più vecchi continuano a ricevere note semplici. I client compatibili leggono i dettagli strutturati dai campi di primo livello, da details, release_details e dai payload del server di aggiornamento meta.release_details o meta.details.

GitHub Actions non crea più pacchetti di release né pubblica metadati di aggiornamento, e i workflow .github sono intenzionalmente assenti dal repository del CMS. I manutentori possono ancora inviare commit e tag git per la cronologia del sorgente, ma le System Updates consumano soltanto metadati del server di aggiornamento e artefatti di pacchetto. publisher.webblocksui.com è il servizio canonico sia per la pubblicazione sia per il consumo degli aggiornamenti: i manutentori pubblicano su https://publisher.webblocksui.com/api/updates/publish, i siti CMS installati leggono gli ultimi metadati da https://publisher.webblocksui.com/api/updates/latest e gli URL degli artefatti nei metadati devono puntare ai download di pacchetto su https://publisher.webblocksui.com/downloads/.... I siti CMS installati non configurano chiavi di ambiente per Publisher/server di aggiornamento, prodotto o canale nei normali file .env, perché il codice di prodotto del CMS possiede il server di release predefinito, la chiave di prodotto, il canale stabile, il percorso di lettura e il percorso di pubblicazione tramite ReleaseDefaults. Il vecchio ponte updates.webblocksui.com è solo storico e non deve essere usato come percorso di configurazione attivo.

Comandi per i manutentori:

La pubblicazione da parte del manutentore normalmente richiede solo WEBBLOCKS_PUBLISHER_TOKEN. I controlli di aggiornamento del CMS installato usano i valori predefiniti di prodotto per https://publisher.webblocksui.com, prodotto webblocks-cms, canale stable e percorso di lettura /api/updates/latest; la pubblicazione del manutentore usa la stessa identità di prodotto e il percorso di pubblicazione /api/updates/publish. Le esecuzioni di pubblicazione con configurazione in cache aggiornano solo il token del publisher dal .env del progetto, così che un token configurato localmente venga rilevato senza export da shell. L'esecuzione a vuoto valida gli input senza caricare nulla. Una pubblicazione reale senza token segnala uno stato controllato di mancata pubblicazione, termina senza successo e non deve essere considerata una pubblicazione di release.

Quando una System Update integrata viene applicata con successo, WebBlocks CMS esegue il flusso post-installazione in questo ordine:

• gestione delle migrazioni per la strategia di installazione corrente
• passaggi di pulizia della cache
• registrazione dell'esecuzione di aggiornamento
• persistenza della versione installata

Le normali System Updates applicano pacchetti di release pubblicati. Non eseguono automaticamente il seeding del catalogo core, block-types:sync-core, la sincronizzazione delle icone, la riparazione dei tipi di slot, la riparazione degli slot del layout di pagina o la riparazione estesa del catalogo. Se una release richiede una trasformazione di schema o di dati, deve essere gestita come migrazione di aggiornamento esplicita per quella release.

I passaggi di pulizia della cache comprendono le pulizie di configurazione, viste, cache applicativa e rotte di Laravel, così che i layout e gli helper Blade di proprietà del pacchetto vengano ricompilati dopo la sostituzione dei file. Su installazioni PHP-FPM in produzione con OPcache configurato per non validare i timestamp, ricaricate il servizio PHP-FPM pertinente dopo un aggiornamento riuscito, in modo che PHP non continui a servire dalla memoria classi del pacchetto precedenti all'aggiornamento.

Per le copie di lavoro di manutenzione gestite da sorgente, la gestione delle migrazioni mantiene l'autorità storica della radice database/migrations ed esegue artisan migrate --force. Questo percorso viene selezionato solo quando il manifest Composer della radice possiede l'autorità di autoload di WebBlocks CMS del repository di manutenzione, inclusa WebBlocks\\Cms\\ => packages/webblocks-cms/src/.

Per i nuovi consumatori Composer nativi di pacchetto installati con webblocks:install, la System Update non esegue la directory radice database/migrations dell'applicazione Laravel ospitante. La sola presenza della directory del pacchetto non è un segnale di checkout del sorgente. Questo evita che migrazioni starter di Laravel in sospeso, come 0001_01_01_000000_create_users_table.php, entrino in conflitto con le tabelle CMS create dallo schema di installazione nuova del pacchetto. Gli aggiornamenti dei consumatori del pacchetto applicano l'artefatto di release a vendor/fklavyenet/webblocks-cms ed eseguono solo migrazioni di aggiornamento dedicate di proprietà del pacchetto da vendor/fklavyenet/webblocks-cms/database/migrations/updates quando quella directory contiene file di migrazione PHP; in caso contrario l'updater registra che le migrazioni dell'host sono state saltate e prosegue con le pulizie di cache e la persistenza della versione installata. Le migrazioni di aggiornamento del pacchetto sono anche il luogo adatto per riparazioni sicure dello schema su installazioni esistenti, come l'aggiunta di chiavi padre mancanti necessarie alla portabilità del backup/ripristino completo del database.

Qualsiasi modifica allo schema di WebBlocks CMS richiesta dal codice a runtime deve supportare entrambi i percorsi di installazione:

1. Installazioni nuove o da consumatore del pacchetto: aggiornate il percorso di migrazione dello schema normale o di installazione nuova.
2. Installazioni native di pacchetto esistenti aggiornate tramite System Updates: aggiungete una migrazione di aggiornamento del pacchetto sotto database/migrations/updates del pacchetto; i consumatori installati la eseguono da vendor/fklavyenet/webblocks-cms/database/migrations/updates.

Lo schema di installazione nuova da solo non basta. Se il nuovo codice a runtime si aspetta una tabella o una colonna, la release deve includere una migrazione di aggiornamento per le installazioni esistenti, oppure l'aggiornamento deve fallire in modo sicuro prima che il nuovo percorso di codice possa generare un errore 500 grezzo. Le System Updates native di pacchetto non devono richiedere agli utenti ordinari di collegarsi via SSH a un sito ed eseguire migrazioni manuali dopo un aggiornamento riuscito.

Una System Update nativa di pacchetto riuscita significa che il codice applicato, lo schema richiesto, le pulizie di cache e la prontezza di versione e schema dopo l'applicazione sono allineati. Le pagine di amministrazione, API e runtime che dipendono da schema appena aggiunto devono mostrare indicazioni controllate di configurazione o aggiornamento in caso di schema mancante, invece di esporre errori grezzi del framework o del database. L'incidente dei token API tra 1.32.146 e 1.32.147 è il caso di riferimento: cms_api_tokens esisteva solo nel percorso di migrazione normale, QuizTem, nativo di pacchetto, ha aggiornato il codice e System -> API Tokens ha restituito un errore 500 grezzo finché la 1.32.147 non ha aggiunto una migrazione di aggiornamento del pacchetto e una gestione corretta della prontezza.

I report di release con modifiche allo schema devono rispondere esplicitamente a:

• percorso dello schema di installazione nuova aggiornato: sì/no
• migrazione di aggiornamento del pacchetto aggiunta: sì/no
• test di regressione della migrazione di aggiornamento aggiunto: sì/no
• comportamento corretto in assenza di schema necessario/aggiunto: sì/no

Durante la transizione a pacchetto, alcune installazioni possono avere ancora una copia obsoleta packages/webblocks-cms nella radice dell'installazione o una vecchia copia annidata di transizione in vendor. Questi percorsi sono artefatti legacy della transizione, non la fonte di verità nativa di pacchetto attiva. La System Update nativa di pacchetto sostituisce ora la radice canonica del pacchetto Composer in vendor/fklavyenet/webblocks-cms e verifica la versione di destinazione da quella radice di pacchetto. Non mantiene packages/webblocks-cms come seconda copia runtime aggiornata.

Le installazioni più vecchie possono avere una directory vendor Composer in forma di repository in vendor/fklavyenet/webblocks-cms, con file di radice come artisan, app/, bootstrap/, packages/webblocks-cms/, plugins/ o tests/. La System Update normalizza quella directory vendor sostituendola con l'artefatto piatto con radice di pacchetto. La radice di pacchetto risultante contiene file del pacchetto come composer.json, src/, docs/, routes/, resources/, database/, public/, config/ e stubs/ direttamente sotto vendor/fklavyenet/webblocks-cms. Gli aggiornamenti nativi di pacchetto normalizzano i metadati dei pacchetti installati di Composer prima di rigenerare i file di autoload ottimizzati, poi verificano che i metadati di autoload generati da Composer risolvano WebBlocks\Cms\ da vendor/fklavyenet/webblocks-cms/src, non dal percorso annidato legacy vendor/fklavyenet/webblocks-cms/packages/webblocks-cms/src. Se restano percorsi annidati obsoleti, l'esecuzione dell'aggiornamento fallisce invece di segnalare un successo con un runtime di amministrazione non funzionante.

Gli aggiornamenti moderni preservano la separazione tra l'amministrazione /webadmin e gli asset /cms introdotta dalla migrazione della v1.32.56. /cms è solo uno spazio dei nomi per asset statici, non un prefisso di amministrazione, perché il try_files di Nginx può risolvere /cms/ come la directory fisica public/cms/ prima che Laravel veda una rotta. Gli aggiornamenti non devono ripristinare alias di amministrazione /cms di proprietà del CMS, redirect /cms, rotte /admin o un passaggio a public/cms/index.php, né nella radice dell'installazione né negli asset pubblici del pacchetto.

Questa sezione è storica. L'updater della 1.31.53 validava il vecchio contratto di archivio gestito dalla radice: artisan e composer.json dovevano trovarsi nella radice dell'archivio o dentro un'unica directory contenitore. Gli artefatti con radice di pacchetto come 1.32.31 non contenevano intenzionalmente un artisan di radice, perciò quei vecchi client fallivano prima dell'applicazione con Package validation failed because composer.json and artisan were not found at the archive root.

La strategia del ponte ritirato prevedeva due passaggi:

• Pubblicare o ripubblicare un artefatto di release ponte nella vecchia forma gestita dalla radice, costruito da un sorgente compatibile con il ponte che conteneva ancora i wrapper legacy App\Support\System\Updates\* e che convalidava già archivi stretti con radice di pacchetto fklavyenet/webblocks-cms. Per il ponte 1.32.33 il riferimento sorgente era v1.32.30.
• Pubblicare release con radice di pacchetto con minimum_client_version impostato a 1.32.18 o successivo, in modo che ai client vecchi non venisse proposto l'ultimo artefatto con radice di pacchetto prima del ponte.
• Dopo l'applicazione del ponte, l'updater installato poteva convalidare e applicare la forma stretta di artefatto con radice di pacchetto fklavyenet/webblocks-cms usata dalle release moderne.

scripts/build-root-managed-bridge-archive.sh VERSION [OUTPUT_DIR] [GIT_REF] è mantenuto soltanto come strumento archiviato di ripristino manuale per lo ZIP ponte nella vecchia forma; per esempio scripts/build-root-managed-bridge-archive.sh 1.32.33 dist v1.32.30. Il builder esclude intenzionalmente i percorsi di proprietà dell'installazione come .env, storage/, project/, public/site/, public/storage e il config/ radice; i valori predefiniti di proprietà del pacchetto sotto packages/webblocks-cms/config restano parte del runtime del pacchetto. La validazione ordinaria nativa del pacchetto non esegue questo percorso ponte.

Il percorso storico completato è stato 1.31.53 -> 1.32.33 bridge -> 1.32.34+ package-rooted. Le installazioni già compatibili con il ponte, come 1.32.30, hanno saltato il ponte e sono state aggiornate direttamente a una release con radice di pacchetto 1.32.34+. Gli attuali controlli di rilascio proteggono soltanto l'artefatto con radice di pacchetto e il comportamento dell'updater nativo del pacchetto.

La riparazione e la sincronizzazione del catalogo sono azioni di manutenzione esplicite, separate da System Updates. Utilizzate:

Il comando supporta la manutenzione mirata con --block-types, --slot-types, --page-layouts e --icons. Eseguitelo prima con --dry-run per vedere quali righe verrebbero create, aggiornate, lasciate invariate o saltate. Il comando è idempotente, preserva le righe di catalogo personalizzate o specifiche dell'installazione e non elimina righe personalizzate.

La sincronizzazione dei tipi di blocco di livello inferiore resta disponibile per compatibilità:

Il percorso di riparazione dei tipi di blocco mantiene il catalogo block_types memorizzato nel database allineato al catalogo del core CMS distribuito nelle installazioni esistenti:

• i tipi di blocco core mancanti vengono creati
• i tipi di blocco core esistenti vengono aggiornati sul posto
• i tipi di blocco personalizzati specifici dell'installazione vengono preservati
• non vengono create righe core duplicate

Questo flusso di manutenzione copre il caso in cui un'installazione debba aggiornare le righe di catalogo senza costringere ogni applicazione di un pacchetto di release a eseguire un'ampia riparazione del catalogo nel database.

Quando l'updater viene eseguito all'interno di un clone di installazione gestito con git che punta ancora all'upstream canonico del CMS, il CMS disabilita ora automaticamente anche il push su origin dopo i comandi di post-installazione, così che futuri tentativi accidentali di git push falliscano in modo chiaro mentre il normale accesso in fetch o pull resta disponibile.

• Operazioni
• Installazione
• Flusso di lavoro di sviluppo