Risolvere il problema della pagina vuota / schermata bianca di ownCloud: scegliere il percorso di ripristino corretto

Inizia decidendo che tipo di pagina bianca hai effettivamente

La "schermata bianca della morte" di ownCloud è un sintomo, non una diagnosi. La soluzione migliore dipende dal fatto che il browser abbia ricevuto un errore del server, abbia ricevuto codice HTML valido ma non sia riuscito a caricare JavaScript o CSS, oppure abbia tentato di raggiungere un proxy inverso che non è riuscito a connettersi a ownCloud.

Questa distinzione è importante perché i compromessi sono molto diversi. Disabilitare un'applicazione di terze parti comporta un rischio relativamente basso quando un'eccezione PHP identifica proprio quell'applicazione. Modificare la proprietà dei file in un'intera installazione è un'operazione molto più invasiva e non dovrebbe essere la prima risposta a un errore JavaScript. Allo stesso modo, riavviare tutti i servizi potrebbe nascondere temporaneamente un problema senza indicare se la causa sia da attribuire a PHP, a un proxy, a un aggiornamento o a un'applicazione.

Questa guida riguarda ownCloud Classic. Secondo la documentazione attuale di ownCloud Classic 11, la versione 11 è supportata come implementazione basata su Docker, con il sistema operativo, il runtime PHP, il database e Apache all'interno dei container forniti da ownCloud. Le installazioni precedenti della versione 10.x potrebbero ancora utilizzare un'architettura tradizionale con server web e PHP-FPM. Utilizzare il ramo di comando corrispondente alla propria implementazione. Consultare i requisiti di sistema di ownCloud Classic 11 .

1. La pagina vuota restituisce un codice HTTP 500, oppure il browser si blocca dopo aver restituito un codice HTTP 200?

Apri gli strumenti per sviluppatori del browser ed esamina le schede Rete e Console . Prova inoltre l'endpoint da un terminale:

curl -I https://cloud.example.com/
curl -sS -o /dev/null -w '%{http_code}\n' https://cloud.example.com/

Didascalia: Una risposta 500 lato server indica un problema con ownCloud, PHP, il database o lo stack web, piuttosto che un semplice problema di rendering del browser.

Se il documento principale restituisce un errore 500 o 502/503 , dare priorità ai log del server e del proxy. Se il documento principale restituisce un errore 200 ma i bundle JavaScript falliscono con errori 404, 403 o eccezioni di script, dare priorità ai percorsi delle risorse, alla riscrittura del reverse proxy, ai temi, alla cache o alla compatibilità dell'app. Se è interessato un solo browser, testare una finestra di navigazione in incognito e un altro browser supportato prima di cambiare server.

2. Il problema è iniziato dopo un aggiornamento di ownCloud o di PHP?

Questa è una delle domande più importanti perché può restringere immediatamente il campo delle possibili cause del problema. Le note di rilascio di ownCloud indicano che ownCloud Classic 11 ha innalzato la versione minima di PHP a PHP 8.3 e che ownCloud Classic 11 è compatibile solo con Docker. Un'installazione legacy di ownCloud 10.x segue regole di compatibilità PHP diverse, quindi non copiare le indicazioni relative a PHP da un'altra versione principale.

Per un'installazione tradizionale di ownCloud 10.x, eseguire il comando dalla directory di ownCloud:

sudo -u www-data ./occ status
php -v

Per ownCloud Classic 11, esegui OCC tramite la distribuzione Compose:

docker compose exec owncloud occ status
docker compose exec owncloud php -v

Didascalia: Verificare le versioni di ownCloud e PHP installate è particolarmente importante quando la schermata bianca è comparsa subito dopo un aggiornamento.

Confronta il risultato con le note di rilascio della versione che stai effettivamente utilizzando. Le note di rilascio ufficiali di ownCloud sono la fonte corretta per le versioni minime correnti e le modifiche che potrebbero causare incompatibilità. Il downgrade non è una soluzione generica sicura: la documentazione di ownCloud avverte che il downgrade non è supportato perché può danneggiare i dati.

3. Quale registro fornisce il primo errore concreto?

I log sono generalmente più utili delle modifiche di configurazione effettuate per tentativi ed errori. Il manuale di amministrazione di ownCloud raccomanda di utilizzare il log di ownCloud per diagnosticare i problemi; per impostazione predefinita, il log viene memorizzato nella directory dei dati configurata, a meno che non ne logfilevenga specificata una diversa.

In un'installazione tradizionale, alcuni esempi includono:

tail -n 100 /path/to/owncloud/data/owncloud.log
journalctl -u php-fpm --since "15 minutes ago"
journalctl -u apache2 --since "15 minutes ago"
journalctl -u nginx --since "15 minutes ago"

Su ownCloud Classic 11, ispeziona invece i servizi Compose:

docker compose logs --tail=200 owncloud
docker compose ps

Didascalia: Un errore irreversibile o una traccia dello stack di PHP che specifica un'applicazione o una classe offre un obiettivo di risoluzione dei problemi molto più sicuro rispetto alla modifica di impostazioni del server non correlate.

Cerca la prima eccezione fatale che si verifica in prossimità della richiesta non riuscita, non solo la cascata finale di errori. Le categorie più comuni includono una classe PHP mancante, un'applicazione incompatibile, un errore di connessione al database, una configurazione illeggibile, file di codice mancanti o un'eccezione durante un aggiornamento non completato.

La documentazione di ownCloud relativa alla registrazione dei log afferma che il livello di log DEBUG può essere utile durante la diagnosi, ma produce un output considerevole e può influire sulle prestazioni. Se si aumenta temporaneamente il livello di log, è necessario riportarlo a un valore meno dettagliato dopo aver raccolto le prove. Consultare la configurazione del logging di ownCloud .

4. Dovresti disabilitare un'app di terze parti?

Scegli questo percorso quando l'errore fa riferimento a un'app non principale, quando la pagina vuota è apparsa dopo l'installazione o l'aggiornamento di un'app, oppure quando l'errore si è verificato durante un aggiornamento di ownCloud. La guida alla risoluzione dei problemi di ownCloud raccomanda esplicitamente di disabilitare le app di terze parti per la risoluzione dei problemi e prima degli aggiornamenti.

Elenca prima le app. Su ownCloud 10.x:

sudo -u www-data ./occ app:list
sudo -u www-data ./occ app:disable APP_ID

Su ownCloud 11:

docker compose exec owncloud occ app:list
docker compose exec owncloud occ app:disable APP_ID

Didascalia: Disabilitare solo l'app indicata dai log è meno problematico che disabilitare molti componenti o modificare l'intero stack web.

Il compromesso riguarda la funzionalità: gli utenti perderanno l'app fino a quando non verrà aggiornata o riattivata. Questa soluzione è generalmente preferibile alla disabilitazione dei servizi principali di ownCloud. La documentazione di OCC indica inoltre che diverse app principali non possono essere disabilitate, tra cui DAV, FederatedFileSharing, Files e Files_External. Consultare la guida ufficiale alla risoluzione dei problemi generali e il manuale di riferimento dei comandi di OCC .

5. Quando conviene correggere i permessi?

I permessi sono un forte indiziato quando il log contiene Permission denied, un recente deployment ha copiato i file app/config con l'utente sbagliato o un aggiornamento ha sostituito file con proprietari errati. Sono un indiziato debole quando l'unica prova è un errore JavaScript lato browser.

Prima di eseguire interventi di riparazione che potrebbero causare interruzioni, mettere il sistema in modalità di manutenzione. Per ownCloud 11:

docker compose exec owncloud occ maintenance:mode --on

Per una distribuzione tradizionale di 10.x:

sudo -u www-data ./occ maintenance:mode --on

Didascalia: La modalità di manutenzione riduce l'attività dell'utente mentre si indaga su errori di proprietà o di autorizzazione dei file già confermati dai log.

Non eseguire un'operazione ricorsiva generica chmod 777o copiare le ricette di autorizzazione da una versione non correlata. Il manuale attuale di ownCloud 11 documenta la proprietà e le modalità specifiche per i file aggiunti manualmente nelle directory montate su Docker apps: configproprietà www-data:root, file dell'app 0644, directory dell'app 0751e file di configurazione aggiunti 0644. Documenta anche 0640le modifiche manuali .htaccess. .user.iniUtilizzare la documentazione di ownCloud 11 sull'aggiornamento manuale come riferimento specifico per la versione.

6. È opportuno modificare i moduli PHP, OPcache o le impostazioni di memoria?

Solo quando i log o i controlli di compatibilità indicano questa direzione. Questa soluzione ha un impatto maggiore rispetto alla disabilitazione di una singola applicazione problematica. La mancanza di un'estensione PHP necessaria può impedire l'esecuzione del codice, mentre una configurazione PHP errata può influire su tutte le applicazioni PHP presenti sull'host.

Per uno stack PHP legacy gestito dall'host, verifica cosa carica effettivamente il runtime web:

php -m
php --ini
php -r 'phpinfo();' | grep opcache.enable

Didascalia: I controlli sui moduli PHP e su OPcache sono utili quando i log del server segnalano estensioni mancanti o incompatibilità a runtime, ma non dovrebbero essere la prima modifica da apportare senza prove.

Per ownCloud 11, l'immagine ufficiale gestisce il runtime PHP, quindi modificare i pacchetti PHP dell'host è generalmente il livello sbagliato. ownCloud documenta OPcache come abilitato di default nella sua immagine Docker. Consultare la documentazione di ownCloud sulla cache di memoria .

Se sospetti che la cache OPcache sia obsoleta dopo aver sostituito manualmente i file PHP su un'installazione legacy, riavviare PHP-FPM o il servizio web/PHP pertinente può svuotare la cache degli opcode locale al processo. Il compromesso è una breve interruzione e prestazioni della cache non ottimali in seguito. Esegui questa operazione dopo aver corretto i file sottostanti, non come sostituto per identificare l'errore.

7. L'aggiornamento è stato interrotto o i file di sistema sono incoerenti?

Se la pagina bianca è apparsa durante o immediatamente dopo un aggiornamento, verificare innanzitutto lo stato dell'aggiornamento. La documentazione di ownCloud relativa agli aggiornamenti consiglia di utilizzare OCC per l'aggiornamento e il ripristino, anziché intervenire manualmente sul database.

Per ownCloud 11:

docker compose exec owncloud occ status
docker compose exec owncloud occ upgrade
docker compose exec owncloud occ maintenance:repair
docker compose exec owncloud occ integrity:check-core

Per ownCloud 10.x, utilizzare i comandi OCC equivalenti con l'utente del server web:

sudo -u www-data ./occ status
sudo -u www-data ./occ maintenance:repair
sudo -u www-data ./occ integrity:check-core

Didascalia: La riparazione OCC è appropriata per un aggiornamento interrotto o incoerente, mentre i controlli di integrità possono identificare file core firmati modificati o mancanti.

I risultati relativi all'integrità del codice necessitano di interpretazione. La documentazione di ownCloud definisce INVALID_HASH, FILE_MISSING, e EXTRA_FILEcome condizioni distinte. Non modificare signature.jsonper far scomparire gli avvisi. La documentazione corrente di ownCloud 11 rende inoltre obbligatoria la firma delle app di terze parti per l'installazione, gli aggiornamenti e l'abilitazione. Consultare la documentazione sulla firma del codice di ownCloud .

8. Come si verifica la correzione?

Un buon ripristino non si limita al semplice fatto che "la pagina non è più bianca". Verifica l'intero percorso della richiesta:

• La pagina principale di ownCloud restituisce lo stato HTTP previsto anziché 500/502/503.
• Gli strumenti per sviluppatori del browser non segnalano errori JavaScript irreversibili o la mancanza del pacchetto principale.
• Il log di ownCloud non registra immediatamente una nuova eccezione fatale per la stessa richiesta.
• occ statussegnala un'istanza installata e nessun requisito di aggiornamento imprevisto.
• La modalità di manutenzione viene disabilitata al termine della manutenzione.
• Un utente di prova può accedere e aprire la pagina File.

Per ownCloud 11:

docker compose exec owncloud occ maintenance:mode --off
docker compose exec owncloud occ status
curl -I https://cloud.example.com/

Didascalia: Il ripristino dovrebbe essere confermato a entrambi i livelli: l'interfaccia di ownCloud si carica e lo stato lato server e i controlli HTTP risultano positivi.

Quale soluzione offre il miglior rapporto rischio-beneficio?

Cosa non fare quando ownCloud mostra una schermata bianca

• Non abilitare PHP display_errorssu un sito di produzione pubblico solo per esporre le tracce dello stack al browser; usa invece i log del server.
• Non impostare ricorsivamente l'intera struttura ad albero di ownCloud con permessi di scrittura per tutti gli utenti.
• Non effettuare il downgrade di ownCloud come ripristino rapido a meno che tu non stia ripristinando un backup supportato in un ambiente compatibile.
• Non eliminare a caso la directory dei dati, i dati dell'app, le tabelle del database o le directory della cache.
• Non disabilitare tutte le app contemporaneamente quando è possibile isolare una singola app specifica.
• Non modificare i file core firmati o signature.jsonlimitarti a sopprimere gli errori di integrità.

Quando è opportuno passare a un approccio più incisivo invece di continuare a sperimentare?

Interrompete le modifiche quando i log indicano danneggiamento del database, problemi con le chiavi di crittografia, ripetuti errori di integrità del core dopo un ripristino pulito o uno stato di aggiornamento che non può essere completato con il flusso di lavoro OCC documentato. Segnalate inoltre il problema quando la pagina vuota interessa un cluster di produzione e non è possibile isolare un singolo nodo senza compromettere la coerenza dei dati.

Prima di aprire una richiesta di assistenza, ownCloud consiglia di raccogliere un report di configurazione e i log pertinenti. Per ownCloud 10.x, il comando documentato è:

sudo -u www-data ./occ configreport:generate > config_report.txt

Utilizza il metodo di esecuzione OCC corrispondente alla tua implementazione e rivedi l'output per verificare la presenza di segreti prima di condividerlo al di fuori della tua organizzazione. La guida alla raccolta di log e configurazione di ownCloud spiega cosa serve in genere ai tecnici dell'assistenza.

Riferimenti ufficiali

• Risoluzione generale dei problemi di ownCloud Classic 11
• Requisiti di sistema di ownCloud Classic 11
• Note di rilascio di ownCloud Server
• Aggiornamento manuale di ownCloud Classic 11
• Configurazione di registrazione di ownCloud