> 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/handbook/di-23-zhang-z-wen-jian-xi-tong-zfs/23.2.-kuai-su-ru-men-zhi-nan.md).

# 23.2.快速入门指南

FreeBSD 安装程序可以直接将系统安装到 ZFS 存储池中，这种配置称为 Root-on-ZFS；参见[引导式 Root-on-ZFS](/handbook/di-2-zhang-an-zhuang-freebsd/2.6.-fen-pei-ci-pan-kong-jian.md)。本节介绍如何在已运行的系统上创建和管理额外的 ZFS 存储池与数据集。

FreeBSD 可以在系统初始化期间挂载 ZFS 存储池和数据集。要启用此功能，请运行：

```sh
# sysrc zfs_enable="YES"
```

这会在 **/etc/rc.conf** 中添加 `zfs_enable="YES"`。运行 `service zfs enable` 也能完成相同的修改。

然后启动服务：

```sh
# service zfs start
```

本节中的示例假设有三块 SATA 磁盘，设备名称分别为 **ada0**、**ada1** 和 **ada2**。使用 SCSI/SAS 硬件的用户应使用 **da** 设备名称，使用 NVMe 存储的用户应使用 **nda** 设备名称。

## 23.2.1. 单磁盘池

首先在空磁盘上创建 GPT 分区，然后添加一个 `freebsd-zfs` 类型的分区，并在此分区上创建单个非冗余池：

```sh
# gpart create -s gpt ada1
# gpart add -t freebsd-zfs ada1
# zpool create example /dev/ada1p1
```

要查看新创建的池，可以查看 `df` 的输出：

```sh
# df /example
Filesystem     1K-blocks    Used    Avail Capacity  Mounted on
example         17547136       0 17547136     0%    /example
```

此输出显示了创建并挂载了 `example` 池，现在它作为文件系统可访问。为用户创建文件以供浏览：

```sh
# cd /example
# ls
# touch testfile
# ls -al
total 4
drwxr-xr-x   2 root  wheel    3 Aug 29 23:15 .
drwxr-xr-x  21 root  wheel  512 Aug 29 23:12 ..
-rw-r--r--   1 root  wheel    0 Aug 29 23:15 testfile
```

这个池还没有使用任何高级 ZFS 功能和属性。要在此池上创建启用压缩的数据集：

```sh
# zfs create example/compressed
# zfs set compression=gzip example/compressed
```

`example/compressed` 数据集现在是 ZFS 压缩文件系统。尝试将一些大文件复制到 **/example/compressed**。

要禁用压缩，请使用：

```sh
# zfs set compression=off example/compressed
```

要卸载文件系统，使用 `zfs umount` 并通过 `df` 验证：

```sh
# zfs umount example/compressed
# df
Filesystem   1K-blocks    Used    Avail Capacity  Mounted on
example       17547008       0 17547008     0%    /example
```

要重新挂载文件系统以使其再次可访问，使用 `zfs mount` 并通过 `df` 验证：

```sh
# zfs mount example/compressed
# df
Filesystem         1K-blocks    Used    Avail Capacity  Mounted on
example             17547008       0 17547008     0%    /example
example/compressed  17547008       0 17547008     0%    /example/compressed
```

运行 `mount` 显示池和文件系统：

```sh
# mount
/dev/ada0p1 on / (ufs, local)
devfs on /dev (devfs, local)
/dev/ada0p2 on /usr (ufs, local, soft-updates)
example on /example (zfs, local)
example/compressed on /example/compressed (zfs, local)
```

创建后，像使用任何文件系统一样使用 ZFS 数据集。根据需要在每个数据集上设置其他可用的特性。下面的示例创建了名为 `data` 的新文件系统。假设该文件系统包含重要文件，并将其配置为存储每个数据块的两个副本。

```sh
# zfs create example/data
# zfs set copies=2 example/data
```

使用 `df` 查看数据和空间使用情况：

```sh
# df
Filesystem        1K-blocks    Used    Avail Capacity  Mounted on
/dev/ada0p1         2026030  235234  1628714    13%    /
devfs                     1       1        0   100%    /dev
/dev/ada0p2        54098308 1032864 48737580     2%    /usr
example            17547008       0 17547008     0%    /example
example/compressed 17547008       0 17547008     0%    /example/compressed
example/data       17547008       0 17547008     0%    /example/data
```

注意，池中的所有文件系统都具有相同的可用空间。使用 `df` 命令显示的这些示例表明，文件系统按需使用空间，并且都来自同一个池。ZFS 摒弃了卷和分区的概念，让多个文件系统能共享同一个池。

要销毁不再需要的文件系统和池：

```sh
# zfs destroy example/compressed
# zfs destroy example/data
# zpool destroy example
```

## 23.2.2. RAID-Z

磁盘会发生故障。避免磁盘故障导致数据丢失的方法之一是使用 RAID。ZFS 在其池设计中支持此功能。RAID-Z 池需要三块或更多的磁盘，但提供比镜像池更多的可用空间。

此示例创建 RAID-Z 池。首先在每块磁盘上创建 GPT 分区，然后使用 `raidz` 关键字将这些 GPT 分区添加到池中：

```sh
# gpart create -s gpt ada0
# gpart add -t freebsd-zfs ada0
# gpart create -s gpt ada1
# gpart add -t freebsd-zfs ada1
# gpart create -s gpt ada2
# gpart add -t freebsd-zfs ada2
# zpool create storage raidz ada0p1 ada1p1 ada2p1
```

> **注意**
>
> 建议在 RAID-Z 配置中使用的设备数量在三块到九块之间。对于需要单个池包含十块或更多磁盘的环境，考虑将其拆分为较小的 RAID-Z 组。如果有两块磁盘可用，ZFS 镜像可以在需要时提供冗余。有关更多详细信息，请参阅 [zpool(8)](https://man.freebsd.org/cgi/man.cgi?query=zpool\&sektion=8\&format=html)。

上面的示例创建了名为 `storage` 的 zpool。这个示例在该池中创建名为 `home` 的新文件系统：

```sh
# zfs create storage/home
```

启用压缩并存储目录和文件的额外副本：

```sh
# zfs set copies=2 storage/home
# zfs set compression=gzip storage/home
```

要将其作为用户的新主目录，请将用户数据复制到此目录并创建适当的符号链接：

```sh
# cp -rp /home/* /storage/home
# rm -rf /home /usr/home
# ln -s /storage/home /home
# ln -s /storage/home /usr/home
```

用户数据现在存储在新创建的 **/storage/home** 中。通过添加新用户并以该用户身份登录来测试。

创建文件系统快照，以便稍后回滚：

```sh
# zfs snapshot storage/home@2026-07-11
```

ZFS 创建的是数据集的快照，而不是单个目录或文件。

`@` 字符是文件系统名称或卷名称之间的分隔符。在删除重要目录之前，先备份文件系统，然后回滚到该目录仍存在的早期快照：

```sh
# zfs rollback storage/home@2026-07-11
```

要列出所有可用的快照，可以在文件系统的 **.zfs/snapshot** 目录中运行 `ls`。例如，要查看刚才创建的快照：

```sh
# ls /storage/home/.zfs/snapshot
```

编写脚本定期创建用户数据的快照。随着时间的推移，快照可能会占用大量磁盘空间。使用以下命令删除先前的快照：

```sh
# zfs destroy storage/home@2026-07-11
```

测试完成后，使用以下命令将 **/storage/home** 设置为真正的 **/home**：

```sh
# zfs set mountpoint=/home storage/home
```

运行 `df` 和 `mount` 确认系统现在将该文件系统视为真实的 **/home**：

```sh
# mount
/dev/ada0p1 on / (ufs, local)
devfs on /dev (devfs, local)
/dev/ada0p2 on /usr (ufs, local, soft-updates)
storage on /storage (zfs, local)
storage/home on /home (zfs, local)
# df
Filesystem   1K-blocks    Used    Avail Capacity  Mounted on
/dev/ada0p1    2026030  235240  1628708    13%    /
devfs                1       1        0   100%    /dev
/dev/ada0p2   54098308 1032826 48737618     2%    /usr
storage       26320512       0 26320512     0%    /storage
storage/home  26320512       0 26320512     0%    /home
```

至此，RAID-Z 配置完成。通过在 **/etc/periodic.conf** 文件中添加以下行，向每晚的 [periodic(8)](https://man.freebsd.org/cgi/man.cgi?query=periodic\&sektion=8\&format=html) 运行添加文件系统的每日状态更新：

```sh
daily_status_zfs_enable="YES"
```

[periodic(8)](https://man.freebsd.org/cgi/man.cgi?query=periodic\&sektion=8\&format=html) 还可以执行存储池的定期 scrub；参见[对池进行 Scrub](/handbook/di-23-zhang-z-wen-jian-xi-tong-zfs/23.3.-zpool-guan-li.md)。

## 23.2.3. 恢复 RAID-Z

每个软件 RAID 都有监控其状态的方法。使用以下命令查看 RAID-Z 设备的状态：

```sh
# zpool status -x
```

如果所有池都是 [在线](/handbook/di-23-zhang-z-wen-jian-xi-tong-zfs/23.10.-zfs-te-xing-he-shu-yu.md)，且一切正常，消息会显示：

```sh
all pools are healthy
```

如果出现问题，可能是磁盘处于 [离线](/handbook/di-23-zhang-z-wen-jian-xi-tong-zfs/23.10.-zfs-te-xing-he-shu-yu.md) 状态，池的状态会显示如下：

```sh
  pool: storage
 state: DEGRADED
status: One or more devices has been taken offline by the administrator.
        Sufficient replicas exist for the pool to continue functioning in a
        degraded state.
action: Online the device using 'zpool online' or replace the device with
        'zpool replace'.
  scan: none requested
config:

        NAME        STATE     READ WRITE CKSUM
        storage     DEGRADED     0     0     0
          raidz1-0  DEGRADED     0     0     0
            ada0p1  ONLINE       0     0     0
            ada1p1  OFFLINE      0     0     0
            ada2p1  ONLINE       0     0     0

errors: No known data errors
```

“OFFLINE”显示管理员通过以下命令将 **ada1p1** 设为离线：

```sh
# zpool offline storage ada1p1
```

现在关机并替换 **ada1p1**。在新磁盘上重建 `freebsd-zfs` 类型的 GPT 分区。开机后将 **ada1p1** 返回池中：

```sh
# zpool replace storage ada1p1
```

接下来，再次检查状态，这次不带 `-x` 选项以显示所有池：

```sh
# zpool status storage
  pool: storage
 state: ONLINE
  scan: resilvered 3.21G in 00:04:36 with 0 errors on Sat Jul 11 10:32:19 2026
config:

        NAME        STATE     READ WRITE CKSUM
        storage     ONLINE       0     0     0
          raidz1-0  ONLINE       0     0     0
            ada0p1  ONLINE       0     0     0
            ada1p1  ONLINE       0     0     0
            ada2p1  ONLINE       0     0     0

errors: No known data errors
```

在此示例中，一切正常。

## 23.2.4. 数据验证

ZFS 使用校验和来验证存储数据的完整性。创建文件系统时会自动启用校验和。

> **警告**
>
> 可以禁用校验和，但 *不推荐*！校验和仅占用极少存储空间，却能确保数据完整性。大多数 ZFS 特性在禁用校验和的情况下无法正常工作。禁用校验和也不会明显提高性能。

验证数据校验和（称为 *scrub*）可以确保 `storage` 池的完整性，命令如下：

```sh
# zpool scrub storage
```

scrub 的持续时间取决于存储的数据量。数据量越大，验证所需的时间就越长。由于 scrub 是 I/O 密集型操作，ZFS 每个池每次只能运行一个 scrub。scrub 完成后，使用 `zpool status` 查看状态：

```sh
# zpool status storage
  pool: storage
 state: ONLINE
  scan: scrub repaired 0B in 00:19:16 with 0 errors on Sat Jul 11 10:32:19 2026
config:

        NAME        STATE     READ WRITE CKSUM
        storage     ONLINE       0     0     0
          raidz1-0  ONLINE       0     0     0
            ada0p1  ONLINE       0     0     0
            ada1p1  ONLINE       0     0     0
            ada2p1  ONLINE       0     0     0

errors: No known data errors
```

显示上次 scrub 完成日期有助于决定何时开始另一次 scrub。定期 scrub 有助于保护数据免受静默损坏，并确保池的完整性。

有关其他 ZFS 选项，请参阅 [zfs(8)](https://man.freebsd.org/cgi/man.cgi?query=zfs\&sektion=8\&format=html) 和 [zpool(8)](https://man.freebsd.org/cgi/man.cgi?query=zpool\&sektion=8\&format=html)。


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://book.bsdcn.org/handbook/di-23-zhang-z-wen-jian-xi-tong-zfs/23.2.-kuai-su-ru-men-zhi-nan.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.