btrfs - Windows 系统上的 Btrfs 文件系统驱动程序

WinBtrfs v1.9

WinBtrfs 是一个适用于下一代 Linux 文件系统 Btrfs 的 Windows 驱动程序。它是从零开始重新实现的，不包含 Linux 内核中的任何代码，应该可以在 Windows XP 及以后的任何版本上运行。它也被包含在免费操作系统 ReactOS 中。

如果您的 Btrfs 文件系统位于 Linux 创建的 MD 软件 RAID 设备上，您还需要 WinMD 才能在 Windows 下显示该设备。

另请参阅 Quibble，这是一个允许 Windows 从 Btrfs 启动的实验性引导加载程序，以及 Ntfs2btrfs，一个允许原位转换 NTFS 文件系统的工具。

首先，声明：

使用本软件风险自负。我对可能对您的文件系统造成的任何损害不承担责任。它应该适合日常使用，但请确保您仍然进行备份。

这里的所有内容都是根据 GNU 较宽松通用公共许可证（LGPL）发布的；有关更多信息，请参阅 LICENCE 文件。欢迎您随意修改源代码，如果您有任何好的想法，我很感激您能告诉我（mark@harmstone.com）。

有关此处包含的第三方代码的版权详细信息，请参阅本文档末尾。

功能

读取和写入 Btrfs 文件系统
基本 RAID：RAID0、RAID1 和 RAID10
高级 RAID：RAID5 和 RAID6
缓存
发现 Btrfs 分区，即使 Windows 通常会忽略它们
获取和设置访问控制列表（ACL），使用 xattr security.NTACL
备用数据流（例如，:Zone.Identifier 存储为 xattr user.Zone.Identifier）
Linux 用户到 Windows 用户的映射（见下文）
符号链接和其他重解析点
用于识别和创建子卷（包括快照）的 Shell 扩展
硬链接
稀疏文件
空闲空间缓存
预分配
异步读写
无分区的 Btrfs 卷
每个卷的注册表挂载选项（见下文）
zlib 压缩
LZO 压缩
LXSS（"Windows 上的 Ubuntu"）支持
平衡（包括恢复在 Linux 上开始的平衡）
设备添加和移除
使用 mkbtrfs.exe 和 ubtrfs.dll 创建新文件系统
清理
TRIM/DISCARD
Reflink 复制
子卷发送和接收
降级挂载
空闲空间树（compat_ro 标志 free_space_cache）
收缩和扩展
LXSS 的权限等传递
Zstd 压缩
Windows 10 区分大小写目录标志
Oplocks
元数据 UUID 不兼容标志（Linux 5.0）
三盘和四盘 RAID1（Linux 5.5）
新的校验和类型（xxhash、sha256、blake2）（Linux 5.5）
块组树（Linux 6.1）

待办事项

完整的 fs-verity 支持（Linux 5.15）
分区支持（Linux 5.11）（Windows 不支持 HM-SMR？）
碎片整理
支持 Btrfs 配额
完整的事务日志支持
支持 Windows 事务（TxF）

安装

要安装驱动程序，下载并解压最新版本，右键单击 btrfs.inf，然后选择安装。该驱动程序已签名，因此应该可以在现代版本的 Windows 上直接使用。

如果您使用的是 Windows 10 并启用了安全启动，您可能需要进行注册表更改才能加载驱动程序 - 请参阅下文。

WinBtrfs 也可在以下包管理器中获得：

Chocolatey

choco install winbtrfs

Scoop

scoop bucket add nonportable
scoop install winbtrfs-np -g

卸载

如果您想卸载，请在命令提示符下运行：

RUNDLL32.EXE SETUPAPI.DLL,InstallHinfSection DefaultUninstall 132 btrfs.inf

您可能需要提供 btrfs.inf 的完整路径。

您也可以进入设备管理器，在"存储卷"下找到"Btrfs 控制器"，右键单击并选择"卸载"。勾选复选框以同时卸载驱动程序，并让 Windows 自行重启。

如果您需要通过注册表卸载，请打开 regedit 并将 HKLM\SYSTEM\CurrentControlSet\services\btrfs\Start 的值设置为 4，以禁用该服务。重启后，您就可以删除 btrfs 键并移除 C:\Windows\System32\drivers\btrfs.sys。

编译

要使用 Visual C++ 2019 进行编译，请打开目录并让 CMake 完成其工作。如果您正确安装了 Windows DDK，它应该可以直接工作。

要在 Linux 上使用 GCC 进行编译，您需要设置交叉编译器，可以是 i686-w64-mingw32 或 x86_64-w64-mingw32。创建一个构建目录，然后使用 mingw-x86.cmake 或 mingw-amd64.cmake 作为 CMake 工具链文件来生成 Makefile。

映射

用户映射存储在注册表键 HKLM\SYSTEM\CurrentControlSet\services\btrfs\Mappings 中。创建一个 DWORD，名称为您的 Windows SID（例如 S-1-5-21-1379886684-2432464051-424789967-1001），值为您的 Linux uid（例如 1000）。它将在下次加载驱动程序时生效。

您可以通过运行 wmic useraccount get name,sid 找到您当前的 SID。

同样，组映射存储在 GroupMappings 下。默认条目将 Windows 的 Users 组映射到 gid 100，这通常是 Linux 上的"users"组。您也可以在这里指定用户 SID，以强制用户创建的文件属于某个特定组。setgid 标志也像在 Linux 上一样工作。

请注意，在用户访问控制令牌下运行的进程会以 BUILTIN\Administrators SID（S-1-5-32-544）创建文件，而不是以用户帐户创建。

LXSS（"Windows 上的 Ubuntu" / "Windows 子系统 for Linux"）

驱动程序将 Linux 元数据传递给最新版本的 LXSS，但您需要让 Windows 知道您希望这样做。在 Windows 上的 Bash 提示符下，编辑 /etc/wsl.conf 文件，使其看起来像下面这样：

[automount]
enabled = true
options = "metadata"
mountFsTab = false

它将在下次重启时生效。是的，如果您愿意，您应该能够 chroot 到一个实际的 Linux 安装中。

命令

DLL 文件 shellbtrfs.dll 提供了 GUI 界面，但它也可以与 rundll32.exe 一起使用，从命令行执行一些任务，如果您希望定期安排某些任务运行，这可能会很有用。请注意，rundll32 不提供任何机制来返回错误代码，因此这些命令中的任何一个都可能会静默失败。

rundll32.exe shellbtrfs.dll,CreateSubvol <路径>
rundll32.exe shellbtrfs.dll,CreateSnapshot <源> <目标>
rundll32.exe shellbtrfs.dll,ReflinkCopy <源> <目标> 这也接受通配符，以及任意数量的源文件。

以下命令需要各种权限，因此必须以管理员身份运行才能生效：

rundll32.exe shellbtrfs.dll,SendSubvol <源> [-p <父级>] [-c <克隆子卷>] <流文件> -p 和 -c 标志与 Linux 上的 btrfs send 相同。你可以指定任意数量的克隆子卷。
rundll32.exe shellbtrfs.dll,RecvSubvol <流文件> <目标>
rundll32.exe shellbtrfs.dll,StartScrub <驱动器>
rundll32.exe shellbtrfs.dll,StopScrub <驱动器>

故障排除

如何调试？

在发布页面上，有包含 PDB 文件的 zip 文件可供下载。或者你可以尝试使用符号服务器 http://symbols.burntcomma.com/ - 在 windbg 中，将你的符号路径设置为类似这样：

symsrv*symsrv.dll*C:\symbols*http://msdl.microsoft.com/download/symbols;symsrv*symsrv.dll*C:\symbols*http://symbols.burntcomma.com

文件名很奇怪！或
某些文件或目录出现奇怪的错误！

驱动程序假设所有文件名都使用 UTF-8 编码。这应该是大多数设置的默认值 - 如果你没有使用 UTF-8，可能值得考虑转换你的文件。

如何在开启安全启动的情况下使用？

对于最新版本的 Windows 10，Microsoft 引入了更严格的签名要求，这似乎不适用于开源驱动程序。

为了解决这个问题，请在注册表编辑器中转到 HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\CI\Policy，创建一个名为 UpgradedSystem 的新 DWORD 值并设置为 1，然后重启。

或者你也可以直接在 BIOS 设置中关闭安全启动。

这是 Microsoft 在 LXSS 中硬编码的内容，可能是为了防止人们通过运行 mkdir /mnt/c/WiNdOwS 来破坏系统。

如何更改驱动器号？

安装了 shell 扩展后，在资源管理器中右击驱动器，单击属性，然后转到 Btrfs 选项卡。应该有一个允许你更改驱动器号的按钮。

我仍然在驱动器号方面遇到问题

在注册表编辑器中，尝试删除 HKEY_LOCAL_MACHINE\SYSTEM\MountedDevices 中的相关条目，然后重新启动。

如何将分区格式化为 Btrfs？

使用包含的命令行程序 mkbtrfs.exe。不幸的是，我们无法将 Btrfs 添加到 Windows 自己的对话框中，因为其文件系统列表是硬编码的。如果你不需要设置任何特定于 Btrfs 的选项，也可以运行 format /fs:btrfs。

我无法重新格式化已挂载的 Btrfs 文件系统

如果 Windows 的格式化对话框拒绝出现，请尝试使用 /fs 标志运行 format.com，例如 format /fs:ntfs D:。

我无法挂载 Synology NAS

Synology 似乎使用 LVM 作为其块设备。在有人为 Windows 编写 LVM 驱动程序之前，你无法使用它。

我无法挂载 Thecus NAS

Thecus 使用 Linux 的 MD raid 作为其块设备。你还需要安装 WinMD。

64 位 Windows 7 无法加载驱动程序

确保已安装 KB3033929。或考虑从包含所有更新的"托管"ISO 安装。

驱动器未显示，并且已安装 Paragon 软件

Paragon 的文件系统读取软件已知会禁用自动挂载。禁用或卸载 Paragon，然后通过运行 diskpart 并输入 automount enable 重新启用自动挂载。

驱动器在非常旧的 Windows 版本上不显示

在非常旧的 Windows 版本（XP、Server 2003？）上，Windows 完全忽略 Linux 分区。如果你遇到这种情况，请尝试在 Linux 上运行 fdisk 并将分区类型从 83 更改为 7。

更新日志

v1.9 (2024-03-15):

添加了对块组树的支持（Linux 6.1）
修复了系统负载过重时的挂起问题
在 mkbtrfs 中添加了 /blockgrouptree 和 /freespacetree 选项
在 mkbtrfs 中跟随 Linux 将 /noholes 默认设置为开启
在 aarch64 上添加了对 CRC32C 指令的支持

v1.8.2 (2023-01-10):

修复了 UAC 不工作的问题
修复了 Windows 11 22H2 上 Smartlocker 崩溃的问题
重新调整了 INF 文件以在 Windows 11 上更好地工作
文件现在使用 SHA256 哈希而不是 SHA1 进行签名

v1.8.1 (2022-08-23):

修复了刷新时的使用后释放问题
修复了安装 AppLocker 时打开卷时的崩溃问题
现在对非 COW 文件禁用压缩，与 Linux 一致
刷新现在在非常快的驱动器上有更好的扩展性
修复了小文件被惰性写入器填充到 4,096 字节的问题
添加了 NoDataCOW 注册表选项

v1.8 (2022-03-12):

添加了对 fs-verity 的最小支持
添加了测试套件
修复了不正确的磁盘使用统计信息
修复了将流重命名为文件或文件重命名为流时的潜在崩溃
修复了查询文件硬链接时的潜在崩溃
修复了打开有机会锁定的文件时的潜在挂起
修复了测试套件发现的其他小问题

v1.7.9 (2021-10-02):

修复了在 Windows 11 上挂载时的死锁问题
添加了对 BitLocker 加密卷的支持
改进了重命名或创建硬链接时的文件名检查
其他错误修复

v1.7.8.1 (2021-06-13):

修复了阻止新目录出现在列表中的错误
修复了发布版驱动程序在 XP 上仍然无法工作的问题

v1.7.8 (2021-06-09):

将 zstd 升级到 1.5.0 版本
修复了导致驱动程序在 XP 下无法工作的回归问题
修复了在 clang 上的编译问题
修复了使用 Linux 挂载选项 inode_cache 时的损坏问题
修复了涉及虚拟目录 \$Root 的递归问题

v1.7.7 (2021-04-12):

修复了高负载时的死锁问题
修复了安装原神时的可用空间问题
修复了在命令提示符中使用通配符复制文件时的问题
提高了目录查找的速度

v1.7.6 (2021-01-14):

修复了使用 Quibble 启动时的竞争条件
初次安装后不再需要重启 Windows
强制将最大文件名限制为 255 个 UTF-8 字符，以匹配 Linux 驱动程序
修复了可能创建带有尾随反斜杠的目录的问题
修复了 Windows 在刷新期间调用 NtCreateSection 时可能出现的潜在死锁
其他错误修复 v1.7.5 (2020-10-31):
修复了外壳扩展中的文本显示问题
添加了对mingw 8的支持
修复了新版Windows中LXSS权限不生效的问题
修复了截断内联文件时不会改变其大小的问题
修复了Quibble中在Windows启用AVX2之前驱动程序尝试使用它而导致的崩溃

v1.7.4 (2020-08-23):

修复了运行压缩EXE文件时的问题
将构建系统更改为cmake
将zstd升级到1.4.5版本
添加了对FSCTL_GET_RETRIEVAL_POINTERS的支持
其他错误修复

v1.7.3 (2020-05-24):

修复了发送文件更改通知时的崩溃
改进了LXSS的符号链接处理
添加了对未记录的标志SL_IGNORE_READONLY_ATTRIBUTE的支持
修复了由边缘情况引起的损坏，其中地址在同一刷新中分配和释放
改进了空闲空间树的处理
改进了对非常满的卷的处理
修复了GCC 10静态分析器提出的虚假警告
在适当的地方用位移操作替换乘法和除法
修复了外壳扩展中的组合框样式

v1.7.2 (2020-04-10):

为Windows 10上从Btrfs启动添加了更多修复
修复了Windows 10 1909上删除或关闭文件时偶尔出现的死锁
修复了读取大型ADS时的崩溃
修复了在RAID5/6上写入文件时偶尔出现的崩溃
其他错误修复

v1.7.1 (2020-03-02):

修复了读取超出文件末尾时的崩溃
修复了进行未对齐读取时的虚假校验和错误

v1.7 (2020-02-26):

添加了对metadata_uuid不兼容标志的支持（Linux 5.0）
添加了对三磁盘和四磁盘RAID1的支持（Linux 5.5）
添加了对新校验和类型的支持：xxhash、sha256、blake2（Linux 5.5）
大幅提高了校验和计算速度
大幅提高了压缩和解压缩速度
修复了数据为DUP时导致错误的空闲空间报告的错误
修复了设置case=dir选项时在LXSS上创建目录的问题

v1.6 (2020-02-04):

添加了实验性（即未经测试的）ARM支持（感谢DjArt的贡献）
为Windows 10上从Btrfs启动添加了修复
现在如果Windows睡眠或休眠时卷发生变化，卷将重新挂载
修复了挂载未被Linux正常卸载的卷时的损坏问题
修复了删除子卷时的崩溃

v1.5 (2019-11-10):

更多从Btrfs启动的修复
添加了虚拟$Root目录（参见下面的"NoRootDir"）
添加了对Windows XP的支持
添加了重命名备用数据流的支持
添加了oplock支持
修复了启动时的潜在死锁
修复了关机时可能出现的崩溃
修复了一系列内存泄漏
许多其他杂项错误修复

v1.4 (2019-08-31):

在属性表中添加了碎片百分比
添加了对Windows Server 2003和Windows Vista的支持
添加了页面文件支持
改进了对文件锁定的支持
添加了在Windows Server 2003上从Btrfs启动的支持（参见https://www.youtube.com/watch?v=-5E2CHmHEUs）
修复了驱动程序可能多次打开同一inode的问题
其他杂项错误修复

v1.3 (2019-06-10):

添加了对Windows 10引入的新重命名和删除函数的支持
添加了对Windows 10区分大小写目录标志的支持
更改了空闲空间计算方法，使其更接近Linux驱动程序的方法
增加了对128位文件ID的支持
修复了导致根项过时的错误
修复了阻止写入VHD的错误

v1.2.1 (2019-05-06):

撤销了影响流创建的提交

v1.2 (2019-05-05):

打开许多小文件时（如Git存储库）的速度大幅提升
修复了可移动设备意外移除时的崩溃
添加了轻松更改驱动器号的功能
不再为非常小的块创建空闲空间缓存，以免混淆Linux驱动程序
修复了创建非常大的文件后立即删除时的损坏
小错误修复

v1.1 (2018-12-15):

支持Zstd压缩
将Linux元数据传递给LXSS
重构了外壳扩展
修复了内存泄漏
许多其他错误修复

v1.0.2 (2018-05-19):

小错误修复

v1.0.1 (2017-10-15):

修复了死锁
二进制文件现已签名
小错误修复

v1.0 (2017-09-04):

第一个非测试版发布！
降级挂载
新的空闲空间缓存（compat_ro标志free_space_cache）
卷的缩小和扩展
注册表选项现在在更改时重新读取，而不是仅在启动时
改进了非常满的文件系统上的平衡
修复了阻止在Windows 8及以上版本中将用户配置文件目录存储在btrfs上的问题
更好的即插即用支持
杂项错误修复

v0.10 (2017-05-02):

Reflink复制
发送和接收子卷
组映射（参见上面的映射部分）
添加了用于脚本编写等的命令（参见上面的命令部分）
修复了阻止在非PNP设备（如VeraCrypt）上挂载的问题
修复了阻止新版本LXSS工作的问题
修复了扩展引用排序的问题，这个问题导致Linux出现问题但未被btrfs check检测到
添加了对读取压缩内联扩展的支持
许多杂项错误修复

v0.9 (2017-03-05):

清理
TRIM/DISCARD
改进了多设备卷的处理
从RAID文件系统读取时性能提升
不再谎称是NTFS，除非必须
如果出现不可恢复的错误，卷现在会变为只读，而不是蓝屏
现在可以使用Windows内置的format.com创建文件系统
Zlib升级到1.2.11版本
杂项性能提升
杂项错误修复

v0.8 (2016-12-30):

卷属性表，用于：
平衡
添加和移除设备
显示磁盘使用情况，即相当于btrfs fi usage
在适当的情况下现在并行计算校验和
使用mkbtrfs.exe创建新文件系统
RAID设备的即插即用支持
在任务管理器中正确分配进程的磁盘使用情况
性能提升
杂项错误修复

v0.7 (2016-10-24):

支持RAID5/6（不兼容标志raid56）
种子支持
LXSS（"Windows上的Ubuntu"）支持
支持Windows扩展属性
改进了可移动设备支持
更好的快照支持
从RAID校验和错误中恢复
修复了创建大量新文件时耗时过长的问题
杂项速度提升和错误修复

v0.6 (2016-08-21):

压缩支持（包括zlib和lzo）
混合组支持
无空洞支持
在外壳扩展中添加了inode属性表
更多挂载选项（见下文）
更好地支持可移动设备
页面文件支持
许多杂项错误修复 v0.5 (2016-07-24):
大幅提升速度（从"缓慢"到"飞快"）
大幅提高稳定性
支持RAID：RAID0、RAID1和RAID10
异步读写
无分区的Btrfs卷
Windows稀疏文件支持
对象ID支持
初步实现每卷挂载选项
安全性改进
通知改进
其他bug修复

v0.4 (2016-05-02):

子卷创建和删除
快照
预分配
重解析点
硬链接
即插即用
空闲空间缓存
修复阻止卷在网络上共享的问题
其他bug修复

v0.3 (2016-03-25):

Bug修复：
修复元数据块为SINGLE时的崩溃问题，如在SSD上
修复分割内部树时的崩溃
修复当树中第一项被删除时树遍历失败的问题
修复整个树清空的问题（可能只与校验和树相关）
修复"btrfs check"中出现的"不正确的本地反向引用计数"消息
其他各种修复
添加shell扩展的初步功能，目前仅更改子卷图标

v0.2 (2016-03-13):

Bug修复版本：
检查内存分配是否成功
检查树项是否为预期大小
添加回滚功能，使失败的操作完全撤销
修复驱动程序声明所有未识别分区的问题（感谢Pierre Schweitzer）
修复"CcCopyRead"中的死锁
修复在资源管理器中更改JPEG属性的问题
谎报FS类型，以使UAC正常工作
大量其他bug修复
基本安全支持
调试日志支持（见下文）

v0.1 (2016-02-21):

初始alpha版本发布

调试日志

WinBtrfs有三个级别的调试消息：错误和FIXME、警告以及跟踪。发布版驱动程序仅显示错误和FIXME，通过"DbgPrint"记录。您可以使用Microsoft的DebugView程序查看这些消息，可在https://technet.microsoft.com/en-gb/sysinternals/debugview下载。

如果您想报告问题，附上完整的调试日志将非常有帮助。为此，您需要使用调试版驱动程序；将Debug\x64或Debug\x86中的文件复制到x64或x86。您还需要在HKLM\SYSTEM\CurrentControlSet\Services\btrfs中设置以下注册表项：

"DebugLogLevel"（DWORD）：0表示无消息，1表示错误和FIXME，2还包括警告，3表示包括跟踪在内的所有内容。
"LogDevice"（字符串，可选）：您想输出到的串行设备，如"\Device\Serial0"。这可能只在虚拟机上有用。
"LogFile"（字符串，可选）：如果未设置"LogDevice"，您希望输出到的文件。请注意这是内核文件名，所以需要加上"\??\"前缀（例如，"\??\C:\btrfs.log"）。显然，不要将其存储在驱动程序本身使用的卷上，否则会造成无限循环。

挂载选项

驱动程序将在HKLM\SYSTEM\CurrentControlSet\Services\btrfs下为每个挂载的文件系统创建子键，以其UUID命名。如果不确定哪个UUID对应哪个卷，可以在Linux上使用"btrfs fi show"检查。您可以在这个子键中添加每卷挂载选项，这些选项将在重启后生效。如果在上一级键中设置了值，它将作为默认值使用。

"Ignore"（DWORD）：设为1可告诉驱动程序不要尝试加载此文件系统。与"Readonly"标志一起，这可能是多余的。
"Readonly"（DWORD）：设为1可告诉驱动程序不允许写入此卷。这相当于Linux上的"ro"标志。
"Compress"（DWORD）：设为1可告诉驱动程序默认以压缩方式写入文件。这相当于Linux上的"compress"标志。
"CompressForce"（DWORD）：设为1可强制压缩，即忽略"nocompress"inode标志，甚至尝试压缩不可压缩的文件。这不是个好主意，但相当于Linux上的"compress-force"标志。
"CompressType"（DWORD）：设为1优先使用zlib压缩，2优先使用lzo压缩，3优先使用zstd压缩。默认为0，如果设置了不兼容标志则使用zstd或lzo压缩，否则使用zlib。
"FlushInterval"（DWORD）：元数据刷新间隔，以秒为单位。默认为30，与Linux相同 - 那里的参数叫"commit"。
"ZlibLevel"（DWORD）：-1到9之间的数字，决定压缩文件时使用的CPU时间。如果您有快速CPU但磁盘较慢，或相反，可能想调整此项。默认为3，这是Linux上的硬编码值。
"MaxInline"（DWORD）：允许"内联"文件的最大大小，即存储在元数据中的文件。默认为2048，这也是现代Linux版本的默认值 - 那里的参数叫"max_inline"。它会被限制在最大值以内，除非您更改了节点大小，否则略低于16 KB。
"SubvolId"（QWORD）：我们将尝试挂载为根的子卷ID。如果不存在，此参数将被静默忽略。子卷ID可以在inode属性表中找到；那里是十六进制，而Linux工具上是十进制。默认是通过"btrfs subvolume set-default"设置的值；如果没有，则为子卷5。Linux上的等效参数叫"subvolid"。
"SkipBalance"（DWORD）：设为1可告诉驱动程序不要尝试恢复系统上次关机时正在运行的平衡操作。默认为0。Linux上的等效参数是"skip_balance"。
"NoPNP"（DWORD）：仅用于调试，强制任何卷出现而不是通过常规即插即用方法公开。
"ZstdLevel"（DWORD）：Zstd压缩级别，默认为3。
"NoTrim"（DWORD）：设为1可禁用TRIM支持。
"AllowDegraded"（DWORD）：设为1可允许挂载降级卷，即缺少设备的卷。强烈建议不要启用此选项，除非必要。
"NoRootDir"（DWORD）：如果您已更改默认子卷，无论是本地还是通过注册表选项，将会有一个名为$Root的隐藏目录指向根目录通常所在的位置。将此值设为1可防止其出现。
"NoDataCOW"（DWORD）：设为1可为新文件禁用写时复制。这相当于Linux上的"nodatacow"标志。