docker-backup/README.md

# Docker Backup

一个功能强大、易于使用的 Docker 数据备份工具，支持文件夹备份、MySQL 容器数据库备份、定时任务和自动清理旧备份。

## 功能特性

- ✅ **文件夹备份**: 打包指定文件夹为 tar.gz 压缩文件
- ✅ **排除目录**: 支持配置需要排除的文件夹和文件模式
- ✅ **MySQL 备份**: 备份 MySQL 容器数据库为 sql.gz 压缩文件
- ✅ **合并打包**: 将文件夹和数据库备份合并为单个压缩文件
- ✅ **定时备份**: 使用 systemd timer 实现定时自动备份
- ✅ **自动清理**: 按天数或数量自动清理旧备份文件
- ✅ **灵活配置**: 使用 YAML 配置文件，易于管理
- ✅ **日志记录**: 完整的操作日志，方便问题排查
- ✅ **一键安装**: 提供自动化安装脚本

## 系统要求

- **操作系统**: Linux (支持 systemd)
- **依赖工具**: bash, tar, gzip, docker, yq
- **权限**: root 或 sudo 权限

## 快速开始

### 1. 一键安装

使用以下命令直接从远程安装：

```bash
bash <(curl -sL https://gitea.bcde.io/wangdefa/docker-backup/raw/branch/main/install.sh)
```

安装脚本会自动完成以下操作：
- 检测操作系统
- 安装依赖工具（yq 等）
- 从远程仓库下载脚本文件
- 安装到系统目录（`/usr/local/bin`、`/etc/docker-backup`）
- 创建配置文件
- 配置 systemd 服务和定时器
- 启动定时任务

### 2. 编辑配置文件

```bash
sudo vi /etc/docker-backup/config.yml
```

根据您的实际环境修改配置，主要包括：
- 备份输出目录
- 需要备份的文件夹
- 需要排除的目录
- MySQL 容器信息
- 保留策略

### 3. 测试备份

```bash
# 手动执行一次备份
docker-backup

# 查看备份文件
docker-backup-cleanup --list
```

## 配置说明

### 配置文件示例

配置文件位于 `/etc/docker-backup/config.yml`，主要配置项说明：

```yaml
# 备份基础配置
backup:
  output_dir: "/var/backups/docker-backup"  # 备份文件存放目录
  prefix: "backup"                          # 备份文件名前缀
  retention:
    enabled: true                           # 是否启用自动清理
    keep_days: 7                            # 保留最近 N 天的备份

# 文件夹备份配置
folders:
  enabled: true                             # 是否启用文件夹备份
  sources:                                  # 需要备份的文件夹列表
    - "/var/lib/docker/volumes"
    - "/opt/app/data"
  excludes:                                 # 需要排除的目录模式
    - "*/logs"
    - "*/temp"
    - "*/cache"

# MySQL 数据库备份配置
mysql:
  enabled: true                             # 是否启用 MySQL 备份
  container_name: "mysql"                   # MySQL 容器名称
  username: "root"                          # 数据库用户名
  password: "your_password_here"            # 数据库密码
  databases:                                # 要备份的数据库列表
    - "database1"
    - "database2"
  # 或者备份所有数据库: databases: "all"

# 日志配置
logging:
  enabled: true
  log_file: "/var/log/docker-backup.log"
  level: "INFO"
```

## 使用指南

### 定时任务管理

```bash
# 查看定时任务状态
systemctl status docker-backup.timer

# 查看下次执行时间
systemctl list-timers docker-backup.timer

# 停止定时任务
sudo systemctl stop docker-backup.timer

# 启动定时任务
sudo systemctl start docker-backup.timer

# 禁用定时任务（开机不自动启动）
sudo systemctl disable docker-backup.timer

# 启用定时任务（开机自动启动）
sudo systemctl enable docker-backup.timer
```

### 手动执行备份

```bash
# 执行备份
docker-backup

# 查看备份日志
sudo journalctl -u docker-backup.service -f
```

### 备份文件管理

```bash
# 列出所有备份文件
docker-backup-cleanup --list

# 删除 7 天前的备份
docker-backup-cleanup --days 7

# 只保留最近 10 个备份
docker-backup-cleanup --count 10

# 使用配置文件中的清理策略
docker-backup-cleanup --auto
```

## 高级配置

### 自定义服务名称

```bash
SERVICE_NAME=mybackup bash <(curl -sL https://gitea.bcde.io/wangdefa/docker-backup/raw/branch/main/install.sh)
```

### 自定义定时计划

```bash
# 每天早上 6 点执行
SCHEDULE="*-*-* 06:00:00" bash <(curl -sL https://gitea.bcde.io/wangdefa/docker-backup/raw/branch/main/install.sh)

# 每周一凌晨 2 点执行
SCHEDULE="Mon *-*-* 02:00:00" bash <(curl -sL https://gitea.bcde.io/wangdefa/docker-backup/raw/branch/main/install.sh)

# 每小时执行
SCHEDULE="hourly" bash <(curl -sL https://gitea.bcde.io/wangdefa/docker-backup/raw/branch/main/install.sh)
```

### 修改已安装的定时计划

编辑 timer 文件：

```bash
sudo vi /etc/systemd/system/docker-backup.timer
```

修改 `OnCalendar` 行，然后重新加载配置：

```bash
sudo systemctl daemon-reload
sudo systemctl restart docker-backup.timer
```

## 备份文件格式

备份文件采用时间戳命名格式：

```
backup-20250125-143022.tar.gz
```

文件内部结构：

```
backup-20250125-143022.tar.gz
├── folders.tar.gz    # 文件夹备份
└── mysql.sql.gz      # MySQL 数据库备份
```

## 故障排查

### 查看服务日志

```bash
# 查看最近的日志
sudo journalctl -u docker-backup.service -n 50

# 实时跟踪日志
sudo journalctl -u docker-backup.service -f

# 查看特定时间的日志
sudo journalctl -u docker-backup.service --since "2025-01-25 14:00:00"
```

### 常见问题

#### 1. 权限不足

确保脚本有执行权限：

```bash
sudo chmod +x /usr/local/bin/docker-backup
sudo chmod +x /usr/local/bin/docker-backup-cleanup
```

#### 2. MySQL 连接失败

检查：
- MySQL 容器是否运行：`docker ps | grep mysql`
- 用户名和密码是否正确
- 容器名称是否匹配

#### 3. 磁盘空间不足

查看磁盘使用情况：

```bash
df -h

# 手动清理旧备份
docker-backup-cleanup --days 3
```

#### 4. yq 命令找不到

重新运行安装脚本安装 yq：

```bash
bash <(curl -sL https://gitea.bcde.io/wangdefa/docker-backup/raw/branch/main/install.sh)
```

## 卸载

```bash
bash <(curl -sL https://gitea.bcde.io/wangdefa/docker-backup/raw/branch/main/install.sh) --uninstall
```

卸载脚本会：
- 停止并禁用 systemd 服务
- 删除 systemd 服务文件
- 删除脚本文件
- 可选删除配置目录（会提示确认）

## 项目结构

```
docker-backup/
├── bin/
│   ├── backup.sh                          # 主备份脚本
│   └── cleanup.sh                         # 清理脚本
├── config/
│   └── backup.yml.example                 # 配置文件示例
├── systemd/
│   ├── docker-backup.service.template     # systemd service 模板
│   └── docker-backup.timer.template       # systemd timer 模板
├── install.sh                             # 安装脚本
└── README.md                              # 项目文档
```

## 安全建议

1. **保护配置文件**: 配置文件包含数据库密码，请设置适当的权限：

   ```bash
   sudo chmod 600 /etc/docker-backup/config.yml
   ```

2. **备份文件权限**: 确保备份文件只能被授权用户访问：

   ```bash
   sudo chmod 700 /var/backups/docker-backup
   ```

3. **定期测试恢复**: 定期测试备份文件的恢复过程，确保备份有效。

4. **异地备份**: 建议将备份文件同步到远程服务器或云存储。

## 贡献

欢迎提交 Issue 和 Pull Request！

## 许可证

MIT License

## 作者

Your Name

## 更新日志

### v1.0.0 (2025-01-25)

- 初始版本发布
- 支持文件夹备份
- 支持 MySQL 容器备份
- 支持定时任务
- 支持自动清理旧备份
- 提供一键安装脚本