apecloud/apecloud-postgres

ApeCloud PostgreSQL 镜像文档

镜像概述

ApeCloud PostgreSQL 是一个健壮且高可用的数据库解决方案，通过集成"postgres with consensus hook"并借助"consensus extension"实现Raft共识算法。其架构设计致力于最小化数据丢失，实现恢复点目标（RPO）为0（几乎消除可接受的数据丢失），并确保故障时的快速恢复，具有低恢复时间目标（RTO）。

核心功能与特性

• 高可用性：基于Raft共识算法构建，确保集群数据一致性和服务持续可用
• 零数据丢失：实现RPO 0，确保数据无丢失
• 快速故障恢复：低RTO设计，故障发生后快速恢复服务
• Leader-Follower集群模式：支持主从节点配置，灵活扩展集群
• 灵活配置：支持环境变量和外部配置文件，满足不同部署需求
• 安全认证：支持密码认证及Docker Secrets管理敏感信息

使用场景

适用于对数据一致性、可用性要求高的业务场景，如：

• 企业级核心业务系统
• ***交易系统
• 电商平台数据存储
• 需要高可靠数据备份与恢复的应用

使用方法

1. 创建容器网络

bash
docker network create --driver bridge \
    --gateway=192.168.0.1 --subnet 192.168.0.0/24 \
    my_pg_network

2. 创建Leader节点

bash
docker run -d \
    --name test-apepg1 \
    --network my_pg_network \
    --ip 192.168.0.2 \
    -p 54322:5432 \
    -e POSTGRES_HOST_AUTH_METHOD=md5 \
    -e POSTGRES_PASSWORD=password   \
    -e CONSENSUS_MODE=leader \
    -e CONSENSUS_POSTGRESQL_HOST=192.168.0.2 \
    apecloud/apecloud-postgres:14.10-0.7.0

3. 检查Leader节点角色

bash
PGPASSWORD=password psql -Upostgres -h127.0.0.1 -p 54322 \
      -c "select role from consensus_member_status"

4. 创建第一个Follower节点

bash
docker run -d \
    --name test-apepg2 \
    --network my_pg_network \
    --ip 192.168.0.3 \
    -p 54323:5432 \
    -e POSTGRES_HOST_AUTH_METHOD=md5 \
    -e POSTGRES_PASSWORD=password   \
    -e CONSENSUS_MODE=follower \
    -e CONSENSUS_POSTGRESQL_HOST=192.168.0.3 \
    -e CONSENSUS_CLUSTER_LEADER_HOST=192.168.0.2 \
    -e CONSENSUS_CLUSTER_LEADER_PORT=5432 \
    apecloud/apecloud-postgres:14.10-0.7.0

5. 创建第二个Follower节点

bash
docker run -d \
    --name test-apepg3 \
    --network my_pg_network \
    --ip 192.168.0.4 \
    -p 54324:5432 \
    -e POSTGRES_HOST_AUTH_METHOD=md5 \
    -e POSTGRES_PASSWORD=password   \
    -e CONSENSUS_MODE=follower \
    -e CONSENSUS_POSTGRESQL_HOST=192.168.0.4 \
    -e CONSENSUS_CLUSTER_LEADER_HOST=192.168.0.2 \
    -e CONSENSUS_CLUSTER_LEADER_PORT=5432 \
    apecloud/apecloud-postgres:14.10-0.7.0

6. 检查PostgreSQL共识集群状态

bash
PGPASSWORD=password psql -Upostgres -h127.0.0.1 -p 54322 \
       -c "select * from consensus_cluster_status"

预期输出：

 server_id |      ip_port      | match_index | next_index |   role   | has_voted | force_sync | election_weight | learner_source | pipelining
-----------+-------------------+-------------+------------+----------+-----------+------------+-----------------+----------------+------------
         1 | 192.168.0.2:15432 |          23 |          0 | Leader   | t         | f          |               5 |              0 | f
         2 | 192.168.0.3:15432 |          23 |         24 | Follower | f         | f          |               5 |              0 | t
         3 | 192.168.0.4:15432 |          23 |         24 | Follower | f         | f          |               5 |              0 | t
(3 rows)

7. 连接客户端到Leader节点

bash
$ PGPASSWORD=password psql -Upostgres -h127.0.0.1 -p 54322
psql (14.10 (with consensus 0.7.0 PGTAG=CONSENSUS_HOOK_2_1_0_PG_14_10))
Type "help" for help.

postgres=# select version();
                                                                                 version                                                     
                            
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 PostgreSQL 14.10 (with consensus 0.7.0 PGTAG=CONSENSUS_HOOK_2_1_0_PG_14_10) on aarch64-unknown-linux-gnu, compiled by gcc (Ubuntu 9.4.0-1ubuntu1~20.04.2) 9.4.0, 64-bit

配置说明

环境变量

CONSENSUS_MODE

启用共识功能并指定实例角色。

-e CONSENSUS_MODE={leader | follower}

• leader：初始化新实例，向postgresql.conf添加共识配置参数后启动。注意：若通过POSTGRESQL_MOUNTED_CONF_DIR使用自定义配置文件，postgresql.conf不会被重新配置，需手动设置以下参数：

  shared_preload_libraries = 'consensus'
  consensus.consensus_enabled = true
  

• follower：基于指定的CONSENSUS_CLUSTER_LEADER_HOST和CONSENSUS_CLUSTER_LEADER_PORT从Leader节点备份数据，以follower角色加入集群。

CONSENSUS_POSTGRESQL_HOST

当前实例作为共识集群节点的IP地址，默认端口5432。此"IP:PORT"组合用于集群节点间的共识信息交互。

-e CONSENSUS_POSTGRESQL_HOST=192.168.0.3

CONSENSUS_CLUSTER_LEADER_HOST

现有共识集群中Leader角色节点的IP。

-e CONSENSUS_CLUSTER_LEADER_HOST=192.168.0.2

CONSENSUS_CLUSTER_LEADER_PORT

现有共识集群中Leader角色节点的端口。

-e CONSENSUS_CLUSTER_LEADER_PORT=5432

POSTGRESQL_REPLICATION_USER

Leader节点首次运行时创建的复制用户，默认值为'replicator'。

-e POSTGRESQL_REPLICATION_USER=repl

POSTGRESQL_REPLICATION_PASSWORD

复制用户的密码，默认值为'replicator'。

-e POSTGRESQL_REPLICATION_PASSWORD=password

POSTGRESQL_MOUNTED_CONF_DIR

指定外部挂载配置文件的目录。容器启动时，挂载目录下的文件将被复制到PGDATA目录，覆盖postgresql.conf和pg_hba.conf。

-e POSTGRESQL_MOUNTED_CONF_DIR=/conf \
-v /u01/conf:/conf

Docker Secrets

作为通过环境变量传递敏感信息的替代方案，可以在部分环境变量后附加"_FILE"，使初始化脚本从容器内文件加载值。支持的环境变量包括：POSTGRESQL_REPLICATION_USER、POSTGRESQL_REPLICATION_PASSWORD、POSTGRES_INITDB_ARGS、POSTGRES_PASSWORD、POSTGRES_USER、POSTGRES_DB。

示例：

bash
echo "apecloud" > /u01/secret/postgres_user.txt
echo "mypassword" > /u01/secret/postgres_password.txt
echo "repl" > /u01/secret/postgres_replication_user.txt
echo "repl_password" > /u01/secret/postgres_replication_password.txt

docker run -d \
    --name test-apepg \
    -e POSTGRES_USER_FILE=/run/secrets/postgres_user.txt \
    -e POSTGRES_PASSWORD_FILE=/run/secrets/postgres_password.txt \
    -e POSTGRESQL_REPLICATION_USER_FILE=/run/secrets/postgres_replication_user.txt \
    -e POSTGRESQL_REPLICATION_PASSWORD_FILE=/run/secrets/postgres_replication_password.txt \
    -v /u01/secret:/run/secrets \
    apecloud/apecloud-postgres:14.10-0.7.0

.backup_restore文件

当通过-v参数将数据目录挂载到/var/lib/postgresql/data并以follower角色启动时，需在数据目录中创建.backup_restore文件。若未创建此文件，将直接以Leader角色启动新的共识集群。

操作步骤：

bash
PGPASSWORD=replicator pg_basebackup -h 127.0.0.1 -p 54322 -U replicator -w \
              -D $PWD/pgconsensus_volume2 -X stream  \
              -P -v

cd $PWD/pgconsensus_volume2
echo "" >> .backup_restore

# 挂载目录时使用
-v $PWD/pgconsensus_volume2:/var/lib/postgresql/data

完整部署示例

bash
docker run -d \
    --name test-apepg \
    --network my_pg_network \
    --ip 192.168.0.2 \
    -p 54322:5432 \
    -e CONSENSUS_MODE=leader \
    -e CONSENSUS_POSTGRESQL_HOST=192.168.0.2 \
    -e CONSENSUS_CLUSTER_LEADER_HOST=192.168.0.2 \
    -e POSTGRESQL_MOUNTED_CONF_DIR=/conf \
    -v /u01/conf:/conf \
    -e POSTGRES_HOST_AUTH_METHOD=md5 \
    -e POSTGRES_DB=apecloud \
    -e POSTGRES_USER=apecloud \
    -e POSTGRES_PASSWORD_FILE=/run/secrets/postgres_password.txt \
    -e POSTGRESQL_REPLICATION_USER=repl \
    -e POSTGRESQL_REPLICATION_PASSWORD_FILE=/run/secrets/postgres_replication_password.txt \
    -v /u01/secret:/run/secrets \
    -e POSTGRES_INITDB_ARGS="--data-checksums" \
    -e POSTGRES_INITDB_WALDIR="/waldir" \
    -v /u01/initdb-scripts:/docker-entrypoint-initdb.d \
    apecloud/apecloud-postgres:14.10-0.7.0