livingdocs/postgres

Postgres 17.2 Docker镜像文档

镜像概述与主要用途

基于Debian构建的生产就绪型PostgreSQL 17.2 Docker镜像，专注于高可用性部署。集成wal-g和pg_auto_failover工具，提供WAL归档、备份及自动故障转移能力，简化流复制配置，适用于对数据库可靠性有高要求的生产环境。

核心功能与特性

• 系统基础：基于Debian系统构建，确保兼容性与稳定性
• 扩展支持：包含postgres-contrib扩展包，默认启用pg_stat_statements性能统计扩展
• 高可用工具：
  • 集成https://github.com/wal-g/wal-g%EF%BC%8C%E6%94%AF%E6%8C%81WAL%EF%BC%88Write-Ahead Logging）归档与传输
  • 集成https://github.com/citusdata/pg_auto_failover%EF%BC%8C%E5%AE%9E%E7%8E%B0%E8%87%AA%E5%8A%A8%E6%95%85%E9%9A%9C%E8%BD%AC%E7%A7%BB
• 运行安全：以postgres用户（uid 1000，gid 1000）运行，遵循最小权限原则
• 启动优化：启动时不执行权限修复操作，加快容器初始化速度
• 升级友好：无Dockerfile VOLUME声明，避免pg_upgrade --link命令使用冲突
• 复制简化：提供便捷命令工具，简化流复制集群配置流程

使用场景与适用范围

• 生产环境中的高可用性PostgreSQL部署
• 需要WAL归档、备份及时间点恢复（PITR）的场景
• 需自动故障转移能力的数据库集群架构
• 简化流复制配置与管理的需求场景
• 需从旧版本PostgreSQL平滑升级的迁移场景

使用方法与配置说明

基本部署：创建容器并命名

bash
# 使用密码保护，默认情况下镜像已配置安全设置
docker run -d --name postgres -p 5432:5432 -v postgres:/var/lib/postgresql -e POSTGRES_PASSWORD=somepassword livingdocs/postgres:17.2

升级现有PostgreSQL容器

bash
# 假设已创建旧版本容器（示例为14.5）
docker run -d --name postgres -p 5432:5432 -v postgres:/var/lib/postgresql livingdocs/postgres:14.5

# 首先停止旧容器，然后运行升级镜像
docker stop postgres
docker run --rm -v postgres:/var/lib/postgresql livingdocs/postgres:17.2-upgrade

# 升级成功后，使用新镜像启动并挂载现有卷
docker run -d --name postgres -p 5432:5432 -v postgres:/var/lib/postgresql livingdocs/postgres:17.2

手动构建镜像

常规构建

bash
docker build -t livingdocs/postgres:17.2 .

使用buildx构建多架构镜像

bash
# 构建并推送多架构镜像（amd64/arm64）至Docker Hub
docker buildx build --platform linux/amd64,linux/arm64 -t livingdocs/postgres:17.2 --push .

# 构建升级版本镜像
docker buildx build --platform linux/amd64,linux/arm64 -t livingdocs/postgres:17.2-upgrade --push -f Dockerfile.upgrade .

使用nerdctl在lima/containerd环境构建

bash
# 构建多架构镜像
nerdctl build --platform=amd64,arm64 -t livingdocs/postgres:17.2 .
nerdctl build --platform=amd64,arm64 -t livingdocs/postgres:17.2-upgrade -f Dockerfile.upgrade .

# 推送所有架构镜像
lima nerdctl push --all-platforms livingdocs/postgres:17.2
lima nerdctl push --all-platforms livingdocs/postgres:17.2-upgrade

配置流复制

简单配置

bash
# 创建主从容器
docker run -d -p 5433:5432 --name postgres-1 livingdocs/postgres:17.2
docker run -d -p 5434:5432 --name postgres-2 livingdocs/postgres:17.2 standby -d "host=host.docker.internal port=5433 user=postgres target_session_attrs=read-write"

# 测试复制功能
docker exec postgres-1 psql -c "CREATE TABLE hello (value text); INSERT INTO hello(value) VALUES('world');"
docker exec postgres-2 psql -c "SELECT * FROM hello;"
# 输出：
#   value
#  -------
#  world
#  (1 row)

高级配置（使用密码认证）

bash
# 创建Docker网络模拟生产环境DNS解析
docker network create local

# 启动主库容器
docker run -d -p 5433:5432 --name postgres-1 --network=local --network-alias=postgres -e POSTGRES_HOST_AUTH_METHOD=md5 livingdocs/postgres:17.2

# 初始化数据库用户（也可在集群启动时挂载SQL脚本至/var/lib/postgresql/initdb.d自动执行）
docker exec postgres-1 psql -c "ALTER ROLE postgres ENCRYPTED PASSWORD 'some-postgres-password';"
docker exec postgres-1 psql -c "CREATE USER replication REPLICATION LOGIN ENCRYPTED PASSWORD 'some-replication-password';"

# 启动副本容器
export DB_URL="host=postgres port=5432 user=replication password=some-replication-password target_session_attrs=read-write"
docker run -d -p 5434:5432 --name postgres-2 --network=local --network-alias=postgres livingdocs/postgres:17.2 standby -d $DB_URL
docker run -d -p 5435:5432 --name postgres-3 --network=local --network-alias=postgres livingdocs/postgres:17.2 standby -d $DB_URL

# 测试复制功能
docker exec postgres-1 psql -c "CREATE TABLE hello (value text); INSERT INTO hello(value) VALUES('hello');"
docker exec postgres-2 psql -c "SELECT * FROM hello;"
docker exec postgres-3 psql -c "SELECT * FROM hello;"
# 两个副本输出均为：
#  value
# -------
# hello
# (1 row)


#
# 测试手动提升副本为主库
#
docker rm -f postgres-1

# 此时向副本插入数据会失败：ERROR:  cannot execute INSERT in a read-only transaction
docker exec postgres-2 psql -c "INSERT INTO hello(value) VALUES('world');"

# 提升副本
docker exec postgres-2 touch /var/lib/postgresql/data/promote.signal

# 验证提升结果
docker exec postgres-2 psql -c "INSERT INTO hello(value) VALUES('world');"
docker exec postgres-3 psql -c "SELECT * FROM hello;"
# 输出均为：
#  value
# -------
#  hello
#  world
# (2 rows)

提升副本为主库

注意：提升前需确保旧主库已停止接受写入，可通过停止容器或执行以下SQL命令实现：

sql
ALTER SYSTEM SET default_transaction_read_only TO 'on';
SELECT pg_terminate_backend(pg_stat_activity.pid) FROM pg_stat_activity WHERE pid <> pg_backend_pid();

提升副本有两种方式：

1. 在副本容器的数据目录创建promote.signal文件：

   bash
   touch /var/lib/postgresql/data/promote.signal
   

   若修改过配置，需确保promote_trigger_file参数指向该路径

2. 在容器内执行pg_ctl promote命令：

   bash
   gosu postgres pg_ctl promote
   

配置参数与环境变量