prodrigestivill/postgres-backup-local

!GitHub stars !GitHub issues https://github.com/prodrigestivill/docker-postgres-backup-local/actions/workflows/ci.yml/badge.svg?branch=main](https://github.com/prodrigestivill/docker-postgres-backup-local/actions)

prodrigestivill/postgres-backup-local

基于https://hub.docker.com/r/schickling/postgres-backup-s3/%EF%BC%8C%E5%B0%86PostgreSQL%E6%95%B0%E6%8D%AE%E5%BA%93%E5%A4%87%E4%BB%BD%E5%88%B0%E6%9C%AC%E5%9C%B0%E6%96%87%E4%BB%B6%E7%B3%BB%E7%BB%9F%EF%BC%8C%E5%B9%B6%E6%94%AF%E6%8C%81%E5%AE%9A%E6%9C%9F%E8%BD%AE%E6%8D%A2%E5%A4%87%E4%BB%BD%E3%80%82%E9%80%9A%E8%BF%87%E5%9C%A8%60POSTGRES_DB%60%E4%B8%AD%E7%94%A8%E9%80%97%E5%8F%B7%E6%88%96%E7%A9%BA%E6%A0%BC%E5%88%86%E9%9A%94%E6%95%B0%E6%8D%AE%E5%BA%93%E5%90%8D%E7%A7%B0%EF%BC%8C%E5%8F%AF%E5%A4%87%E4%BB%BD%E5%90%8C%E4%B8%80%E4%B8%BB%E6%9C%BA%E4%B8%8A%E7%9A%84%E5%A4%9A%E4%B8%AA%E6%95%B0%E6%8D%AE%E5%BA%93%E3%80%82

支持以下Docker架构：linux/amd64、linux/arm64、linux/arm/v7、linux/s390x、linux/ppc64le。

请务必详细阅读备份文件夹工作原理。

本应用要求/backups docker卷为POSIX兼容文件系统（主要支持硬链接和软链接），因此VFAT、EXFAT、SMB/CIFS等文件系统无法与此docker镜像一起使用。

使用方法

Docker：

sh
docker run -u postgres:postgres -e POSTGRES_HOST=postgres -e POSTGRES_DB=dbname -e POSTGRES_USER=user -e POSTGRES_PASSWORD=password  prodrigestivill/postgres-backup-local

Docker Compose：

yaml
services:
    postgres:
        image: postgres
        restart: always
        environment:
            - POSTGRES_DB=database
            - POSTGRES_USER=username
            - POSTGRES_PASSWORD=password
         #  - POSTGRES_PASSWORD_FILE=/run/secrets/db_password <-- POSTGRES_PASSWORD的替代方案（用于docker secrets）
    pgbackups:
        image: prodrigestivill/postgres-backup-local
        restart: always
        user: postgres:postgres # 可选：详见下文
        volumes:
            - /var/opt/pgbackups:/backups
        links:
            - postgres
        depends_on:
            - postgres
        environment:
            - POSTGRES_HOST=postgres
            - POSTGRES_DB=database
            - POSTGRES_USER=username
            - POSTGRES_PASSWORD=password
         #  - POSTGRES_PASSWORD_FILE=/run/secrets/db_password <-- POSTGRES_PASSWORD的替代方案（用于docker secrets）
            - POSTGRES_EXTRA_OPTS=-Z1 --schema=public --blobs
            - SCHEDULE=@daily
            - BACKUP_ON_START=TRUE
            - BACKUP_KEEP_DAYS=7
            - BACKUP_KEEP_WEEKS=4
            - BACKUP_KEEP_MONTHS=6
            - HEALTHCHECK_PORT=8080

出于安全考虑，建议以postgres:postgres用户运行。

若以postgres用户运行，系统管理员需按以下方式初始化目标文件夹权限：

sh
# 对于默认镜像（debian）
mkdir -p /var/opt/pgbackups && chown -R 999:999 /var/opt/pgbackups
# 对于alpine镜像
mkdir -p /var/opt/pgbackups && chown -R 70:70 /var/opt/pgbackups

环境变量

大多数变量与https://hub.docker.com/_/postgres/%E7%9B%B8%E5%90%8C%E3%80%82

特殊环境变量

这些变量不用于正常部署操作：

备份文件夹工作原理

首先，新备份会创建在last文件夹中，文件名包含完整时间。

备份成功完成后，会通过硬链接（而非复制，以避免占用更多空间）将其链接到其他文件夹（daily、weekly和monthly）。此步骤会替换该类别的旧备份，始终只保留每个类别的最新备份（因此每月备份存储的是该月的最新备份，而非第一个）。

备份文件夹结构如下：

• BACKUP_DIR/last/DB-YYYYMMDD-HHmmss.sql.gz：所有备份单独存储在此文件夹中。
• BACKUP_DIR/daily/DB-YYYYMMDD.sql.gz：始终存储（硬链接）当天的最新备份。
• BACKUP_DIR/weekly/DB-YYYYww.sql.gz：始终存储（硬链接）当周的最新备份（由于使用ISO周编号，周末为周日）。
• BACKUP_DIR/monthly/DB-YYYYMM.sql.gz：始终存储（硬链接）当月的最新备份（通常为每月最后一天）。

每次成功备份后，还会更新以下符号链接以便使用：

BACKUP_DIR/last/DB-latest.sql.gz -> BACKUP_DIR/last/DB-YYYYMMDD-HHmmss.sql.gz
BACKUP_DIR/daily/DB-latest.sql.gz -> BACKUP_DIR/daily/DB-YYYYMMDD.sql.gz
BACKUP_DIR/weekly/DB-latest.sql.gz -> BACKUP_DIR/weekly/DB-YYYYww.sql.gz
BACKUP_DIR/monthly/DB-latest.sql.gz -> BACKUP_DIR/monthly/DB-YYYYMM.sql.gz

清理时，脚本仅在新备份成功后删除各分类的旧文件：

• BACKUP_KEEP_MINS：新备份成功后，删除last文件夹中超过指定分钟数的文件（不影响其他备份，因为它们是硬链接）。
• BACKUP_KEEP_DAYS：新备份成功后，删除daily文件夹中超过指定天数的文件。
• BACKUP_KEEP_WEEKS：新备份成功后，删除weekly文件夹中超过指定周数的文件（从每周结束开始计数，而非开始）。
• BACKUP_KEEP_MONTHS：新备份成功后，删除monthly文件夹中超过指定月数（按31天计）的文件（从每月结束开始计数，而非开始）。

Hooks

容器内的hooks文件夹可包含在不同情况下运行的钩子脚本，第一个参数为具体状态（error：错误，pre-backup：备份前，post-backup：备份后）。

只需在该文件夹中创建具有执行权限的脚本，run-parts会在每个状态变化时执行它。

作为示例，可查看已存在的实现WEBHOOK_URL功能的脚本。

手动备份

默认情况下，容器每日执行备份，但可通过运行/backup.sh手动启动备份。

以下示例脚本以运行用户身份创建一个备份，并保存到工作目录：

sh
docker run --rm -v "$PWD:/backups" -u "$(id -u):$(id -g)" -e POSTGRES_HOST=postgres -e POSTGRES_DB=dbname -e POSTGRES_USER=user -e POSTGRES_PASSWORD=password  prodrigestivill/postgres-backup-local /backup.sh

自动定期备份

可通过-e SCHEDULE="@daily"修改SCHEDULE环境变量来更改默认备份频率，默认为daily（每日）。

调度相关更多信息可查看此处。

daily、weekly和monthly文件夹通过硬链接创建和填充，以节省磁盘空间。

恢复示例

以下是恢复/应用备份的示例。

使用同一容器恢复

要使用同一备份容器恢复，替换以下命令中的$BACKUPFILE（备份文件路径）、$CONTAINER（容器名）、$USERNAME（用户名）和$DBNAME（数据库名）：

sh
docker exec --tty --interactive $CONTAINER /bin/sh -c "zcat $BACKUPFILE | psql --username=$USERNAME --dbname=$DBNAME -W"

使用新容器恢复

替换以下命令中的$BACKUPFILE（备份文件路径）、$VERSION（postgres版本）、$HOSTNAME（主机名）、$PORT（端口）、$USERNAME（用户名）和$DBNAME（数据库名）：

sh
docker run --rm --tty --interactive -v $BACKUPFILE:/tmp/backupfile.sql.gz postgres:$VERSION /bin/sh -c "zcat /tmp/backupfile.sql.gz | psql --host=$HOSTNAME --port=$PORT --username=$USERNAME --dbname=$DBNAME -W"