Remedierea erorii „Database Error” din Nextcloud WebGUI după o actualizare: Ghid practic de recuperare

Un mesaj Nextcloud WebGUI, cum ar fi Excepție: Eroare bază de date, imediat după o actualizare, înseamnă de obicei că aplicația web se poate încărca suficient de departe pentru a ajunge la stratul bazei de date, dar o interogare, o migrare, o așteptare de schemă, o conexiune sau o operațiune specifică aplicației în baza de date eșuează. Nu începeți prin a șterge tabele, a reinstala Nextcloud sau a restaura un director de cod vechi peste cel nou. Secvența mai sigură este să identificați codul SQL sau migrarea eșuată, să finalizați calea de actualizare acceptată, să reparați doar ceea ce Nextcloud știe cum să repare și să verificați serviciul și schema bazei de date înainte de a redeschide accesul.

Această referință respectă documentația actuală de administrare Nextcloud 35 disponibilă în octombrie 2026. Comenzile de mai jos presupun o instalare obișnuită în stil Debian/Ubuntu la /var/www/nextcloudcu utilizatorul serverului web www-data. Ajustați calea, fișierul binar PHP, comanda containerului sau utilizatorul HTTP pentru implementarea dvs.

Diagnostic rapid: la ce indică de obicei eroarea

1. Păstrați starea curentă înainte de a face modificări în baza de date

Dacă încă aveți copia de rezervă pre-actualizare, păstrați-o intactă. Nextcloud recomandă în mod explicit o copie de rezervă înainte de fiecare actualizare, iar instrumentul său de actualizare încorporat acoperă baza de cod, dar nu face copii de rezervă ale bazei de date sau ale directorului de date . Dacă nu aveți o copie de rezervă curentă a bazei de date, creați una cu instrumentul normal de backup al platformei bazei de date înainte de a încerca modificări sau restaurări SQL manuale.

Evitați o versiune inferioară ca soluție rapidă. Nextcloud afirmă că downgrade-ul nu este acceptat și poate corupe datele. Dacă devine necesară o revenire la versiunea anterioară, modelul de recuperare acceptat este o instalare nouă a versiunii mai vechi, urmată de restaurarea unei copii de rezervă corespunzătoare, nu copierea fișierelor de program vechi peste o bază de date care a început deja migrarea. Consultați documentația instrumentului de actualizare încorporat Nextcloud .

2. Citiți excepția exactă a bazei de date din jurnalul Nextcloud

În cazul înregistrării fișierelor în jurnal, jurnalul implicit se află nextcloud.logîn directorul de date configurat. Ghidul de depanare Nextcloud recomandă verificarea acelui jurnal și, atunci când este relevant, a jurnalelor serverului web și PHP. Dacă pagina de eroare afișează un ID de solicitare, căutați acel ID pentru a izola tranzacția corespondentă.

sudo -u www-data tail -n 100 /var/www/nextcloud/data/nextcloud.log

Nu reduceți jurnalul la sintagma „Eroare bază de date”. Capturați codul SQLSTATE, clasa de excepție, tabelul sau coloana defectă și aplicația sau componenta principală numită în urmărirea stivei. De exemplu, „tabelul nu există” este o eroare foarte diferită de „prea multe conexiuni” sau „Serverul MySQL a dispărut”. Nextcloud listează câteva erori comune în stil SQLSTATE în documentația sa generală de depanare .

3. Verificați dacă actualizarea este într-adevăr finalizată

Instrumentul de actualizare încorporat înlocuiește mai întâi codul Nextcloud. Migrările bazelor de date și ale aplicațiilor reprezintă o fază separată. În modul linie de comandă, instrumentul de actualizare poate rula occ upgradeautomat; altfel, migrarea trebuie finalizată ulterior. Această distincție explică multe cazuri în care instrumentul de actualizare părea „terminat”, dar interfața grafică WebGUI normală returnează o excepție la baza de date.

cd /var/www/nextcloud
sudo -E -u www-data php occ status

Dacă trebuie să protejați instanța în timpul depanării, activați modul de întreținere. Nextcloud descrie modul de întreținere ca fiind modul destinat actualizărilor, deoarece previne noi conectări și blochează sesiunile active.

sudo -E -u www-data php occ maintenance:mode --on
sudo -E -u www-data php occ status

4. Finalizați migrările suportate ale bazelor de date și aplicațiilor cu upgrade-ul occ

Dacă codul a fost actualizat, dar migrările nu s-au finalizat, executați comanda de upgrade ca utilizator HTTP:

cd /var/www/nextcloud
sudo -E -u www-data php occ upgrade

Urmăriți rezultatul până când comanda fie raportează succes, fie se oprește în urma unei anumite erori. Dacă eșuează, remediați acea cerință prealabilă înainte de a repeta comanda. Printre blocanții tipici se numără o aplicație incompatibilă, o versiune PHP/a bazei de date neacceptată, un serviciu de bază de date indisponibil sau permisiuni care împiedică lucrările de actualizare necesare. Nu reîmprospătați în mod repetat interfața grafică WebGUI în timp ce migrarea eșuează.

Documentația de actualizare Nextcloud avertizează, de asemenea, să nu se sară peste versiunile majore. Actualizați câte o versiune majoră odată atunci când treceți de la o versiune majoră la alta.

5. Rulați rutina de reparare Nextcloud după ce problema de migrare este corectată

maintenance:repairExecută pașii de reparare Nextcloud și se execută automat și în timpul actualizărilor. Rularea manuală este rezonabilă după ce ați corectat condiția care a întrerupt actualizarea:

sudo -E -u www-data php occ maintenance:repair

Acest lucru este mai sigur decât inventarea de instrucțiuni SQL, deoarece pașii de reparare sunt furnizați de nucleul și aplicațiile Nextcloud. Nu este un înlocuitor magic pentru occ upgradeși nu va repara un server de baze de date defect sau o versiune de bază de date neacceptată. Comanda este documentată în comenzile de sistem și de întreținere Nextcloud .

6. Verificați serviciul bazei de date, setările de conexiune și versiunea acceptată

Dacă jurnalul indică conectivitate și nu schemă, verificați dacă serviciul bazei de date rulează și este accesibil din mediul PHP Nextcloud. Pe o gazdă MariaDB tipică, o verificare utilă este:

sudo systemctl status mariadb

Apoi, verificați setările bazei de date în config/config.php: tipul bazei de date, gazda, numele bazei de date, utilizatorul și orice setare de socket sau port. O eroare Unix-socket poate apărea ca „Nu există un astfel de fișier sau director”, în timp ce o bază de date la distanță poate eșua din cauza rutării, DNS, TLS, regulilor de firewall, acreditărilor sau a serverului în sine.

Compatibilitatea versiunilor contează după o actualizare majoră Nextcloud. Pentru Nextcloud 35, notele oficiale de lansare menționează că MariaDB 10.6 și MySQL 8.0 nu mai sunt suportate; cerințele minime documentate sunt MariaDB 10.11 LTS și MySQL 8.4 LTS. Verificați cerințele pentru versiunea majoră exactă de Nextcloud înainte de a actualiza independent baza de date. Consultați Actualizarea la Nextcloud 35 .

7. Inspectați abaterea de la schemă și adăugați doar structurile lipsă documentate

Nextcloud 35 adaugă db:schema:check, care compară schema live cu schema așteptată de nucleul instalat și de migrările de aplicații. Este doar pentru citire: raportează diferențele fără a modifica baza de date.

sudo -E -u www-data php occ db:schema:check
sudo -E -u www-data php occ db:schema:check -v

Dacă prezentarea generală a administratorului sau ieșirea comenzii raportează coloane, indexuri sau chei primare opționale lipsă, utilizați comenzile de întreținere documentate:

sudo -E -u www-data php occ db:add-missing-columns
sudo -E -u www-data php occ db:add-missing-indices
sudo -E -u www-data php occ db:add-missing-primary-keys

Fiecare dintre acestea este disponibilă --dry-runatunci când doriți să previzualizați comanda SQL. Aceste comenzi nu ar trebui utilizate ca înlocuitor pentru o migrare eșuată a nucleului. Dacă db:schema:checkraportează obiecte neașteptate sau diferențe între proprietățile coloanei, examinați constatarea înainte de a modifica ceva; Nextcloud notează că unele valori implicite la nivelul bazei de date sunt în afara modelului de schemă așteptată. Referința autoritară a comenzii este Nextcloud DAV și comenzile bazei de date .

8. Izolați erorile aplicațiilor terțe înainte de a redeschide WebGUI

Dacă urmărirea stivei denumește o aplicație nelivrată, migrarea acesteia poate fi incompatibilă cu noua versiune de server. Ghidul de depanare Nextcloud recomandă dezactivarea aplicațiilor terțe/nelivrate pentru actualizări și depanare. Folosește comenzile aplicației disponibile în versiunea instalată pentru a dezactiva aplicația suspectă specifică din linia de comandă, rulează-o din nou occ upgradeși reactivează aplicația doar după confirmarea unei versiuni compatibile.

Această ramură este deosebit de importantă atunci când tabelele de bază par sănătoase, dar excepția denumește un spațiu de nume al furnizorului sau un tabel aparținând unei aplicații. Eliminarea manuală a tabelelor acelei aplicații este riscantă, deoarece este posibil să distrugi datele pe care aplicația le așteaptă încă.

9. Ieșiți din modul de întreținere și verificați mai mult decât pagina de conectare

După occ upgradefinalizare, verificările de reparare/schemă nu mai arată o problemă de blocare, iar serviciul bazei de date este stabil, dezactivați modul de întreținere:

sudo -E -u www-data php occ maintenance:mode --off

Apoi verificați instanța pe straturi: încărcați pagina de conectare, conectați-vă, deschideți Fișiere, răsfoiți câteva foldere, testați încărcarea/descărcarea unui fișier, verificați setările de administrare pentru avertismente și examinați cele mai noi nextcloud.logintrări. De asemenea, confirmați că activitățile cron/background rulează normal. O pagină de pornire recuperată nu dovedește, în sine, că migrările aplicațiilor, operațiunile cu fișierele și activitățile din fundal sunt sănătoase.

Listă de verificare pentru recuperare

• Păstrați copia de rezervă anterioară actualizării și evitați o versiune inferioară neacceptată.
• Citiți excepția completă a bazei de date din nextcloud.log, inclusiv SQLSTATE și componenta numită în urmărire.
• Verificați occ statusși puneți instanța în modul de întreținere în timpul reparației.
• Executați occ upgradepentru a finaliza migrările de bază și aplicații acceptate.
• Corectează primul blocant de beton în loc să editezi orbește tabelele bazei de date.
• Execută maintenance:repairdupă ce eroarea subiacentă este remediată.
• Verificați starea serviciului bazei de date, setările de conexiune și compatibilitatea versiunilor.
• Folosește db:schema:checkpe Nextcloud 35 și comenzile documentate db:add-missing-*acolo unde este cazul.
• Dezactivați o aplicație terță care funcționează greșit dacă urmărirea indică în mod clar spre aceasta, apoi încercați din nou actualizarea.
• Dezactivați modul de întreținere numai după ce verificările CLI sunt validă, apoi testați fișierele, transferurile, avertismentele de administrator, jurnalele și lucrările în fundal.

Când să restaurezi în loc să repari

Restaurați dintr-o copie de rezervă bună și consistentă intern atunci când baza de date în sine este deteriorată, migrările au modificat parțial datele într-un mod pe care nu îl puteți anula în siguranță sau tabelele/datele necesare au fost șterse în afara Nextcloud. Baza de date, configurația, directorul de date și versiunea de cod trebuie să aparțină unui punct de recuperare compatibil. Dacă ați plătit asistență Nextcloud sau ați efectuat o implementare critică pentru afacere, opriți-vă înainte de o intervenție chirurgicală SQL distructivă și escalați cu intrarea completă în jurnal, versiunile exacte sursă și țintă Nextcloud, tipul/versiunea bazei de date, versiunea PHP și rezultatul comenzii relevante occ.

Principiul de bază este simplu: o „Eroare în baza de date” post-actualizare nu este un motiv pentru a ghici codul SQL. Lăsați jurnalul să identifice eroarea, lăsați occ upgradesă finalizeze migrările dorite, folosiți instrumentele de reparare și schemă ale Nextcloud și validați platforma bazei de date înainte de a redeschide instanța.