操作指导

前提条件

节点修复
- 该工具支持对故障的ETCD/DN/CN/CM/GTM进行节点修复。
- 若参数enable_synclist_single_inst值为off，则在一主多备场景下，每组DN中至少保证多数派实例正常工作，仅允许少数派实例故障。此时通过gs_replace修复故障DN不影响业务。修复DN实例时，需确保DN环中存在CM可正常监控的主DN，以保障数据一致性。
- 集群内分别至少存在一个正常运行的实例含：CM Server、GTM、CN。
- 若集群中部署有ETCD，则正常的ETCD数量必须大于ETCD总数量的一半。
- 修复CN实例时，集群内必须至少存在一个CN状态为Normal，否则修复不成功。
- 忽略故障节点升级后，若故障节点因升级导致与正常节点版本不一致，不能直接进行修复，需改用节点替换功能。
- 修复多个CN时，最大并发修复数量与正常CN的max_wal_senders参数有关，单次操作允许修复的CN数量为max_wal_senders参数值的一半。
节点替换（不换IP）
- 若参数enable_synclist_single_inst值为off，则在一主多备场景下，每组DN中至少保证多数派实例正常工作，仅允许少数派实例故障。此时通过gs_replace节点替换不影响业务。修复DN实例时，需确保DN环中存在CM可正常监控的主DN，以保障数据一致性。
- 使用gs_replace替换DN实例时，被替换的DN不能是主DN，否则替换不成功。
- 集群内分别至少存在一个可正常运行的实例含：CM Server、GTM、CN。
- 如果集群中已部署ETCD，则正常的ETCD个数必须大于ETCD总个数的一半。
- 新节点的IP、主机名等信息必须与原故障节点保持一致。
- 不支持备DN节点替换为日志节点，且不支持日志节点替换为备DN节点。
节点替换（换IP）
- 若参数enable_synclist_single_inst值为off，则在一主多备场景下，每组DN中至少保证多数派实例正常工作，仅允许少数派实例故障，此时通过gs_replace替换故障DN不影响业务。修复DN实例时，需确保DN环中存在CM可正常监控的主DN，以保障数据一致性。
- 使用gs_replace替换DN实例时，被替换的DN不能是主DN，否则替换不成功。
- 集群内分别至少存在一个可正常运行的实例含：CM Server、GTM、CN。
- 如果集群中已部署ETCD，则正常的ETCD个数必须大于ETCD总个数的一半。
- 用户可执行单节点卸载操作，以移除故障节点。具体操作包括：卸载需被替换的节点或手动清理损坏节点上的数据库相关目录及残留进程。
- 需提前准备基于新节点IP的集群配置文件，该文件仅调整原配置中的IP和主机名，其余内容保持不变。
- 混合部署不支持备DN节点替换为日志节点，且不支持日志节点替换为备DN节点。

注意事项

节点修复
- 若集群中存在状态非Deleted的故障CN，那么在修复过程中用户执行DDL会报错，但DML可以正常执行，其他业务场景不受影响。
  
  修复CN的过程中会短暂锁集群。锁集群期间，若用户下发包含显式事务启动的DDL语句，该操作将进入等待状态。集群解锁后或等待时间超过20分钟会报错。如执行创建临时表操作，集群解锁后会报错"Don't support temp table when need reconnect pooler"。
- 若故障实例所在节点的安装目录下（$GAUSSHOME/bin/）的二进制文件损坏或丢失，则不能通过替换实例进行修复。需复制其他正常节点对应的二进制文件到该节点，或将该节点卸载后再通过节点替换进行修复。
- 节点修复操作将修复故障节点下的全部故障实例。
- 在config阶段优先修复指定节点的CM Agent组件，以确保能正常获取节点实例状态。如果节点上的某些实例被人为停止，在CM Agent组件修复成功之后，这些原来正常的实例会被正常拉起，而不会被修复。如果在一定时间内拉起失败，这些实例将会被修复。
- 修复故障实例过程中系统将关闭“自动剔除故障CN”功能，修复完成后系统再次打开该功能。因此建议在开始修复前确认故障的CN已经被自动剔除（即故障的CN状态为Deleted），否则在修复过程中用户执行DDL会报错。
- 若修复过程中因步骤错误导致失败，需使用原命令重试修复流程。部分实例可能已修复并启动，但状态未完全恢复，需继续执行修复直至所有实例状态正常。
节点替换（不换IP）
- 若集群中存在状态非Deleted的故障CN，那么在修复过程中用户执行DDL会报错，但DML可以正常执行，其他业务场景不受影响。因此建议在开始替换前确认故障的CN已经被自动剔除（即故障的CN状态为Deleted）。
  
  修复CN的过程中会短暂锁集群。锁集群期间，若用户下发包含显式事务启动的DDL语句，该操作将进入等待状态。集群解锁后或等待时间超过20分钟会报错。如执行创建临时表操作，集群解锁后会报错"Don't support temp table when need reconnect pooler"。
- 当故障节点与新节点为同一节点时，需在替换操作前执行单节点卸载流程。
节点替换（换IP）
- 若集群中存在状态非Deleted的故障CN，那么在修复过程中用户执行DDL会报错，但DML可以正常执行，其他业务场景不受影响。因此建议在开始替换前确认故障的CN已经被自动剔除（即故障的CN状态为Deleted）。
  
  修复CN的过程中会短暂锁集群。锁集群期间，若用户下发包含显式事务启动的DDL语句，该操作将进入等待状态。集群解锁后或等待时间超过20分钟会报错。如执行创建临时表操作，集群解锁后会报错"Don't support temp table when need reconnect pooler"。
- 若某节点完全故障且其他节点存在部分实例故障，在满足节点替换（换IP）条件的前提下，替换成功后仍需对其他部分故障节点执行节点修复操作。
- 若集群中部署ETCD，部署ETCD的节点轮流被替换且未重启过主备GTM，则在最后一个节点被替换完成后，需要重启主备GTM以保障集群可靠性。
  示例：假设集群中部署3个ETCD分别在节点node1、node2、node3上，替换流程如下：
  - node1故障替换为node4，未重启主备GTM。
  - node2故障替换为node5，未重启主备GTM。
  - node3故障替换为node6，替换完成后需重启集群主备GTM。
- 若故障节点处于断连状态，执行替换后需由运维人员手动清理以下残留内容：
  - 节点上的数据库数据。
  - 残留的数据库进程、实例目录及环境变量（清理路径需与新节点配置保持一致，可类比查看新节点的以上信息对该节点进行清理）。
- 在备DN节点替换为日志节点的场景中，必须完成所有分片替换操作后，方可执行扩容、升降副本或缩容等运维操作。

示例

示例一 节点修复

以修复节点plat1、plat2上的故障实例为例。

以操作系统用户omm登录数据库任意一台正常的节点。
使用如下命令对需要修复实例的节点进行配置操作。配置操作会清理需修复实例的空间，初始化需修复实例，配置需修复实例。
```
gs_replace -t config -h plat1,plat2
```
如果收到提示：“GAUSS_50201: The XXX does not exist.”，则请检查对应的实例数据目录是否存在。如果不存在，请重新创建目录后再次执行上述命令。
- 若指定节点的表空间所在磁盘出现故障，从而导致表空间中的数据损坏，更换新磁盘后需指定--force参数强制恢复该节点的表空间数据。如果在config阶段指定--force参数，则在start阶段也必须指定--force参数。
- 替换CN实例过程中，不可在CN状态未恢复至Normal时连接该节点执行业务操作。
- 实例修复前，用户在故障实例上手动配置的GUC参数或gs_hba.conf配置的白名单会丢失，需要重新设置。
- 实例修复过程中系统将关闭CM隔离特性开关，修复完成后系统恢复该功能至替换前状态。
使用如下命令对需要修复实例的节点进行启动操作。启动操作会启动需修复实例的节点。
```
gs_replace -t start -h plat1,plat2
```
使用如下命令重置实例状态。重置过程会恢复集群初始状态，以保证各节点的负载都是均衡的。
执行SWITCH操作前需确保：
- 集群状态正常。
- 所有业务已结束。
- 通过PG_GET_SENDERS_CATCHUP_TIME视图确认无主备追赶。
```
gs_om -t switch --reset
```
执行gs_om -t status重新查看集群状态。确认集群balanced状态是否已恢复为“Yes”。
```
[   Cluster State   ]
cluster_state   : Normal
redistributing  : No
balanced        : Yes
```

示例二 节点替换（不换IP）

以需要替换的节点为plat3为例。

以root用户登录到新节点plat3，检查字符集。
```
echo $LANG
en_US.UTF-8
```
新节点上的字符集、编码方式等信息，需与其他节点保持一致。

如果不一致请使用如下方式设置字符集。
```
export LANG="en_US.UTF-8"
```
以root用户登录集群的任意一台正常的节点。
进入安装包解压后的script文件夹。例如，安装包存放路径为/opt/software/gaussdb。
```
cd /opt/software/gaussdb/script
```
准备集群环境。
```
./gs_preinstall -U omm -G dbgrp -X ../clusterconfig.xml --alarm-type=5
```
omm为运行集群的操作系统用户，dbgrp为操作系统用户的群组名称，clusterconfig.xml为集群配置文件（配置文件中IP和主机名均与老节点保持一致），此示例中假设其存储在安装包存放路径下。
切换为运行集群的操作系统用户omm。
```
su - omm
```
执行如下命令完成新增节点的安装操作。
```
gs_replace -t install -h plat3
```
执行如下命令完成新增节点的配置操作。
```
gs_replace -t config -h plat3
```
- 在节点替换CN实例过程中，不可在CN状态未恢复至Normal时连接该节点执行业务。
- 节点替换前，用户在故障节点上手动配置的GUC参数或gs_hba.conf配置的白名单会丢失，需要重新设置。
- 节点替换过程中系统将关闭CM隔离特性开关，完成后系统恢复该功能至替换前状态。
执行如下命令完成新增节点的启动操作。
```
gs_replace -t start -h plat3
```
执行如下命令恢复集群初始状态，以保证负载均衡。
```
gs_om -t switch --reset
```
执行gs_om -t status重新查看集群状态。确认集群balanced状态是否已恢复为“Yes”。
```
[   Cluster State   ]
cluster_state   : Normal
redistributing  : No
balanced        : Yes
```

示例三 节点替换（换IP）

以root用户登录新节点，并检查新节点上的字符集。
```
echo $LANG
en_US.UTF-8
```
新节点上的字符集、编码方式等信息，使与其他节点保持一致。

如果不一致请使用如下方式设置字符集。
```
export LANG="en_US.UTF-8"
```
以root身份登录集群的任意一台正常节点。
进入安装包解压后的script文件夹。例如，安装包存放路径为/opt/software/gaussdb。
```
cd /opt/software/gaussdb/script
```
准备集群环境。
```
./gs_preinstall -U omm -G dbgrp -X ../clusterconfig.xml --alarm-type=5
```
omm为运行集群的操作系统用户，dbgrp为操作系统用户的群组名称，clusterconfig.xml为集群配置文件（配置文件中IP和主机名均已替换为新节点），此示例中假设其存储在安装包存放路径下。
切换为运行集群的操作系统用户omm。
```
su - omm
```
执行如下命令进行节点替换操作。
```
gs_replace -t warm-standby -X clusterconfig.xml
```
如果执行过程中出现异常，请根据提示信息排除异常后重新执行该命令。
- 节点替换CN实例过程中，不可在CN状态未恢复至Normal时连接该节点执行业务。
- 节点替换前，用户在故障节点上手动配置的GUC参数或gs_hba.conf配置的白名单会丢失，需要重新设置。
- 节点替换过程中系统将关闭CM隔离特性开关，完成后系统恢复该功能至替换前状态。
执行如下命令恢复集群初始状态，以保证负载均衡。
```
gs_om -t switch --reset 
```
执行gs_om -t status重新查看集群状态。确认集群balanced状态是否已恢复为“Yes”。
```
[   Cluster State   ]
cluster_state   : Normal
redistributing  : No
balanced        : Yes
```