backup/README.md

Backup Service

自动化备份服务，支持本地目录、MySQL、MariaDB 和 PostgreSQL 数据库的定期备份，并上传到 S3 对象存储。

功能特性

• 支持多种备份类型：
  • 本地目录备份
  • MySQL 数据库备份
  • MariaDB 数据库备份
  • PostgreSQL 数据库备份
• 自动打包为 tar.gz 格式
• 上传到 S3 兼容的对象存储
• 自动清理旧备份，保留指定数量
• 可配置的备份间隔
• 适用于 Docker 容器环境

配置说明

配置文件使用 YAML 格式，示例：

name: "backup"

items:
  - name: "app"
    type: "local"
    path: "/data/app"
    exclude:
      - "*.log"         # 排除所有 .log 文件
      - "*.tmp"         # 排除所有临时文件
      - "cache"         # 排除 cache 目录
      - "node_modules"  # 排除 node_modules 目录
  - name: "mysql-db"
    type: "mysql"
    host: "localhost"
    port: 3306
    user: "root"
    password: "password"
    database: "app"
  - name: "mariadb-db"
    type: "mariadb"
    host: "localhost"
    port: 3307
    user: "root"
    password: "password"
    database: "app"

options:
  storage: "s3"
  s3:
    endpoint: "https://s3.example.com"
    access_key: "access_key"
    secret_key: "secret_key"
    bucket: "bucket"
    region: "region"
    path: "path"
  max_backups: 3
  backup_interval: "1d"

配置项说明

• name: 备份任务名称，用于生成备份文件名
• items: 备份项列表
  • name: 备份项名称
  • type: 类型，可选 local、mysql、mariadb、postgresql
    • mysql: 使用 mysqldump 工具备份 MySQL 数据库
    • mariadb: 使用 mariadb-dump 工具备份 MariaDB 数据库
    • postgresql: 使用 pg_dump 工具备份 PostgreSQL 数据库
  • 本地目录备份 (local) 参数：
    • path: 要备份的目录路径
    • exclude: （可选）排除模式列表，支持：
      • 文件名通配符，如 *.log、*.tmp
      • 目录名，如 cache、node_modules、.git
      • 相对路径，如 logs/debug.log
  • 数据库备份参数：
    • host: 数据库主机地址
    • port: 端口号
    • user: 用户名
    • password: 密码
    • database: 数据库名
• options:
  • storage: 存储类型，目前仅支持 s3
  • s3: S3 配置
    • endpoint: S3 端点 URL
    • access_key: 访问密钥
    • secret_key: 密钥
    • bucket: 存储桶名称
    • region: 区域
    • path: 存储路径前缀
  • max_backups: 保留的最大备份数量
  • backup_interval: 备份间隔（如 1h、6h、12h、1d、7d）

构建和运行

构建 Docker 镜像

docker build -t backup:latest .

运行容器

docker run -d \
  --name backup \
  -v /path/to/backup.yaml:/config/backup.yaml \
  -v /data:/data \
  backup:latest

Docker Compose 示例

services:
  backup:
    build: https://git.nyne.dev/x/backup.git
    volumes:
      - ./backup.yaml:/config/backup.yaml
      - /data:/data
    restart: unless-stopped

备份文件命名

备份文件按照 {name}-{timestamp}.tar.gz 格式命名，例如：

• backup-20260202-143000.tar.gz

时间戳格式为 YYYYMMDD-HHMMSS。

注意事项

1. 确保容器有权限访问需要备份的目录和数据库
2. MySQL（mysqldump）、MariaDB（mariadb-dump）和 PostgreSQL（pg_dump）的客户端工具已预装在容器中
3. 备份过程中会创建临时目录，完成后自动清理
4. 确保 S3 配置正确，具有上传和删除权限
5. 首次启动时会立即执行一次备份，然后按照配置的间隔定期执行
6. S3 版本控制支持：
   • 如果 S3 存储桶启用了版本控制，删除旧备份时会彻底删除所有版本
   • 包括删除所有历史版本和删除标记（Delete Markers）
   • 确保备份完全被清理，不会占用额外存储空间
   • 如果未启用版本控制，会执行标准的删除操作