> For the complete documentation index, see [llms.txt](https://book.bsdcn.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://book.bsdcn.org/zfs/shou-ce-ye/xi-tong-guan-li-ming-ling-system-administration-8/zdb.8.md).

# zdb(8)

## 名称

`zdb` — 显示 ZFS 存储池的调试与一致性信息

## 概述

```sh
zdb [-AbcdDFGhikLMNPsTvXYyZ] [-e [-V] [-p 路径]…] [-I 在途 I/O 操作数] [-o 变量=值]… [-t 事务组] [-U 缓存文件] [-x 转储目录] [-K 密钥] [池名[/数据集|objset ID]] [对象|范围]…
```

```sh
zdb [-AdiPv] [-e [-V] [-p 路径]…] [-U 缓存文件] [-K 密钥] 池名[/数据集|objset ID] [对象|范围]…
```

```sh
zdb -B [-e [-V] [-p 路径]…] [-U 缓存文件] [-K 密钥] 池名/objset ID [备份标志]
```

```sh
zdb -C [-A] [-U 缓存文件] [池名]
```

```sh
zdb -E [-A] word0:word1:…:word15
```

```sh
zdb -l [-Aqu] 设备
```

```sh
zdb -m [-AFLPXY] [-e [-V] [-p 路径]…] [-t 事务组] [-U 缓存文件] 池名 [vdev [metaslab]…]
```

```sh
zdb --allocated-map [-mAFLPXY] [-e [-V] [-p 路径]…] [-t 事务组] [-U 缓存文件] 池名 [vdev [metaslab]…]
```

```sh
zdb -O [-K 密钥] 数据集 路径
```

```sh
zdb -r [-K 密钥] 数据集 路径 目标
```

```sh
zdb -r -O [-K 密钥] 数据集 对象 ID 目标
```

```sh
zdb -R [-A] [-e [-V] [-p 路径]…] [-U 缓存文件] 池名 vdev:偏移:[逻辑大小/]物理大小[:标志]
```

```sh
zdb -S [-AP] [-e [-V] [-p 路径]…] [-U 缓存文件] 池名
```

## 说明

`zdb` 工具显示有助于调试的 ZFS 存储池信息，并执行一定程度的一致性检查。它不是通用工具，其选项（及功能）可能会变更。它不是 `fsck(8)` 工具。

一般而言，该命令的输出反映 ZFS 存储池的磁盘上结构，本质上并不稳定。大多数调用方式的确切输出并无文档记录，此处假定你已了解 ZFS 的内部原理。

如果 `dataset` 参数中不含 `/` 或 `@` 字符，则将其解释为池名。根数据集可以指定为 `池名/`。

`zdb` 是“离线”工具：它直接从用户空间访问存储池之下的块设备，并不关心存储池是否已导入、数据集是否已挂载（甚至系统是否根本支持 ZFS）。当操作已导入且处于活动状态的存储池时，`zdb` 可能会对不一致的存储池数据做出错误解释，从而行为异常，尽管这种情况不太可能发生。

## 选项

显示选项：

### `--allocated-map`

打印池中所有已分配区域的列表。主要用于配合 `zhack metaslab leak` 子命令使用。

### `-b`、`--block-stats`

显示有关块的数量、大小（逻辑大小、物理大小与已分配大小）及去重情况的统计信息。

### `--bin=(lsize|psize|asize)`

与 `-bb` 配合使用时，按给定的大小将所有块归入全部三个分箱（而不是为每个大小分别分箱）。

例如，使用 `--bin=lsize` 时，逻辑大小为 16K、物理大小为 4K 的块将被归入全部三列中的 16K 分箱。

### `--class=(normal|special|dedup|other)[,…]`

与 `-bb` 配合使用时，仅考虑来自这些分配类的块。

### `-B`、`--backup`

生成备份流，类似于 `zfs send`，但针对数字 objset ID，且不打开数据集。当数据集元数据已损坏而数据集本身仍可读时，这在恢复场景中可能有用。

可选的 `flags` 参数是一个字符串，包含 `e`、`L`、`c`、`w` 中的一个或多个字母，它们与 zfs-send(8) 中的同名标志含义相同。

### `-c`、`--checksum`

在打印块统计信息时，验证所有元数据块的校验和（参见 `-b`）。

如果指定多次，则验证所有块的校验和。

### `-C`、`--config`

显示有关配置的信息。如果未指定其他选项，则改为显示有关缓存文件（`/etc/zfs/zpool.cache`）的信息。要指定要显示的缓存文件，参见 `-U`。

如果指定多次，并且同时指定了池名，则同时显示缓存的配置与磁盘上的配置。如果与 `-e` 一起指定多次，还会显示池若被导入时将会使用的配置。

### `-d`、`--datasets`

显示有关数据集的信息。指定一次时，显示基本数据集信息：ID、创建事务、大小与对象数量。参见 `-N`，了解当数据集使用数字名称时，如何确定 `池名[/数据集|objset ID]` 是将指定的 `数据集|objset ID` 作为字符串（数据集名）还是数字（objset ID）处理。

如果指定多次，提供的详细程度会逐级提高。

如果指定了对象 ID 或对象 ID 范围，则仅显示有关这些特定对象或范围的信息。

对象 ID 范围以冒号分隔的元组指定，格式为 `start:end[:flags]`。`start` 与 `end` 字段是表示该范围上、下界的整数对象标识符。`end` 值为 `-1` 表示该范围没有上界。`flags` 字段可选地指定一组标志（下文说明），用于控制转储哪些对象类型。默认转储所有对象类型。减号（`-`）会消除紧随其后的标志的作用，且除非前面带有 `A` 标志，否则该减号不起作用。例如，范围 `0:-1:A-d` 将转储除目录以外的所有对象类型。

* `A`：转储所有对象（默认）
* `d`：转储 ZFS 目录对象
* `f`：转储 ZFS 普通文件对象
* `m`：转储 SPA 空间映射对象
* `v`：转储 ZVol 对象
* `z`：转储 ZAP 对象
* `-`：消除后一个标志的作用

### `-D`、`--dedup-stats`

显示去重统计信息，包括去重比率（`dedup`）、压缩比率（`compress`）、`copies` 属性造成的膨胀（`copies`）以及总体有效比率（`dedup * compress / copies`）。

### `-DD`

显示去重统计信息的直方图，按引用计数显示已分配（物理存在于磁盘上）与被引用（在池中被逻辑引用）的块数量与大小。

### `-DDD`

为每个去重表分别显示统计信息。

### `-DDDD`

转储描述重复块的各个去重表的内容。

### `-DDDDD`

同时转储描述唯一块的各个去重表的内容。

### `-E`、`--embedded-block-pointer=word0:word1:…:word15`

解码并显示由各个 `word` 参数指定的内嵌块指针中的块。

### `-f`、`--file-layout`

显示某个对象在 raidz vdev 的各磁盘上的文件布局。其中显示的数值为十六进制。配合 `-H` 时，输出为便于解析的脚本模式，所有数值均以十进制表示为 512 字节块；配合 `-v` 时，会显示块类型（校验或数据）；配合 `-vv` 时，还会打印每个块在文件内的偏移量。仅支持单个顶级 raidz vdev。

### `-h`、`--history`

显示的存储池历史类似于 `zpool history`，但还包括内部变更、事务与数据集信息。

### `-i`、`--intent-logs`

显示与每个数据集相关的意图日志（ZIL）条目信息。如果指定多次，则显示每种意图日志事务类型的计数。

### `-k`、`--checkpointed-state`

检查存储池的检查点状态。注意，存储池的磁盘上格式不会回退到检查点状态。

### `-l`、`--label=device`

从指定设备读取 vdev 标签与 L2ARC 头。`zdb -l` 在找到有效标签时返回 0，出错时返回 1，未找到有效标签时返回 2。L2ARC 头的存在由特定序列（L2ARC\_DEV\_HDR\_MAGIC）指示。如果 L2ARC 日志块的大小或数量存在计数错误，`zdb -l` 将返回 1。每个唯一配置只显示一次。

### `-ll 设备`

此外还显示标签空间使用统计。如果找到有效的 L2ARC 头，还会显示用于恢复 L2ARC 内容的日志块的属性（持久化 L2ARC）。

### `-lll 设备`

显示每个配置，不论是否唯一。如果找到有效的 L2ARC 头，还会显示用于恢复 L2ARC 内容的日志块中日志条目的属性（持久化 L2ARC）。

如果同时指定 `-q` 选项，则不打印标签或 L2ARC 头。

如果同时指定 `-u` 选项，还会显示该设备上的 uberblock。指定多次可提高详细程度。

### `-L`、`--disable-leak-tracking`

禁用泄漏检测与空间映射的加载。默认情况下，`zdb` 会验证所有非空闲块均被引用，这可能非常耗时。

### `-m`、`--metaslabs`

显示每个 metaslab 的偏移量、空间映射、空闲空间，以及全部日志空间映射及其过时条目的统计信息。

### `-mm`

同时还显示与每个 metaslab 关联的磁盘上空闲空间直方图的信息。

### `-mmm`

显示最大连续空闲空间、内存中的空闲空间直方图，以及每个空间映射中的空闲空间百分比。

### `-mmmm`

显示每个空间映射记录。

### `-M`、`--metaslab-groups`

显示所有“普通”vdev 的 metaslab 组信息——每个 vdev 的 metaslab 数量、碎片化程度与空闲空间直方图，以及整个存储池的碎片化程度与直方图。

### `-MM`

在 `-M` 的普通输出之外增加“特殊”vdev 的信息。同时还显示最大连续空闲空间与每个空间映射中的空闲空间百分比。

### `-MMM`

显示每个空间映射记录。

### `-N`

与 `-d` 相同，但强制 `zdb` 将 `池名[/数据集|objset ID]` 中的 `数据集|objset ID` 解释为数字 objset ID。

### `-O`、`--object-lookups=dataset path`

在指定的 `数据集` 中查找指定的 `路径`，并显示其元数据与间接块。指定的 `路径` 必须相对于 `数据集` 的根。此选项可与 `-v` 配合使用以提高详细程度。

### `-r`、`--copy-object=dataset path destination`

将指定 `数据集` 中指定的 `路径` 复制到指定的目标位置。指定的 `路径` 必须相对于 `数据集` 的根。与 `-O` 配合使用时，`路径` 参数被解释为对象标识符，而非路径。此选项可与 `-v` 配合使用以提高详细程度。

### `-R`、`--read-block=poolname vdev:offset:[lsize/]psize[:flags]`

从指定设备读取并显示一个块。默认情况下，该块以十六进制转储形式显示；有关 `r` 标志的说明见下文。

该块以冒号分隔的元组指定：`vdev`（整数 vdev 标识符）、`offset`（vdev 内的偏移量）、`size`（要读取块的物理大小，或逻辑大小/物理大小），以及可选的 `flags`（一组标志，下文说明）。

* `b offset`：打印给定十六进制偏移量处的块指针
* `c`：计算并显示校验和
* `d`：解压该块。设置环境变量 `ZDB_NO_ZLE`，在推测压缩算法时跳过 zle
* `e`：对该块进行字节序交换
* `g`：转储 gang 块头
* `i`：转储间接块
* `r`：转储未经解释的原始块数据
* `v`：推测压缩算法时输出详细信息

### `-s`、`--io-stats`

报告 `zdb` I/O 的统计信息。显示 `zdb` 对存储池进行 I/O 的操作次数、带宽与错误次数。

### `-S`、`--simulate-dedup`

模拟去重的效果：构建一个 DDT，然后像使用 `-DD` 那样显示该 DDT。

### `-T`、`--brt-stats`

显示块引用表（BRT）统计信息，包括被克隆的唯一块的大小、因克隆而节省的空间以及节省比率。

### `-TT`

显示每个 vdev 的 BRT 统计信息，包括总引用次数。

### `-TTT`

显示每个 vdev 的 BRT 引用计数直方图。

### `-TTTT`

转储块引用表的内容。

### `-u`、`--uberblock`

显示当前 uberblock。

其他选项：

### `-A`、`--ignore-assertions`

任何断言失败时都不中止。

### `-AA`

启用 panic 恢复，某些否则会致命的错误将被降级为警告。

### `-AAA`

断言失败时不中止，同时启用 panic 恢复。

### `-e`、`--exported=[-p path]…`

操作已导出、不在 `/etc/zfs/zpool.cache` 中的存储池。`-p` 标志指定用于搜索设备的路径。

### `-x`、`--dump-blocks=dumpdir`

所有被访问的块都会被复制到指定目录下的文件中。这些块将被放入稀疏文件中，文件名与所读取的文件或设备相同。随后可以在生成的文件上运行 `zdb`。注意，`-bbc` 标志足以访问（并因此复制）存储池上的全部元数据。

### `-F`、`--automatic-rewind`

尝试通过逐次使用更早的事务，使无法读取的存储池变得可读。

### `-G`、`--dump-debug-msg`

在退出 `zdb` 前，转储 `zfs_dbgmsg` 缓冲区的内容。`zfs_dbgmsg` 是 ZFS 用于转储高级调试信息的缓冲区。

### `-I`、`--inflight=inflight-I/O-ops`

将未完成的校验和 I/O 操作数量限制为指定值（默认值: `200`）。此选项会影响 `-c` 选项的性能。

### `-K`、`--key=密钥`

访问加密数据集所需的解密密钥。这将使 `zdb` 尝试使用给定数据集上的加密根、密钥格式及其他加密参数来解锁该数据集。`zdb` 仍可在不解锁的情况下检查加密数据集上的存储池与数据集结构，但将无法访问文件名、属性及对象内容。 **警告** ：在 `zdb` 运行期间，原始解密密钥及任何已解密数据都会存在于用户内存中。其他用户程序可以通过检查运行中的 `zdb` 提取它。在共享或不受控的环境中使用此选项时，请务必格外谨慎。

### `-o`、`--option=var=value…`

将给定的可调参数设为提供的值。

### `-o`、`--option=var…`

显示给定可调参数的值。

### `-o`、`--option=show`

显示所有可调参数及其值。

### `-o`、`--option=info=value…`

显示有关某个可调参数的信息，包括其名称、类型与描述。

### `-o`、`--option=info`

显示有关所有可调参数的信息。

### `-P`、`--parseable`

以更利于解析的未缩放形式打印数字，例如 `1000000` 而不是 `1M`。

### `-t`、`--txg=transaction`

指定搜索 uberblock 时使用的最高事务。另请参见 `-u` 与 `-l` 选项，可以通过它们查看可用的 uberblock 及其关联的事务号。

### `-U`、`--cachefile=cachefile`

使用 `/etc/zfs/zpool.cache` 之外的其他缓存文件。

### `-v`、`--verbose`

启用详细输出。指定多次可提高详细程度。

### `-V`、`--verbatim`

尝试逐字导入。这模拟了内核从缓存文件加载存储池时的行为。仅可与 `-e` 配合使用。

### `-X`、`--extreme-rewind`

尝试“极端”事务回退，即尝试与 `-F` 相同的恢复过程，但会读取那些否则会被认为过于久远的事务。

### `-Y`、`--all-reconstruction`

在重建被拆分的间接块时，尝试所有可能的组合。此标志会禁用单个 I/O 的 deadman 定时器，以便为尝试中的重建留出所需的时间。

### `-y`、`--livelist`

对正在删除的 livelist 执行验证。扫描 livelist 与各 metaslab，检查重复条目并对两者进行比较，以发现潜在的双重释放。如果遇到问题，将打印警告，但命令不一定会失败。

### `-Z`、`--zstd-headers`

读取每个经 ZSTD 压缩的块，并显示其 ZSTD 头：压缩后的大小、zstd 库版本以及所用的压缩级别。

多次指定同一个显示选项，只会提高该选项的详细程度，指定次数越多详细程度越高。

如果未指定任何选项，将以默认详细程度显示指定存储池的所有信息。

## 退出状态

`zdb` 在成功时以 `0` 退出；发生致命错误时以 `1` 退出；指定了无效的命令行选项时以 `2` 退出；检测到磁盘上损坏但不致命时以 `3` 退出。

## 示例

### 示例 1：显示已导入存储池 `rpool` 的配置

```sh
# zdb -C rpool
MOS Configuration:
        version: 28
        name: 'rpool'
 …
```

### 示例 2：显示 `rpool` 的基本数据集信息

```sh
# zdb -d rpool
Dataset mos [META], ID 0, cr_txg 4, 26.9M, 1051 objects
Dataset rpool/swap [ZVOL], ID 59, cr_txg 356, 486M, 2 objects
 …
```

### 示例 3：显示 `rpool/export/home` 中对象 0 的基本信息

```sh
# zdb -d rpool/export/home 0
Dataset rpool/export/home [ZPL], ID 137, cr_txg 1546, 32K, 8 objects

    Object  lvl   iblk   dblk  dsize  lsize   %full  type
         0    7    16K    16K  15.0K    16K   25.00  DMU dnode
```

### 示例 4：显示在 `rpool` 上启用去重的预期效果

```sh
# zdb -S rpool
Simulated DDT histogram:

bucket              allocated                       referenced
______   ______________________________   ______________________________
refcnt   blocks   LSIZE   PSIZE   DSIZE   blocks   LSIZE   PSIZE   DSIZE
------   ------   -----   -----   -----   ------   -----   -----   -----
     1     694K   27.1G   15.0G   15.0G     694K   27.1G   15.0G   15.0G
     2    35.0K   1.33G    699M    699M    74.7K   2.79G   1.45G   1.45G
 …
dedup = 1.11, compress = 1.80, copies = 1.00, dedup * compress / copies = 2.00
```

## 参考文献

zfs(8)、zpool(8)

2026 年 9 月 10 日


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://book.bsdcn.org/zfs/shou-ce-ye/xi-tong-guan-li-ming-ling-system-administration-8/zdb.8.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
