Nexsoon Office R5.65 — configurazione e crescita della piattaforma

1. Da uno spazio a più server

Questa versione mantiene l'installazione singola e introduce configurazione separata dall'interfaccia degli editor. Il browser continua a usare un solo indirizzo HTTPS per Nexsoon Office. Dietro quell'indirizzo possono esserci un server web, più server web, un archivio separato e worker su altre macchine.

“Più spazi” significa servizi collegati: caricare copie indipendenti in hosting diversi non crea una piattaforma distribuita. Database, chiave crittografica, archivio, sessioni e configurazione devono essere coerenti. Il numero dei worker è indipendente da quello dei server web.

Non è necessario distribuire subito tutto. Senza platform.json il comportamento predefinito resta disco locale e sessioni su file. Uno spazio condiviso non garantisce Docker, processi Python persistenti o Redis: verificare le capacità del proprio piano. Nessuna compatibilità specifica con il piano Aruba dell'utente è stata collaudata in questa consegna.

2. I pochi punti di configurazione

1. _server/config.php esistente: configurazione storica, account del database, chiave dell'installazione e servizi già collegati. Non sostituirlo con un esempio e non cambiare la chiave: protegge dati già cifrati.
2. _server/platform.json: modalità, tipo di archivio, sessioni e valori operativi iniziali. Gli esempi sono in nexsoon-office-r5-1-2/deployment/platform/.
3. _server/environment.env, facoltativo: indirizzi e credenziali dei nuovi servizi. Le variabili già definite dal processo prevalgono su questo file. Le variabili esplicitamente definite prevalgono sulla corrispondente configurazione storica.
4. Distribuzione sul server: deployment/compose.platform.yml per il web e deployment/compose.worker-aruba.yml per i worker, se si usa Docker. Nell'hosting PHP classico non occorre Docker: si carica l'applicazione e si configurano i servizi disponibili.

Si usa JSON, letto direttamente da PHP, per non introdurre un interprete YAML nell'applicazione. YAML rimane nei file Docker Compose.

Percorsi esterni al sito possono essere indicati con NXO_CONFIG, NXO_ENV_FILE, NXO_PLATFORM_FILE. Quelli espliciti devono esistere; un profilo esplicito mancante non viene ignorato. Conservare preferibilmente i segreti fuori dalla directory pubblica. La cartella _server è protetta da .htaccess su Apache; Nginx richiede regole esplicite, fornite come esempio.

Il file ambiente accetta NXO_NOME=valore, righe vuote, commenti su riga separata e virgolette esterne. Non espande $variabili, comandi shell o escape. Esempio: la password con # resta letterale; non scrivere commenti alla fine del valore.

3. Aggiornamento da R5.65

Eseguire prima un backup coerente del database, dell'archivio e dei segreti. Installare i file applicativi preservando _server/config.php, eventuale app/config.php, cartella private, archivio esterno e impostazioni personali. Non estrarre il pacchetto sopra l'installazione con opzioni che cancellano file non presenti nello ZIP.

Questa release aggiunge una tabella: platform_settings, tramite migrazione 008. Contiene revisione, impostazioni, autore e data; non contiene password o documenti. Le migrazioni precedenti restano necessarie.

Aprire il pannello amministratore, Diagnostica → Aggiornamento tabelle, con la procedura esistente. In alternativa importare migrations/008_mysql.sql nel database Nexsoon corretto tramite phpMyAdmin. Lo schema completo in database/NexsoonOffice_MySQL_Aruba.sql include l'aggiunta. L'operazione usa CREATE TABLE IF NOT EXISTS e non cancella le tabelle esistenti.

Prima della migrazione la configurazione da file e il funzionamento singolo restano disponibili; salvataggio e cronologia delle nuove impostazioni amministrative richiedono la tabella.

4. Comandi del pannello Piattaforma e capacità

Nel pannello amministratore aprire Servizio. La sezione nuova è riservata all'amministratore principale dell'installazione, come gli altri comandi del server.

Le impostazioni salvate nel database prevalgono sui valori runtime del file e sono lette dai nodi a ogni richiesta. Le impostazioni di topologia, i segreti e i percorsi NON vengono cambiati dal pannello: modificare l'archivio richiede prima la migrazione dei dati.

Il passaggio in sola lettura viene rifiutato mentre esistono job running. Prima fermare le nuove richieste e attendere la conclusione; per lavori abbandonati mantenere attivi i worker affinché la gestione delle lease possa recuperarli o portarli a errore. Annullare esplicitamente i job da interrompere.

5. Archivio locale, condiviso e S3

local conserva il percorso storico storage/blobs. I file temporanei e le sessioni locali rimangono sotto storage.

shared richiede una directory assoluta già montata e scrivibile da ogni nodo. Il filesystem deve garantire lock flock condivisi e rinomina atomica nello stesso filesystem. Configurare l'avvio del servizio in modo che dipenda dal mount: la sola esistenza di una directory vuota non prova che il filesystem remoto sia montato. Il profilo non crea automaticamente la directory e non ripiega su disco locale.

s3 usa un bucket privato già creato e questi valori: NXO_S3_ENDPOINT, NXO_S3_REGION, NXO_S3_BUCKET, NXO_S3_PREFIX, NXO_S3_ACCESS_KEY, NXO_S3_SECRET_KEY; NXO_S3_SESSION_TOKEN è facoltativo. Endpoint HTTPS senza percorso, query o credenziali nell'URL; accesso path-style e firma SigV4. Il provider deve supportare PUT condizionale If-None-Match, GET, DELETE e ListObjectsV2. Sono richiesti PHP cURL e SimpleXML.

Le autorizzazioni del bucket devono limitare lettura/scrittura/eliminazione al prefisso dell'installazione e consentire l'elenco di quel prefisso. Il browser non riceve le credenziali e i documenti restano scaricati tramite API autorizzata. Il bucket non diventa pubblico e non serve abilitarne CORS per l'editor.

Gli oggetti mantengono identificatori immutabili, senza nomi dei documenti nel percorso. La scrittura usa pubblicazione atomica su directory e PUT condizionale su S3. I download verificano dimensione e SHA-256 prima di consegnare i byte. S3 usa temporanei sul nodo web: dimensionare anche quel disco. Il trasporto attuale non include upload multipart, URL presigned, streaming di video multi-gigabyte o cifratura KMS gestita dal pannello. Cifratura, replica e lifecycle del bucket sono configurazioni del provider.

6. Migrazione senza cambiare gli identificatori dei documenti

La copia riguarda tutte le versioni referenziate, inclusi i documenti nel cestino. Non cancella la sorgente e non modifica i riferimenti nel database. È ripetibile: gli oggetti già presenti vengono confrontati e quelli differenti causano un errore.

1. Preparare il nuovo archivio privato, le credenziali e il backup; mantenere attivo nel profilo l'archivio sorgente.
2. Disattivare Accetta nuove lavorazioni e attendere lo svuotamento. Se un tipo è disabilitato, la sua coda non si svuota: riabilitarlo o annullare i job.
3. Disattivare Consenti salvataggi e verificare zero job in corso.
4. Mettere il sito in manutenzione al livello del proxy/web server e attendere che finiscano le richieste PHP già avviate. Il comando CLI deve rimanere disponibile. Questo evita che un upload iniziato prima della pausa finisca durante la copia.
5. Eseguire dal percorso nexsoon-office-r5-1-2:

php tools/storage-copy.php --destination=shared --path=/mnt/nexsoon-private/blobs
php tools/storage-copy.php --destination=shared --path=/mnt/nexsoon-private/blobs --apply
php tools/storage-copy.php --destination=shared --path=/mnt/nexsoon-private/blobs --verify

Per S3 usare --destination=s3 e omettere --path, dopo aver impostato le variabili S3 private. Per ritornare a un archivio locale usare --destination=local --path=/percorso/storage: la sottocartella blobs deve già esistere.

Senza --apply o --verify si ottengono conteggi senza copiare; non è una prova della raggiungibilità S3. --apply copia e rilegge ogni oggetto; --verify controlla tutte le versioni nella destinazione. Un errore interrompe il comando; non proseguire al cambio di profilo. Per archivi enormi pianificare la finestra: la copia è sequenziale e l'elenco degli identificatori di destinazione viene tenuto in memoria.

6. Solo dopo esito positivo cambiare il driver/percorso nel profilo, distribuire la stessa configurazione su tutti i nodi e riavviare i processi PHP dove necessario.
7. Eseguire il controllo CLI, verificare accesso e documenti e infine riabilitare salvataggi e lavorazioni, quindi riaprire il traffico.

php tools/platform-check.php
php tools/platform-check.php --probe

Il primo legge lo stato; il secondo aggiunge scrittura, rilettura con SHA-256 e rimozione di un oggetto casuale non collegato a documenti. Il test non sostituisce la verifica di tutte le versioni.

Rollback: prima di riaprire le scritture si può tornare al vecchio profilo e ai dati ancora conservati. Dopo nuove scritture nel nuovo archivio, occorre ricopiare e verificare anche quelle versioni verso il vecchio archivio: cambiare solo il profilo farebbe perdere l'accesso ai nuovi documenti.

7. Sessioni condivise e più nodi web

mode: distributed richiede storage: shared oppure s3, sessioni Redis e un database MySQL comune. SQLite viene rifiutato per questa modalità.

Installare l'estensione PHP Redis, configurare host/porta/database/prefisso nel profilo e password/utente nel file ambiente. redis_tls: true abilita TLS; i certificati devono essere attendibili dal server. Redis deve essere privato o raggiunto attraverso rete protetta; non esporlo liberamente a Internet. Usare un prefisso distinto per ogni installazione.

I nodi devono condividere stesso database, stessa chiave NXO_SECRET, stesso archivio, stessa configurazione Redis e stessa release. I temporanei restano locali. Usare un unico URL pubblico dietro bilanciatore; configurare in trusted_proxies solo gli IP reali del proxy che termina HTTPS.

Passando da sessioni su file a Redis gli utenti devono normalmente effettuare di nuovo l'accesso. I file di sessione non vengono migrati. Redis configurato ma non disponibile non viene sostituito automaticamente con sessioni locali, perché separerebbe gli accessi tra nodi.

Questa implementazione usa Redis singolo endpoint con lock sessione. Non configura Redis Cluster, Sentinel o failover del database: per alta disponibilità scegliere endpoint gestiti o aggiungere e collaudare questi servizi infrastrutturali.

8. Distribuzione e worker

Il Dockerfile web usa l'intero pacchetto come contesto. Prima dell'avvio creare deployment/secrets/config.php copiando in sicurezza la configurazione reale, platform.json dal profilo scelto ed environment.env. Impostare permessi che consentano la lettura al processo PHP senza renderli pubblici. Il file .dockerignore esclude dati privati e credenziali dal build.

cd nexsoon-office-r5-1-2/deployment
# Dopo aver preparato secrets e il proxy HTTPS:
docker compose -f compose.platform.yml up -d --build

Il web espone solo 127.0.0.1:8080 sul nodo. Il proxy HTTPS deve inoltrare qui le richieste e deve essere riconosciuto dall'applicazione. Il database non viene creato da questo Compose: si usa quello configurato. Per shared storage usare anche compose.shared.override.yml, dopo aver montato l'archivio sull'host e impostato NXO_SHARED_MOUNT.

Per più nodi web eseguire il deployment su ogni macchina dietro lo stesso bilanciatore, con profilo distribuito e servizi comuni. Il Compose fornito è un deployment per nodo; non è un orchestratore multinodo e non crea automaticamente macchine Aruba, DNS o certificati. I servizi Redis, database e S3 vanno predisposti separatamente. Se non si usa Docker, valgono gli stessi profili nell'installazione PHP tradizionale.

I worker continuano a usare il contratto API esistente. Non ricevono password del database o chiavi S3; recuperano sorgenti e pubblicano risultati tramite l'API. Possono stare sullo stesso dedicato o su macchine separate già dal primo giorno.

Nel loro nexsoon-worker.env configurare indirizzo API, chiave worker, identificatore univoco, concorrenza, limiti memoria/tempo e capacità consentite. Consultare DEDICATO_R5_63.md e l'esempio ambiente già incluso. Separare pool documenti/OCR e media permette di aumentare le risorse di un gruppo senza cambiare gli editor. Ogni processo deve avere un'identità distinta.

9. Pulizia, backup e capacità

php tools/gc.php
php tools/gc.php --apply

La prima forma elenca oggetti orfani più vecchi di 24 ore; non elimina dati. --apply richiede manutenzione con job sospesi e nessun job in corso, oltre al drenaggio delle richieste già avviate. Gli oggetti referenziati da versions sono conservati. Su S3 versionato una cancellazione può lasciare versioni storiche: il loro costo dipende dal lifecycle del bucket.

Backup e ripristino devono coprire database, oggetti e segreti come un insieme coerente. Verificare realmente un ripristino su ambiente separato. Conservare copie fuori dalla macchina principale.

Per aumentare capacità osservare attesa della coda, tempi di elaborazione, CPU/RAM, spazio temporaneo, throughput archivio e latenza del database. Il pannello mostra code e worker, ma non misura CPU remota, non esegue autoscaling e non garantisce un numero arbitrario di utenti. Aumentare prima i worker per code di conversione; aumentare nodi web per richieste API; ottimizzare database e indici sulla base di misure. I limiti di memoria e GPU del browser degli editor rimangono limiti del dispositivo dell'utente.

10. Aggiunte future senza riscrivere gli editor

Per cambiare indirizzi, credenziali, archivio o sessioni si modificano i file di configurazione descritti. Per cambiare limiti operativi si usa il pannello. Per aggiungere capacità si aumenta il numero di worker o la loro concorrenza entro le risorse effettive.

Un nuovo backend di archiviazione implementa l'interfaccia BlobStore e viene collegato nel factory blob_store; le funzioni documentali continuano a usare gli stessi metodi. Una nuova funzione editor o una nuova conversione richiede comunque implementazione, validazione, interfaccia e prove: non nasce da una riga di configurazione. Mantenere compatibile il contratto API e introdurre migrazioni additive numerate per i dati nuovi.

Separare le release: prima backend compatibile, poi worker con la capacità, infine interfaccia. Conservare un ambiente di staging e la release precedente. Disabilitare temporaneamente l'operazione dal pannello se la sua verifica fallisce.

11. Collaudo prima del traffico reale

Il rapporto R5.65 distingue prove eseguite e prove ancora necessarie. Su Aruba restano da eseguire: PHP nativo con tutte le estensioni, migrazione MySQL sul proprio schema, S3 reale/Redis reale se scelti, proxy HTTPS, test dal browser, due nodi con lo stesso account, spegnimento di un worker, restore backup e test di carico rappresentativo. Non attivare più nodi web finché sessioni e archivio comuni non sono stati verificati.