中文： 本文件僅記錄救援流程與技術發現，不包含任何 QNAP 專有軟體、二進位檔案或原始碼。文中描述的操作步驟需要使用者從自己合法擁有的 QNAP NAS 設備上取得所需工具。本文件僅供教育與研究用途，作者不對任何因使用本文件所造成的資料損失負責。在嘗試任何救援操作之前，建議先聯繫 QNAP 原廠客服，他們可能有更簡單的標準處理方式。
English: This document only records the rescue process and technical findings. It does not contain any QNAP proprietary software, binaries, or source code. The procedures described require users to obtain necessary tools from their own legitimately owned QNAP NAS devices. This document is for educational and research purposes only. The author is not responsible for any data loss resulting from the use of this document. Before attempting any rescue operations, it is recommended to contact QNAP official support first, as they may have simpler standard procedures available.
這是一份完整的 QNAP QuTS Hero ZFS pool 救援紀錄與教學。當你的 QNAP NAS 遇到 ZFS metadata corruption（錯誤碼 ZFS-8000-72），所有硬碟都健康但 pool 無法掛載時，這份文件可以幫助你救回資料。
QNAP 的 QuTS Hero 使用的是 魔改版 ZFS（QZFS），與標準 OpenZFS 存在多處不相容。這導致：
- 標準 OpenZFS 工具無法識別 QNAP 的 pool
- 專業資料救援公司的工具也可能無法處理
- 網路上幾乎找不到相關技術文件
本案例中，專業救援公司（具備 PC-3000 等頂級設備）檢查後判定無法救援。最終透過逆向工程 QNAP 的 ZFS 修改，成功救回所有資料。
# zpool import
pool: zpool1
id: [pool-id]
state: FAULTED
status: The pool metadata is corrupted.
action: The pool cannot be imported due to damaged devices or data.
see: http://www.sun.com/msg/ZFS-8000-72
config:
zpool1 FAULTED corrupted data
raidz1-0 ONLINE
[disk1] ONLINE
[disk2] ONLINE
... (所有硬碟都 ONLINE)
關鍵特徵：所有硬碟 ONLINE，但 pool 層級 FAULTED + corrupted data。
| 項目 | QNAP QZFS | 標準 OpenZFS |
|---|---|---|
| Uberblock magic number | 0x00bab10b |
0x00bab10c |
| Feature flags | 包含自訂 features | 無法識別 QNAP features |
| Indirect layout | indirect_layout=1（專有格式） |
不支援 |
| DMU byteswap | ZAP type 0x3 |
ZAP type 0x4 |
| RAIDZ layout | raidz_layout=1（自訂） |
標準 layout |
| Large directory | QNAP_LARGE_DIR 修改 |
無此功能 |
| Device paths | /dev/qzfs/enc_0/disk_* |
標準 /dev/sd* |
這些差異意味著：
- OpenZFS 的
zpool import會判定所有 uberblock invalid（因為 magic number 不同） - 就算修改 magic number，indirect_layout 不同導致無法讀取實際資料
- QNAP 開源的 CDDL 原始碼缺少關鍵標頭檔（如
zib.h），無法完整移植
- 所有硬碟都還在且可讀取
- 你有一台正在運行的 QNAP NAS（相同或相近版本的 QuTS Hero）
- 一台 Linux 機器（Ubuntu 22.04/24.04），能同時接上所有 RAID 硬碟
- 足夠的空間存放救回的資料
| 品項 | 用途 | 參考價格（TWD） |
|---|---|---|
| LSI 9300-8i 或 9211-8i HBA 卡（IT Mode） | 擴充 SATA 接口 | $1,000-2,000 |
| SFF-8643 或 SFF-8087 轉 SATA 線 ×2 | 連接硬碟 | $300-500 |
| SATA 電源分接線 ×2-3 | 供電給所有硬碟 | $100-300 |
| Ubuntu USB 開機碟 | 開機環境 | 手邊隨身碟即可 |
# 安裝 ZFS 工具
sudo apt update
sudo apt install -y zfsutils-linux
# 掃描硬碟（用 by-id 路徑，更穩定）
sudo zpool import -d /dev/disk/by-id
# 確認症狀：FAULTED + corrupted data，但硬碟全部 ONLINE# 找到其中一顆硬碟的 ZFS 分區（通常是 part3）
DISK="/dev/sdX3" # 替換為實際硬碟
# 讀取 uberblock 區域，檢查 magic number
sudo dd if=$DISK bs=512 skip=256 count=1 2>/dev/null | xxd | head -5
# 如果看到 0b b1 ba 00 而不是 0c b1 ba 00
# 就確認是 QNAP QZFS 格式正常 OpenZFS magic： 0x00bab10c → 顯示為 0c b1 ba 00
QNAP QZFS magic： 0x00bab10b → 顯示為 0b b1 ba 00
⚠️ 此方法只能讀到 MOS（Meta Object Set），無法讀取實際檔案資料。 記錄在此是因為對理解問題有幫助。
# Clone OpenZFS 原始碼
git clone -b zfs-2.2.2 https://github.com/openzfs/zfs.git
cd zfs
# 修改 include/sys/uberblock_impl.h
# 加入：#define UBERBLOCK_MAGIC_QNAP 0x00bab10bULL
# 修改 module/zfs/uberblock.c
# 在 uberblock_verify() 中接受 QNAP magic
# 編譯 userspace-only
./autogen.sh
./configure --with-config=user
make -j$(nproc)
# 使用修改版工具掃描
./cmd/zdb/zdb -l /dev/sdX3
# 此時可以看到 uberblock 和 label 資訊
# 但嘗試讀取 dataset 時會失敗（indirect_layout 不相容）這是突破口的開始。你需要一台正在運行的 QNAP NAS（QuTS Hero）。
# SSH 登入你的 QNAP NAS
ssh admin@[NAS-IP]
# 需要複製的檔案
# 1. ZFS 工具
/sbin/zdb
/sbin/zpool
/sbin/zfs
# 2. 相關的 shared libraries（約 50-60 個）
# 用 ldd 查看依賴
ldd /sbin/zdb
# 3. 動態連結器
/lib/ld-linux-x86-64.so.2 # 或 QNAP 版本的路徑
# 複製到你的 Ubuntu 機器
scp -r admin@[NAS-IP]:/sbin/zdb ./qnap_tools/
scp -r admin@[NAS-IP]:/lib/*.so* ./qnap_libs/
# ... 複製所有 ldd 列出的依賴# 在 Ubuntu 上用 QNAP 的連結器執行 QNAP zdb
./qnap_tools/ld-linux-x86-64.so.2 \
--library-path ./qnap_libs \
./qnap_tools/zdb -l /dev/sdX3
# 如果成功，你可以看到完整的 metadata 和目錄結構
# 但 QNAP 的 zdb 沒有 -r/-O 選項，無法匯出檔案內容既然 QNAP 的工具被閹割，無法匯出檔案，那就建一個完整的 QNAP 環境。
# SSH 登入 NAS，找到系統分區
# 通常是 DOM（Disk on Module）上的分區
ssh admin@[NAS-IP]
# 找到 kernel 和 initrd
find / -name "bzImage" -o -name "initrd*" 2>/dev/null
# 複製到 Ubuntu 機器
scp admin@[NAS-IP]:/path/to/bzImage ./qnap_boot/
scp admin@[NAS-IP]:/path/to/initrd.boot ./qnap_boot/
scp admin@[NAS-IP]:/path/to/rootfs2.bz ./qnap_boot/mkdir /tmp/qnap_initrd
cd /tmp/qnap_initrd
# 解壓 initrd（QNAP 使用 cpio 格式）
zcat /path/to/initrd.boot | cpio -idmv
# 同時解壓 rootfs
bzcat /path/to/rootfs2.bz | cpio -idmv建立 /tmp/qnap_initrd/sbin/init（覆蓋原有的）：
#!/bin/sh
export PATH=/sbin:/bin:/usr/sbin:/usr/bin
# 掛載基本檔案系統
mount -t proc proc /proc
mount -t sysfs sysfs /sys
mount -t devtmpfs devtmpfs /dev
# 等待裝置就緒
sleep 3
# 載入必要驅動（順序重要！）
# VirtIO 驅動（用於 QEMU）
insmod /lib/modules/*/virtio.ko
insmod /lib/modules/*/virtio_ring.ko
insmod /lib/modules/*/virtio_pci.ko
insmod /lib/modules/*/failover.ko
insmod /lib/modules/*/net_failover.ko
insmod /lib/modules/*/virtio_net.ko
insmod /lib/modules/*/virtio_blk.ko
# QNAP ZFS 驅動（依賴順序）
insmod /lib/modules/*/lpl.ko
insmod /lib/modules/*/icp.ko
insmod /lib/modules/*/zfs.ko
sleep 2
# 掛載 ZFS pool（唯讀模式！）
zpool import -d /dev -o readonly=on -R /oldpool -f zpool1 oldpool
# 設定網路
ip addr add [VM-IP]/23 dev eth0
ip link set eth0 up
ip route add default via [GATEWAY-IP]
# 掛載 NFS（用於傳輸資料到 NAS）
mkdir -p /mnt/nas
mount -t nfs [NAS-IP]:/share/[VOLUME]/[PATH] /mnt/nas
# 開始複製資料
echo "=== Starting data transfer ==="
cp -av /oldpool/[dataset-name]/ /mnt/nas/
echo "=== Transfer complete ==="
# 保持系統運行
exec /bin/sh# 設定執行權限
chmod +x /tmp/qnap_initrd/sbin/init
# 重新打包 initrd
cd /tmp/qnap_initrd
find . | cpio -o -H newc | gzip > /tmp/custom_initrd.gz# 在 Ubuntu 主機上設定 bridge
sudo apt install -y bridge-utils
# 建立 bridge（替換 eno1 為你的實際網路介面）
sudo ip link add br0 type bridge
sudo ip link set eno1 master br0
sudo ip addr flush dev eno1
sudo ip addr add [HOST-IP]/23 dev br0
sudo ip link set br0 up
sudo ip route add default via [GATEWAY-IP]
# 建立 tap 裝置給 VM 用
sudo ip tuntap add tap0 mode tap
sudo ip link set tap0 master br0
sudo ip link set tap0 up# 收集所有硬碟的 by-id 路徑
ls -la /dev/disk/by-id/ | grep part3
# 啟動 VM（範例為 12 顆硬碟）
sudo qemu-system-x86_64 \
-m 8G \
-smp 4 \
-kernel /path/to/bzImage \
-initrd /tmp/custom_initrd.gz \
-append "console=ttyS0" \
-nographic \
-netdev tap,id=net0,ifname=tap0,script=no,downscript=no \
-device virtio-net-pci,netdev=net0 \
-drive file=/dev/disk/by-id/[DISK1]-part3,format=raw,if=virtio,readonly=on \
-drive file=/dev/disk/by-id/[DISK2]-part3,format=raw,if=virtio,readonly=on \
-drive file=/dev/disk/by-id/[DISK3]-part3,format=raw,if=virtio,readonly=on \
-drive file=/dev/disk/by-id/[DISK4]-part3,format=raw,if=virtio,readonly=on \
-drive file=/dev/disk/by-id/[DISK5]-part3,format=raw,if=virtio,readonly=on \
-drive file=/dev/disk/by-id/[DISK6]-part3,format=raw,if=virtio,readonly=on \
-drive file=/dev/disk/by-id/[DISK7]-part3,format=raw,if=virtio,readonly=on \
-drive file=/dev/disk/by-id/[DISK8]-part3,format=raw,if=virtio,readonly=on \
-drive file=/dev/disk/by-id/[DISK9]-part3,format=raw,if=virtio,readonly=on \
-drive file=/dev/disk/by-id/[DISK10]-part3,format=raw,if=virtio,readonly=on \
-drive file=/dev/disk/by-id/[DISK11]-part3,format=raw,if=virtio,readonly=on \
-drive file=/dev/disk/by-id/[DISK12]-part3,format=raw,if=virtio,readonly=on
⚠️ 注意：所有硬碟都以readonly=on掛載，不會寫入任何資料到原始硬碟。
# 在 VM console 中
df -h /mnt/nas
ls -la /mnt/nas/
# 或從 Ubuntu 主機透過 NFS 確認
ls -la /path/to/nas/mount/A: 你需要從某處取得 QNAP 的 ZFS 工具和驅動。可能的來源：
- 找朋友借一台 QNAP NAS（需要是 QuTS Hero 版本）
- 從 QNAP 的韌體更新檔中提取（較複雜）
- 聯繫 QNAP 技術支援詢問
A: QTS 使用的是 ext4 + mdadm RAID，不是 ZFS。這份指南不適用。QTS 的 RAID 可以用標準 Linux 工具（mdadm）重組，救援難度低很多。
A: 這份指南適用於「硬碟都健康但 metadata 損壞」的情況。如果有硬碟實體損壞，你可能需要先用 ddrescue 做映像備份，或送專業救援。
A: QEMU + NFS 的方式大約 30-40 MB/s。90TB 的資料大概需要數天。可以考慮：
- 只先複製最重要的目錄
- 用多個 cp 進程並行複製不同目錄
- 確認網路是 1Gbps 或以上
A: 可以，但 NFS 設定比較簡單。如果你的 NAS 支援 iSCSI 且需要更好的效能，可以試試。
本章節詳細記錄 QNAP QuTS Hero 對 OpenZFS 的修改內容，以及每一道技術障礙的分析過程。這些資訊截至本文撰寫時（2026-04），在網路上尚無公開文件記錄。
標準 OpenZFS 行為：
ZFS 在每顆硬碟上寫入 128 個 uberblock 作為 pool 的「超級區塊」。每個 uberblock 開頭有一個 64-bit magic number 0x00bab10c，用於驗證這個 block 是否為有效的 ZFS uberblock。
驗證邏輯位於 module/zfs/uberblock.c 的 uberblock_verify() 函數：
// OpenZFS 原始碼（簡化）
int uberblock_verify(uberblock_t *ub)
{
if (ub->ub_magic == UBERBLOCK_MAGIC) // 0x00bab10c
return 0; // valid
return EINVAL; // invalid
}QNAP 的修改：
QNAP 將 magic number 改為 0x00bab10b（最後一個 byte 從 0c 改成 0b）。
驗證方式：
# 讀取硬碟 ZFS 分區的 uberblock 區域
sudo dd if=/dev/sdX3 bs=512 skip=256 count=1 2>/dev/null | xxd | head -3
# QNAP 輸出（注意第一行的 0b b1 ba 00）：
# 00000000: 0bb1 ba00 0000 0000 01f8 cd01 0000 0000 ................
# 00000010: a3e4 6683 0000 0000 ...
# 標準 OpenZFS 應該是：
# 00000000: 0cb1 ba00 ...影響： 標準 OpenZFS 的 zpool import 會掃描所有 128 個 uberblock，全部判定 invalid，最終報告「The pool metadata is corrupted」。實際上 uberblock 內容完全正常——TXG（Transaction Group）序號連續、時間戳正確、checksum 有效——只是門口的鑰匙孔形狀不對。
修補方式：
修改 include/sys/uberblock_impl.h：
#define UBERBLOCK_MAGIC 0x00bab10cULL
#define UBERBLOCK_MAGIC_QNAP 0x00bab10bULL // 新增修改 module/zfs/uberblock.c：
int uberblock_verify(uberblock_t *ub)
{
if (ub->ub_magic == UBERBLOCK_MAGIC ||
ub->ub_magic == UBERBLOCK_MAGIC_QNAP) // 新增
return 0;
return EINVAL;
}修補後重新編譯（userspace-only）：
./autogen.sh
./configure --with-config=user
make -j$(nproc)此修補讓 zdb -l 成功讀取所有 label 和 uberblock 資訊。
修補 magic number 後，zpool import 仍然失敗，因為 pool 包含 OpenZFS 不認識的 feature flags。
在 module/zfs/spa.c 中，ZFS 會檢查 pool 的 feature flags 是否全部被本地系統支援。QNAP 加入了多個自訂 feature，標準 OpenZFS 不認識這些 feature，因此拒絕 import。
修補方式： 在 spa.c 中 bypass feature check（僅用於唯讀 import）：
// 在 feature 驗證邏輯中加入 bypass
// 注意：這只適用於唯讀模式的救援用途修補後，MOS（Meta Object Set）成功讀取。可以看到 pool 的結構、dataset 列表、snapshot 等 metadata。
問題： 即使 MOS 可讀，嘗試讀取任何 dataset 的實際資料時都會失敗。
根因： QNAP 在 pool 的 feature flags 中設定了 indirect_layout=1，這是一套完全不同的間接塊（indirect block）格式，用於 dnode 到資料塊的索引。
在標準 OpenZFS 中，dnode 透過 block pointer tree 來定位資料塊：
dnode → indirect block (level N) → ... → indirect block (level 1) → data block
QNAP 的 indirect_layout=1 改變了 indirect block 的內部結構，包括：
- block pointer 的排列方式
- indirect block 的大小和對齊方式
- 可能還包括 checksum 計算方式
QNAP CDDL 原始碼分析：
從 SourceForge 下載 QNAP 的 CDDL 釋出（QuTS Hero 5.0.1）：
搜尋 QNAP_INDIRECT_LAYOUT 相關修改，發現涉及以下檔案：
| 檔案 | 修改內容 |
|---|---|
dnode.c |
dnode 讀取邏輯修改，判斷 indirect_layout 版本 |
dmu_objset.c |
Object set 操作適配新的間接塊格式 |
dbuf.c |
Buffer 快取邏輯修改 |
dmu.c |
DMU 層的讀取路徑修改 |
zib.h |
核心標頭檔，定義 indirect layout 的資料結構（未釋出） |
致命問題： zib.h 是定義整個 indirect layout 資料結構的核心標頭檔，但 QNAP 的 CDDL 釋出中沒有包含這個檔案。沒有它，就無法理解 indirect block 的確切格式，也無法在 OpenZFS 上實作相容的讀取邏輯。
在分析過程中還發現 QNAP 修改了 DMU（Data Management Unit）的 byteswap 行為：
- 標準 OpenZFS 的 ZAP（ZFS Attribute Processor）使用 type
0x4 - QNAP QZFS 使用 type
0x3
這會影響在不同 endianness 的系統之間移植 pool 時的資料轉換邏輯。
QNAP 的 pool 設定中包含 raidz_layout=1，這是一個自訂的 RAIDZ 條帶化佈局。
標準 OpenZFS 的 RAIDZ 使用固定的演算法來計算每個資料塊分佈在哪些硬碟上。QNAP 的修改可能涉及條帶大小、parity 分佈方式、或 skip sector 的處理。
由於最終方案是使用 QNAP 原生驅動，此差異未被深入逆向分析。
QNAP 加入了 QNAP_LARGE_DIR 功能，修改了 master node 的尋址方式，以支援包含大量檔案的目錄。
在 QNAP 的原始碼中可以看到相關的條件編譯：
#ifdef QNAP_LARGE_DIR
// 使用擴展的目錄定址方式
#else
// 標準 OpenZFS 目錄處理
#endif從運行中的 QNAP NAS 提取 /sbin/zdb 後，使用 QNAP 的動態連結器在 Ubuntu 上執行：
# 需要約 58 個 shared libraries
./ld-linux-x86-64.so.2 --library-path ./qnap_libs ./qnap_tools/zdb -l /dev/sdX3QNAP 的 zdb 成功讀取了所有 metadata，包括：
- Pool 配置和 feature flags
- 所有 dataset 和 snapshot 列表
- 完整的目錄結構和檔案列表
但 QNAP 編譯的 zdb 移除了以下選項：
-r：讀取 raw block 資料-O：透過 object ID 匯出檔案內容-R：讀取特定的 dva（Data Virtual Address）
這意味著 QNAP 的 zdb 只能用於診斷，不能用於資料提取。
在 QEMU VM 中載入 QNAP 的 ZFS kernel module 時，依賴順序非常重要：
lpl.ko → icp.ko → zfs.ko
lpl.ko：QNAP 的授權/平台抽象層（必須最先載入）icp.ko：Integrated Crypto Provider（ZFS 加密和 checksum 需要）zfs.ko：ZFS 主模組（依賴前兩者）
如果順序錯誤，zfs.ko 會載入失敗，錯誤訊息為 missing symbols。
基於以上分析，專業資料救援公司無法處理此類問題的原因可以總結為：
- 工具層面： 行業標準工具（如 R-Studio、UFS Explorer、PC-3000 的 ZFS 模組）都基於標準 OpenZFS 的格式定義。QNAP 的 magic number 改動讓這些工具在最初的掃描階段就判定「metadata 全部損壞」。
- 知識層面： QNAP 的 ZFS 修改沒有公開文件。即使救援公司知道是格式不相容的問題，也沒有足夠的技術資料來實作相容的讀取邏輯。
- 經濟層面： 為單一案例逆向工程一套私有檔案系統的成本極高，可能超過客戶願意支付的金額。
以下資訊尚待確認，歡迎社群補充：
- QNAP 原廠客服聲稱有「2~3 個標準指令」可以修復此問題，具體指令內容未知
-
zib.h是否在較新版本的 CDDL 釋出中被包含 - QNAP 是否在 QuTS Hero 5.1 或更新版本中改回標準 OpenZFS magic number
- 其他 NAS 廠商（如 TrueNAS、UnRAID）是否也有類似的 ZFS 修改
- QNAP 的
raidz_layout=1與標準 RAIDZ 的具體差異
本次救援全程由 Claude Code (Anthropic) 輔助完成，包括：
- 診斷 QNAP QZFS 與標準 OpenZFS 的差異
- 修改 OpenZFS 原始碼
- 逆向分析 QNAP 的 ZFS 修改
- 設計 QEMU VM 方案
- 撰寫自訂 init 腳本
- 除錯和調整整個流程
作者沒有 Linux、ZFS、QEMU 的專業經驗，全程由 AI 指導完成。
MIT License. 歡迎分享與改進。
A complete guide for rescuing a QNAP QuTS Hero ZFS pool with corrupted metadata (ZFS-8000-72). This is specifically for cases where all disks are healthy but the pool cannot be imported due to metadata corruption.
QNAP's QuTS Hero uses a heavily modified version of ZFS ("QZFS") that is incompatible with standard OpenZFS in several critical ways:
- Different uberblock magic number (
0x00bab10bvs0x00bab10c) — OpenZFS marks all uberblocks as invalid - Custom indirect layout (
indirect_layout=1) — completely different block indexing format - Custom RAIDZ layout — modified striping and parity calculation
- Missing source headers — QNAP's CDDL source release lacks key headers needed to port their changes
Since standard OpenZFS cannot read QNAP's format, and QNAP's included tools are limited, the solution is to boot a QEMU VM with QNAP's own kernel and ZFS drivers:
- Diagnose — Confirm all disks are healthy, identify QNAP magic number
- Extract QNAP boot files — Get kernel, initrd, and ZFS modules from a running QNAP NAS
- Create custom init script — Load ZFS drivers, import pool read-only, mount NFS target
- Boot QEMU VM — Pass all disks as virtio-blk devices (read-only)
- Transfer data — Copy from mounted pool to NAS via NFS
See the Chinese section above for detailed step-by-step instructions.
- All original disks (in any order — ZFS identifies disks by label, not slot position)
- A running QNAP NAS with QuTS Hero (same or similar version) for extracting tools
- Ubuntu Linux machine with enough SATA/SAS ports for all disks
- HBA card (e.g., LSI 9300-8i) if motherboard doesn't have enough ports
- Network connection between Ubuntu machine and NAS
| Item | QNAP QZFS | Standard OpenZFS |
|---|---|---|
| Uberblock magic | 0x00bab10b |
0x00bab10c |
| Feature flags | Custom features unrecognized by OpenZFS | Standard |
| Indirect layout | indirect_layout=1 (proprietary) |
Not supported |
| DMU byteswap | ZAP type 0x3 |
ZAP type 0x4 |
| RAIDZ layout | raidz_layout=1 (custom) |
Standard |
| QNAP source release | Incomplete (missing zib.h) |
N/A |