PostgreSQL Backup 镜像文档

1. 镜像概述

1.1 主要用途

该镜像专为 PostgreSQL 数据库提供自动化备份解决方案，通过集成 pg_dump 工具与定时任务调度功能，实现数据库全量/增量备份、备份文件管理及存储策略的统一配置，适用于开发、测试及生产环境的 PostgreSQL 数据保护需求。

2. 核心功能与特性

3. 使用场景与适用范围

3.1 典型场景

• 开发/测试环境：定期备份数据库，避免开发过程中数据丢失。
• 生产环境：配置高频率备份（如每小时）+ 长期保留策略，满足数据容灾需求。
• 多实例管理：通过统一镜像配置，实现多套 PostgreSQL 实例的标准化备份流程。

3.2 适用版本

兼容 PostgreSQL 9.6+ 版本（需确保 pg_dump 版本与数据库服务版本匹配）。

4. 使用方法与配置说明

4.1 快速启动（docker run）

通过 docker run 命令快速创建备份任务，示例如下（本地存储+每日备份）：

bash
docker run -d \
  --name postgres-backup \
  -e POSTGRES_HOST=postgres-server \    # PostgreSQL 服务地址
  -e POSTGRES_PORT=5432 \              # PostgreSQL 端口
  -e POSTGRES_USER=backup_user \       # 具备备份权限的数据库用户
  -e POSTGRES_PASSWORD=SecurePass123 \ # 数据库用户密码
  -e POSTGRES_DB=target_db \           # 需备份的数据库名（多库用逗号分隔）
  -e BACKUP_SCHEDULE="0 2 * * *" \     # cron 表达式：每日凌晨 2 点执行
  -e BACKUP_RETENTION_DAYS=7 \         # 保留最近 7 天备份
  -v /host/backup/dir:/backup \        # 本地挂载备份目录
  postgres-backup:latest

4.2 环境变量配置

4.3 Docker Compose 示例

以下为与 PostgreSQL 服务联动的 docker-compose.yml 配置示例：

yaml
version: '3.8'

services:
  postgres:
    image: postgres:14-alpine
    environment:
      POSTGRES_USER: backup_user
      POSTGRES_PASSWORD: SecurePass123
      POSTGRES_DB: target_db
    volumes:
      - postgres-data:/var/lib/postgresql/data
    restart: unless-stopped

  postgres-backup:
    image: postgres-backup:latest
    depends_on:
      - postgres
    environment:
      POSTGRES_HOST: postgres
      POSTGRES_PORT: 5432
      POSTGRES_USER: backup_user
      POSTGRES_PASSWORD: SecurePass123
      POSTGRES_DB: target_db
      BACKUP_SCHEDULE: "0 2 * * *"       # 每日凌晨 2 点备份
      BACKUP_RETENTION_DAYS: 7           # 保留 7 天备份
      BACKUP_FORMAT: "custom"            # 使用 pg_dump 自定义格式（支持增量恢复）
    volumes:
      - /host/backup/dir:/backup         # 本地备份目录
    restart: unless-stopped

volumes:
  postgres-data:

4.4 备份文件管理

• 文件命名规则：{数据库名}_{备份时间戳}.{格式}.gz（如 target_db_20240520_020000.custom.gz）。
• 清理机制：容器启动时及每次备份后，自动删除超过 BACKUP_RETENTION_DAYS 天数的文件。

4.5 恢复方法

使用 pg_restore 工具恢复备份文件（以 custom 格式为例）：

bash
# 从本地备份文件恢复
pg_restore -h postgres-host -U postgres-user -d target_db /backup/target_db_20240520_020000.custom.gz

5. 注意事项

1. 权限配置：挂载的本地备份目录需确保容器内用户（通常为 postgres 或 root）有读写权限。
2. 版本兼容性：镜像内置的 pg_dump 版本需与 PostgreSQL 服务版本一致，避免备份格式不兼容。
3. 密码安全：生产环境建议通过 Docker Secrets 或环境变量文件传递密码，避免明文暴露。
4. 网络连通性：确保备份容器与 PostgreSQL 服务之间网络通畅（可通过 docker network 互联）。
5. 备份验证：定期手动验证备份文件完整性，建议结合监控工具（如 Prometheus）跟踪备份状态。