heyman/postgresql-backup

Docker PostgreSQL Backup

Docker镜像，用于定期备份PostgreSQL数据库，并可选择将备份文件上传到Amazon S3存储桶。

Docker Hub地址：https://hub.docker.com/r/heyman/postgresql-backup

示例

bash
docker run -it --rm --name=pgbackup \
    -e CRON_SCHEDULE="* * * * *" \
    -e DB_HOST=数据库主机地址 \
    -e DB_USER=用户名 \
    -e DB_PASS=密码 \
    -e DB_NAME=数据库名称 \
    -e S3_PATH='s3://我的存储桶/备份目录/' \
    -e AWS_ACCESS_KEY_ID='[AWS访问密钥ID]' \
    -e AWS_SECRET_ACCESS_KEY='[AWS密钥]' \
    heyman/postgresql-backup:15

必需环境变量

• CRON_SCHEDULE: crontab文件中的时间调度表达式（例如：15 3 * * * 表示每天凌晨03:15执行备份）
• DB_HOST: PostgreSQL主机名
• DB_PASS: PostgreSQL密码
• DB_USER: PostgreSQL用户名
• DB_NAME: 数据库名称

可选环境变量

• S3_PATH: Amazon S3路径，格式为：s3://存储桶名称/路径
• AWS_ACCESS_KEY_ID: AWS访问密钥ID（与S3_PATH配合使用）
• AWS_SECRET_ACCESS_KEY: AWS密钥（与S3_PATH配合使用）
• AWS_DEFAULT_REGION: AWS区域
• S3_STORAGE_CLASS: 指定上传对象的S3存储类别，默认值为STANDARD_IA
• S3_EXTRA_OPTIONS: 为S3添加额外选项，例如--endpoint=用于自定义S3服务提供商
• DB_USE_ENV: 从环境变量注入PostgreSQL环境变量，忽略DB_HOST、DB_PASS、DB_USER和DB_NAME，可用于配置高级连接（如mTLS连接）。
  容器环境变量文件示例（--env-file=.env）：

  DB_USE_ENV=True
  PGSSLMODE=verify-full
  PGSSLROOTCERT=/path/ca.crt
  PGSSLCERT=<path>/user.crt
  PGSSLKEY=<path>/user.key
  PGHOSTADDR=1.2.3.4
  PGHOST=db.domain.com
  PGUSER=myuser
  PGDATABASE=mydb
  

• MAIL_TO: 若同时指定MAIL_TO和MAIL_FROM，每次备份后将通过Amazon SES发送邮件通知
• MAIL_FROM: 邮件发送地址（与MAIL_TO配合使用）
• WEBHOOK: 指定HTTP请求URL，备份后将发送请求
• WEBHOOK_METHOD: Webhook的HTTP方法，默认GET，可通过此变量修改
• WEBHOOK_CURL_OPTIONS: 为curl命令添加额外选项（如请求头），例如-H 'Content-type: application/json'
• WEBHOOK_DATA: Webhook请求体内容，默认隐含使用POST方法，支持变量插值（如{"text":"备份完成于 %(date)s %(time)s!"}）
• KEEP_BACKUP_DAYS: 保留备份文件的天数，默认7天
• FILENAME: 备份文件名格式字符串（通过strftime()处理），默认$DB_NAME_%Y-%m-%d
• PG_DUMP_EXTRA_OPTIONS: pg_dump命令的额外选项，例如--exclude-table-data=table_name用于排除表数据

变量插值

WEBHOOK_DATA中的文本支持通过%(变量)s格式插入以下变量：

• date: 日期（yyyy-mm-dd格式）
• time: 时间（hh:mm:ss格式）
• duration: 备份耗时（秒）
• filename: 上传到S3的文件名
• size: 备份文件大小（带单位，如MB、GB）

Slack消息通知示例

1. 按照Slack文档配置Webhook
2. 设置相关环境变量：

   WEBHOOK=https://hooks.slack.com/services/.../.../...
   WEBHOOK_METHOD=POST
   WEBHOOK_CURL_OPTIONS=-H 'Content-type: application/json'
   WEBHOOK_DATA={"text":":white_check_mark: 备份完成于 %(date)s %(time)s\n耗时: %(duration)s 秒\n文件: %(filename)s (%(size)s)"}
   

数据卷

• /data/backups - 数据库备份文件存储目录

恢复备份

可通过一次性任务恢复备份，将容器命令设置为python -u /backup/restore.py [backup-filename]（[backup-filename]为备份文件名，若需从S3下载则需配置S3相关环境变量）。

必需环境变量

• DB_HOST: PostgreSQL主机名
• DB_PASS: PostgreSQL密码
• DB_USER: PostgreSQL用户名
• DB_NAME: 目标数据库名称

从S3恢复时的额外必需环境变量

• S3_PATH: Amazon S3目录路径（格式：s3://存储桶名称/路径）
• AWS_ACCESS_KEY_ID
• AWS_SECRET_ACCESS_KEY
• AWS_DEFAULT_REGION

其他可选环境变量

• S3_EXTRA_OPTIONS: S3额外选项（如自定义服务端点）
• DB_USE_ENV: 高级连接配置（见可选环境变量）

执行一次性备份

首次配置时可执行一次性备份测试，将容器命令设置为python -u /backup/backup.py，并传入所有必需环境变量。

Docker标签

基于PostgreSQL官方Alpine镜像构建，可用标签对应PostgreSQL版本：

• 16、latest
• 15
• 14
• 13
• 12
• 11
• 10