                               =================
                               磁盘阵列的 SnapRAID 备份
                               =================


1 SYNOPSIS
==========

snapraid [-c, --conf CONFIG]
	[-f, --filter PATTERN] [-d, --filter-disk NAME]
	[-m, --filter-missing] [-e, --filter-error]
	[-a, --audit-only] [-h, --pre-hash] [-i, --import DIR]
	[-p, --plan PERC|bad|new|full]
	[-o, --older-than DAYS] [-l, --log FILE]
	[-s, --spin-down-on-error] [-w, --bw-limit RATE]
	[-t, --tail]
	[-Z, --force-zero] [-E, --force-empty]
	[-U, --force-uuid] [-D, --force-device]
	[-N, --force-nocopy] [-F, --force-full]
	[-R, --force-realloc] [-W, --force-realloc-tail]
	[-S, --start BLKSTART] [-B, --count BLKCOUNT]
	[-L, --error-limit NUMBER]
	[-A, --stats]
	[-v, --verbose] [-q, --quiet]
	status|smart|probe|up|down|diff|sync|scrub|fix|check
	|list|dup|pool|devices|touch|rehash|locate

snapraid [-V, --version] [-H, --help] [-C, --gen-conf CONTENT]


2 DESCRIPTION
=============

SnapRAID 是一款专为磁盘阵列设计的备份程序，它存储奇偶校验信息，
以在最多六个磁盘发生故障时进行数据恢复。

SnapRAID 主要面向拥有大型、不常更改文件的家庭媒体中心，提供以下特性：

* 您可以使用已填充文件的磁盘，无需重新格式化，并像往常一样访问它们。
* 您的所有数据都会被散列，以确保存储完整性并防止静默损坏。
* 当故障磁盘数量超过奇偶校验数时，数据丢失仅限于受影响的磁盘；
  其他磁盘上的数据仍然可访问。
* 如果您不小心删除了磁盘上的文件，可以进行恢复。
* 磁盘可以有不同的尺寸。
* 您可以随时添加磁盘。
* SnapRAID 不会锁定您的数据；您可以随时停止使用它，无需重新格式化或移动数据。
* 访问文件时，只需一个磁盘转动，从而节省电力并降低噪音。

欲了解更多信息，请访问 SnapRAID 官方网站：

    https://www.snapraid.it/


3 LIMITATIONS
=============

SnapRAID 是 RAID 和备份程序之间的混合体，旨在结合两者的优点。
然而，在使用它之前，您应该考虑一些限制。

主要的限制是，如果一个磁盘发生故障而您最近没有进行同步（sync），
您可能无法完全恢复。
更具体地说，您可能无法恢复自上次同步操作以来已更改或已删除文件的
大小所对应的部分。
即使更改或删除的文件不在发生故障的磁盘上，也会发生这种情况。
这就是为什么 SnapRAID 更适用于很少更改的数据。

另一方面，新添加的文件不会阻止对已有文件的恢复。
您只会丢失位于发生故障磁盘上的最近添加的文件。

SnapRAID 的其他限制包括：

* 使用 SnapRAID，每个磁盘仍然有单独的文件系统。
  使用 RAID，您可以获得一个单一的大型文件系统。
* SnapRAID 不进行数据条带化。
  使用 RAID，您可以通过条带化获得速度提升。
* SnapRAID 不支持实时恢复。
  使用 RAID，当磁盘发生故障时，您不必停止工作。
* SnapRAID 只能从有限数量的磁盘故障中恢复数据。
  使用备份，您可以从整个磁盘阵列的完全故障中恢复。
* 仅保存文件名、时间戳、符号链接和硬链接。
  不保存权限、所有权和扩展属性。


4 GETTING STARTED
=================

要使用 SnapRAID，您需要首先选择磁盘阵列中的一个磁盘专用于
`parity`（奇偶校验）信息。使用一个奇偶校验磁盘，
您将能够从单磁盘故障中恢复，类似于 RAID5。

如果您想从更多的磁盘故障中恢复，类似于 RAID6，
您必须预留额外的磁盘用于奇偶校验。每增加一个奇偶校验磁盘，
就可以多恢复一个磁盘故障。

作为奇偶校验磁盘，您必须选择阵列中最大的磁盘，
因为奇偶校验信息可能会增长到阵列中最大的数据磁盘的大小。

这些磁盘将专门用于存储 `parity` 文件。
您不应该在它们上面存储您的数据。

然后，您必须定义要使用 SnapRAID 保护的 `data`（数据）磁盘。
如果这些磁盘包含很少更改的数据，保护会更有效。因此，
最好**不要**包含 Windows C:\ 磁盘或 Unix 的 /home、/var 和 /tmp 目录。

文件列表保存在 `content`（内容）文件中，通常存储在数据、奇偶校验或
引导磁盘上。
该文件包含备份的详细信息，包括所有用于验证其完整性的校验和。
`content` 文件存储有多个副本，每个副本必须位于不同的磁盘上，
以确保存储有多个磁盘故障时，至少有一个副本可用。

例如，假设您只对一个奇偶校验保护级别感兴趣，并且您的磁盘位于：

    /mnt/diskp <- 选定的奇偶校验磁盘
    /mnt/disk1 <- 第一个要保护的磁盘
    /mnt/disk2 <- 第二个要保护的磁盘
    /mnt/disk3 <- 第三个要保护的磁盘

您必须创建配置文件 /etc/snapraid.conf，并包含以下选项：

    parity /mnt/diskp/snapraid.parity
    content /var/snapraid/snapraid.content
    content /mnt/disk1/snapraid.content
    content /mnt/disk2/snapraid.content
    data d1 /mnt/disk1/
    data d2 /mnt/disk2/
    data d3 /mnt/disk3/

如果您使用 Windows，您应该使用 Windows 路径格式，
用驱动器号和反斜杠代替斜杠。

    parity E:\snapraid.parity
    content C:\snapraid\snapraid.content
    content F:\array\snapraid.content
    content G:\array\snapraid.content
    data d1 F:\array\
    data d2 G:\array\
    data d3 H:\array\

如果您有许多磁盘且驱动器号用尽，您可以将磁盘直接挂载到子文件夹中。请参阅：

    https://www.google.com/search?q=Windows+mount+point

此时，您已准备好运行 `sync` 命令来构建奇偶校验信息。

    snapraid sync

第一次运行此过程可能需要几个小时，具体取决于磁盘上已存在数据的大小。
如果磁盘是空的，则过程是即时的。

您可以随时按 Ctrl+C 停止它，在下次运行时，它将从中断的地方恢复。

当此命令完成时，您的数据是**安全的**。

现在您可以开始随意使用您的阵列，并定期运行 `sync` 命令更新奇偶校验信息。

4.1 Scrubbing
-------------

要定期检查数据和奇偶校验的错误，您可以运行 `scrub` 命令。

    snapraid scrub

此命令将阵列中的数据与 `sync` 命令期间计算的散列进行比较，
以验证完整性。

每次运行该命令会检查大约 8% 的阵列，排除在过去 10 天内
已被 scrub 的数据。
您可以使用 -p, --plan 选项来指定不同的量，
并使用 -o, --older-than 选项来指定不同的天数。
例如，要检查 20 天以上块的 5% 阵列，请使用：

    snapraid -p 5 -o 20 scrub

如果在过程中发现静默错误或输入/输出错误，
相应的块会在 `content` 文件中被标记为坏块，并列在 `status` 命令中。

    snapraid status

要修复它们，您可以使用 `fix` 命令，使用 -e, --filter-error 选项过滤坏块：

    snapraid -e fix

在下次 `scrub` 时，如果它们确实被修复了，错误将从 `status` 报告中消失。
为了更快，您可以使用 -p bad 来仅 scrub 标记为坏块的块。

    snapraid -p bad scrub

在未同步的阵列上运行 `scrub` 可能会报告由已删除或已修改文件引起的错误。
这些错误会在 `scrub` 输出中报告，但相关块不会被标记为坏块。

4.2 Pooling
-----------

注意：下面描述的 pooling 功能已被 mergerfs 工具取代，
mergerfs 现在是 SnapRAID 社区推荐的 Linux 用户选项。
Mergefs 提供了一种更灵活、更高效的方式，将多个驱动器汇集到一个
统一的挂载点中，允许跨阵列无缝访问文件，而无需依赖符号链接。
它与 SnapRAID 很好地集成以提供奇偶校验保护，常用于
OpenMediaVault (OMV) 或自定义 NAS 配置等设置中。

要使阵列中的所有文件显示在同一个目录树中，
您可以启用 `pooling` 功能。它使用符号链接创建了一个
阵列中所有文件的只读虚拟视图。

您可以在配置文件中使用以下选项配置 `pooling` 目录：

    pool /pool

或者，如果您使用 Windows，则使用：

    pool C:\pool

然后运行 `pool` 命令创建或更新虚拟视图。

    snapraid pool

如果您使用 Unix 平台并希望通过网络将此目录共享给 Windows 或 Unix 机器，
您应该在 /etc/samba/smb.conf 中添加以下选项：

    # 在 smb.conf 的全局部分
    unix extensions = no

    # 在 smb.conf 的共享部分
    [pool]
    comment = Pool
    path = /pool
    read only = yes
    guest ok = yes
    wide links = yes
    follow symlinks = yes

在 Windows 中，通过网络共享符号链接需要客户端远程解析它们。
要启用此功能，除了共享 pool 目录之外，您还必须独立共享所有磁盘，
使用配置文件中定义的磁盘名称作为共享点。
您还必须在配置文件的 `share` 选项中指定远程客户端访问这些
共享磁盘所需的 Windows UNC 路径。

例如，在名为 `darkstar` 的服务器上操作，您可以使用以下选项：

    data d1 F:\array\
    data d2 G:\array\
    data d3 H:\array\
    pool C:\pool
    share \\darkstar

并通过网络共享以下目录：

    \\darkstar\pool -> C:\pool
    \\darkstar\d1 -> F:\array
    \\darkstar\d2 -> G:\array
    \\darkstar\d3 -> H:\array

以允许远程客户端访问 \\darkstar\pool 处的所有文件。

您可能还需要配置远程客户端，使用以下命令启用对远程符号链接的访问：

    fsutil behavior set SymlinkEvaluation L2L:1 R2R:1 L2R:1 R2L:1

4.3 Undeleting
--------------

SnapRAID 的功能更像一个备份程序而不是 RAID 系统，
它可以使用 -f, --filter 选项来恢复或取消删除文件到其以前的状态：

    snapraid fix -f FILE

或者对于一个目录：

    snapraid fix -f DIR/

您也可以使用 -m, --filter-missing 选项来仅恢复目录内意外删除的文件，
该选项仅恢复丢失的文件，保持所有其他文件不变。

    snapraid fix -m -f DIR/

或者使用以下命令恢复所有驱动器上所有已删除的文件：

    snapraid fix -m

4.4 Recovering
--------------

最糟糕的情况发生了，您丢失了一个或多个磁盘！

**不要惊慌！** 您将能够恢复它们！

您必须做的第一件事是避免对磁盘阵列进行进一步的更改。
禁用对其的任何远程连接以及任何计划的进程，包括任何计划的 SnapRAID
夜间同步或 scrub。

然后继续执行以下步骤。

---- 4.4.1 STEP 1 -> 重新配置 ----
您需要一些空间来恢复，理想情况下是在额外的备用磁盘上，
但外部 USB 磁盘或远程磁盘也足够。

修改 SnapRAID 配置文件，使故障磁盘的 `data` 或 `parity` 选项指向
一个具有足够空闲空间来恢复文件的位置。

例如，如果磁盘 `d1` 发生故障，则从：

    data d1 /mnt/disk1/

更改为：

    data d1 /mnt/new_spare_disk/

如果需要恢复的磁盘是奇偶校验磁盘，请更新相应的 `parity` 选项。
如果您有多个故障磁盘，请更新所有它们的配置选项。

---- 4.4.2 STEP 2 -> 修复 ----
运行 fix 命令，并将日志存储在外部文件中：

    snapraid -d NAME -l fix.log fix

其中 NAME 是磁盘的名称，例如我们前面例子中的 `d1`。
如果需要恢复的磁盘是奇偶校验磁盘，请使用名称 `parity`、`2-parity` 等。
如果您有多个故障磁盘，请使用多个 -d 选项来指定所有它们。

此命令将花费很长时间。

确保您有几 GB 的可用空间来存储 fix.log 文件。
在有足够可用空间的磁盘上运行它。

现在您已经恢复了所有可恢复的内容。如果有些文件部分或完全不可恢复，
它们将被重命名并添加 `.unrecoverable` 扩展名。

您可以通过检查所有以 `unrecoverable:` 开头的行，在 fix.log 文件中
找到所有不可恢复块的详细列表。

如果您对恢复不满意，您可以根据需要重试多次。

例如，如果您在上次 `sync` 之后从阵列中删除了文件，
这可能导致某些文件无法恢复。
在这种情况下，您可以使用 -i, --import 选项重试 `fix`，
指定这些文件现在在哪里，以便将它们再次包含在恢复过程中。

如果您对恢复感到满意，您可以继续进行，
但请注意，在同步之后，您不能再重试 `fix` 命令了！

---- 4.4.3 STEP 3 -> 检查 ----
作为一项谨慎的检查，您现在可以运行 `check` 命令，以确保
恢复的磁盘上的一切都是正确的。

    snapraid -d NAME -a check

其中 NAME 是磁盘的名称，例如我们前面例子中的 `d1`。

    -d 和 -a 选项告诉 SnapRAID 只检查指定的磁盘并忽略所有奇偶校验数据。

此命令将花费很长时间，但如果您不是过于谨慎，可以跳过它。

---- 4.4.4 STEP 4 -> 同步 ----
运行 `sync` 命令以将阵列与新磁盘重新同步。

    snapraid sync

如果所有内容都已恢复，此命令是即时的。


5 COMMANDS
==========

SnapRAID 提供了一些简单的命令，允许您：

* 打印阵列的状态 -> `status`
* 控制磁盘 -> `smart`、`probe`、`up`、`down`
* 进行备份/快照 -> `sync`
* 定期检查数据 -> `scrub`
* 恢复上次备份/快照 -> `fix`。

命令必须用小写字母书写。

5.1 status
----------

打印磁盘阵列状态的摘要。

它包括有关奇偶校验碎片、块未经检查有多久，以及在 scrubbing
期间遇到的所有记录的静默错误的信息。

所提供的信息指的是您上次运行 `sync` 的时间。
不考虑后来的修改。

如果检测到坏块，则会列出它们的块号。
要修复它们，您可以使用 `fix -e` 命令。

它还会显示一个图表，表示每个块上次被 scrub 或 sync 的时间。
被 scrub 的块显示为 `*`，已同步但尚未 scrub 的块显示为 `o`。

不会修改任何内容。

5.2 smart
---------

打印系统中所有磁盘的 SMART 报告。

它包括对明年故障概率的估计，允许您计划更换显示
可疑属性的磁盘进行维护。

此概率估计是通过将磁盘的 SMART 属性与
Backblaze 提供的以下数据进行关联获得的：

    https://www.backblaze.com/hard-drive-test-data.html

如果 SMART 报告磁盘正在发生故障，则会为该磁盘打印 `FAIL` 或 `PREFAIL`，
并且 SnapRAID 返回错误。
在这种情况下，**强烈建议**立即更换磁盘。

其他可能的状态字符串有：
    logfail - 过去，某些属性低于阈值。
    logerr - 设备错误日志包含错误。
    selferr - 设备自检日志包含错误。

如果指定了 -v, --verbose 选项，则会提供更深入的统计分析。
此分析可以帮助您决定是否需要更多或更少的奇偶校验。

此命令使用 `smartctl` 工具，相当于在所有设备上运行 `smartctl -a`。

如果您的设备未正确自动检测，您可以使用配置
文件中的 `smartctl` 选项指定自定义命令。

不会修改任何内容。

5.3 probe
---------

打印系统中所有磁盘的**电源**状态。

`Standby`（待机）表示磁盘未转动。`Active`（活动）表示
磁盘正在转动。

此命令使用 `smartctl` 工具，相当于在所有设备上运行
`smartctl -n standby -i`。

如果您的设备未正确自动检测，您可以使用配置
文件中的 `smartctl` 选项指定自定义命令。

不会修改任何内容。

5.4 up
------

使阵列中的所有磁盘转动起来。

您可以使用 -d, --filter-disk 选项只启动特定的磁盘。

同时启动所有磁盘需要大量的电力。
确保您的电源能够承受。

不会修改任何内容。

5.5 down
--------

使阵列中的所有磁盘停转。

此命令使用 `smartctl` 工具，相当于在所有设备上运行
`smartctl -s standby,now`。

您可以使用 -d, --filter-disk 选项只停转特定的磁盘。

要在发生错误时自动停转，您可以将 -s, --spin-down-on-error
选项与任何其他命令一起使用，这相当于在发生错误时手动运行 `down`。

不会修改任何内容。

5.6 diff
--------

列出自上次 `sync` 以来所有已修改、需要重新计算奇偶校验数据的
文件。

此命令不检查文件数据，仅检查文件时间戳、大小和 inode。

列出所有更改的文件后，会显示更改的摘要，按以下方式分组：
    equal - 文件与之前相比未更改。
    added - 之前不存在、已添加的文件。
    removed - 已删除的文件。
    updated - 大小或时间戳不同的文件，表示它们已被修改。
    moved - 在同一磁盘上移动到不同目录的文件。
        它们通过具有相同的名称、大小、时间戳和 inode，但目录不同来识别。
    copied - 在相同或不同磁盘上复制的文件，且原始文件仍然存在。
        它们通过具有相同的名称、大小和时间戳进行识别。
        如果亚秒级时间戳为零，则必须完整路径匹配才能识别，而不仅仅是名
        称。
    relocated - 在相同或不同磁盘上移动的文件，且原始文件已消失。
        它们通过具有相同的名称、大小和时间戳进行识别。
        如果亚秒级时间戳为零，则必须完整路径匹配才能识别。
        与同一磁盘上的 'moved' 文件不同，重定位的文件具有不同的 inode。
    restored - inode 不同但目录、名称、大小和时间戳匹配的文件。
        这些通常是删除后恢复的文件。

如果需要 `sync`，进程返回码为 2，而不是默认的 0。
返回码 1 用于一般错误情况。

不会修改任何内容。

5.7 sync
--------

更新奇偶校验信息。读取磁盘阵列中所有已修改的文件，
并更新相应的奇偶校验数据。

您可以随时按 Ctrl+C 停止此过程，而不会丢失已完成的工作。
在下次运行时，`sync` 过程将从中断的地方恢复。

如果在过程中发现静默错误或输入/输出错误，
相应的块会被标记为坏块。

文件通过路径和/或 inode 识别，并检查大小和时间戳。
如果文件大小或时间戳不同，则会为整个文件重新计算奇偶校验数据。
如果文件在同一磁盘上被移动或重命名，保持相同的 inode，则不重新计算奇偶校验。
如果文件移动到另一个磁盘，则重新计算奇偶校验，
但保留以前计算的散列信息。

如果需要，会修改 `content` 和 `parity` 文件。
阵列中的文件**不会**被修改。

5.8 scrub
---------

Scrub 阵列，检查数据和奇偶校验磁盘中的静默或输入/输出错误。

每次调用检查大约 8% 的阵列，排除在过去 10 天内
已被 scrub 的数据。
这意味着每周 scrub 一次可确保每隔三个月至少检查一次数据的每一位。

您可以使用 -p, --plan 选项定义不同的 scrub 计划或数量，
该选项接受：
bad - Scrub 标记为坏块的块。
new - Scrub 刚刚同步但尚未 scrub 的块。
full - Scrub 所有内容。
0-100 - Scrub 指定百分比的块。

如果指定了百分比数量，您还可以使用 -o, --older-than
选项来定义块应该有多旧。
最旧的块首先被 scrub，确保最佳检查。
如果您只想 scrub 刚刚同步但尚未 scrub 的块，
请使用 `-p new` 选项。

要获取 scrub 状态的详细信息，请使用 `status` 命令。

对于发现的任何静默错误或输入/输出错误，相应的块
会在 `content` 文件中被标记为坏块。
这些坏块列在 `status` 中，可以使用 `fix -e` 修复。
修复后，在下次 scrub 时，它们将被重新检查，如果发现已更正，
则会删除坏块标记。
要仅 scrub 坏块，您可以使用 `scrub -p bad` 命令。

建议仅在已同步的阵列上运行 `scrub`，以避免
由未同步数据引起的报告错误。这些错误被识别为不是静默错误，
并且块不会被标记为坏块，但此类错误会在命令的输出中报告。

`content` 文件会被修改以更新每个块上次检查的时间
并标记坏块。
`parity` 文件**不会**被修改。
阵列中的文件**不会**被修改。

5.9 fix
-------

修复所有文件和奇偶校验数据。

所有文件和奇偶校验数据都与上次 `sync` 中保存的快照
状态进行比较。
如果发现差异，则将其恢复到存储的快照。

**警告！** `fix` 命令不区分错误和
故意修改。它**无条件地**将文件状态恢复到上次 `sync`。

如果未指定其他选项，则处理整个阵列。
使用过滤选项选择要操作的文件或磁盘的子集。

要仅修复在 `sync` 和 `scrub` 期间标记为坏块的块，
请使用 -e, --filter-error 选项。
与其他过滤选项不同，此选项仅对自上次 `sync` 以来未更改的
文件应用修复。

SnapRAID 会重命名所有无法修复的文件，并添加
`.unrecoverable` 扩展名。

在修复之前，会扫描整个阵列以查找自上次 `sync`
操作以来移动的任何文件。
这些文件通过它们的时间戳识别，忽略它们的名称
和目录，并在必要时用于恢复过程。
如果您将其中一些移到了阵列之外，您可以使用 -i, --import
选项指定额外的目录进行扫描。

文件仅通过路径识别，而不通过 inode 识别。

`content` 文件**不会**被修改。
如果需要，`parity` 文件会被修改。
如果需要，阵列中的文件会被修改。

5.10 check
----------

验证所有文件和奇偶校验数据。

它的工作方式类似于 `fix`，但它只模拟恢复，**不会**对阵列
写入任何更改。

此命令主要用于手动验证，
例如在恢复过程之后或在其他特殊条件下。
对于定期和计划的检查，请使用 `scrub`。

如果您使用 -a, --audit-only 选项，则仅检查文件
数据散列，而忽略奇偶校验数据，以加快运行速度。

文件仅通过路径识别，而不通过 inode 识别。

不会修改任何内容。

5.11 list
---------

列出上次 `sync` 时阵列中包含的所有文件。

使用 -v 或 --verbose，还会显示亚秒级时间。

不会修改任何内容。

5.12 dup
--------

列出所有重复文件。如果两个文件的散列匹配，则认为它们相等。
不读取文件数据；仅使用预先计算的散列。

不会修改任何内容。

5.13 pool
---------

在 `pooling` 目录中创建或更新磁盘阵列中所有文件
的虚拟视图。

文件不会被复制，而是使用符号链接连接。

更新时，所有现有的符号链接和空
子目录都会被删除，并替换为阵列的新视图。
任何其他常规文件保留在原位。

不会修改 pool 目录之外的任何内容。

5.14 devices
------------

打印阵列使用的低级设备。

此命令显示阵列中的设备关联，主要用作脚本接口。

前两列是低级设备 ID 和路径。
接下来的两列是高级设备 ID 和路径。
最后一列是阵列中的磁盘名称。

在大多数情况下，阵列中的每个磁盘都有一个低级设备，
但在一些更复杂的配置中，单个阵列磁盘可能会使用多个
低级设备。

不会修改任何内容。

5.15 touch
----------

为所有亚秒级时间戳设置为零的文件设置一个任意的
亚秒级时间戳。

这提高了 SnapRAID 识别移动和复制文件的能力，
因为它使时间戳几乎独一无二，减少了可能的重复。

更具体地说，如果亚秒级时间戳不为零，
则移动或复制的文件在名称、大小和时间戳匹配时被识别为
此类。如果亚秒级时间戳为零，则仅当完整路径、
大小和时间戳都匹配时才被视为副本。

不会修改秒精度时间戳，
因此会保留文件的所有日期和时间。

5.16 rehash
-----------

安排对整个阵列进行重新散列。

此命令更改使用的散列类型，通常是在从 32 位系统升级到 64 位系统时，
以从 MurmurHash3 切换到更快的 SpookyHash。

如果您已经在使用最佳散列，则此命令不执行任何操作，
并通知您无需执行任何操作。

重新散列不会立即执行，而是在 `sync` 和 `scrub` 期间
逐步进行。

您可以使用 `status` 检查重新散列状态。

在重新散列期间，SnapRAID 保持完全功能，
唯一的例外是 `dup` 无法使用不同的散列检测重复的文件。

5.17 locate
-----------

查找存储在校验盘中的文件。对于每个匹配的文件，它会打印其在校验文件中的位置
以及占用的分片数量。

您可以使用 -t, --tail 选项将操作限制在占用校验盘指定尾部部分的
文件上。

如果您想重新分配这些文件，可以使用 -W, --force-realloc-tail 选项。
请注意，在重新分配过程中，此类文件将不受校验保护。


6 OPTIONS
=========

SnapRAID 提供以下选项：

    -c, --conf CONFIG
        选择要使用的配置文件。如果未指定，在 Unix 中，
        如果存在，则使用文件 `/usr/local/etc/snapraid.conf`，
        否则使用 `/etc/snapraid.conf`。
        在 Windows 中，它使用与 `snapraid.exe` 相同的目录中的文件 `snapraid.conf`。

    -f, --filter PATTERN
        过滤要在 `check` 和 `fix` 中处理的文件。
        仅处理与指定模式匹配的文件。
        此选项可以多次使用。
        有关模式规范的更多详细信息，请参阅 PATTERN 部分。
        在 Unix 中，如果使用 globbing 字符，请确保它们被引用。
        此选项只能与 `check` 和 `fix` 一起使用。
        不能与 `sync` 和 `scrub` 一起使用，因为它们总是处理整个阵列。

    -d, --filter-disk NAME
        过滤要在 `check`、`fix`、`up` 和 `down` 中处理的磁盘。
        您必须指定配置文件中定义的磁盘名称。
        您也可以指定奇偶校验磁盘的名称：`parity`、`2-parity`、
        `3-parity` 等，以将操作限制到特定的奇偶校验磁盘。
        如果您组合使用多个 --filter、--filter-disk 和 --filter-missing 选项，
        则仅选择与所有过滤器匹配的文件。
        此选项可以多次使用。
        此选项只能与 `check`、`fix`、`up` 和 `down` 一起使用。
        不能与 `sync` 和 `scrub` 一起使用，因为它们总是处理整个阵列。

    -m, --filter-missing
        过滤要在 `check` 和 `fix` 中处理的文件。
        仅处理阵列中丢失或已删除的文件。
        与 `fix` 一起使用时，此选项充当 `undelete` 命令。
        如果您组合使用多个 --filter、--filter-disk 和 --filter-missing 选项，
        则仅选择与所有过滤器匹配的文件。
        此选项只能与 `check` 和 `fix` 一起使用。
        不能与 `sync` 和 `scrub` 一起使用，因为它们总是处理整个阵列。

    -e, --filter-error
        处理 `check` 和 `fix` 中有错误的文件。
        它仅处理在 `sync` 和 `scrub` 期间块被标记为静默或输入/输出错误的
        文件，如 `status` 中所列。
        此选项只能与 `check` 和 `fix` 一起使用。

    -p, --plan PERC|bad|new|full
        选择 scrub 计划。如果 PERC 是一个介于 0 到 100 之间的数值，
        则将其解释为要 scrub 的块的百分比。
        除了百分比，您还可以指定一个计划：
        `bad` scrub 坏块，`new` scrub 尚未 scrub 的块，
        `full` scrub 所有内容。
        此选项只能与 `scrub` 一起使用。

    -o, --older-than DAYS
        选择要在 `scrub` 中处理的阵列的最旧部分。
        DAYS 是块被 scrub 的最小天数；默认值为 10。
        无论此选项如何，标记为坏块的块始终会被 scrub。
        此选项只能与 `scrub` 一起使用。

    -a, --audit-only
        在 `check` 中，验证文件的散列而不
        检查奇偶校验数据。
        如果您只对检查文件数据感兴趣，此选项可以显著加快
        检查过程。
        此选项只能与 `check` 一起使用。

    -h, --pre-hash
        在 `sync` 中，运行所有新数据的初步散列阶段，
        以便在奇偶校验计算之前进行额外验证。
        通常，在 `sync` 中，不进行初步散列，并且新
        数据仅在首次读取进行奇偶校验计算之前散列。
        此过程在系统处于
        重负载下发生，所有磁盘都在转动，CPU 也很忙。
        这对机器来说是一种极端情况，如果它有潜在的硬件问题，
        静默错误可能无法被检测到，因为数据尚未散列。
        为避免此风险，您可以启用 `pre-hash` 模式，将
        所有数据读取两次以确保其完整性。
        此选项还会验证阵列内移动的文件，
        以确保移动操作成功，并在必要时
        允许您在继续之前运行 fix 操作。
        此选项只能与 `sync` 一起使用。

    -i, --import DIR
        从指定目录导入自上次 `sync` 以来从阵列中删除的任何文件。
        如果您仍然拥有此类文件，它们可用于 `check`
        和 `fix` 以改进恢复过程。
        读取文件，包括在子目录中，并且无论其名称如何都会被识别。
        此选项只能与 `check` 和 `fix` 一起使用。

    -s, --spin-down-on-error
        在任何错误发生时，在退出并带有非零状态码之前，
        将所有托管的磁盘停转。这可以防止驱动器在中止操作后
        保持活动和转动，有助于避免不必要的热量积聚和功耗。
        使用此选项可确保即使命令失败，磁盘也能安全停止。

    -w, --bw-limit RATE
        对所有磁盘应用全局带宽限制。RATE 是
        每秒的字节数。您可以指定乘数，例如 K、M 或 G
        （例如，--bw-limit 1G）。

    -t, --tail 大小
        将文件列表限制为那些使用校验盘指定尾部大小以内的文件。
        您可以使用乘数，如 K、M、G 或 T（例如 --tail 1G）。
        此选项仅在与 `locate` 命令配合使用时有效。

    -A, --stats
        启用扩展状态视图，显示附加信息。
        屏幕显示两个图表：
        第一个图表显示每个磁盘的缓冲条带数，以及
        当前正在该磁盘上访问的文件的文件路径。
        通常，最慢的磁盘将没有可用缓冲区，
        这决定了可达到的最大带宽。
        第二个图表显示在过去 100 秒内等待所花费的时间百分比。
        预计最慢的磁盘会导致大部分等待时间，
        而其他磁盘应该只有很少或没有等待时间，
        因为它们可以使用缓冲条带。
        此图表还显示了等待散列计算和 RAID
        计算所花费的时间。
        所有计算都与磁盘操作并行运行。
        因此，只要至少一个磁盘有可测量的等待时间，
        就表明 CPU 足够快，能够跟上工作负载。

    -Z, --force-zero
        强制执行不安全的同步操作：同步大小为零但以前非零的文件。
        如果 SnapRAID 检测到这种情况，它会停止进行，
        除非您指定此选项。
        这使您可以轻松检测到在系统崩溃后，
        某些访问的文件被截断的情况。
        这在带有 ext3/ext4 文件系统的 Linux 中是一种可能的情况。
        此选项只能与 `sync` 一起使用。

    -E, --force-empty
        强制执行不安全的同步操作：同步所有原始文件丢失的磁盘。
        如果 SnapRAID 检测到磁盘上最初存在的所有文件都丢失或被重写，
        它会停止进行，除非您指定此选项。
        这使您可以轻松检测到数据文件系统未挂载的情况。
        此选项只能与 `sync` 一起使用。

    -U, --force-uuid
        强制执行不安全的同步、检查和修复操作，当磁盘更改了它们的 UUID 时。
        如果 SnapRAID 检测到某些磁盘更改了 UUID，
        它会停止进行，除非您指定此选项。
        这使您可以检测到您的磁盘被挂载在
        错误的挂载点的情况。
        但是，允许在单奇偶校验下进行单个 UUID 更改，
        在多奇偶校验下进行更多更改，因为这是恢复后更换磁盘时的正常情况。
        此选项只能与 `sync`、`check` 或 `fix` 一起使用。

    -D, --force-device
        强制执行不安全的修复操作，当磁盘无法访问或位于同一物理设备上时。
        例如，如果您丢失了两个数据磁盘，并且有一个备用磁盘
        只能恢复第一个，您可以忽略第二个无法访问的磁盘。
        或者，如果您想在已使用的磁盘上剩余的可用空间中恢复一个磁盘，
        共享同一物理设备。
        此选项只能与 `fix` 一起使用。

    -N, --force-nocopy
        在 `sync`、`check` 和 `fix` 中，禁用复制检测启发式。
        如果没有此选项，SnapRAID 假定具有相同属性（例如名称、大小和时间戳）
        的文件是具有相同数据的副本。
        这允许识别从一个磁盘移动到另一个磁盘的复制或移动的文件，
        并重用已计算的散列信息以检测静默错误或恢复丢失的文件。
        在某些罕见的情况下，此行为可能导致误报
        或由于许多散列验证而导致过程缓慢，此选项允许您解决此类问题。
        此选项只能与 `sync`、`check` 和 `fix` 一起使用。

    -F, --force-full
        在 `sync` 中，强制完全重新计算奇偶校验。
        当您添加新的奇偶校验级别或如果使用较新的奇偶校验数据恢复到旧的内容文件时，
        可以使用此选项。
        这允许您重用内容文件中存在的散列来验证数据，
        并使用现有奇偶校验数据在 `sync` 过程中保持数据保护，
        而不是从头开始重新创建奇偶校验。
        此选项只能与 `sync` 一起使用。

    -R, --force-realloc
        在 `sync` 中，强制完全重新分配文件并重建奇偶校验。
        此选项可用于完全重新分配所有文件，
        消除碎片，同时重用内容文件中存在的散列来验证数据。
        此选项只能与 `sync` 一起使用。
        **警告！** 此选项仅供专家使用，强烈建议不要使用它。
        在 `sync` 操作期间，您**没有**数据保护。

    -W, --force-realloc-tail 大小
        工作方式类似于 -R, --force-realloc，但仅限于每个校验文件的
        指定尾部部分（最后“大小”字节）。
        它会强制重新分配（移动）当前存储在该尾部部分的任何文件分片/块，
        允许它们被放置在校验文件中任何有可用空间的地方（包括现有的
        空隙）。
        此选项的主要目的是缩小校验文件的磁盘占用大小。
        如果重新分配成功清空了整个尾部区域（没有块继续使用它），
        则校验文件将被截断，回收未使用的尾部空间。
        您可以使用乘数，如 K、M、G 或 T（例如
        --force-realloc-tail 1G）。
        您可以使用 locate -t, --tail 提前了解受影响的文件。
        警告！
        此选项仅供专家使用，强烈建议不要使用。
        在执行 `sync` 操作期间，受影响的文件将没有数据保护。

    -l, --log FILE
        将详细日志写入指定文件。
        如果未指定此选项，则会将意外错误打印到屏幕，
        在出现许多错误的情况下，可能导致输出过多。
        指定 -l, --log 时，仅将导致 SnapRAID 停止的**致命错误**打印到
        屏幕。
        如果路径以 `>>` 开头，则文件以追加模式打开。
        名称中的 `%D` 和 `%T` 出现会被替换为日期和时间，格式分别为 YYYYMMDD 和
        HHMMSS。在 Windows 批处理文件中，您必须双写 `%` 字符，
        例如 result-%%D.log。要使用 `>>`，您必须将名称括在引号中，
        例如 `">>result.log"`。
        要将日志输出到标准输出或标准错误，
        您可以使用 `">&1"` 和 `">&2"`。
        有关日志标签描述，请参阅 snapraid_log.txt 文件或 man 页面。

    -L, --error-limit NUMBER
        设置停止执行前的新错误限制。
        默认情况下，如果 SnapRAID 遇到超过 100 个
        输入/输出错误，它会停止，表明磁盘可能正在发生故障。
        此选项影响 `sync` 和 `scrub`，它们被允许在第一组
        磁盘错误后继续，以尝试完成其操作。
        但是，`check` 和 `fix` 总是会在第一次错误时停止。

    -S, --start BLKSTART
        从指定的块号开始处理。
        在磁盘损坏的情况下，这对于重试检查或修复特定块可能很有用。
        此选项主要用于高级手动恢复。

    -B, --count BLKCOUNT
        仅处理指定数量的块。
        此选项主要用于高级手动恢复。

    -C, --gen-conf CONTENT
        从现有内容文件生成一个虚拟配置文件。
        配置文件写入标准输出，不会覆盖现有文件。
        此配置文件还包含在您丢失整个系统的情况下
        重建磁盘挂载点所需的信息。

    -v, --verbose
        向屏幕打印更多信息。
        如果指定一次，它会打印排除的文件
        和附加统计信息。
        此选项对日志文件没有影响。

    -q, --quiet
        向屏幕打印更少信息。
        如果指定一次，它会删除进度条；两次，
        正在运行的操作；三次，信息
        消息；四次，状态消息。
        致命错误始终会打印到屏幕。
        此选项对日志文件没有影响。

    -H, --help
        打印简短的帮助屏幕。

    -V, --version
        打印程序版本。


7 CONFIGURATION
===============

SnapRAID 需要一个配置文件来了解您的磁盘阵列
位于何处以及在哪里存储奇偶校验信息。

在 Unix 中，如果存在，它使用文件 `/usr/local/etc/snapraid.conf`，
否则使用 `/etc/snapraid.conf`。
在 Windows 中，它使用与 `snapraid.exe` 相同的目录中的文件 `snapraid.conf`。

它必须包含以下选项（区分大小写）：

7.1 parity FILE [,FILE] ...
---------------------------

定义用于存储奇偶校验信息的文件。
奇偶校验可实现针对单个磁盘
故障的保护，类似于 RAID5。

您可以指定多个文件，它们必须位于不同的磁盘上。
当一个文件不能再增长时，使用下一个文件。
总可用空间必须至少与阵列中最大的数据磁盘一样大。

您可以稍后添加额外的奇偶校验文件，但是您
不能重新排序或删除它们。

将奇偶校验磁盘保留用于奇偶校验可确保它们不会碎片化，从而提高性能。

在 Windows 中，每个磁盘会留下 256 MB 未使用空间，以避免
有关磁盘已满的警告。

此选项是强制性的，并且只能使用一次。

7.2 (2,3,4,5,6)-parity FILE [,FILE] ...
---------------------------------------

定义用于存储额外奇偶校验信息的文件。

为指定的每个奇偶校验级别启用一个额外的保护级别：

* 2-parity 启用 RAID6 双奇偶校验。
* 3-parity 启用三奇偶校验。
* 4-parity 启用四奇偶校验。
* 5-parity 启用五奇偶校验。
* 6-parity 启用六奇偶校验。

每个奇偶校验级别都需要存在所有先前的奇偶校验级别。

与 `parity` 选项相同的注意事项适用。

这些选项是可选的，并且只能使用一次。

7.3 z-parity FILE [,FILE] ...
-----------------------------

定义用于存储三奇偶校验的备用文件和格式。

此选项是 `3-parity` 的替代方案，主要面向不支持
SSSE3 指令集的低端 CPU，如 ARM 或 AMD Phenom、Athlon 和 Opteron。
在这种情况下，它提供了更好的性能。

此格式类似于 ZFS RAIDZ3 使用的格式，但更快。
与 ZFS 一样，它在三奇偶校验之外不起作用。

当使用 `3-parity` 时，如果建议使用 `z-parity` 格式以提高性能，
您将收到警告。

可以通过调整配置文件中的所需 z-parity 或 3-parity 文件，
并使用 `fix` 重新创建它，从一种格式转换为另一种格式。

7.4 content FILE
----------------

定义用于存储磁盘阵列中所有文件的列表和校验和的文件。

它可以放置在用于数据、奇偶校验或
任何其他可用磁盘上。
如果您使用数据磁盘，此文件会自动从 `sync` 过程中排除。

此选项是强制性的，并且可以多次使用以保存
同一文件的多个副本。

您必须为使用的每个奇偶校验磁盘存储至少一个副本，
再加上一个。使用额外的副本不会有害。

7.5 data NAME DIR
-----------------

定义阵列中数据磁盘的名称和挂载点。
NAME 用于标识磁盘，并且必须是唯一的。
DIR 是磁盘在文件系统中的挂载点。

您可以根据需要更改挂载点，只要保持 NAME 固定即可。

您应该为阵列中的每个数据磁盘使用一个选项。

您可以通过直接在配置文件中更改 NAME，然后运行 `sync` 命令来
稍后重命名磁盘。
在重命名的情况下，关联是使用存储的磁盘 UUID 完成的。

7.6 extra NAME DIR
------------------

定义要通过 `smart` 和 `probe` 命令监控的额外磁盘的名称和挂载点。

这对于监控不属于阵列但系统运行所必需的磁盘（例如启动盘）非常有用。

请注意，此类磁盘不受 `up` 和 `down` 命令的影响，因为它们被预期始终处于
旋转状态。

7.7 nohidden
------------

排除所有隐藏文件和目录。
在 Unix 中，隐藏文件是以 `.` 开头的文件。
在 Windows 中，它们是具有隐藏属性的文件。

7.8 exclude/include PATTERN
---------------------------

定义要从同步过程中排除或包含的文件或目录模式。
所有模式都按指定的顺序处理。

如果匹配的第一个模式是 `exclude` 模式，则排除该文件。
如果它是 `include` 模式，则包含该文件。
如果没有模式匹配，则如果指定的最后一个模式是 `include`，则排除该文件，
或者如果指定的最后一个模式是 `exclude`，则包含该文件。

有关模式规范的更多详细信息，请参阅 PATTERN 部分。

此选项可以多次使用。

7.9 blocksize SIZE_IN_KIBIBYTES
-------------------------------

定义奇偶校验的基本块大小（以 KiB 为单位）。
一 KiB 是 1024 字节。

默认的 blocksize 是 256，这应该适用于大多数情况。

**警告！** 此选项仅供专家使用，强烈建议不要更改此值。
将来要更改此值，您将需要重新创建整个奇偶校验！

使用不同 blocksize 的一个原因是，如果您有许多小型文件，
数量级为数百万。

对于每个文件，即使只有几个字节，也会分配一个完整的奇偶校验块，
并且对于许多文件，这可能导致大量的未使用奇偶校验空间。
当您完全填满奇偶校验磁盘时，不允许向数据磁盘
添加更多文件。
但是，浪费的奇偶校验不会跨数据磁盘累积。
数据磁盘上大量文件导致的浪费空间仅限制该数据磁盘上的数据量，
而不限制其他磁盘上的数据量。

作为一个近似值，您可以假设每个文件浪费了半个块大小的空间。
例如，对于 100,000 个文件和 256 KiB 的块大小，您将浪费 12.8 GB 的奇偶校验空间，
这可能导致数据磁盘上少 12.8 GB 的可用空间。

您可以使用 `status` 检查每个磁盘上浪费的空间量。
这是您必须在数据磁盘上留出的空闲空间量，
或用于不包含在阵列中的文件的空间量。
如果此值为负，则表示您即将填满奇偶校验空间，
它表示您仍然可以浪费的空间。

为避免此问题，您可以为奇偶校验使用更大的分区。
例如，如果奇偶校验分区比数据磁盘大 12.8 GB，
则您有足够的额外空间来处理每个数据磁盘上多达 100,000 个
文件而不会浪费任何空间。

在 Linux 中获得更大的奇偶校验分区的一个技巧是使用以下命令格式化它：

    mkfs.ext4 -m 0 -T largefile4 DEVICE

这会导致大约 1.5% 的额外空间，对于 4 TB 磁盘约为 60 GB，
这允许每个数据磁盘上大约 460,000 个文件而不会浪费任何空间。

7.10 hashsize SIZE_IN_BYTES
---------------------------

定义保存块的散列大小（以字节为单位）。

默认的 hashsize 是 16 字节（128 位），这应该适用于大多数情况。

**警告！** 此选项仅供专家使用，强烈建议不要更改此值。
将来要更改此值，您将需要重新创建整个奇偶校验！

使用不同 hashsize 的一个原因是，如果您的系统内存有限。
根据经验，SnapRAID 通常每 16 TB 的阵列数据需要 1 GiB 的 RAM。

具体来说，为了存储数据的散列，SnapRAID 大约需要
$TS*(1+HS)/BS$ 字节的 RAM，
其中 $TS$ 是您的磁盘阵列的总大小（以字节为单位），$BS$ 是块大小（以字节为单位），
$HS$ 是散列大小（以字节为单位）。

例如，对于 8 个 4 TB 磁盘，块大小为 256 KiB
（1 KiB = 1024 字节），散列大小为 16，您将获得：

RAM = $(8 * 4 * 10^{12}) * (1+16) / (256 * 2^{10}) = 1.93$ GiB

切换到散列大小为 8，您将获得：

RAM = $(8 * 4 * 10^{12}) * (1+8) / (256 * 2^{10}) = 1.02$ GiB

切换到块大小为 512，您将获得：

RAM = $(8 * 4 * 10^{12}) * (1+16) / (512 * 2^{10}) = 0.96$ GiB

切换到散列大小为 8 和块大小为 512，您将获得：

RAM = $(8 * 4 * 10^{12}) * (1+8) / (512 * 2^{10}) = 0.51$ GiB

7.11 autosave SIZE_IN_GIGABYTES
-------------------------------

在同步或 scrub 之后，处理指定数量的 GB 后，自动保存状态。
此选项有助于避免在机器崩溃或任何其他事件中断时，
从头开始重新启动长时间的 `sync` 命令。

7.12 temp_limit TEMPERATURE_CELSIUS
-----------------------------------

设置允许的最高磁盘温度（摄氏度）。指定后，
SnapRAID 会使用 smartctl 工具定期检查所有磁盘的温度。
SnapRAID 运行时会显示当前磁盘温度。
如果任何磁盘超过此限制，所有操作都会停止，
并在 `temp_sleep` 选项定义的持续时间内将磁盘停转（置于待机状态）。
在休眠期过后，操作恢复，如果温度限制再次达到，
可能会再次暂停。

在操作期间，SnapRAID 还会分析每个磁盘的加热曲线，
并估计如果活动继续，它们预计将达到的长期稳定温度。
仅在磁盘温度增加了四次后才执行估计，
以确保有足够的数据点来建立可靠的趋势。
此预测的稳定温度显示在当前值旁边的括号中，
有助于评估系统的冷却是否足够。
此估计温度仅供参考，对 SnapRAID 的行为没有影响。
程序的动作仅基于实际测量的磁盘温度。

要执行此分析，SnapRAID 需要一个系统温度的参考。
它首先尝试从可用的硬件传感器读取。
如果无法访问系统传感器，它会使用运行时测量的最低磁盘温度
作为备用参考。

通常，SnapRAID 只显示最热磁盘的温度。
要显示所有磁盘的温度，请使用 -A 或 --stats 选项。

7.13 temp_sleep TIME_IN_MINUTES
-------------------------------

设置达到温度限制时的待机时间（以分钟为单位）。
在此期间，磁盘保持停转状态。默认值为 5 分钟。

7.14 pool DIR
-------------

定义 `pooling` 目录，其中使用 `pool` 命令创建磁盘
阵列的虚拟视图。

目录必须已经存在。

7.15 share UNC_DIR
------------------

定义远程访问磁盘所需的 Windows UNC 路径。

如果指定了此选项，则在 pool 目录中创建的符号链接会使用此 UNC 路径
来访问磁盘。
如果没有此选项，则生成的符号链接仅使用本地路径，
这不允许通过网络共享 pool 目录。

符号链接是使用指定的 UNC 路径，添加在 `data` 选项中指定的
磁盘名称，最后添加文件目录和名称形成的。

此选项仅在 Windows 中需要。

7.16 smartctl DISK/PARITY OPTIONS...
------------------------------------

定义自定义 smartctl 选项以获取每个磁盘的 SMART 属性。
这对于 RAID 控制器和一些无法自动检测的 USB
磁盘可能需要。%s 占位符会被设备名称替换，
但对于固定的设备（如 RAID 控制器）是可选的。

DISK 是在 `data` 选项中指定的相同磁盘名称。
PARITY 是奇偶校验名称之一：`parity`、`2-parity`、`3-parity`、
`4-parity`、`5-parity`、`6-parity` 或 `z-parity`。

在指定的 OPTIONS 中，字符串 `%s` 被设备名称替换。
对于 RAID 控制器，设备可能是固定的，
您可能不需要使用 `%s`。

请参阅 smartmontools 文档以了解可能的选项：

    https://www.smartmontools.org/wiki/Supported_RAID-Controllers
    https://www.smartmontools.org/wiki/Supported_USB-Devices

例如：

    smartctl parity -d sat %s

7.17 smartignore DISK/PARITY ATTR [ATTR...]
-------------------------------------------

在计算磁盘故障概率时忽略指定的 SMART 属性。
如果磁盘报告了特定属性的不寻常或误导值，此选项很有用。

DISK 是在 `data` 选项中指定的相同磁盘名称。
PARITY 是奇偶校验名称之一：`parity`、`2-parity`、`3-parity`、
`4-parity`、`5-parity`、`6-parity` 或 `z-parity`。
特殊值 * 可用于在所有磁盘上忽略该属性。

例如，要在所有磁盘上忽略 `Current Pending Sector Count` 属性：

    smartignore * 197

要仅在第一个奇偶校验磁盘上忽略它：

    smartignore parity 197

7.18 Examples
-------------

Unix 的典型配置示例如下：

    parity /mnt/diskp/snapraid.parity
    content /mnt/diskp/snapraid.content
    content /var/snapraid/snapraid.content
    data d1 /mnt/disk1/
    data d2 /mnt/disk2/
    data d3 /mnt/disk3/
    exclude /lost+found/
    exclude /tmp/
    smartctl d1 -d sat %s
    smartctl d2 -d usbjmicron %s
    smartctl parity -d areca,1/1 /dev/sg0
    smartctl 2-parity -d areca,2/1 /dev/sg0

Windows 的典型配置示例如下：

    parity E:\snapraid.parity
    content E:\snapraid.content
    content C:\snapraid\snapraid.content
    data d1 G:\array\
    data d2 H:\array\
    data d3 I:\array\
    exclude Thumbs.db
    exclude \$RECYCLE.BIN
    exclude \System Volume Information
    smartctl d1 -d sat %s
    smartctl d2 -d usbjmicron %s
    smartctl parity -d areca,1/1 /dev/arcmsr0
    smartctl 2-parity -d areca,2/1 /dev/arcmsr0


8 PATTERN
=========

模式提供了一种灵活的方法来过滤要包含或排除的文件。通过使用通配符（globbing），
您可以定义匹配特定文件名或整个目录结构的规则，而无需手动列出每个路径。

问号 `?` 匹配除目录分隔符以外的任何单个字符。这使得它在匹配具有变量字符
的文件名时非常有用，同时将模式限制在单个目录层级内。

单星号 `*` 匹配任何字符序列，但与问号一样，它绝不会跨越目录边界。
它在正斜杠处停止，因此适用于匹配单个路径组件内的内容。
这是 Shell 通配符中常见的标准行为。

双星号 `**` 功能更强大，它可以匹配任何字符序列，包括目录分隔符。
这允许模式匹配跨越多个目录层级。当 `**` 直接嵌入在模式中时，
它可以匹配零个或多个字符，包括周围文字文本之间的斜杠。

`**` 最重要的用法是特殊形式 `/**/`。它可以匹配零个或多个完整的目录层级，
从而可以在不知道确切路径结构的情况下，匹配目录树中任何深度的文件。
例如，模式 `src/**/main.js` 匹配 `src/main.js`（跳过零个目录）、
`src/ui/main.js`（跳过一个目录）以及 `src/ui/components/main.js`
（跳过两个目录）。

使用方括号 `[]` 的字符类匹配指定集合或范围内的单个字符。
与其他单字符模式一样，它们不匹配目录分隔符。字符类支持使用
感叹号进行范围指定和否定。

需要记住的根本区别是，`*`、`?` 和字符类都遵循目录边界，
并且仅在单个路径组件内匹配，而 `**` 是唯一可以跨越目录分隔符匹配的模式。

有四种不同类型的模式：

    FILE
        选择任何名为 FILE 的文件。
        此模式仅适用于文件，不适用于目录。

    DIR/
        选择任何名为 DIR 的目录及其内部的所有内容。
        此模式仅适用于目录，不适用于文件。

    /PATH/FILE
        选择指定的确切文件路径。此模式仅适用于文件，不适用于目录。

    /PATH/DIR/
        选择指定的确切目录路径及其内部的所有内容。此模式仅适用于目录，
        不适用于文件。

当您指定以 / 开头的绝对路径时，它应用于阵列**根目录**，
而不是本地文件系统根目录。

在 Windows 中，您可以使用反斜杠 \ 代替正斜杠 /。
Windows 系统目录、连接点、挂载点和其他 Windows
特殊目录被视为文件，这意味着要排除它们，
您必须使用文件规则，而不是目录规则。

如果文件名包含 `*`、`?`、`[`
或 `]` 字符，您必须对其进行转义，以避免将其解释为
globbing 字符。在 Unix 中，转义字符是 `\`；在 Windows 中，它是 `^`。
当模式在命令行上时，您必须双写转义
字符，以避免命令 shell 对其进行解释。

在配置文件中，您可以使用不同的策略来过滤要处理的文件。
最简单的方法是仅使用 `exclude` 规则来删除所有您不想处理的
文件和目录。例如：

    # 排除任何名为 `*.unrecoverable` 的文件
    exclude *.unrecoverable
    # 排除根目录 `/lost+found`
    exclude /lost+found/
    # 排除任何名为 `tmp` 的子目录
    exclude tmp/

相反的方法是仅定义您想要处理的文件，仅使用 `include` 规则。例如：

    # 仅包含一些目录
    include /movies/
    include /musics/
    include /pictures/

最后的方法是混合使用 `exclude` 和 `include` 规则。在这种情况下，
规则的顺序很重要。较早的规则优先于
较晚的规则。
为了简化，您可以先列出所有 `exclude` 规则，然后
列出所有 `include` 规则。例如：

    # 排除任何名为 `*.unrecoverable` 的文件
    exclude *.unrecoverable
    # 排除任何名为 `tmp` 的子目录
    exclude tmp/
    # 仅包含一些目录
    include /movies/
    include /musics/
    include /pictures/

在命令行上，使用 -f 选项，您只能使用 `include`
模式。例如：

    # 仅检查 .mp3 文件。
    # 在 Unix 中，使用引号以避免 shell 扩展 globbing。
    snapraid -f "*.mp3" check

在 Unix 中，在命令行上使用 globbing 字符时，必须
引用它们以防止 shell 扩展它们。


9 IGNORE FILE
=============

除了配置文件中的全局规则外，您还可以在阵列内的任何目录中放置
`.snapraidignore` 文件，以定义分散的排除规则。

在 `.snapraidignore` 中定义的规则会在配置文件中的规则之后应用。
这意味着它们具有更高的优先级，可用于排除先前由全局配置包含的文件。
实际上，如果本地规则匹配，则无论全局包含设置如何，该文件都会被排除。

`.snapraidignore` 中的模式逻辑与全局配置相同，但模式锚定在
该文件所在的目录：

    FILE
        选择此目录或其下方任何名为 FILE 的文件。
        这遵循与全局模式相同的通配符规则。

    DIR/
        选择任何名为 DIR 的目录及其内部的所有内容，
        位于此目录或其下方。

    /PATH/FILE
        选择相对于 `.snapraidignore` 文件位置指定的精确文件。

    /PATH/DIR/
        选择相对于 `.snapraidignore` 文件位置指定的精确目录
        及其内部的所有内容。

与全局配置不同，`.snapraidignore` 文件仅支持排除规则；
您不能使用 `include` 模式或否定符号 (!)。

例如，如果您在 `/mnt/disk1/projects/` 中有一个 `.snapraidignore`：

    # 仅排除 /mnt/disk1/projects/output.bin
    /output.bin
    # 排除 projects/ 中任何名为 `build` 的目录
    build/
    # 排除 projects/ 或其子文件夹中任何 .tmp 文件
    *.tmp


10 CONTENT
==========

SnapRAID 将文件列表和校验和存储在 content 文件中。

它是一个二进制文件，列出了磁盘阵列中存在的所有文件，
以及用于验证其完整性的所有校验和。

此文件由 `sync` 和 `scrub` 命令读取和写入，并由
`fix`、`check` 和 `status` 命令读取。


11 PARITY
=========

SnapRAID 将阵列的奇偶校验信息存储在 parity 文件中。

这些是二进制文件，包含 `content` 文件中定义的所有
块的计算奇偶校验。

这些文件由 `sync` 和 `fix` 命令读取和写入，
并且仅由 `scrub` 和 `check` 命令读取。


12 ENCODING
===========

SnapRAID 在 Unix 中忽略任何编码。它读取并存储
文件系统使用的相同编码的文件名。

在 Windows 中，从文件系统读取的所有名称都会被转换并
以 UTF-8 格式处理。

要使文件名正确打印，您必须使用命令 `chcp 65001` 将 Windows
控制台设置为 UTF-8 模式，并使用 TrueType 字体，如 `Lucida Console`，
作为控制台字体。这仅影响打印的文件名；如果
您将控制台输出重定向到文件，则生成的文件始终
采用 UTF-8 格式。


13 COPYRIGHT
============

此文件版权所有 (C) 2025 Andrea Mazzoleni


14 SEE ALSO
===========

snapraid_log(1), snapraidd(1)
