Napraw błąd bazy danych Nextcloud WebGUI po aktualizacji: praktyczny przewodnik odzyskiwania

Komunikat Nextcloud WebGUI, taki jak „Wyjątek: Błąd bazy danych ”, pojawia się bezpośrednio po aktualizacji i zazwyczaj oznacza, że ​​aplikacja internetowa może załadować się wystarczająco daleko, aby dotrzeć do warstwy bazy danych, ale zapytanie, migracja, oczekiwanie schematu, połączenie lub operacja bazy danych specyficzna dla aplikacji kończy się niepowodzeniem. Nie należy zaczynać od usuwania tabel, ponownej instalacji Nextcloud ani przywracania starego katalogu kodu na nowy. Bezpieczniejszą kolejnością jest zidentyfikowanie niedziałającego kodu SQL lub migracji, dokończenie obsługiwanej ścieżki aktualizacji, naprawienie tylko tego, co Nextcloud potrafi naprawić, oraz zweryfikowanie usługi i schematu bazy danych przed ponownym otwarciem dostępu.

To odniesienie jest zgodne z aktualną dokumentacją administracyjną NextCloud 35, dostępną w październiku 2026 r. Poniższe polecenia zakładają standardową instalację w stylu Debian/Ubuntu z /var/www/nextcloudużytkownikiem serwera WWW www-data. Dostosuj ścieżkę, plik binarny PHP, polecenie kontenera lub użytkownika HTTP dla swojego wdrożenia.

Szybka diagnoza: na co zazwyczaj wskazuje błąd

1. Zachowaj aktualny stan przed wprowadzeniem zmian w bazie danych

Jeśli nadal posiadasz kopię zapasową sprzed aktualizacji, zachowaj ją w stanie nienaruszonym. Nextcloud wyraźnie zaleca tworzenie kopii zapasowej przed każdą aktualizacją, a jego wbudowana funkcja aktualizacji obejmuje bazę kodu, ale nie tworzy kopii zapasowej bazy danych ani katalogu danych . Jeśli nie posiadasz aktualnej kopii zapasowej bazy danych, utwórz ją za pomocą standardowego narzędzia do tworzenia kopii zapasowych platformy bazodanowej przed podjęciem próby ręcznych zmian lub przywracania danych SQL.

Unikaj downgrade'u jako szybkiego rozwiązania. Nextcloud informuje, że downgrade nie jest obsługiwany i może uszkodzić dane. Jeśli konieczne będzie wycofanie, obsługiwany model odzyskiwania to nowa instalacja starszej wersji, a następnie przywrócenie pasującej kopii zapasowej, a nie kopiowanie starych plików programu do bazy danych, której migracja już się rozpoczęła. Zapoznaj się z dokumentacją wbudowanego programu aktualizującego Nextcloud .

2. Przeczytaj dokładny wyjątek bazy danych w dzienniku Nextcloud

W przypadku rejestrowania plików domyślny dziennik znajduje się nextcloud.logw skonfigurowanym katalogu danych. Poradnik rozwiązywania problemów Nextcloud zaleca sprawdzenie tego dziennika, a w razie potrzeby także dzienników serwera WWW i PHP. Jeśli strona błędu wyświetla identyfikator żądania, wyszukaj go, aby wyizolować pasującą transakcję.

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

Nie ograniczaj logu do frazy „Błąd bazy danych”. Zapisz kod SQLSTATE, klasę wyjątku, błędną tabelę lub kolumnę oraz aplikację lub główny komponent wymieniony w śladzie stosu. Na przykład „tabela nie istnieje” to zupełnie inna awaria niż „zbyt wiele połączeń” lub „serwer MySQL nie działa”. Nextcloud wymienia kilka typowych błędów w stylu SQLSTATE w swojej ogólnej dokumentacji rozwiązywania problemów .

3. Sprawdź, czy aktualizacja faktycznie się zakończyła

Wbudowany aktualizator najpierw zastępuje kod Nextcloud. Migracje bazy danych i aplikacji to osobna faza. W trybie wiersza poleceń aktualizator może działać occ upgradeautomatycznie; w przeciwnym razie migracja musi zostać ukończona później. To rozróżnienie wyjaśnia wiele przypadków, w których aktualizator wyglądał na „ukończony”, ale normalny interfejs WebGUI zwraca wyjątek bazy danych.

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

Jeśli chcesz chronić instancję podczas rozwiązywania problemów, włącz tryb konserwacji. Nextcloud opisuje tryb konserwacji jako tryb przeznaczony do aktualizacji, ponieważ uniemożliwia on nowe logowania i blokuje aktywne sesje.

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

4. Zakończ obsługiwane migracje baz danych i aplikacji za pomocą aktualizacji occ

Jeśli kod został zaktualizowany, ale migracje się nie zakończyły, uruchom polecenie aktualizacji jako użytkownik HTTP:

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

Obserwuj dane wyjściowe, aż polecenie zgłosi powodzenie lub zatrzyma się po wystąpieniu określonego błędu. Jeśli polecenie się nie powiedzie, usuń ten warunek wstępny przed powtórzeniem polecenia. Typowe blokady to niekompatybilna aplikacja, nieobsługiwana wersja PHP/bazy danych, niedostępna usługa bazy danych lub uprawnienia uniemożliwiające wykonanie wymaganych aktualizacji. Nie odświeżaj wielokrotnie interfejsu WebGUI, gdy migracja się nie powiedzie.

Dokumentacja aktualizacji Nextcloud ostrzega również, aby nie pomijać głównych wersji. Podczas migracji między wersjami głównymi należy aktualizować jedną główną wersję na raz.

5. Uruchom procedurę naprawczą NextCloud po rozwiązaniu problemu z migracją

maintenance:repairWykonuje kroki naprawy NextCloud i jest również uruchamiany automatycznie podczas aktualizacji. Ręczne uruchomienie jest uzasadnione po usunięciu przyczyny, która przerwała aktualizację:

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

Jest to bezpieczniejsze niż wymyślanie instrukcji SQL, ponieważ kroki naprawy są dostarczane przez rdzeń i aplikacje Nextcloud. Nie jest to magiczny zamiennik occ upgradei nie naprawi niedziałającego serwera bazy danych ani nieobsługiwanej wersji bazy danych. Polecenie jest udokumentowane w poleceniach systemowych i konserwacyjnych Nextcloud .

6. Sprawdź usługę bazy danych, ustawienia połączenia i obsługiwaną wersję

Jeśli log wskazuje na łączność, a nie schemat, sprawdź, czy usługa bazy danych działa i jest dostępna ze środowiska PHP Nextcloud. Na typowym hoście MariaDB przydatne jest sprawdzenie:

sudo systemctl status mariadb

Następnie sprawdź ustawienia bazy danych w zakresie config/config.php: typu bazy danych, hosta, nazwy bazy danych, użytkownika oraz wszelkich ustawień gniazda lub portu. Błąd gniazda Unix może pojawić się jako „Brak takiego pliku lub katalogu”, a zdalna baza danych może ulec awarii z powodu routingu, DNS, TLS, reguł zapory sieciowej, poświadczeń lub samego serwera.

Kompatybilność wersji ma znaczenie po dużej aktualizacji Nextcloud. W przypadku Nextcloud 35, oficjalne informacje o wydaniu informują, że MariaDB 10.6 i MySQL 8.0 nie są już obsługiwane; udokumentowane minimalne wymagania to MariaDB 10.11 LTS i MySQL 8.4 LTS. Przed samodzielną aktualizacją bazy danych sprawdź wymagania dotyczące konkretnej głównej wersji Nextcloud . Zobacz Aktualizacja do Nextcloud 35 .

7. Sprawdź odchylenie schematu i dodaj tylko udokumentowane brakujące struktury

NextCloud 35 dodaje funkcję db:schema:check, która porównuje schemat rzeczywisty ze schematem oczekiwanym po zainstalowaniu rdzenia i migracji aplikacji. Funkcja jest tylko do odczytu: raportuje różnice bez zmiany bazy danych.

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

Jeśli w przeglądzie administratora lub wynikach polecenia zgłoszono brakujące opcjonalne kolumny, indeksy lub klucze podstawowe, należy użyć udokumentowanych poleceń konserwacyjnych:

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

Każda z nich umożliwia --dry-runpodgląd kodu SQL. Polecenia te nie powinny być używane jako substytut nieudanej migracji rdzenia. Jeśli db:schema:checkzgłoszono nieoczekiwane obiekty lub różnice we właściwościach kolumn, należy je sprawdzić przed wprowadzeniem jakichkolwiek zmian; Nextcloud zauważa, że ​​niektóre domyślne ustawienia dla całej bazy danych wykraczają poza model oczekiwanego schematu. Autorytatywnym źródłem poleceń jest Nextcloud DAV i polecenia bazy danych .

8. Wyizoluj awarie aplikacji innych firm przed ponownym otwarciem interfejsu WebGUI

Jeśli ślad stosu wskazuje aplikację niedostarczoną, jej migracja może być niezgodna z nową wersją serwera. Przewodnik rozwiązywania problemów Nextcloud zaleca wyłączenie aplikacji innych firm/niedostarczonych na czas aktualizacji i rozwiązywania problemów. Użyj poleceń aplikacji dostępnych w zainstalowanej wersji, aby wyłączyć konkretną podejrzaną aplikację z poziomu wiersza poleceń, uruchom ponownie occ upgradei włącz aplikację dopiero po potwierdzeniu zgodności wersji.

Ta gałąź jest szczególnie ważna, gdy tabele rdzeniowe wyglądają na sprawne, ale wyjątek wskazuje przestrzeń nazw dostawcy lub tabelę należącą do jednej aplikacji. Ręczne usuwanie tabel tej aplikacji jest ryzykowne, ponieważ może spowodować utratę danych, których aplikacja nadal oczekuje.

9. Wyjdź z trybu konserwacji i sprawdź więcej niż tylko stronę logowania

Po occ upgradezakończeniu sprawdzania schematu/naprawy nie będzie już problemu blokującego, a usługa bazy danych będzie stabilna. Wyłącz tryb konserwacji:

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

Następnie sprawdź działanie instancji warstwowo: wczytaj stronę logowania, zaloguj się, otwórz Pliki, przejrzyj kilka folderów, przetestuj przesyłanie/pobieranie jednego pliku, sprawdź ustawienia administracyjne pod kątem ostrzeżeń i przejrzyj najnowsze nextcloud.logwpisy. Upewnij się również, że zadania cron/w tle działają prawidłowo. Samo odzyskanie strony głównej nie dowodzi, że migracje aplikacji, operacje na plikach i zadania w tle działają prawidłowo.

Lista kontrolna odzyskiwania

• Zachowaj kopię zapasową sprzed aktualizacji i unikniesz nieobsługiwanej obniżki wersji.
• Odczytaj cały wyjątek bazy danych w nextcloud.log, łącznie z SQLSTATE i składnikiem nazwanym w śledzeniu.
• Sprawdź occ statusi przełącz instancję w tryb konserwacyjny na czas naprawy.
• Uruchom occ upgrade, aby dokończyć obsługiwane migracje rdzenia i aplikacji.
• Popraw pierwszy konkretny błąd zamiast bezmyślnie edytować tabele bazy danych.
• Uruchom maintenance:repairpo usunięciu przyczyny błędu.
• Sprawdź stan usługi bazy danych, ustawienia połączenia i zgodność wersji.
• Stosować db:schema:checkw NextCloud 35 i w stosownych przypadkach stosować udokumentowane db:add-missing-*polecenia.
• Jeśli ślad wyraźnie na to wskazuje, wyłącz niedziałającą aplikację innej firmy i spróbuj ponownie przeprowadzić aktualizację.
• Wyłącz tryb konserwacji dopiero po pomyślnym zakończeniu kontroli CLI, a następnie przetestuj pliki, transfery, ostrzeżenia administratora, dzienniki i zadania w tle.

Kiedy przywracać zamiast naprawiać

Przywróć z kopii zapasowej, która jest znana i spójna wewnętrznie, gdy baza danych jest uszkodzona, migracje częściowo zmieniły dane w sposób, którego nie można bezpiecznie cofnąć, lub wymagane tabele/dane zostały usunięte poza NextCloud. Baza danych, konfiguracja, katalog danych i wersja kodu muszą należeć do kompatybilnego punktu odzyskiwania. Jeśli korzystasz z płatnego wsparcia NextCloud lub wdrażasz wdrożenie o znaczeniu krytycznym dla firmy, zatrzymaj się przed destrukcyjną operacją SQL i eskaluj, uwzględniając pełny wpis w dzienniku, dokładne źródłowe i docelowe wersje NextCloud, typ/wersję bazy danych, wersję PHP oraz dane wyjściowe odpowiedniego occpolecenia.

Podstawowa zasada jest prosta: „Błąd bazy danych” po aktualizacji nie jest powodem do zgadywania kodu SQL. Pozwól, aby log zidentyfikował awarię, dokończył occ upgradeplanowane migracje, skorzystał z własnych narzędzi naprawczych i schematów Nextcloud oraz zwalidował platformę bazy danych przed ponownym otwarciem instancji.