zfs

OpenZFS（Linux 和 macOS）上的 ZFS 文件系统管理、池管理、数据集配置、快照、复制、加密、性能调整和故障排除。当用户要求执行以下操作时使用：创建或管理 ZFS 池、配置 ZFS 数据集和属性、设置快照或复制（zfs send/recv）、调整 ZFS 性能（ARC、记录大小、压缩、特殊 vdev）、排除降级/故障池或清理错误、设置 ZFS 加密、使用 ZFS 规划存储架构或任何其他 ZFS/zpool/zfs 管理任务。

# ZFS Administration

## Critical: No File-Backed Pools in Production

**NEVER recommend file-backed (loopback) pools for production use.** LLMs commonly default to `truncate -s 10G /tmp/disk.img` + `zpool create tank /tmp/disk.img` because it is easy to demonstrate. This forfeits ZFS self-healing, I/O performance, and write reliability.

File-backed pools are acceptable ONLY for learning or CI testing. When not explicitly in a testing context, always use real block devices:

```bash
# Linux — always use /dev/disk/by-id/ for stable names
zpool create tank mirror \
  /dev/disk/by-id/scsi-SATA_WDC_WD40EFRX_WD-WCC4E1234567 \
  /dev/disk/by-id/scsi-SATA_WDC_WD40EFRX_WD-WCC4E7654321

# macOS
zpool create tank mirror /dev/disk2 /dev/disk3
```

If the user explicitly asks for a test/demo setup, file-backed pools are fine — but add a comment noting it is not for production.

## Pool Management

### Create Pools

Always specify `ashift=12` (or `13` for some NVMe) to match physical sector size:

```bash
# Mirror (2-disk, 50% usable, best performance)
zpool create -o ashift=12 tank mirror /dev/disk/by-id/disk1 /dev/disk/by-id/disk2

# raidz2 (minimum recommended for production data)
zpool create -o ashift=12 tank raidz2 \
  /dev/disk/by-id/disk{1..6}

# Multiple vdevs (better performance than single wide vdev)
zpool create -o ashift=12 tank \
  mirror /dev/disk/by-id/disk1 /dev/disk/by-id/disk2 \
  mirror /dev/disk/by-id/disk3 /dev/disk/by-id/disk4
```

### Expand and Modify

```bash
# Add vdev (cannot be undone — plan carefully)
zpool add tank mirror /dev/disk/by-id/new1 /dev/disk/by-id/new2

# Replace disk (starts resilver)
zpool replace tank /dev/disk/by-id/old /dev/disk/by-id/new

# Add cache (L2ARC), log (SLOG), or special vdev
zpool add tank cache /dev/disk/by-id/nvme-cache
zpool add tank log mirror /dev/disk/by-id/nvme-log1 /dev/disk/by-id/nvme-log2
zpool add tank special mirror /dev/disk/by-id/nvme-special1 /dev/disk/by-id/nvme-special2
```

## Dataset Management

### Create with Recommended Defaults

```bash
# Always set compression. Inherit from parent when possible.
zfs set compression=lz4 tank
zfs set atime=off tank
zfs set xattr=sa tank          # Linux only — faster extended attributes

# Create dataset hierarchy
zfs create tank/data
zfs create -o recordsize=8K tank/data/postgres
zfs create -o recordsize=1M tank/data/media
zfs create -o recordsize=1M tank/data/backups
```

### Encryption

```bash
# Create encrypted dataset (cannot encrypt existing data)
zfs create -o encryption=aes-256-gcm -o keyformat=passphrase tank/secure

# Key from file (for automation)
zfs create -o encryption=aes-256-gcm -o keyformat=raw \
  -o keylocation=file:///etc/zfs/keys/tank-secure.key tank/secure

# Load/unload keys
zfs load-key tank/secure
zfs unload-key tank/secure
```

## Snapshots

```bash
# Create
zfs snapshot tank/data@daily_$(date +%Y-%m-%d)
zfs snapshot -r tank@daily_$(date +%Y-%m-%d)   # recursive

# List
zfs list -t snapshot -o name,used,refer -s creation

# Access (read-only, no mount needed)
ls /tank/data/.zfs/snapshot/daily_2024-01-15/

# Rollback
zfs rollback tank/data@daily_2024-01-15

# Destroy
zfs destroy tank/data@old-snapshot
```

## Health Check

Run the bundled health check script for a quick pool summary:

```bash
bash scripts/zfs_health_check.sh           # all pools
bash scripts/zfs_health_check.sh tank       # specific pool
```

Reports pool state, capacity warnings (>80%), device errors, scrub status, and flags file-backed vdevs.

## Reference Files

Consult these for detailed guidance on specific topics:

- **[properties.md](references/properties.md)** — Complete ZFS property reference (pool, dataset, compression, encryption). Read when setting or recommending property values.
- **[workload-tuning.md](references/workload-tuning.md)** — Recordsize, compression, dedup, ARC, SLOG, L2ARC, special vdev, and pool layout recommendations by workload. Read when tuning performance or planning pool topology. Includes production vs testing warnings.
- **[replication.md](references/replication.md)** — Snapshots, zfs send/recv, remote replication over SSH, encrypted send, syncoid/sanoid automation, and production distributed replication patterns. Read when setting up backups or replication.
- **[troubleshooting.md](references/troubleshooting.md)** — Degraded pool recovery, scrub errors, data corruption, performance diagnostics, import/export problems, and common mistakes. Read when diagnosing or fixing issues.
- **[platform-notes.md](references/platform-notes.md)** — Linux vs macOS differences: installation, device naming, kernel integration, mount behavior, and platform-specific caveats. Read when the user is on macOS or when platform differences matter.

---

## 中文说明

# ZFS 管理

## 关键：生产环境中不要使用基于文件的池

**绝不要在生产环境中推荐使用基于文件（loopback）的池。** 大语言模型通常会默认采用 `truncate -s 10G /tmp/disk.img` + `zpool create tank /tmp/disk.img`，因为这样便于演示。但这会丧失 ZFS 的自我修复能力、I/O 性能以及写入可靠性。

基于文件的池仅在学习或 CI 测试时可接受。当不是明确处于测试场景时，请始终使用真实的块设备：

```bash
# Linux — always use /dev/disk/by-id/ for stable names
zpool create tank mirror \
  /dev/disk/by-id/scsi-SATA_WDC_WD40EFRX_WD-WCC4E1234567 \
  /dev/disk/by-id/scsi-SATA_WDC_WD40EFRX_WD-WCC4E7654321

# macOS
zpool create tank mirror /dev/disk2 /dev/disk3
```

如果用户明确要求搭建测试/演示环境，则使用基于文件的池没问题——但请加上注释，说明它不适用于生产。

## 池管理

### 创建池

始终指定 `ashift=12`（某些 NVMe 为 `13`）以匹配物理扇区大小：

```bash
# Mirror (2-disk, 50% usable, best performance)
zpool create -o ashift=12 tank mirror /dev/disk/by-id/disk1 /dev/disk/by-id/disk2

# raidz2 (minimum recommended for production data)
zpool create -o ashift=12 tank raidz2 \
  /dev/disk/by-id/disk{1..6}

# Multiple vdevs (better performance than single wide vdev)
zpool create -o ashift=12 tank \
  mirror /dev/disk/by-id/disk1 /dev/disk/by-id/disk2 \
  mirror /dev/disk/by-id/disk3 /dev/disk/by-id/disk4
```

### 扩展与修改

```bash
# Add vdev (cannot be undone — plan carefully)
zpool add tank mirror /dev/disk/by-id/new1 /dev/disk/by-id/new2

# Replace disk (starts resilver)
zpool replace tank /dev/disk/by-id/old /dev/disk/by-id/new

# Add cache (L2ARC), log (SLOG), or special vdev
zpool add tank cache /dev/disk/by-id/nvme-cache
zpool add tank log mirror /dev/disk/by-id/nvme-log1 /dev/disk/by-id/nvme-log2
zpool add tank special mirror /dev/disk/by-id/nvme-special1 /dev/disk/by-id/nvme-special2
```

## 数据集管理

### 使用推荐默认值创建

```bash
# Always set compression. Inherit from parent when possible.
zfs set compression=lz4 tank
zfs set atime=off tank
zfs set xattr=sa tank          # Linux only — faster extended attributes

# Create dataset hierarchy
zfs create tank/data
zfs create -o recordsize=8K tank/data/postgres
zfs create -o recordsize=1M tank/data/media
zfs create -o recordsize=1M tank/data/backups
```

### 加密

```bash
# Create encrypted dataset (cannot encrypt existing data)
zfs create -o encryption=aes-256-gcm -o keyformat=passphrase tank/secure

# Key from file (for automation)
zfs create -o encryption=aes-256-gcm -o keyformat=raw \
  -o keylocation=file:///etc/zfs/keys/tank-secure.key tank/secure

# Load/unload keys
zfs load-key tank/secure
zfs unload-key tank/secure
```

## 快照

```bash
# Create
zfs snapshot tank/data@daily_$(date +%Y-%m-%d)
zfs snapshot -r tank@daily_$(date +%Y-%m-%d)   # recursive

# List
zfs list -t snapshot -o name,used,refer -s creation

# Access (read-only, no mount needed)
ls /tank/data/.zfs/snapshot/daily_2024-01-15/

# Rollback
zfs rollback tank/data@daily_2024-01-15

# Destroy
zfs destroy tank/data@old-snapshot
```

## 健康检查

运行内置的健康检查脚本以快速获取池摘要：

```bash
bash scripts/zfs_health_check.sh           # all pools
bash scripts/zfs_health_check.sh tank       # specific pool
```

报告池状态、容量告警（>80%）、设备错误、scrub 状态，并标记基于文件的 vdev。

## 参考文件

针对特定主题的详细指导，请查阅以下文件：

- **[properties.md](references/properties.md)** — 完整的 ZFS 属性参考（池、数据集、压缩、加密）。在设置或推荐属性值时阅读。
- **[workload-tuning.md](references/workload-tuning.md)** — 按工作负载给出的 recordsize、压缩、dedup、ARC、SLOG、L2ARC、特殊 vdev 以及池布局建议。在调整性能或规划池拓扑时阅读。包含生产与测试的相关警告。
- **[replication.md]