hleroy/backup-s3

backup-s3

镜像概述和主要用途

backup-s3 是一个 Docker 镜像，用于定期将数据库（PostgreSQL 或 MySQL）和/或数据文件夹备份到 Amazon S3，并支持通过单个命令恢复备份。典型用例是备份使用 docker-compose 运行的应用（如 Wordpress）。v3.0 版本支持指定 PostgreSQL 客户端版本（v13 至 v15），v2.2 版本支持 S3 兼容端点。

核心功能和特性

• 支持 PostgreSQL 和 MySQL 数据库备份
• 支持数据文件夹备份，可指定多个路径（用冒号分隔）
• 基于 cron 调度的定期备份
• 支持 Amazon S3 及 S3 兼容端点（如 Scaleway）
• 备份文件包含时间戳和随机字符串，确保唯一性
• 单命令立即备份和恢复功能
• 支持特定 PostgreSQL 客户端版本（v13 至 v15）

支持的标签

• v3.0-pg15, latest
• v3.0-pg14
• v3.0-pg13

使用场景和适用范围

适用于需要定期备份数据的 Docker 应用，特别是使用 docker-compose 部署的 Web 应用（如 Wordpress、博客系统、小型业务系统等），需将数据库和文件数据安全存储到 S3 或 S3 兼容存储服务的场景。

使用方法和配置说明

1. docker-compose 配置

在 docker-compose 文件中添加 backup-s3 服务。以下是备份 Wordpress 容器的示例：

yaml
  backup:
    image: hleroy/backup-s3
    init: true                   # 启用更快的容器终止
    volumes:
      - wordpress:/var/www/html  # 需要备份的卷
    environment:                 # 提供环境变量（S3 密钥等）
      BACKUP_ENABLED: yes        # 非空值即可启用备份
      # S3 设置
      S3_REGION: eu-central-1
      S3_BUCKET: my-bucket
      S3_ACCESS_KEY_ID: access_key_id
      S3_SECRET_ACCESS_KEY: secret_access_key
      # S3_ENDPOINT_URL:         # 可选：仅使用 S3 兼容端点时需要，如 https://s3.fr-par.scw.cloud
      # 数据库设置
      DB_ENGINE: mysql
      DB_NAME: wordpress
      DB_USER: wordpress
      DB_PASS: wordpress
      DB_HOST: mysql
      DB_PORT: 5432
      # 数据路径
      DATA_PATH: '/var/www/html' # 根据需求自定义
      # Cron 调度
      CRON_SCHEDULE: '0 0 * * *' # 每天午夜执行

2. 环境变量说明

必选变量

• BACKUP_ENABLED: 启用备份，非空值即可（如 yes、true）。若省略，容器以代码 0 退出。
• S3_REGION: S3 区域（如 eu-central-1）。
• S3_BUCKET: S3 存储桶名称。
• S3_ACCESS_KEY_ID: S3 访问密钥 ID。
• S3_SECRET_ACCESS_KEY: S3 密钥。

可选变量

• S3_ENDPOINT_URL: S3 兼容端点 URL（v2.2 新增），如 Scaleway 巴黎区域 https://s3.fr-par.scw.cloud。
• DB_ENGINE: 数据库引擎，可选 mysql 或 postgres。若省略，不执行数据库备份；若指定但缺少其他数据库设置，容器以代码 1 退出。
• DB_PORT: 数据库端口，默认 3306（MySQL）或 5432（PostgreSQL）。
• DATA_PATH: 数据文件夹绝对路径（无尾随斜杠），可指定多个路径（用冒号分隔，如 /path1:/path2）。若省略，不执行数据备份。
• CRON_SCHEDULE: cron 调度表达式，默认 0 0 * * *（每天午夜）。可使用 crontab.guru 生成自定义表达式。

3. 操作命令

定时备份

启动 Compose 应用后，备份将按 CRON_SCHEDULE 自动执行。备份文件名格式：时间戳.随机字符串.tgz（如 2020-04-22T00:00:01Z.87793a5e1556e0ff8a8b528328fab4ad.tgz）。

立即备份

执行以下命令触发立即备份：

bash
docker-compose run --rm backup no-cron

恢复备份

执行以下命令恢复指定备份（需提供不带扩展名的备份文件名）：

bash
docker-compose run --rm backup restore BACKUP_FILENAME

示例（恢复 2020-04-22T00:00:01Z.87793a5e1556e0ff8a8b528328fab4ad.tgz）：

bash
docker-compose run --rm backup restore 2020-04-22T00:00:01Z.87793a5e1556e0ff8a8b528328fab4ad

完整示例

仓库提供 Wordpress 的完整 docker-compose 示例（docker-compose-wp-example.yml），步骤如下：

1. 打开 docker-compose-wp-example.yml，填写 S3 区域、存储桶和凭证。
2. 启动应用：docker-compose -f docker-compose-wp-example.yml up -d。
3. 访问 http://localhost:8080 完成 Wordpress 设置。
4. 查看备份日志：docker-compose -f docker-compose-wp-example.yml logs --follow（每 15 分钟执行一次）。
5. 强制立即备份：docker-compose -f docker-compose-wp-example.yml run --rm backup no-cron。
6. 对 Wordpress 进行操作（如添加内容）。
7. 登录 AWS S3 控制台获取最新备份文件名。
8. 恢复备份：docker-compose -f docker-compose-wp-example.yml run --rm backup restore BACKUP_FILENAME。
9. 访问 http://localhost:8080 确认恢复成功。

安全注意事项

备份机密性

启用 Amazon S3 Block Public Access 功能，防止备份被公开访问。

限制 S3 权限

为避免***者删除备份，创建 IAM 策略仅授权 put 和 get 操作（禁止 list）。示例策略：

json
{
    "Version": "2012-10-17",
    "Statement": {
        "Effect": "Allow",
        "Action": [
            "s3:GetObject",
            "s3:PutObject"
        ],
        "Resource": [
            "arn:aws:s3:::your-bucket-1/*",
            "arn:aws:s3:::your-bucket-2/*",
            "arn:aws:s3:::your-bucket-3/*"
        ]
    }
}

备份文件唯一性

备份文件名包含随机字符串，即使容器被入侵，***者也难以猜测文件名。结合限制 S3 权限（仅 put 和 get），可防止覆盖旧备份。