paunin/postdock-pgsql

PostDock - Postgres + Docker

Postgres流复制集群，适用于任何Docker环境（Kubernetes、Docker Compose、Docker Swarm、Apache Mesos）

• 概述
  • 发布内容
  • 包含组件
  • 镜像标签约定
• 示例集群架构
• 使用Docker Compose启动集群
• 在Kubernetes中启动集群
• 自适应模式
• SSH访问
• 复制槽
• 集群配置
  • Postgres
  • Pgpool
  • Barman
  • 其他配置
• Postgres扩展版本
• 备份与恢复
• 健康检查
• 常用命令
• 场景说明
• 贡献方式
• 常见问题
• 文档与手册

概述

发布内容

• Medium文章
• Habr文章

包含组件

该项目包含：

• PostgreSQL集群的Dockerfile
  • postgresql
  • pgpool
• 生产环境可用的使用示例（具备故障自动转移的容错架构）
  • docker-compose.yml文件示例
  • k8s目录包含Kubernetes集群部署信息

镜像标签约定

PostDock项目镜像标签格式为：postdock/<组件>:<postdock版本>-<组件><组件版本>，其中：

• <组件>：可选值为postgres、postgres-extended、pgpool、barman
• <postdock版本>：语义化版本（不含bug-fix部分）
• <组件版本>：
  • postgres：主版本+次版本（无点，如95、96、100）
  • pgpool：主版本+次版本（无点，如33、36）
  • barman：主版本（如2、3）

别名：

• postdock/<组件>:latest-<组件><组件版本>：指向PostDock最新版本和指定组件版本
• postdock/<组件>:latest：指向PostDock和组件的最新版本

master分支构建无别名

示例集群架构

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

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

使用Docker Compose启动集群

执行常规Docker Compose命令启动集群：
docker-compose up -d

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

在Kubernetes中启动集群

仓库k8s目录下包含服务对象配置。参考示例步骤设置PostgreSQL集群，可查看集群状态：

从任意DB节点Pod执行：

Role      | Name  | Upstream | Connection String
----------+-------|----------|---------------------------------------------------------------------------------------------------------------------
* master  | node1 |          | user=replica_user password=replica_pass host=mysystem-db-node1-service dbname=replica_db port=5432 connect_timeout=2
  standby | node4 | node1    | user=replica_user password=replica_pass host=mysystem-db-node4-service dbname=replica_db port=5432 connect_timeout=2
  standby | node2 | node1    | user=replica_user password=replica_pass host=mysystem-db-node2-service dbname=replica_db port=5432 connect_timeout=2
  standby | node3 | node2    | user=replica_user password=replica_pass host=mysystem-db-node3-service dbname=replica_db port=5432 connect_timeout=2
  standby | node5 | node4    | user=replica_user password=replica_pass host=mysystem-db-node5-service dbname=replica_db port=5432 connect_timeout=2

从任意Pgpool Pod执行：

 node_id |         hostname          | port | status | lb_weight |  role   | select_cnt | load_balance_node | replication_delay
---------+---------------------------+------+--------+-----------+---------+------------+-------------------+-------------------
 0       | mysystem-db-node1-service | 5432 | up     | 0.200000  | primary | 0          | false             | 0
 1       | mysystem-db-node2-service | 5432 | up     | 0.200000  | standby | 0          | false             | 0
 2       | mysystem-db-node3-service | 5432 | up     | 0.200000  | standby | 0          | false             | 0
 3       | mysystem-db-node4-service | 5432 | up     | 0.200000  | standby | 0          | false             | 0
 4       | mysystem-db-node5-service | 5432 | up     | 0.200000  | standby | 0          | true              | 0
(5 rows)

集群配置

可通过环境变量CONFIGS配置集群节点（postgres.conf）或Pgpool（pgpool.conf），格式：variable1:value1[,variable2:value2[,...]]。建议查看Dockerfile和根目录的docker-compose.yml了解所有可用配置。

Postgres

建议查看Postgres-latest.Dockerfile文件，其中包含详细注释。

Pgpool

Pgpool的关键配置包括后端节点和访问用户，可通过环境变量设置。示例参考docker-compose.yml：

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::::" # 格式：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.yml：

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

其他配置

请查看Dockerfile和根目录的docker-compose.yml了解所有可用配置！

自适应模式

自适应模式允许节点启动时自动判断角色：若为原主节点且无新主节点（来自PARTNER_NODES列表），则保持主角色；否则作为从节点启动，上游为新主节点。

注意：该功能不适用于级联复制，二级节点不应设置PARTNER_NODES。可通过NODE_PRIORITY环境变量调整节点优先级，避免二级节点成为根主节点。

SSH访问

若需复杂逻辑或跨节点检查，可启用SSH服务：设置环境变量SSH_ENABLE=1（默认禁用）。postgres用户可通过gosu postgres ssh {节点网络名}连接任意节点。

可通过挂载自定义密钥到/home/postgres/.ssh/id_rsa和/home/postgres/.ssh/id_rsa.pub修改默认密钥。

复制槽

若需禁用Postgres>=9.4的复制槽功能，设置USE_REPLICATION_SLOTS=0（默认启用）。默认max_replication_slots为5，可通过CONFIGS调整。

Postgres扩展版本

postgres-extended组件包含扩展和库，每个扩展对应PostgresExtended/bin/extensions目录下的子目录。

备份与恢复

使用Barman提供实时备份和时间点恢复（PITR）。需配置连接信息和两组凭证：复制凭证、Postgres管理员凭证。

Barman作为热备从源节点流复制WAL，定期通过pg_basebackup进行远程物理备份，支持按保留策略自动删除旧备份和WAL。备份源默认是pgmaster节点，主节点故障转移后继续从从节点备份。

生产环境使用前请阅读：

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

灾难恢复流程参考RECOVERY.md。Barman在:8080/metrics暴露指标，详情见Barman文档。

健康检查

为避免集群脑裂等问题，需设置健康检查，非零结果时停止容器：

• 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]（检查后端节点数量）
  • /usr/local/bin/pgpool/has_write_node.sh（检查是否有可写主节点）

常用命令

• 获取集群当前状态（任意Postgres节点）：
  • gosu postgres repmgr cluster show（尝试连接所有节点）
  • gosu postgres psql $REPLICATION_DB -c "SELECT * FROM repmgr_$CLUSTER_NAME.repl_nodes"（查询表数据）
• 获取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或Kubernetes执行：docker-compose exec {节点} bash -c '{命令}'或kubectl exec {Pod名} -- bash -c '{命令}'。

场景说明

参考FLOWS.md了解故障转移、脑裂抵抗和恢复的不同场景。

贡献方式

参考CONTRIBUTE.md了解贡献方法。

常见问题

• 实际使用案例：Lazada/Alibaba Group
• 为何不用sorintlab/stolon：逻辑复杂、使用非标准Postgres生态工具
• PostgreSQL Docker环境故障转移后如何提升主节点
• 中间节点（如pgslave1）故障会导致整个分支失效：二级及以上复制节点不应直接连接根主节点，避免增加负载。

文档与手册

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