Unofficial

LVM Pool Repair: skrypt, który naprawia metadane puli thin w NAS-ie QNAP

Jeden skrypt powłoki z menu naprawia przez SSH metadane puli thin w NAS-ie QNAP z systemem QTS.

Skrypt prowadzi naprawę przez pięć kroków: diagnozę, przygotowanie puli, kopię zapasową, naprawę oraz uruchomienie puli i woluminów.

W menu Enter uruchamia krok, który skrypt zaleca jako następny. Po zerwaniu sesji SSH albo restarcie NAS-a kontynuujesz tę samą sesję naprawy.

Wersja 1.8 · na NAS-ie, przez SSH, jako admin · QTS z pulą LVM thin · freeware

  • 5kroków w menu, w kolejności naprawy
  • 3typy uszkodzeń metadanych, każdy z własną ścieżką naprawy
  • YESsłowo, które wpisujesz, zanim naprawa nadpisze metadane puli

Nagrania skryptu

Każde nagranie to prawdziwa sesja SSH ze skryptem w wersji 1.7 na NAS-ie QNAP, w terminalu 80 na 25 znaków. Wersja 1.8 dodaje na tych ekranach jedną sekcję: sprawdzenie RAID i dysków tylko do odczytu, przed menu i na początku kroku 1. Celowo uszkodziliśmy metadane puli w znanych miejscach i zachowaliśmy oryginalne bloki. Uszkodzenie powstało po kroku 2, gdy pula była offline. Nagrania pomijają tę przerwę: po kroku 2 skrypt od razu przechodzi do diagnozy w tej samej sesji. Długie oczekiwania są w nagraniach skrócone. Ich prawdziwa długość zależy od rozmiaru puli i jej migawek.

sh qnap-pool-repair-1.7.sh80×25
  ░░░   ░░░ ░░░ ░░░ ░░░ ░░░ ░░░ ░░░ ░░░      ░░░ ░░░ ░░░ ░░░ ░░░ ░░░ ░░░ ░░░      ▀▀▀▀▀ ▀▀▀▀▀▀▀ ▀▀▀▀▀▀▀ ▀▀▀ ▀▀▀ ▀▀▀▀▀▀▀       ▀▀▀▀▀▀ ▀▀▀▀▀▀▀ ▀▀▀▀▀▀▀ ▀▀▀▀▀▀                                                                                     Mounted:                                                                               /share/CACHEDEV2_DATA                                                           /share/CACHEDEV1_DATA                                                           /mnt/pool1                                                                      (and 12 mounts of apps and containers on these volumes)                    [auto] Data reachable - finish the repair session? -> y                       [ OK ] Report:                                                                         /share/external/DEV3302_1/pool-recovery-NAS-DEMO-vg1-tp1-20261121-010858/report.txt                                                                      [ OK ] Log package:                                                                    /share/external/DEV3302_1/pool-recovery-NAS-DEMO-vg1-tp1-20261121-010858/logs-20261121-012354.tgz                                                               Look through it before sending: it holds the host name, the device              layout, directory listings of the test mount and, in debug mode, the            shell trace. The metadata image is not in it.                            [ OK ] Session finished.                                                               Keep the copy of the original metadata:                                         /share/external/DEV3302_1/pool-recovery-NAS-DEMO-vg1-tp1-20261121-010858/tmeta.raw                                                                       Pool vg1/tp1 is back online with all its volumes mounted. Let's rock.           [ OK ] Nothing left to do.                                                      Press Enter to return to the menu.                                              
Nagranie zaczyna się od poleceń pobierania, od cd /mnt/HDA_ROOT. Krok 2 wyłącza pulę, a gdy skrypt czeka w menu, jeden wpis mapy zajętości metadanych zostaje ustawiony źle. Potem a uruchamia tryb automatyczny: diagnozę, obraz metadanych, naprawę oraz start puli, woluminów i aplikacji. Skrypt zatrzymuje się raz: przed zapisem do puli czeka na wpisanie YES.Jeden wpis mapy zajętości metadanych jest błędny. Skrypt zatrzymuje usługi, zapisuje sprawdzony obraz metadanych, buduje naprawioną kopię i ją sprawdza. Po wpisaniu YES zapisuje kopię do puli. Krok 5 uruchamia pulę, woluminy i aplikacje.Główny superblok jest uszkodzony, a jego kopie zapasowe są poprawne. Skrypt czyta metadane przez najnowszą kopię. Po wpisaniu YES odtwarza z niej superblok, sprawdza metadane i uruchamia pulę.Uszkodzone są dwa liście drzewa mapowań woluminu testowego. Pula działa na naprawionej kopii podczas montowania testowego tylko do odczytu i tam czytamy pliki. Po potwierdzeniu danych i wpisaniu YES skrypt zapisuje kopię do puli i sprawdza system plików, zanim QTS zamontuje wolumin. Na końcu test sum kontrolnych 600 plików: 534 całe, 66 zmienionych.To samo uszkodzenie. NAS restartuje się w trakcie montowania testowego. Po restarcie pula zostaje offline, bo skrypt przed testem ustawił flagę skip-activation. Po nowym logowaniu przez SSH skrypt zostaje uruchomiony ponownie. Znajduje niedokończoną sesję i kończy naprawę.

Pobierz skrypt

Skrypt udostępniamy po podaniu kodu PIN. Wpisz PIN, aby zobaczyć link do pobrania.

Uruchom skrypt

Skrypt działa na samym NAS-ie. Wymaga konta admin, bo QTS nie ma sudo.

  1. Zaloguj się do NAS-a przez SSH jako admin.
  2. Przejdź do folderu ze skryptem. Folder nie może leżeć na naprawianej puli.
  3. Uruchom skrypt pierwszym poleceniem poniżej.
  4. Wybierz katalog roboczy poza pulą. Bez niego skrypt wykona diagnozę, ale krok 3 nie zapisze obrazu metadanych.
# uruchom skrypt i jego menu
sh qnap-pool-repair.sh
# wróć do sesji po zerwanym połączeniu
screen -r qnap-pool-repair

Naprawa pamięci masowej bywa nieodwracalna. Zanim skrypt cokolwiek zapisze, upewnij się, że masz kopię ważnych danych i że diagnoza pasuje do Twojego NAS-a.

Opcje

--auto
Uruchamia przebieg automatyczny, gdy skrypt wykryje pulę: kroki od 1 do 5 po kolei. Przebieg automatyczny wymaga katalogu roboczego.
--debug
Pokazuje ślad wywołań i każde polecenie w ramce. Zapisuje pełny ślad powłoki w trace.log, do czego potrzebny jest katalog roboczy.
--no-screen
Uruchamia skrypt bez sesji screen.
--selftest
Sprawdza polecenia, których skrypt używa, tylko do odczytu, i kończy pracę.
--raid-check
Sprawdza macierze RAID, ich członków i sygnatury QNAP na dyskach, tylko do odczytu, i kończy pracę. Nie potrzebuje puli.
--allow-no-backup
Tylko w sytuacji awaryjnej. Możesz wtedy potwierdzić szybką albo pełną ścieżkę bez obrazu metadanych: wpisujesz NO-BACKUP, a potem nazwę puli w postaci, którą pokazuje skrypt, na przykład vg1/tp1. Przebieg automatyczny nie używa tej opcji.
--help
Wypisuje opcje.
--version
Wypisuje wersję.

Pięć kroków

Przed menu skrypt pokazuje czerwone WARNING i sprawdza, czy NAS ma 79 poleceń, których skrypt używa. W nowej sesji sprawdza potem macierze RAID i ich dyski, tylko do odczytu. Menu pokazuje kroki w kolejności naprawy i stan każdego z nich. Enter uruchamia zalecany krok. Przebieg automatyczny wykonuje po kolei wszystkie pozostałe kroki, a na pytania z bezpieczną odpowiedzią domyślną odpowiada sam. Nadal pyta Cię o zajęte woluminy, o dane na montowaniu testowym i o wpisanie YES.

  1. Status and diagnosis

    Stan i diagnoza. Skrypt sprawdza RAID i sprzęt. Gdy pula jest offline, uruchamia thin_check na metadanych puli. Gdy pula jest jeszcze aktywna, proponuje wstępne sprawdzenie tylko do odczytu.

    tylko odczyt
  2. Prepare

    Przygotowanie. Skrypt odmontowuje woluminy puli i dezaktywuje grupę woluminów. W trybie łagodnym odmontowuje tylko to, co należy do tej puli, a usługi zatrzymują się tylko wtedy, gdy coś nadal blokuje pulę.

    pula offline
  3. Backup

    Kopia zapasowa. Skrypt zapisuje konfigurację LVM i obraz metadanych w katalogu roboczym. Uznaje obraz dopiero wtedy, gdy sprawdzi jego zgodność z urządzeniem.

    zweryfikowany obraz
  4. Repair the metadata

    Naprawa metadanych. Skrypt proponuje ścieżkę naprawy pasującą do diagnozy. Zanim naprawa nadpisze oryginalne metadane, wpisujesz YES.

    wpisane YES
  5. Bring the pool and the volumes up

    Uruchomienie puli i woluminów. Skrypt aktywuje pulę. QTS montuje woluminy, a skrypt sprawdza każdy z nich z listą zapisaną wcześniej. Proponuje uruchomienie usług, które zatrzymał. Gdy wszystkie woluminy wrócą, pokazuje LOOKS GOOD, zapisuje raport i pakuje logi.

    raport i logi

Co znajduje diagnoza

Krok 1 podaje wynik thin_check jednym z określeń skryptu. Krok 4 proponuje potem ścieżkę naprawy dla tego wyniku.

  • space map counts only

    Błędy są tylko w licznikach mapy przestrzeni. Drzewa mapowań są całe.

    Szybka ścieżka: skrypt buduje naprawioną kopię na zarezerwowanym woluminie i ją sprawdza. Gdy wpiszesz YES, zapisuje kopię do puli.

  • damaged superblock

    Główny superblok jest uszkodzony, a skrypt znajduje w metadanych jego poprawne kopie zapasowe.

    Skrypt czyta metadane przez najnowszą poprawną kopię. Gdy wpiszesz YES, odtwarza z niej superblok i powtarza diagnozę.

  • mapping tree errors

    Uszkodzone są części drzewa, które mapuje bloki woluminu. Naprawa usuwa te zakresy, a ich bloki są potem puste przy odczycie.

    Pełna ścieżka: pula działa na naprawionej kopii podczas montowania testowego tylko do odczytu. Oglądasz dane i je potwierdzasz. Gdy wpiszesz YES, skrypt zapisuje kopię do puli.

  • data NOT OK

    Podczas montowania testowego odpowiadasz, że dane nie są w porządku. Skrypt wraca do oryginalnej konfiguracji LVM, a oryginalne metadane zostają bez zmian.

    Przekaż sprawę do wsparcia QNAP z pakietem logów z menu 7 i pakietem tp_collect z menu Tools.

Wynik, którego nie rozpoznaje, skrypt traktuje jak uszkodzenie mapowań. Przy uszkodzeniu mapy przestrzeni proponuje też dwie ścieżki, które zapisują bezpośrednio do oryginalnych metadanych: legacy (thin_dump i thin_restore) oraz rebuild (thin_rebuild firmy QNAP). Obie wymagają zweryfikowanego obrazu i wpisanego YES. W puli bez zarezerwowanego woluminu na kopię legacy jest jedyną ścieżką dla uszkodzenia mapowań, a wybierasz ją, wpisując LEGACY.

Zasady bezpieczeństwa

  • Ścieżka naprawy zapisuje do oryginalnych metadanych dopiero wtedy, gdy krok 3 ma ich zweryfikowany obraz. Surowy obraz musi mieć rozmiar urządzenia i ten sam wynik thin_check. Skompresowany obraz skrypt porównuje z urządzeniem bajt po bajcie.
  • Zanim naprawa nadpisze oryginalne metadane, wpisujesz YES. Każda inna odpowiedź anuluje zapis.
  • Przed zapisem skrypt szuka w logu jądra zgłoszeń błędów pamięci i błędów wejścia-wyjścia dysków, na których leży pula. Gdy je znajdzie, pyta, czy kontynuować, a domyślna odpowiedź to „nie”.
  • Skrypt nie zaczyna naprawy na nieaktywnej macierzy RAID. Gdy macierz jest zdegradowana albo trwa na niej odbudowa, synchronizacja, zmiana układu lub sprawdzanie, skrypt najpierw pyta, a domyślna odpowiedź to „nie”.
  • Po naprawie uszkodzonych mapowań krok 5 proponuje sprawdzenie systemu plików tylko do odczytu (e2fsck -fn) na woluminach objętych uszkodzeniem, zanim je zamontuje. Gdy sprawdzenie znajdzie błędy, wybierasz naprawę: e2fsck -fp, e2fsck -fy po wpisaniu FSCK albo później funkcję Check File System w QTS.
  • Katalog roboczy z logami i obrazem metadanych leży poza pulą: na dysku zewnętrznym albo na woluminie innej puli. Skrypt nie przyjmuje folderu na naprawianej puli.
  • Skrypt działa w screen, więc zerwanie sesji SSH go nie zatrzymuje. Uruchom skrypt ponownie, aby wrócić do sesji.
  • Stan sesji leży na partycji systemowej NAS-a (md9), poza pulą. Po restarcie skrypt znajduje niedokończoną sesję i pyta, czy ją kontynuować.
  • Podczas montowania testowego LVM kieruje pulę na naprawioną kopię. Grupa woluminów ma wtedy flagę skip-activation, więc po restarcie NAS-a pula zostaje offline.
  • Od tych zasad są dwa wyjątki. Gdy metadane są spójne, a ustawiona jest tylko flaga needs_check, skrypt kasuje flagę bez obrazu, bez sprawdzenia sprzętu i RAID oraz bez wpisywania YES. Awaryjna opcja --allow-no-backup znosi tylko zasadę obrazu, a opisują ją opcje poniżej.
  • Gdy któryś wolumin nie wróci, QTS może odbudować konfigurację pamięci masowej poleceniem init_lvm.sh. Skrypt uruchamia je dopiero po wpisaniu REBUILD, najpierw zapisuje kopie plików, a potem wypisuje każde ustawienie, które odbudowa zmieniła.

Ograniczenia

  • Naprawa nie odzyska danych z uszkodzonych zakresów mapowań. W nagraniu z mapowaniami uszkodziliśmy dwa liście drzewa mapowań woluminu testowego z 600 plikami po 4 MiB. Po naprawie 534 pliki miały zgodne sumy kontrolne. 66 plików miało dane w dwóch usuniętych zakresach i się zmieniło.
  • Skrypt naprawia tylko metadane puli. Nie naprawia dysku, macierzy RAID ani brakującego woluminu fizycznego LVM.
  • Skrypt działa w QTS z pulą LVM thin. W QuTS hero, który używa ZFS, kończy pracę na starcie.
  • Przy pamięci podręcznej SSD do zapisu (read-write albo write-only) albo przy danych w dwóch lub więcej warstwach Qtier skrypt zatrzymuje się przed krokiem 2 i przed naprawą i odsyła do pomocy technicznej QNAP. Przy pamięci podręcznej SSD tylko do odczytu najpierw pyta, czy jest usunięta albo wyłączona dla tej puli.
  • Na czas naprawy pula przechodzi w stan offline. W trybie łagodnym skrypt zatrzymuje menedżera migawek, gdy migawki puli są zamontowane. Gdy coś blokuje wolumin, wybierasz, jak daleko skrypt się posunie: zatrzyma menedżera migawek, zatrzyma wszystkie usługi QTS, zakończy procesy, które blokują wolumin, albo oznaczy grupę woluminów flagą, dzięki której pula zostanie offline po restarcie NAS-a. W trybie pełnym skrypt od razu zatrzymuje wszystkie usługi QTS, a krok 5 proponuje ich ponowne uruchomienie.
  • Skrypt nie sprawdza systemu plików na zaszyfrowanym woluminie. Gdy NAS ma wolumin pamięci podręcznej SSD, skrypt pomija sprawdzenie systemu plików.
  • Czysty wynik sprawdzenia sprzętu nie dowodzi, że pamięć RAM jest sprawna. Testem pamięci jest MemHound.
  • Komunikaty skryptu są po angielsku. Na każde pytanie odpowiadasz literą, cyfrą albo słowem i naciskasz Enter. Strzałki w menu nie działają. Ctrl+C nie przerywa skryptu.