Unofficial

LVM Pool Repair:修復 QNAP 精簡儲存池中繼資料的指令碼

這個提供選單的 Shell 指令碼,透過 SSH 修復 QTS 上 QNAP 精簡儲存池的中繼資料。

修復分成五個步驟。指令碼會診斷、準備儲存池、備份、修復,最後讓儲存池和磁碟區恢復運作。

在選單中按 Enter,即可執行指令碼建議的下一個步驟。SSH 連線中斷或 NAS 重新啟動後,您可以繼續同一個修復工作階段。

版本 1.8 · 透過 SSH 以 admin 身分在 NAS 上執行 · 使用 LVM 精簡儲存池的 QTS · 免費軟體

  • 5選單中的步驟,依修復順序排列
  • 3中繼資料損壞類型,各有對應的修復方式
  • YES覆寫儲存池中繼資料前須輸入的字詞

指令碼執行錄影

每段錄影都是真實的 SSH 工作階段,在 QNAP NAS 上執行 1.7 版指令碼。終端機大小為橫向 80 個字元、縱向 25 個字元。1.8 版在這些畫面中新增了一段 RAID 和磁碟的唯讀檢查,會在顯示選單前和步驟 1 開始時執行。我們刻意破壞儲存池中已知位置的中繼資料,並保留原始區塊。我們在步驟 2 後趁儲存池離線時寫入損壞的中繼資料。錄影省略了這段暫停。步驟 2 結束後,指令碼會在同一個工作階段繼續進行診斷。錄影縮短了較長的等待時間。實際等待時間取決於儲存池的大小和快照。

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.                                              
錄影從下載指令開始,第一條是 cd /mnt/HDA_ROOT。步驟 2 會讓儲存池離線。指令碼在選單等待輸入時,我們把中繼資料的空間配置表中的一筆記錄設成錯誤的值。接著輸入 a 開始自動執行。指令碼會進行診斷、儲存中繼資料映像、執行修復,並讓儲存池、磁碟區和應用程式恢復運作。指令碼只會暫停一次,在寫入儲存池前等待操作者輸入 YES。中繼資料的空間配置表有一筆記錄的設定不正確。指令碼會停止服務、儲存已驗證的中繼資料映像,並建立及檢查修復後的副本。操作者輸入 YES 後,指令碼會將副本寫入儲存池。步驟 5 會讓儲存池、磁碟區和應用程式恢復運作。主要超級區塊已損壞,備份仍有效。指令碼會透過最新的備份讀取中繼資料。操作者輸入 YES 後,指令碼會從該副本還原超級區塊、檢查中繼資料,並讓儲存池恢復運作。測試磁碟區的對應樹有兩個葉節點損壞。儲存池會使用修復後的副本進行唯讀測試掛載,並在這次掛載中讀取檔案。操作者確認資料並輸入 YES 後,指令碼會將副本寫入儲存池,並在 QTS 掛載測試磁碟區前檢查其檔案系統。最後比對 600 個測試檔案的總和檢查碼,結果有 534 個檔案完好,66 個已有變更。損壞情況相同。NAS 在唯讀測試掛載期間重新啟動。由於指令碼在測試前已設定 skip-activation 旗標,重新啟動後,儲存池仍維持離線。透過 SSH 重新登入後,再次執行指令碼。指令碼會找到尚未完成的工作階段並完成修復。

下載指令碼

下載指令碼需要 PIN。請輸入 PIN 以顯示下載連結。

啟動指令碼

指令碼直接在 NAS 上執行。QTS 沒有 sudo,因此需要使用 admin 帳號。

  1. 透過 SSH 以 admin 身分登入 NAS。
  2. 切換至存放指令碼的資料夾。該資料夾必須位於要修復的儲存池之外。
  3. 使用下方第一個命令啟動指令碼。
  4. 選擇位於儲存池之外的工作目錄。若未指定工作目錄,指令碼仍可診斷,但步驟 3 無法儲存中繼資料的映像檔。
# 啟動指令碼並顯示選單
sh qnap-pool-repair.sh
# 連線中斷後回到工作階段
screen -r qnap-pool-repair

儲存空間的修復操作可能無法復原。在指令碼寫入任何資料前,請確認重要資料已有備份,且診斷結果符合您的 NAS 狀況。

選項

--auto
指令碼偵測到儲存池後開始自動執行,依序執行步驟 1 到 5。自動執行需要工作目錄。
--debug
顯示呼叫追蹤,並以方框標示各個命令。將完整的 Shell 執行追蹤寫入 trace.log。寫入時需要工作目錄。
--no-screen
執行指令碼時不使用 screen 工作階段。
--selftest
以唯讀方式檢查指令碼使用的指令,然後結束。
--raid-check
以唯讀方式檢查 RAID 陣列、其成員及磁碟上的 QNAP 簽章,然後結束。不需要儲存池。
--allow-no-backup
僅供緊急情況使用。您可以在沒有中繼資料映像檔的情況下,確認執行快速修復或完整修復。請輸入 NO-BACKUP,再輸入指令碼顯示的儲存池名稱,例如 vg1/tp1。自動執行不會使用此選項。
--help
顯示選項。
--version
顯示版本。

五個步驟

顯示選單前,指令碼會以紅色顯示 WARNING,並確認 NAS 上有它使用的 79 個指令。在新的工作階段中,指令碼接著會以唯讀方式檢查 RAID 陣列及其磁碟。選單依修復順序列出步驟,並顯示各步驟的狀態。按 Enter 可執行建議的步驟。自動執行會依序完成剩餘步驟,並對有安全預設答案的問題採用該答案。指令碼仍會詢問使用中的磁碟區,以及測試掛載時看到的資料是否正確。您也仍須輸入 YES。

  1. Status and diagnosis

    指令碼會檢查 RAID 和硬體。儲存池離線時,指令碼會對儲存池的中繼資料執行 thin_check。儲存池仍在運作時,指令碼會提供唯讀的初步檢查。

    唯讀
  2. Prepare

    指令碼會卸載儲存池的磁碟區,並停用磁碟區群組。在較保守的模式下,指令碼只卸載屬於此儲存池的項目。只有當資源仍在使用中時,才會停止服務。

    儲存池離線
  3. Backup

    指令碼會儲存 LVM 組態,並將中繼資料的映像檔寫入工作目錄。指令碼會先比對裝置,確認映像檔相符後才採用。

    已驗證的映像檔
  4. Repair the metadata

    指令碼會提供符合診斷結果的修復方式。修復程序覆寫原始中繼資料前,請輸入 YES。

    輸入 YES
  5. Bring the pool and the volumes up

    指令碼會啟用儲存池。QTS 會掛載磁碟區,指令碼則會逐一比對磁碟區與先前儲存的清單。指令碼會詢問是否啟動先前停止的服務。所有磁碟區恢復可用後,指令碼會顯示 LOOKS GOOD、寫入報告並打包記錄檔。

    報告與記錄檔

診斷結果

步驟 1 會以指令碼內建的訊息顯示 thin_check 的結果。步驟 4 接著提供對應的修復方式。

  • space map counts only

    只有空間配置表的計數有誤。對應樹沒有損壞。

    快速修復。指令碼會在保留的磁碟區上建立修復後的副本,並加以檢查。您輸入 YES 後,指令碼會將副本寫入儲存池。

  • damaged superblock

    主要超級區塊已損壞。指令碼在中繼資料中找到有效的備份。

    指令碼會透過最新的有效副本讀取中繼資料。您輸入 YES 後,指令碼會從這份副本還原超級區塊,並再次進行診斷。

  • mapping tree errors

    用來對應磁碟區區塊的樹有部分損壞。修復程序會從對應關係中移除這些範圍。之後讀取這些範圍的區塊時,會顯示為空白。

    完整修復。儲存池會使用修復後的副本進行唯讀測試掛載。請查看資料並確認是否正確。您輸入 YES 後,指令碼會將副本寫入儲存池。

  • data NOT OK

    在測試掛載期間,如果您回覆資料有誤,指令碼會還原原始的 LVM 組態。原始中繼資料不會變更。

    請聯絡 QNAP 技術支援,並附上選單 7 的記錄檔套件,以及 Tools 選單的 tp_collect 套件。

指令碼會將無法辨識的結果視為對應關係損壞。若空間配置表損壞,指令碼也提供兩種直接寫入原始中繼資料的方法,即 legacy(thin_dump 和 thin_restore)與 rebuild(QNAP 的 thin_rebuild)。兩種方法都需要已驗證的映像檔,且須輸入 YES。如果儲存池沒有保留供副本使用的磁碟區,就只能用 legacy 修復對應關係。請輸入 LEGACY 選擇這個方法。

安全規則

  • 只有在步驟 3 備妥已驗證的映像檔後,修復程序才會寫入原始中繼資料。原始格式的映像檔必須與裝置大小相同,且 thin_check 的結果也必須相同。若為壓縮映像檔,指令碼會逐一比對映像檔與裝置的每個位元組。
  • 修復程序覆寫原始中繼資料前,請輸入 YES。任何其他答案都會取消寫入。
  • 寫入前,指令碼會搜尋核心記錄,查看是否有記憶體錯誤報告或儲存池底層磁碟的 I/O 錯誤。如果發現任何一項錯誤,就會詢問是否繼續。預設答案為否。
  • RAID 未啟用時,指令碼不會開始修復。如果 RAID 處於降級狀態,或正在重建、重新同步、調整配置或檢查,指令碼會先詢問是否繼續。預設答案為否。
  • 修復受損的對應關係後,步驟 5 會在掛載受影響的磁碟區之前,提供唯讀的檔案系統檢查(e2fsck -fn)。如果檢查發現錯誤,請選擇 e2fsck -fp,或選擇 e2fsck -fy 並先輸入 FSCK,也可以稍後使用 QTS 的 Check File System。
  • 存放記錄檔和中繼資料映像檔的工作目錄須位於儲存池之外,可放在外接磁碟或另一個儲存池的磁碟區上。指令碼不接受位於修復中儲存池的資料夾。
  • 指令碼在 screen 中執行,因此 SSH 連線中斷時仍會繼續運作。再次執行指令碼即可回到該工作階段。
  • 工作階段的狀態儲存在儲存池之外的 NAS 系統分割區(md9)。重新啟動後,指令碼會找到未完成的工作階段,並詢問是否繼續。
  • 測試掛載期間,LVM 會讓儲存池指向修復後的副本。這段期間,磁碟區群組會設定 skip-activation 旗標,因此 NAS 重新啟動後,儲存池仍會保持離線。
  • 這些規則有兩種例外情況。如果中繼資料一致,且只設定了 needs_check 旗標,指令碼會直接清除旗標,不建立映像檔、不檢查硬體或 RAID,也不要求輸入 YES。緊急選項 --allow-no-backup 只免除映像檔的要求。詳細說明請參閱選項一節。
  • 如果某個磁碟區未恢復可用,QTS 可使用 init_lvm.sh 重建該磁碟區的儲存配置。指令碼會等您輸入 REBUILD 才執行該指令。執行前會先儲存檔案,重建後會列出所有變更的設定。

限制

  • 修復無法還原位於受損對應範圍內的資料。在對應關係的修復錄影中,測試磁碟區的對應樹有兩個葉節點損壞。該磁碟區有 600 個檔案,每個檔案大小為 4 MiB。修復後,有 534 個檔案的總和檢查碼與先前儲存的值相符。有 66 個檔案的資料位於被捨棄的兩個範圍內,這些檔案已有變更。
  • 指令碼只修復儲存池的中繼資料,無法修復磁碟、RAID 或遺失的 LVM 實體磁碟區。
  • 指令碼可在使用 LVM 精簡儲存池的 QTS 上執行。在使用 ZFS 的 QuTS hero 上,指令碼啟動後便會停止。
  • 如果 SSD 快取可讀寫或僅供寫入,或資料分布於兩個或更多 Qtier 層級,指令碼會在步驟 2 與修復開始前停止,並請您聯絡 QNAP 技術支援。如果是唯讀 SSD 快取,指令碼會先詢問快取是否已移除,或是否已針對這個儲存池停用。
  • 儲存池在修復期間會離線。在較保守的模式下,如果儲存池的快照已掛載,指令碼會停止快照管理員。如果磁碟區仍在使用中,您可以選擇要採取的措施。您可以停止快照管理員、停止所有 QTS 服務、結束占用磁碟區的程序,或為磁碟區群組設定旗標,讓儲存池在 NAS 重新啟動後維持離線。在完整模式下,指令碼會立即停止所有 QTS 服務,並在步驟 5 詢問是否重新啟動這些服務。
  • 指令碼不會檢查加密磁碟區的檔案系統。如果 NAS 上有 SSD 快取磁碟區,指令碼會略過檔案系統檢查。
  • 硬體檢查沒有發現錯誤,無法證明 RAM 正常。請使用 MemHound 測試記憶體。
  • 指令碼以英文顯示訊息。回答每個問題時,請輸入一個字母、數字或字詞,再按 Enter。選單不支援方向鍵。Ctrl+C 無法中斷指令碼。