GaussRoach.py备份恢复

备份恢复概述

GaussDB支持OBS/NAS/XBSA等存储介质的集群级物理备份能力，并在同构的数据库（分片相同，大版本号相同）中提供集群备份恢复能力，支持全量和差量备份。全量和差量备份支持备机备份，且全量备份支持并行备份。

NAS支持实例级全量、差量、日志备份，表级全量、差量和日志备份，以及租户级全量备份。

XBSA支持实例级全量、差量、日志备份。

备份原理

全量备份

**概述：**全量备份表示对所有目标数据进行备份，包含备份时刻点上数据库的全量数据，耗时长（和数据库数据总量成正比），自身即可恢复出完整的数据库。全量备份总是备份所有选择的目标，即使从上次备份后数据没有变化。

原理：

1. 日志中获取备份数据文件的开始位置start_lsn
2. 备份全量数据文件
3. 日志中获取备份数据文件的结束位置end_lsn
4. 备份截止到barrier点的增量日志（即start_lsn到end_lsn备份结束时间点）之间产生的日志

对于单分片主备场景来说，通过全量的数据文件备份加增量的日志来保证数据的一致性。

对于多分片分布式场景来说，引入了barrier的概念，在各个分片全量数据备份完成之后，在所有分片中并行插入barrier日志（阻塞两阶段提交，避免出现某些分片有数据，某些分片没有的情况），然后获取barrier scn作为每个分片备份结束的时间点。

差量备份

**概述：**差量备份即差分备份或增量备份，只包含从指定时刻点之后的增量修改数据，耗时短（和增量数据成正比，和数据总量无关），但是必须要和全量备份数据一起才能恢复出完整的数据库。GaussDB默认自动每30分钟对上一次自动备份后更新的数据进行备份，支持修改备份周期为最小15分钟，最大72小时。

原理：

1. 增量数据页面识别和备份

说明：数据库正常运行中，除了处理客户端查询的work线程外，存在一个CBM线程（CHANGE BLOCK MAP），该线程会异步解析产生的日志，分析日志内容，确定日志对哪些数据库文件的修改，并压缩这些修改信息到位图。

增量备份开始时，会获取上一次全量备份的start lsn点，以及这次备份的start lsn点，查看两次lsn之间位图，知道哪些页面进行了修改。

1. 上传增量备份时间段修改的全部数据文件到备份介质
2. 截止一致性barrier点的增量备份

日志备份（PITR）

**概述：**日志备份是恢复到指定时间点（即PITR恢复）对应的备份形式。PITR恢复时，必须要和全量备份数据一起才能恢复出完整的数据库。目前的分布式PITR的恢复时间粒度达到秒级，与当前全量、差量备份恢复功能相比，不仅可以提供更为灵活的备份恢复策略，也将进一步提升备份恢复的数据可靠性。系统自动每5分钟进行一次备份，备份这5分钟内对数据库的所有写入和更新操作，通过日志备份可以将数据恢复到历史时间的任意一秒。

原理：

1. 恢复用户指定恢复时间点之前的最后一次全量备份
2. 恢复用户指定恢复时间点之前的最后一次全量备份后的若干次差量备份
3. 回放用户指定恢复时间点到上述最后一次差量备份之间的归档日志（XLOG）

日志归档：

1. 备机归档，归档日志满足多数派
2. 4M切断，满4M或归档时间间隔1S（archive_interval）

恢复原理

原理：

1）恢复全量备份数据

2）恢复增量备份1数据页面

3）恢复增量备份X数据页面

4）恢复增量备份X的日志

5）启动集群

GaussDB在进行细粒度恢复时（表级、PITR），会在备份恢复发起的主机创建一个新的辅助库，用来辅助数据库的恢复。$GAUSSLOG/roach/controller目录下存在auxdb的辅助库日志。

备份恢复方式

1. 通过管理平台TPOPS或ServiceOM下发备份恢复的相关命令
2. 通过命令行GaussRoach.py工具进行备份恢复

Roach备份恢复

GaussRoach.py脚本路径

$GPHOME/script/

GaussRoach.py常用参数说明

进行gbr恢复时必须指定以下内容：–gbr-owner ‘xxx’ -U rdsAdmin --aux-db-path /data/aux_db

备份

备份前准备，需要确保备份使用的–master-port在各个节点可以通信，TPOPS安装的数据库会通过iptables限制端口的访问，需要进行端口开放，否则会出现长时间没有反应的情况

iptables -I INPUT -p tcp --dport 6000 -j ACCEPT

从磁盘进行备份-全量备份

python3 GaussRoach.py -t backup --master-port 6000 --media-destination /home/Ruby/media --media-type DISK --dbname mtest --metadata-destination /home/Ruby/metadata

从磁盘进行备份-增量备份

python3 GaussRoach.py -t backup --master-port 6000 --media-destination /home/Ruby/media --media-type Disk --metadata-destination /home/Ruby/metadata --prior-backup-key 20251201_161032

从NAS进行备份-全量备份

python3 GaussRoach.py -t backup --master-port 6000 --media-destination /nas/media --media-type NAS --metadata-destination /home/Ruby/metadata --cluster-unique-id gaussdb_backup

从NAS进行备份-增量备份

python3 GaussRoach.py -t backup --master-port 6000 --media-destination /nas/media --media-type NAS --metadata-destination /home/Ruby/metadata --cluster-unique-id gaussdb_backup --prior-backup-key 20251201_173724

从NAS进行备份-表级备份（OBS|NAS|REMTOE支持）

创建测试表

维护表的备份清单列表

vi /home/Ruby/table.json

{“TableList”:[{“DBName”:“atest”,“SchemaName”:“public”,“TableName”:“test”}]}

全量备份

python3 GaussRoach.py -t backup --master-port 6000 --media-destination /nas/media --media-type NAS --metadata-destination /home/Ruby/metadata --cluster-unique-id gaussdb_backup --gbr-table-list /home/Ruby/table.json

M兼容模式数据库不支持细粒度表级备份恢复

增量备份

python3 GaussRoach.py -t backup --master-port 6000 --media-destination /nas/media --media-type NAS --metadata-destination /home/Ruby/metadata --cluster-unique-id gaussdb_backup --gbr-table-list /home/Ruby/table.json --prior-backup-key 20251202_093224_table

备份查看

查看所有的备份信息

python3 GaussRoach.py -t show --all-backups --metadata-destination /home/Ruby/metadata

Disk

NAS

表级

查看全量备份集信息

python3 GaussRoach.py -t show --related-backup-keys --metadata-destination /home/Ruby/metadata --backup-key 20251201_161032

查看增量备份集信息

python3 GaussRoach.py -t show --related-backup-keys --metadata-destination /home/Ruby/metadata --backup-key 20251201_162633

停止备份

python3 $GPHOME/script/GaussRoach.py -t stop

恢复

从磁盘进行恢复-全量恢复

python3 GaussRoach.py -t restore --clean --master-port 6000 --media-destination /home/Ruby/media --media-type Disk --backup-key 20251201_161032 --metadata-destination /home/Ruby/metadata

–clean恢复前是否清除数据。

从磁盘进行恢复-增量恢复

python3 GaussRoach.py -t restore --clean --master-port 6000 --media-destination /home/Ruby/media --media-type DISK --backup-key 20251201_162633 --metadata-destination /home/Ruby/metadata

从NAS进行恢复-全量恢复

python3 GaussRoach.py -t restore --clean --master-port 6000 --media-destination /nas/media --media-type NAS --backup-key 20251201_173724 --metadata-destination /home/Ruby/metadata --cluster-unique-id gaussdb_backup

从NAS进行恢复-增量恢复

python3 GaussRoach.py -t restore --clean --master-port 6000 --media-destination /nas/media --media-type NAS --backup-key 20251201_173939 --metadata-destination /home/Ruby/metadata --cluster-unique-id gaussdb_backup

实例级备份恢复完成后必须执行命令启动集群

python3 GaussRoach.py -t start

从NAS进行恢复-表级恢复

删除表

维护表的备份恢复清单列表

vi /home/Ruby/table2.json

{“TableList”: [{“DBName”: “atest”,“SchemaName”: “public”,“TableName”: “test”,“NewDBName”:“atest”,“NewSchemaName”:“public”,“NewTableName”:“test”}]}

全量恢复

python3 GaussRoach.py -t restore --clean --master-port 6000 --media-destination /nas/media --media-type NAS --backup-key 20251202_093224_table --metadata-destination /home/Ruby/metadata --cluster-unique-id gaussdb_backup --gbr-table-list /home/Ruby/table2.json --gbr-owner ‘test’ -U rdsAdmin --aux-db-path /data/aux_db

增量恢复

python3 GaussRoach.py -t restore --clean --master-port 6000 --media-destination /nas/media --media-type NAS --backup-key 20251202_093913_table --metadata-destination /home/Ruby/metadata --cluster-unique-id gaussdb_backup --gbr-table-list /home/Ruby/table2.json --gbr-owner ‘test’ -U rdsAdmin --aux-db-path /data/aux_db

删除备份

python3 GaussRoach.py -t delete --media-type NAS --media-destination /nas/media --master-port 6000 --metadata-destination /home/Ruby/metadata --cluster-unique-id gaussdb_backup --backup-key 20251201_173939

归档

archive命令用于开启归档、关闭归档、删除归档日志和查询可恢复时间段的功能，配合备份功能可以实现PITR功能，目前只支持OBS和NAS介质。

一般可以在备份开始前开启，备份完成后关闭，一直开启的话会一直进行归档记录。第一次通过管控下发全量备份命令后会自动开启归档。

开启NAS归档

python3 GaussRoach.py -t archive --task-id gaussdb_archive -U rdsAdmin --archive-mode on --media-destination /nas/media --media-type NAS

关闭NAS归档

python3 GaussRoach.py -t archive --task-id gaussdb_archive -U rdsAdmin --archive-mode off --media-destination /nas/media --media-type NAS

清理NAS全部归档

python3 GaussRoach.py -t archive --task-id gaussdb_archive -U rdsAdmin --archive-mode clean --media-destination /nas/media --media-type NAS --delete-all-archived-xlog

PITR表级恢复

PITR恢复需要依赖归档和全量备份。

SELECT FLOOR(EXTRACT(EPOCH FROM now())) AS timestamp_sec_int;

python3 GaussRoach.py -t restore --clean --master-port 6000 --media-destination /nas/media --media-type NAS --backup-key 20251202_153320 --metadata-destination /home/Ruby/metadata --cluster-unique-id gaussdb_backup --gbr-table-list /home/Ruby/table.json --gbr-owner ‘test’ -U rdsAdmin --aux-db-path /data/aux_db --pitr-time 1764661512 --task-id gaussdb_archive

备份恢复问题定位

相关日志

/home/Ruby/log/asyncJobResult.dat

异步任务结果文件，记录了从管控下发的异步任务的运行结果和运行时间。state=2表示失败的任务，可以定位问题时间范围。

/home/Ruby/log/agent.log

管控agent日志，记录节点上的一些agent操作。可以通过这个步骤看见当前在执行具体什么操作时出现问题。

/home/Ruby/log/adaptor_log/om_adaptor.log

om_adaptor日志，一般只有备份命令会发送到其他节点的om_agent执行，其余命令均在调用om_adaptor的节点执行。可以通过该日志确定，备份命令执行的节点。

/home/Ruby/log/om_agent/agent.log

om_agent日志。关注备份主节点om_agent日志是否有相关备份日志，如果没有说明om_agent出现了问题，报错相关关键字：illegal、Fail、invalid、Error。

$GAUSSLOG/roach/controller或$GAUSSLOG/roach/controller_inc

实例全备、增备、表全备、增备主节点MASTER进程日志。

$GAUSSLOG/roach/agent或$GAUSSLOG/roach/agent_inc

全备、增备，内核备份agent进程日志。

PITR单表恢复问题排查

cd /home/Ruby/log/

vim asyncJobResult.dat --搜索state = 2的找到失败的任务，定位具体报错时间点

cd $GAUSSLOG/roach/controller --找到报错时间点的日志VIM，搜索对应时间点后，搜索ERROR，找到具体报错。

cd $GAUSSLOG/roach/controller --若controller无更多信息，则登录去查看辅助库的日志，下面有个aux的文件夹

503版本目前已知的报错有：

1. 数据中带单引号、分号（给表或者索引加的注释部分）；

2. 505.2.1 SPC0600以下的环境B模式中列有auto increment的约束也会导致单表恢复失败。

3. 表级恢复不支持依赖对象有函数