# 配置架构参考

## 配置项概览

### `backup` 区块

| 配置项 | 类型 | 必填 | 默认值 | 描述 |
|--------|------|------|--------|------|
| `output_dir` | 字符串 | 是 | `/var/backups/docker-backup` | 备份文件存储目录 |
| `prefix` | 字符串 | 否 | `backup` | 备份文件名前缀 |
| `retention.enabled` | 布尔 | 否 | `true` | 是否启用自动清理 |
| `retention.keep_days` | 整数 | 否 | `7` | 保留最近 N 天备份 |
| `retention.keep_count` | 整数 | 否 | `null` | 保留最近 N 个备份文件 |

### `folders` 区块

| 配置项 | 类型 | 必填 | 默认值 | 描述 |
|--------|------|------|--------|------|
| `enabled` | 布尔 | 否 | `true` | 是否启用文件夹备份 |
| `sources` | 字符串数组 | 是 | `[]` | 需备份的文件夹路径列表 |
| `excludes` | 字符串数组 | 否 | 预定义排除模式 | 排除的文件/文件夹模式 |

### `mysql` 区块

| 配置项 | 类型 | 必填 | 默认值 | 描述 |
|--------|------|------|--------|------|
| `enabled` | 布尔 | 否 | `true` | 是否启用 MySQL 备份 |
| `container_name` | 字符串 | 是 | 无 | MySQL 容器名称 |
| `username` | 字符串 | 是 | 无 | 数据库用户名 |
| `password` | 字符串 | 是 | 无 | 数据库密码 |
| `databases` | 字符串数组或字符串 | 是 | 无 | 要备份的数据库，可以是具体库名或 `"all"` |

### `logging` 区块

| 配置项 | 类型 | 必填 | 默认值 | 描述 |
|--------|------|------|--------|------|
| `enabled` | 布尔 | 否 | `true` | 是否启用日志 |
| `log_file` | 字符串 | 是 | `/var/log/docker-backup.log` | 日志文件路径 |
| `level` | 字符串 | 否 | `"INFO"` | 日志级别 (`DEBUG`, `INFO`, `WARN`, `ERROR`) |

### `notification` 区块

| 配置项 | 类型 | 必填 | 默认值 | 描述 |
|--------|------|------|--------|------|
| `enabled` | 布尔 | 否 | `false` | 是否启用通知 |
| `method` | 字符串 | 条件必填 | 无 | 通知方式 (`email`, `webhook`) |
| `webhook_url` | 字符串 | 条件必填 | 无 | Webhook 地址 |
| `on_failure_only` | 布尔 | 否 | `true` | 是否仅在备份失败时通知 |

## 配置依赖和约束

1. 互斥配置：
   - `retention.keep_days` 和 `retention.keep_count` 互斥

2. 必要条件：
   - MySQL 备份需要 `container_name`、`username`、`password`
   - 通知需要 `method` 和相应的地址

3. 验证规则：
   - 文件夹备份需要至少一个有效的 `sources`
   - 检查路径有效性
   - 验证工具依赖（`yq`, `tar`, `docker`）