openGauss 主备集群部署指南

目标：搭建 openGauss 5.1.0 一主一备（Primary/Standby）高可用集群，覆盖两种部署路线——OM 企业版标准流程（config.xml、gs_preinstall、gs_install）与极简版 --multinode 流程（gs_initdb 主备、gs_ctl build 建备机、switchover/failover 切换、pg_stat_replication 验证）。除标注「预期输出」的 OM 流程外，其余命令与回显均为实测结果。

环境信息

openGauss 版本：5.1.0（基于 PostgreSQL 9.2.4 内核）
集群拓扑：一主一备
- 主节点（Primary）：/opt/software/openGauss/data/master，端口 6432
- 备节点（Standby）：/opt/software/openGauss/data/slave，端口 6632（备机端口 = 主端口 + 200）
主备节点数据目录初始化 nodename：datanode1 / datanode2
复制模式：同步（sync_state = Sync，sync_percent = 100%）

前置条件

已按下文《环境准备》完成 openGauss 5.1.0 极简版安装包下载解压至 /opt/software/openGauss，并创建运行用户 omm（密码 Q1w2e3r4#）赋权完毕
主备之间端口互通：主节点需放行备机连接端口（本文 6432~~6437），备机放行 6632~~6637
同步时间（NTP/chrony），避免复制链路抖动

方案选型说明

方案	安装包	适用场景	实测状态
OM 企业版	`/5.1.0/x86_64/`（含 OM）	生产一主多备，完整集群管理	该路径 OBS 下载 403，未实测；按官方命令给出预期输出，需 systemd 真机
极简版 `--multinode`	`/5.1.0/x86/`	开发测试一主一备	✅ 本文实测，回显真实

⚠️ OM 方式（gs_preinstall/gs_install）依赖 systemd 服务、/etc/hosts 主机名解析、NTP 等完整系统环境，需 systemd 真机执行；极简版 --multinode 无此要求，适合开发/测试快速验证。

环境准备（两节点 / 单机双实例）

以下步骤在两台服务器（或单机双实例演练时本机）上执行，为后续安装准备好安装介质与运行用户。

步骤 1：下载并解压极简版安装包

从 openGauss 官网下载中心（https://opengauss.org/zh/download/）下载 5.1.0 极简版安装包（x86_64），放入 /opt/software 后解压：

mkdir -p /opt/software
cd /opt/software
tar -zxvf openGauss-5.1.0-CentOS-64bit.tar.gz
ls /opt/software/openGauss
bin  lib  share  version.cfg  ...

💡 极简版解压即用，内含 gs_initdb、gs_ctl、gsql、gaussdb 等二进制（无需编译安装）；OM 企业版（含 gs_preinstall/gs_install）需另行获取含 OM 的完整安装包（见方式一说明）。Ubuntu 22.04 下载对应 Ubuntu x86_64 版本包，解压步骤一致。

步骤 2：创建运行用户 omm 并赋权

useradd -m -d /home/omm -s /bin/bash omm
echo 'Q1w2e3r4#' | passwd omm --stdin

💡 passwd --stdin 为 CentOS 8 写法；Ubuntu 22.04 用 echo 'omm:Q1w2e3r4#' | chpasswd。密码 Q1w2e3r4# 满足 openGauss 密码复杂度要求（至少含大写/小写/数字/特殊字符三类）。也可用 passwd omm 交互设置。

chown -R omm:omm /opt/software/openGauss
chmod -R 755 /opt/software/openGauss

完成以上准备后，选择方式一（OM 企业版）或方式二（极简版 --multinode）继续部署。

方式一：OM 企业版一主一备（完整命令 + 预期输出）

⚠️ 以下流程需 systemd 真机执行，命令为 openGauss 官方标准流程，输出为预期输出。

步骤 1：编写 config.xml

主备节点配置示例（/opt/software/openGauss/cluster_config.xml）：

<?xml version="1.0" encoding="UTF-8"?>
<ROOT>
  <CLUSTER>
    <PARAM name="clusterName" value="ogCluster" />
    <PARAM name="nodeNames" value="node1,node2" />
    <PARAM name="backIp1s" value="10.0.0.11,10.0.0.12" />
    <PARAM name="gaussdbAppPath" value="/opt/software/openGauss/app" />
    <PARAM name="gaussdbLogPath" value="/var/log/omm" />
    <PARAM name="tmpMppdbPath" value="/opt/software/openGauss/tmp" />
    <PARAM name="gaussdbToolPath" value="/opt/software/openGauss/tool" />
    <PARAM name="corePath" value="/opt/software/openGauss/corefile" />
    <PARAM name="clusterType" value="single-inst" />
  </CLUSTER>
  <DEVICELIST>
    <DEVICE sn="1001">
      <PARAM name="name" value="node1" />
      <PARAM name="azName" value="AZ1" />
      <PARAM name="azPriority" value="1" />
      <PARAM name="backIp1" value="10.0.0.11" />
      <PARAM name="sshIp1" value="10.0.0.11" />
      <PARAM name="dataNum" value="1" />
      <PARAM name="dataPortBase" value="5432" />
      <PARAM name="dataNode1" value="/data/og/data1,node1,10.0.0.11" />
    </DEVICE>
    <DEVICE sn="1002">
      <PARAM name="name" value="node2" />
      <PARAM name="azName" value="AZ1" />
      <PARAM name="azPriority" value="1" />
      <PARAM name="backIp1" value="10.0.0.12" />
      <PARAM name="sshIp1" value="10.0.0.12" />
      <PARAM name="dataNum" value="1" />
      <PARAM name="dataPortBase" value="5632" />
      <PARAM name="dataNode1" value="/data/og/data1,node2,10.0.0.12" />
    </DEVICE>
  </DEVICELIST>
</ROOT>

步骤 2：环境预检查与预安装

gs_preinstall -U omm -G dbgroup -X /opt/software/openGauss/cluster_config.xml

预期输出末尾：

Success to preinstall openGauss.

步骤 3：执行安装

gs_install -X /opt/software/openGauss/cluster_config.xml --gsinit-parameter="--locale=en_US.UTF-8"

预期输出末尾：

Success to install openGauss.

步骤 4：验证集群

gs_om -t status

预期输出（节选）：

cluster_name    : ogCluster
cluster_state   : Normal
redistributing  : No
node           node_ip         instance        state
----------------------------------------------
1  node1        10.0.0.11       6001 /data/og/data1  P Primary Normal
2  node2        10.0.0.12       6002 /data/og/data1  S Standby Normal

方式二：极简版 --multinode 一主一备（实测）

步骤 1：初始化主备数据目录

💡 极简版数据目录需手工初始化（与单节点 single_node 不同，集群使用 master/slave）。若此前已用 5432 安装过单节点，可用 -p 6432 错开端口。

su - omm
source ~/.bashrc
cd /opt/software/openGauss

gs_initdb -D /opt/software/openGauss/data/master --nodename=datanode1 -E UTF-8 --locale=en_US.UTF-8 -U omm -w Q1w2e3r4#
# Success. You can now start the database server of single node using:
#     gaussdb -D /opt/software/openGauss/data/master --single_node

gs_initdb -D /opt/software/openGauss/data/slave --nodename=datanode2 -E UTF-8 --locale=en_US.UTF-8 -U omm -w Q1w2e3r4#
# Success. You can now start the database server of single node using:
#     gaussdb -D /opt/software/openGauss/data/slave --single_node

步骤 2：配置主备复制参数

修改 master/postgresql.conf 与 slave/postgresql.conf（关键项，以主节点为例）：

listen_addresses = 'localhost,172.17.0.19'
port = 6432
replconninfo1 = 'localhost=172.17.0.19 localport=6433 localheartbeatport=6437 localservice=6436 remotehost=172.17.0.19 remoteport=6633 remoteheartbeatport=6637 remoteservice=6636'
remote_read_mode = non_authentication

备节点 port = 6632，replconninfo1 的 local/remote 两端对调。同时在两个 pg_hba.conf 追加节点间互信：

host all all 172.17.0.19/32 trust

💡 replconninfo1 各端口规则：localport = 数据端口+1，localservice = 数据端口+4，localheartbeatport = 数据端口+5。

步骤 3：启动主节点并 build 备节点

gs_ctl start -D /opt/software/openGauss/data/master -M primary
# [2026-10-07 03:41:10.092][8526][][gs_ctl]:  done
# [2026-10-07 03:41:10.092][8526][][gs_ctl]: server started (/opt/software/openGauss/data/master)

gs_ctl build -D /opt/software/openGauss/data/slave -b full
# [2026-10-07 03:41:24.154][8638][datanode2][gs_ctl]:  done
# [2026-10-07 03:41:24.154][8638][datanode2][gs_ctl]: server started (/opt/software/openGauss/data/slave)

-b full 表示全量 build（从主节点全量同步数据目录），备机 build 完成后自动以 Standby 启动。

步骤 4：验证集群状态

gs_ctl query -D /opt/software/openGauss/data/master
#         local_role                     : Primary
#         peer_role                      : Standby
#         peer_state                     : Normal
#         state                          : Streaming
#         sender_sent_location           : 0/4000000
#         sender_write_location          : 0/4000000
#         sender_flush_location          : 0/4000000
#         sender_replay_location         : 0/4000000
#         receiver_received_location     : 0/4000000
#         receiver_write_location        : 0/4000000
#         receiver_flush_location        : 0/4000000
#         receiver_replay_location       : 0/4000000
#         sync_percent                   : 100%
#         sync_state                     : Sync
#         sync_priority                  : 1
#         sync_most_available            : Off
#         channel                        : 172.17.0.19:6433-->172.17.0.19:34994

gs_ctl query -D /opt/software/openGauss/data/slave
#         receiver_pid                   : 8722
#         local_role                     : Standby
#         peer_role                      : Primary
#         peer_state                     : Normal
#         state                          : Normal
#         channel                        : 172.17.0.19:34994<--172.17.0.19:6433

步骤 5：pg_stat_replication 验证复制链路

gsql -d postgres -p 6432 -c "SELECT pid, state, sync_state, sync_priority, sender_sent_location, receiver_replay_location FROM pg_stat_replication;"
#        pid       |   state   | sync_state | sync_priority | sender_sent_location | receiver_replay_location
# -----------------+-----------+------------+---------------+----------------------+--------------------------
#  124068070094592 | Streaming | Sync       |             1 | 0/4000000            | 0/4000000
# (1 row)

步骤 6：主写备读与只读约束验证

# 主节点写入
gsql -d postgres -p 6432 -c "CREATE TABLE repl_test(id int PRIMARY KEY, data varchar(40));"
# CREATE TABLE
gsql -d postgres -p 6432 -c "INSERT INTO repl_test VALUES (1, 'primary 写入');"
# INSERT 0 1

# 备节点读取（数据实时同步）
gsql -d postgres -p 6632 -c "SELECT * FROM public.repl_test;"
#  id |     data
# ----+--------------
#   1 | primary 写入
# (1 row)

# 备节点写入被拒绝（只读）
gsql -d postgres -p 6632 -c "INSERT INTO public.repl_test VALUES (99, 'should fail');"
# ERROR:  cannot execute INSERT in a read-only transaction

故障演练：switchover 与 failover

正常切换（switchover）

gs_ctl switchover -D /opt/software/openGauss/data/slave
# [2026-10-07 03:42:34.248][9145][][gs_ctl]: gs_ctl switchover ,datadir is /opt/software/openGauss/data/slave
# [2026-10-07 03:42:34.248][9145][][gs_ctl]: switchover term (1)
# [2026-10-07 03:42:34.255][9145][][gs_ctl]: waiting for server to switchover........
# [2026-10-07 03:42:39.297][9145][][gs_ctl]: done
# [2026-10-07 03:42:39.297][9145][][gs_ctl]: switchover completed (/opt/software/openGauss/data/slave)

切换后验证角色互换：

gs_ctl query -D /opt/software/openGauss/data/slave  | grep local_role
#         local_role                     : Primary
gs_ctl query -D /opt/software/openGauss/data/master | grep local_role
#         local_role                     : Standby

需要切回原主时对原主目录执行同样的 switchover：

gs_ctl switchover -D /opt/software/openGauss/data/master
# [2026-10-07 03:42:55.300][9288][][gs_ctl]: switchover completed (/opt/software/openGauss/data/master)

强制切换（failover，主节点故障时）

# 在主节点宕机无法恢复时，直接提升备机
gs_ctl failover -D /opt/software/openGauss/data/slave
# [2026-10-07 03:xx:xx.xxx][pid][][gs_ctl]: failover completed (/opt/software/openGauss/data/slave)

💡 failover 后原主恢复时，需对原主执行 gs_ctl build -D <原主目录> -b incremental 重新追平数据（增量 build），再以 Standby 角色加入集群。

注意事项

一主一备使用 同步复制（synchronous_commit = on）时，sync_state = Sync，主库事务需备机确认后才返回，保证 RPO=0。
备机端口 = 主端口 + 200（极简版约定），replconninfo1 的 localport/remoteservice 等按端口+1/+4/+5 推导，勿随意填写。
生产环境建议使用 OM 企业版流程（方式一）以获得完整集群管理能力（gs_om）；极简版 --multinode 无 OM，切换需手工执行 gs_ctl。

常见问题

问题 1：build 备机卡在 waiting

定位：主备 replconninfo1 端口不匹配或防火墙未放行。
解决：核对两端 replconninfo 的 local/remote 端口一一对应，放行 6433/6633 等链路端口后重试。

问题 2：备机查询报 `cannot execute INSERT in a read-only transaction`

定位：属正常行为，备机只读。
解决：写入需连接主节点端口（本示例 6432）；若需备机承载报表，使用只读查询即可。

问题 3：切换后业务连接未自动重定向

定位：客户端连接串仍指向旧主。
解决：应用层做读写分离/主备探测，或使用中间件（如 ShardingSphere、ProxySQL）实现自动切换。

参考链接

openGauss OM 安装文档：https://docs.opengauss.org/zh/docs/latest/docs/InstallationGuide/安装openGauss.html
gs_ctl 工具参考：https://docs.opengauss.org/zh/docs/latest/docs/Toolreference/gs_ctl.html
主备机概念：https://docs.opengauss.org/zh/docs/latest/docs/AdministratorGuide/主备机.html

openGauss 主备集群部署指南

openGauss 主备集群部署指南

环境信息

前置条件

方案选型说明

环境准备（两节点 / 单机双实例）

步骤 1：下载并解压极简版安装包

步骤 2：创建运行用户 omm 并赋权

方式一：OM 企业版一主一备（完整命令 + 预期输出）

步骤 1：编写 config.xml

步骤 2：环境预检查与预安装

步骤 3：执行安装

步骤 4：验证集群

方式二：极简版 --multinode 一主一备（实测）

步骤 1：初始化主备数据目录

步骤 2：配置主备复制参数

步骤 3：启动主节点并 build 备节点

步骤 4：验证集群状态

步骤 5：pg_stat_replication 验证复制链路

步骤 6：主写备读与只读约束验证

故障演练：switchover 与 failover

正常切换（switchover）

强制切换（failover，主节点故障时）

注意事项

常见问题

问题 1：build 备机卡在 waiting

问题 2：备机查询报 cannot execute INSERT in a read-only transaction

问题 3：切换后业务连接未自动重定向

参考链接

问题 2：备机查询报 `cannot execute INSERT in a read-only transaction`