postdock/postgres

PostDock - Postgres + Docker

适用于任何云环境和Docker环境（Amazon、Google Cloud、Kubernetes、Docker Compose、Docker Swarm、Apache Mesos）的PostgreSQL集群，具备高可用性和自我修复特性。

!https://raw.githubusercontent.com/paunin/PostDock/master/artwork/formula2.png

![构建状态]([***]

• 概述
  • 核心功能
  • 包含组件
  • Docker镜像标签约定
    • 仓库
• 使用docker-compose启动集群
• 在Kubernetes中启动集群
• 自适应模式
• SSH访问
• 复制槽
• 集群配置
  • Postgres
  • Pgpool
  • Barman
  • 其他配置
• Postgres扩展版本
• 备份与恢复
• 健康检查
• 常用命令
• 相关文章
• 场景说明
• 贡献指南
• 常见问题
• 文档与手册

概述

核心功能

• 高可用性
• 自我修复与自动重建
• 脑裂)容忍
• 最终一致性/部分严格一致性/严格一致性模式
• 读负载均衡与连接池
• 增量备份（可选零数据丢失，RPO=0）
• 半自动化时间点恢复流程
• 所有组件（节点、均衡器、备份）的监控导出器

包含组件

https://github.com/paunin/postgres-docker-cluster%E5%8C%85%E5%90%AB%EF%BC%9A

• 用于postgresql集群和备份系统的Dockerfile
  • postgresql
  • pgpool
  • barman
• 使用示例（适用于生产环境，架构具备自动故障转移的故障保护）
  • 启动集群的docker-compose文件示例
  • k8s目录包含在Kubernetes中构建此集群的相关信息

Docker镜像标签约定

考虑到PostDock项目本身有版本控制方案，仓库生成的所有Docker镜像遵循以下格式：postdock/<组件>:<postdock_version>-<component><component_version>-<sub_component><sub_component_version>[...]，其中：

• <postdock_version> - 不带bug-fix部分的语义化版本（如1.1、1.2等）
• <component>、<component_version> - 取决于组件：
  • postgres、postgres-extended - 主版本和次版本（无点，如95、96、10、11等）
  • pgpool - 组件的主版本和次版本（无点，如33、36、37等）
  • barman - 仅主版本（如23、24等）
• <sub_component>、<sub_component_version> - 取决于组件：
  • 对于postgres - repmgr版本（如32、40等）
  • 对于barman - postgres版本（如96、10、11等）
  • 对于pgpool - postgres版本（如96、10、11等）

别名可用**（不建议用于生产环境）**：

• postdock/<component>:latest-<component><component_version>[-<sub_component><sub_component_version>[...]] - 指向PostDock的最新发布版，特定组件版本和子组件版本（如postdock/postgres:latest-postgres101-repmgr32、postdock/postgres:latest-barman23-postgres101）
• postdock/<component>:latest - 指向PostDock的最新发布版以及所有组件和子组件的最新版本（如postdock/postgres:latest）
• postdock/<component>:edge - 指向PostDock的master分支构建，包含组件和所有子组件的最新版本（如postdock/postgres:edge）

仓库

所有可用标签（版本及组合）列于相应的Docker Hub仓库中：

• https://hub.docker.com/r/postdock/postgres
• https://hub.docker.com/r/postdock/pgpool
• https://hub.docker.com/r/postdock/barman

使用docker-compose启动集群

要启动集群，以常规docker-compose应用方式运行：docker-compose -f ./docker-compose/latest.yml up -d pgmaster pgslave1 pgslave2 pgslave3 pgslave4 pgpool backup

示例集群架构：

pgmaster (主节点1)  --|
|- pgslave1 (节点2)       --|
|  |- pgslave2 (节点3)    --|----pgpool (主从流模式)
|- pgslave3 (节点4)       --|
   |- pgslave4 (节点5)    --|

每个postgres节点（pgmaster、pgslaveX）由repmgr/repmgrd管理，支持自动故障转移和集群状态检查。

请查看./docker-compose/latest.yml文件中每个环境变量的注释，以了解集群节点的参数。

在Kubernetes中启动集群

使用Helm（生产环境推荐）

可通过Helm包管理器安装PostDock，详情参见包的README.md。

简易方式（不推荐用于生产环境）

为简化操作，仓库在k8s目录下提供了服务对象。按照示例中的步骤设置PostgreSQL集群，其中还包含检查集群状态的方法。

集群配置

可通过环境变量CONFIGS配置集群的任何节点（postgres.conf）或pgpool（pgpool.conf）（格式：variable1:value1[,variable2:value2[,...]]，可通过变量CONFIGS_DELIMITER_SYMBOL和CONFIGS_ASSIGNMENT_SYMBOL重新定义分隔符和赋值符号）。同时，请查看仓库根目录下的Dockerfile和docker-compose/latest.yml文件，以了解所有可用和已使用的配置！

Postgres

其他配置建议参考src/Postgres-latest.Dockerfile文件，其中包含详细注释。

Pgpool

Pgpool中除常规CONFIGS外，最重要的配置是后端和可访问这些后端的用户。可通过环境变量配置后端。docker-compose/latest.yml文件中提供了Pgpool的配置示例：

DB_USERS: monkey_user:monkey_pass # 格式：user:password[,user:password[...]]
BACKENDS: "0:pgmaster:5432:1:/var/lib/postgresql/data:ALLOW_TO_FAILOVER,1:pgslave1::::,3:pgslave3::::,2:pgslave2::::" #,4:pgslaveDOES_NOT_EXIST::::
            # 格式：num:host:port:weight:data_directory:flag[,...]
            # 默认值：
            #   port: 5432
            #   weight: 1
            #   data_directory: /var/lib/postgresql/data
            #   flag: ALLOW_TO_FAILOVER
REQUIRE_MIN_BACKENDS: 3 # 启动pgpool所需的最小后端数量（部分可能不可达）

Barman

Barman最重要的配置是访问变量。docker-compose/latest.yml文件中提供了示例：

REPLICATION_USER: replication_user # 默认值为replication_user
REPLICATION_PASSWORD: replication_pass # 默认值为replication_pass
REPLICATION_HOST: pgmaster
POSTGRES_PASSWORD: monkey_pass
POSTGRES_USER: monkey_user
POSTGRES_DB: monkey_db

其他配置

请查看仓库根目录下的Dockerfile和docker-compose/latest.yml文件，以了解所有可用和已使用的配置！

自适应模式

“自适应模式”指节点在启动时能够决定是作为主节点运行还是切换到备用角色。通过传递PARTNER_NODES（同一层级集群节点的逗号分隔列表）实现。每次容器启动时，会检查自身之前是否为主节点，以及PARTNER_NODES列表中是否存在新主节点；否则，将作为新的备用节点启动，集群中upstream = new master。

注意：此功能不适用于级联复制，不应向集群第二层节点传递PARTNER_NODES。应确保第一层所有节点运行，以便第二层节点重启后能从第一层的初始上游节点同步。这也意味着第二层复制可能连接到根主节点...如果决定使用自适应模式，这影响不大。但仍可通过NODE_PRIORITY环境变量确保第二层复制的入口点不会被选举为新的根主节点。

SSH访问

如需使用复杂逻辑或减少跨节点检查问题，可在每个节点上启用SSH服务器。只需在所有容器（包括pgpool和barman）中设置环境变量SSH_ENABLE=1（默认禁用）。这允许通过postgres用户执行简单命令连接到任何节点：gosu postgres ssh {节点网络名称}。

还需为所有容器设置相同的SSH密钥，需将密钥文件挂载到/tmp/.ssh/keys/id_rsa和/tmp/.ssh/keys/id_rsa.pub路径。

复制槽

如要禁用Postgres>=9.4的复制槽功能，只需设置环境变量USE_REPLICATION_SLOTS=0（默认启用）。此时集群将仅依赖Postgres配置wal_keep_segments（默认值500）。还需注意，配置max_replication_slots的默认值为5，可通过环境变量CONFIGS修改（与其他配置相同）。

Postgres扩展版本

Docker镜像标签约定中的postgres-extended组件适用于需要包含扩展和库的Postgres。此处的每个目录代表镜像中包含的扩展。

备份与恢复

Barman用于提供实时备份和时间点恢复（PITR）。此镜像需要连接信息（主机、端口）和两组凭证，如Dockerfile所示：

• 复制凭证
• Postgres管理员凭证

Barman作为热备用从源端流式传输WAL。此外，它定期使用pg_basebackup进行远程物理备份。这允许在指定大小的窗口内以合理时间进行PITR（只需重放最新基础备份后的WAL）。Barman根据保留策略自动删除旧备份和WAL。备份源是静态的——pgmaster节点。主节点故障转移后，备份将继续从备用服务器进行。整个备份过程远程执行，但恢复需要SSH访问。

生产环境使用前请阅读以下文档：

• [***]
• [***]

灾难恢复流程参见RECOVERY.md

Barman在:8080/metrics上公开多个指标，详情参见Barman文档。

健康检查

为确保集群正常运行（无“脑裂”或其他问题），需设置健康检查，当任何健康检查返回非零结果时停止容器。在Kubernetes中使用存活探针（livenessProbe）非常有用（参见示例中的使用方法）。

• Postgres容器：
  • /usr/local/bin/cluster/healthcheck/is_major_master.sh - 检测节点是否为“伪”主节点且存在另一个拥有更多备用节点的主节点
• Pgpool
  • /usr/local/bin/pgpool/has_enough_backends.sh [REQUIRED_NUM_OF_BACKENDS, 默认=$REQUIRE_MIN_BACKENDS] - 检查pgpool后端数量是否足够
  • /usr/local/bin/pgpool/has_write_node.sh - 检查是否有后端可作为具有写权限的主节点

常用命令

• 获取当前集群映射（在任何postgres节点上）：
  • gosu postgres repmgr cluster show - 尝试连接所有请求节点，忽略$(get_repmgr_schema).$REPMGR_NODES_TABLE中的节点状态
  • gosu postgres psql $REPLICATION_DB -c "SELECT * FROM $(get_repmgr_schema).$REPMGR_NODES_TABLE" - 直接查询表数据
• 获取pgpool状态（在任何pgpool节点上）：PGPASSWORD=$CHECK_PASSWORD psql -U $CHECK_USER -h localhost template1 -c "show pool_nodes"
• 在pgpool容器中检查主节点是否存在：/usr/local/bin/pgpool/has_write_node.sh

任何命令可通过docker-compose或kubectl执行：docker-compose exec {节点} bash -c '{命令}'或kubectl exec {Pod名称} -- bash -c '{命令}'

场景说明

参见文档了解故障转移、脑裂抵抗和恢复的不同情况。

相关文章

• ***文章
• habr上的文章

贡献指南

参见文档了解贡献方式。

常见问题

• 实际使用示例：
  • Lazada/阿里巴巴集团
• 为何不使用https://github.com/sorintlab/stolon%EF%BC%9A
  • 复杂逻辑，包含大量Go代码
  • 非Postgres生态系统的标准工具
• 如何在Docker环境下的PostgreSQL故障转移后提升主节点
• 中间节点（如pgslave1）故障将导致整个分支不可用
  • 这是合理的，因为第二层或更深层的复制不应连接到根主节点（会增加服务器负载）或更改上游。

文档与手册

• Postgres流式复制：[***]
• Repmgr：https://github.com/2ndQuadrant/repmgr
• Pgpool2：[***]
• Barman：[***]
• Kubernetes：[***]