# 安装（以 Debian/Ubuntu 为例）
sudo apt update && sudo apt install btrfs-progs

# 确认安装
btrfs version
# btrfs-progs v6.6.3

# 检查内核是否加载了 Btrfs 模块
cat /proc/filesystems | grep btrfs
# nodev   btrfs

# 检查模块信息
modinfo btrfs | head -5
# filename:       /lib/modules/6.1.0/kernel/fs/btrfs/btrfs.ko
# license:        GPL
# description:    B-Tree Filesystem (Btrfs)
# author:         Oracle

# 如果没有加载，手动加载
sudo modprobe btrfs

# 在单个分区上创建 Btrfs
sudo mkfs.btrfs /dev/sdb1

# 指定标签
sudo mkfs.btrfs -L "mydata" /dev/sdb1

# 指定 UUID（通常不需要，系统自动生成）
sudo mkfs.btrfs -U 12345678-1234-1234-1234-123456789012 /dev/sdb1

# 将多个设备组成一个 Btrfs 文件系统（single 模式）
sudo mkfs.btrfs -L "pool" /dev/sdb1 /dev/sdc1

# RAID 1 模式（数据和元数据都镜像）
sudo mkfs.btrfs -d raid1 -m raid1 -L "mirror" /dev/sdb1 /dev/sdc1

# RAID 10 模式（至少 4 个设备）
sudo mkfs.btrfs -d raid10 -m raid10 -L "fast-mirror" /dev/sd{b,c,d,e}1

# RAID 5 模式（不推荐用于生产）
sudo mkfs.btrfs -d raid5 -m raid5 -L "raid5-pool" /dev/sd{b,c,d}1

# 查看支持的校验和算法
mkfs.btrfs --help 2>&1 | grep csum

# 使用 xxhash（比 CRC32C 更快，需要内核 5.5+）
sudo mkfs.btrfs --csum xxhash -L "fast-check" /dev/sdb1

# 使用 sha256（更安全，但较慢）
sudo mkfs.btrfs --csum sha256 -L "secure-check" /dev/sdb1

# 使用 blake2b（需要内核 5.17+，速度接近 xxhash）
sudo mkfs.btrfs --csum blake2b -L "balanced" /dev/sdb1

# 小分区推荐使用混合模式
sudo mkfs.btrfs --mixed -L "boot-btrfs" /dev/sdb1

# 基础挂载
sudo mount /dev/sdb1 /mnt/data

# 通过 UUID 挂载（推荐）
sudo mount UUID=a1b2c3d4-e5f6-7890-abcd-ef1234567890 /mnt/data

# 通过标签挂载
sudo mount -L "mydata" /mnt/data

# 卸载
sudo umount /mnt/data

mount -o compress=zstd:1,noatime,ssd,discard=async,space_cache=v2 /dev/sda2 /mnt

mount -o compress=zstd:3,noatime,space_cache=v2,commit=60 /dev/sdb1 /data

mount -o compress=zstd:3,noatime,space_cache=v2 /dev/sdb1 /data
# RAID 信息存储在文件系统内部，不需要额外指定

# 获取 UUID
sudo blkid /dev/sdb1
# /dev/sdb1: LABEL="mydata" UUID="a1b2c3d4-e5f6-7890-abcd-ef1234567890" TYPE="btrfs"

# /etc/fstab 配置（单设备）
UUID=a1b2c3d4-e5f6-7890-abcd-ef1234567890 /data btrfs defaults,compress=zstd:3,noatime,ssd,discard=async 0 0

# /etc/fstab 配置（带子卷）
UUID=xxxx /        btrfs subvol=/@,defaults,compress=zstd:1,ssd,discard=async 0 0
UUID=xxxx /home    btrfs subvol=/@home,defaults,compress=zstd:3,ssd,discard=async 0 0
UUID=xxxx /var     btrfs subvol=/@var,defaults,ssd,discard=async 0 0
UUID=xxxx /.snapshots btrfs subvol=/@snapshots,defaults,ssd,discard=async 0 0

# 测试 fstab 是否正确
sudo mount -a

# 检查挂载状态
mount | grep btrfs
findmnt -t btrfs

# 查看文件系统摘要
sudo btrfs filesystem show /data
# Label: 'mydata'  uuid: a1b2c3d4-e5f6-7890-abcd-ef1234567890
#     Total devices 1  FS bytes used 10.00GiB
#     devid    1  size 100.00GiB  used 12.04GiB  path /dev/sdb1

# 查看详细空间使用
sudo btrfs filesystem df /data

# 输出示例：
# Data, single: total=8.01GiB, used=6.50GiB
# System, DUP: total=8.00MiB, used=16.00KiB
# Metadata, DUP: total=1.01GiB, used=350.50MiB
# GlobalReserve, single: total=512.00MiB, used=0.00B
# unknown, single: total=0.00B, used=0.00B

# 查看设备级空间使用
sudo btrfs filesystem show --raw /data
sudo btrfs filesystem usage /data

# 查看设备统计
sudo btrfs device stats /data

# 输出（正常情况下全为 0）：
# [/dev/sdb1].write_io_errs    0
# [/dev/sdb1].read_io_errs     0
# [/dev/sdb1].flush_io_errs    0
# [/dev/sdb1].corruption_errs  0
# [/dev/sdb1].generation_errs  0

# 非零的值表示有问题！

# 查看主 superblock 信息
sudo btrfs inspect-internal dump-super /dev/sdb1

# 查看所有 superblock 副本
sudo btrfs inspect-internal dump-super -f /dev/sdb1

# 查看 chunk 信息
sudo btrfs inspect-internal dump-tree -t chunk /dev/sdb1

# 查看文件系统 tree root
sudo btrfs inspect-internal dump-tree -t root /dev/sdb1

# 查看文件系统 UUID
sudo blkid /dev/sdb1

# 查看所有 Btrfs 文件系统
sudo btrfs filesystem show

# 通过 UUID 查找设备
sudo btrfs filesystem show a1b2c3d4-e5f6-7890-abcd-ef1234567890

# 创建时设置标签
sudo mkfs.btrfs -L "production-data" /dev/sdb1

# 修改标签（文件系统需要已挂载）
sudo btrfs filesystem label /mnt/data
# production-data

sudo btrfs filesystem label /mnt/data "new-label"

# 通过标签查找
findfs LABEL=production-data
sudo btrfs filesystem show -L "production-data"

# ⚠️ 警告：check 之前必须卸载文件系统！
sudo umount /mnt/data

# 只读检查（安全）
sudo btrfs check /dev/sdb1
# Opening filesystem to check...
# Checking filesystem on /dev/sdb1
# UUID: a1b2c3d4-e5f6-7890-abcd-ef1234567890
# [1/7] checking root items
# [2/7] checking extents
# [3/7] checking free space cache
# [4/7] checking fs roots
# [5/7] checking only csums items (without verifying data)
# [6/7] checking root refs
# [7/7] checking quota groups
# found 10737418240 bytes used, no error found
# total csum bytes: 9876543
# total tree bytes: 123456789
# total fs tree bytes: 987654321
# total extent tree bytes: 12345678
# btree space waste bytes: 1234567
# file data blocks allocated: 10737418240
#  referenced: 10737418240

# 查看文件系统树（详细）
sudo btrfs check --tree-stats /dev/sdb1

# 查看 extent 树
sudo btrfs check --check-data-csum /dev/sdb1
# 这会验证所有数据块的校验和，比较慢但更彻底

# ⚠️ 危险修复模式
sudo btrfs check --repair /dev/sdb1

# 更安全的 init-extent-tree 修复
sudo btrfs check --init-extent-tree /dev/sdb1

# 清除空间缓存（如果缓存损坏）
sudo btrfs check --clear-space-cache v1 /dev/sdb1
sudo btrfs check --clear-space-cache v2 /dev/sdb1

# 尝试从损坏的文件系统中恢复数据
# -s  恢复 snapshots
# -m  恢复 metadata
# -S  恢复 symlinks
# -i  忽略错误
sudo btrfs restore /dev/sdb1 /recovery/

# 恢复指定子卷
sudo btrfs restore -r 256 /dev/sdb1 /recovery/

# 指定 root tree 的 bytenr（高级用法）
sudo btrfs restore -r 256 -t <bytenr> /dev/sdb1 /recovery/

# 1. 准备磁盘
lsblk
sudo fdisk /dev/sdb
# 创建新分区 sdb1

# 2. 创建 Btrfs 文件系统
sudo mkfs.btrfs -L "project-data" --csum xxhash /dev/sdb1

# 3. 创建挂载点
sudo mkdir -p /data

# 4. 挂载
sudo mount -o compress=zstd:3,noatime,space_cache=v2 /dev/sdb1 /data

# 5. 验证挂载
df -h /data
mount | grep /data

# 6. 测试读写
sudo touch /data/testfile
echo "Hello Btrfs" | sudo tee /data/testfile
cat /data/testfile

# 7. 查看文件系统信息
sudo btrfs filesystem show /data
sudo btrfs filesystem df /data
sudo btrfs device stats /data

# 8. 配置开机自动挂载
echo "UUID=$(sudo blkid -s UUID -o value /dev/sdb1) /data btrfs defaults,compress=zstd:3,noatime,space_cache=v2 0 0" | sudo tee -a /etc/fstab

# 9. 测试 fstab
sudo umount /data
sudo mount -a
df -h /data

# 10. 清理测试文件
sudo rm /data/testfile