说明： kpatch 工具通常随内核补丁包配套提供，若无该工具则代表当前环境不支持热补丁升级；补丁包内附带完整升级指导文档，具体可参照文档中列明的适配升级路径执行。若待升级版本不在支持路径清单内，说明该版本无法使用 kpatch 热更，建议调整版本后再开展升级操作。  

kpatch 在线热补丁工具 介绍

kpatch是金仓数据库KingbaseES的在线热补丁工具，主要用来给数据库集群在线打补丁和升级，它简化了升级操作步骤，将一个复杂的集群升级过程简化为了一个命令，将升级对业务的影响最小化。

Kpatch补丁升级功能是将应用兼容和数据兼容的补丁包，替换当前正在运行的数据库。

工作流程

主要分为下面几个部分：

1.检查补丁包：对补丁完整的版本号是否与当前数据库兼容。

2. 备份二进制：原本二进制没有备份过，将备份。已经是软连接，就不需要备份

3. 解压部署补丁包：将补丁包解压到特定文件夹中，以备做软连接

4. 升级替换：采用软连接方式整体替换文件夹，精确到 bin 、 lib 、 share 、 etc 、 log 目录

5. 状态检查：检查数据库是否正常运行状态， sys_ctl status –D data

6. 集群升级：

a) 需要停止高可用组件

b) 需要同步转异步，以免对应用的影响

c) 对每个节点逐步滚动替换，优先回滚备节点，再回滚主节点（主节点回滚前需要 switchover 到备节点）

7.在升级任意一环境错误时，退出

8. 升级中断时，可以重新运行升级

9.在升级时，关闭数据库、高可用组件前，需最终让用户确认是否升级

升级模式

kpatch有两种升级模式:

1. 滚动升级：对集群中的节点逐一进行维护。当修补节点1时，业务流量由节点2承载；修补完成后，节点1重新加入集群，再对节点2进行同样操作。
2. 并行升级：需要 先停止集群，在集群停止的情况下 ，并行同时升级集群的两个节点。

适用范围

目前只适配了V8R6及后续版本（含R版本和M版本），部署架构上，目前只适配了单机和RWC集群，RAC暂不支持。

升级限制

1. 升级与回滚时，版本号相匹配是否匹配，是指判断PSxxx前的版本号是否相同。比如：

V008R006C003B0071PS001 应该和 V008R006C003B0071 匹配

V008R006C003B0071PS002 应该和 V008R006C003B0071PS001 匹配

V008R006C003B0071PS001应该和V008R006C003B0072不匹配

1. 升级时，不能往小的版本号升级：只能往大的版本号升级（比如：V8R6B23PS001可升级到V8R6B23PS001，V8R6B23可升级到V8R6B23PS001）

1. 回滚时，不能往大的版本号回滚，：只能往小的版本号升级（比如：V8R6B23PS003可回滚到V8R6B23PS001，V8R6B23PS001可回滚到V8R6B23）

准备工作

集群信息收集和需求

收集现场集群信息，实现将金仓数据库从 KingbaseES_V008R006C009B0014 升级到 KingbaseES_V008R006C009B0014PS058 版本。

注意：数据data路径（例如/home/kingbase/cluster/test/data，data目录不能在bin、lib、share、include目录下，如果在上述目录请更改）

状态检查

滚动升级方式要求集群必须是启动状态。

数据节点查看集群状态

repmgr cluster show

重点检查：Role、Status、Upstream、Sync、LSN_Lag。Status 为 running 表示正常；failed、? unreachable、running as primary/standby 等均需先处理。

查看集群高可用服务状态

repmgr service status

重 点检查：repmgrd 是否 running，Paused 是否 no。若 Paused 为 yes，可按实际情况使用 repmgr service unpause 恢复。

集群同步检查

只有在主节点查询有结果输出

ksql -U system test
select pid,usename,state,sync_state,write_lsn,flush_lsn,replay_lsn from sys_stat_replication;

node2/node3 sync_state 为 quorum，无延迟。  

版本检查

--服务器端版本查询
kingbase -V 
--客户端版本查询
ksql -V
--数据库中查询
ksql test system -c "select version();"
ksql test system -c "select build_version;"

vip和子网掩码长度检查(可选)

注意：如果集群使用VIP并且没有设置子网掩码，那么子网掩码默认长度是24。如果集群使用VIP且未配置子网掩码，子网掩码不是默认的24只能使用并行升级方式。

repmgr.conf文件位置：安装目录/kingbase/etc/下。

本文实验环境未配置vip

--查看repmgr.conf中是否配置vip信息
repmgr.conf中virtual_ip参数中配置 IP 或 IP/掩码 的形式。
例如：
virtual_ip='192.168.1.100'
或
virtual_ip='192.168.1.100/20'
如果virtual_ip参数中没有配置掩码，那么默认使用24作为掩码。
--查看子网掩码
[kingbase@node1 ~]$ route -n
Kernel IP routing table
Destination     Gateway         Genmask         Flags Metric Ref    Use Iface
0.0.0.0         192.168.40.2    0.0.0.0         UG    100    0        0 ens192
192.168.40.0    0.0.0.0         255.255.255.0   U     100    0        0 ens192

环境变量检查(所有节点)

LD_LIBRARY_PATH 用于 Linux 系统指定 动态库检索路径 ，金仓（KingbaseES）客户端、ksql、备份工具、驱动、自定义存储过程运行时，优先读取该变量下的金仓 lib 库文件，避免系统自带库冲突。  

查看LD_LIBRARY_PATH环境变量是否包含kingbase/lib，如果包含需去掉。

# Kingbase Env
export KINGBASE_HOME=/home/kingbase/cluster/install/ingbase
export PATH=$KINGBASE_HOME/bin:$PATH
export LD_LIBRARY_PATH=$KINGBASE_HOME/lib:$KINGBASE_HOME/lib/plugins:$LD_LIBRARY_PATH

配置免密登录

sys_encpwd -Usystem -D \* -H \* -P \* -W kingbase

备份(可选)

主备节点备份data数据目录（或主节点使用在线物理备份工具sys_basebackup/sys_rman备份)

本文采用sys_rman备份

cd /home/kingbase/cluster/zyzx/yxzx/kingbase
cp -r data data_bak_20260804

由于数据量较大，先物理全备再增备，节省备份时间。注意：如果时间要求高，可去掉压缩参数：_compress_type、_compress_level

--编辑sys_backup.conf  _target_db_style="single-pro" 每个节点都备份
cd /home/kingbase/cluster/zyzx/yxzx/kingbase/share
vi sys_backup.conf
_target_db_style="single-pro"
_one_db_ip="192.168.40.111"
_repo_ip="192.168.40.111"
_repo_path="/home/kingbase/kbbr_repo"
_repo_retention_full_count=5
_crond_full_days=1
_crond_diff_days=0
_crond_incr_days=1
_crond_full_hour=2
_crond_diff_hour=0
_crond_incr_hour=4
_compress_type=gz
_compress_level=3
--备份初始化  初始化过程中会进行一次全备
sys_backup.sh init
--开启物理全备
/home/kingbase/cluster/zyzx/yxzx/kingbase/bin/sys_rman --config=/home/kingbase/kbbr_repo/sys_rman.conf --stanza=kingbase --archive-copy --type=full backup >> /home/kingbase/cluster/zyzx/yxzx/kingbase/log/sys_rman_backup_full_20260804.log 
--开启物理增备    可选
/home/kingbase/cluster/zyzx/yxzx/kingbase/bin/sys_rman --config=/home/kingbase/kbbr_repo/sys_rman.conf --stanza=kingbase --archive-copy --type=incr backup >> /home/kingbase/cluster/zyzx/yxzx/kingbase/log/sys_rman_backup_incr_20260804.log

补丁包上传并解压

联系厂商获取补丁包 V008R006C009B0014PS058.zip 并上传至主节点的/home/kingbase/software下。

cd /home/kingbase/software
unzip V008R006C009B0014PS058.zip

升级步骤

上传补丁包并解压kpatch可执行文件(主节点)

--在安装同级目录下创建Kpatch目录和patch_packages目录(kingbase子目录的上一级目录)
cd /home/kingbase/cluster/zyzx/yxzx/
mkdir -p Kpatch/patch_packages
--上传补丁包到patch_packages目录下并解压kpatch可执行文件到Kpatch目录
cp /home/kingbase/software/V008R006C009B0014PS058/精简版/kingbase-server-V008R006C009B0014PS058-linux-x86_64.tar /home/kingbase/cluster/zyzx/yxzx/Kpatch/patch_packages/
cd /home/kingbase/cluster/zyzx/yxzx/Kpatch/patch_packages
tar -zxf kingbase-server-V008R006C009B0014PS058-linux-x86_64.tar  -C ../

执行滚动升级

注意:

• 鲲鹏环境升级前主备节点需查看LD_LIBRARY_PATH环境变量是否包含kingbase/xxx/lib，如果包含需去掉。
• 如果集群使用VIP并且没有设置子网掩码长度则只能使用并行方式对集群升级。
• kpatch滚动升级需要在集群启动状态下升级，升级过程中需根据终端提示确认升级(y/n)。
• 升级过程中默认用system超级用户连接test库，如果system用户或test库不存在，请自行添加参数--ext-args='-d 库名 -u 超级用户名'到kpatch执命令中。
• 升级后安装目录的上级目录{install_dir}../会建立KESRealPro目录存储升级前后的bin、lib、share、include目录，并且集群原主节点会变为备节点（可通过--switchover-on-old-primary参数使升级前后集群主备节点不变）。

整个过程耗时约2.5s，node2节点成为了新主节点。

cd /home/kingbase/cluster/zyzx/yxzx/Kpatch/bin
./kpatch -k /home/kingbase/cluster/zyzx/yxzx/kingbase/ -D /home/kingbase/cluster/zyzx/yxzx/kingbase/data -t V008R006C009B0014PS058 apply cluster_rolling --switchover-on-old-primary
参数说明：
-t：升级后的版本，需根据现场选择升级到的版本确定
--switchover-on-old-primary: 升级前后集群主备节点不变

升级后版本检查

查看升级后的版本号是否正确

--服务器端版本查询
kingbase -V 
ksql -V
ksql test system -c "select version();"
ksql test system -c "select build_version;"

集群同步检查

只有在主节点查询有结果输出

ksql -U system test
select pid,usename,state,sync_state,write_lsn,flush_lsn,replay_lsn from sys_stat_replication;

node2/node3 sync_state 为 quorum，无延迟。  

状态检查

查看集群状态

repmgr cluster show

重点检查：Role、Status、Upstream、Sync、LSN_Lag。Status 为 running 表示正常；failed、? unreachable、running as primary/standby 等均需先处理。

查看集群高可用服务状态

repmgr service status

重 点检查：repmgrd 是否 running，Paused 是否 no。若 Paused 为 yes，可按实际情况使用 repmgr service unpause 恢复。

手动执行CompatibleOp.sh脚本

--配置免密登录
sys_encpwd -U system -D \* -H \* -P 54321 -W 'kingbase'
--执行CompatibleOp.sh脚本
cd /home/kingbase/cluster/zyzx/yxzx/Kpatch/share/CompatibleOp/
./CompatibleOp.sh -u system -d test -p 54321 -o V008R006C009B0014 -n V008R006C008B0014PS058 -t upgrade 
--查看日志
cd /home/kingbase/cluster/zyzx/yxzx/Kpatch/share/CompatibleOp/log | ls -l

回退步骤

停止集群

主节点操作即可

sys_monitor.sh stop

停止securecmd服务

主备所有节点使用root用户通过sys_HAscmdd.sh脚本停sys_securecmdd

su - root
cd /home/kingbase/cluster/zyzx/yxzx/kingbase/bin/
./sys_HAscmdd.sh stop

删除数据目录

不建议直接rm -rf，若磁盘空间不够和客户沟通挂载临时盘，后面再回收

cd /home/kingbase/cluster/zyzx/yxzx/kingbase/
mv data data_new_20260804

所有节点还原升级前备份数据

本文采用sys_rman方式备份，所以还原还采用sys_rman方式， 所有节点还原升级前备份数据

cd /home/kingbase/cluster/zyzx/yxzx/kingbase
cp -r data_bak_20260804 data 
或  
/home/kingbase/cluster/zyzx/yxzx/kingbase/bin/sys_rman --config=/home/kingbase/kbbr_repo/sys_rman.conf --stanza=kingbase   restore >> /home/kingbase/cluster/zyzx/yxzx/kingbase/log/sys_rman_restore_20260804.log

启动securecmd服务

主备所有节点使用root用户通过sys_HAscmdd.sh脚本停sys_securecmdd

su - root
cd /home/kingbase/cluster/zyzx/yxzx/kingbase/bin/
./sys_HAscmdd.sh start

启动集群

sys_monitor.sh start

执行回退操作

注意： 补丁回退也有两种方式：滚动回退和并行回退，本文采用滚动回滚方式， 回退过程中需根据终端提示确认回退(y/n)。

--Kpatch目录下，执行集群回滚操作（仅主节点执行）
cd /home/kingbase/cluster/zyzx/yxzx/Kpatch/bin
--通过回滚方式对读写分离集群回滚
./kpatch -k /home/kingbase/cluster/zyzx/yxzx/kingbase -D /home/kingbase/cluster/zyzx/yxzx/kingbase/data -t V008R006C009B0014 rollback cluster_rolling 
参数说明：
-k KingbaseES安装路径
-D 数据data路径
-t 升级前版本号
rollback 回滚
cluster_rolling 集群节点并行回滚

执行主节点回切操作(可选)

恢复node1是主节点，在node1节点上执行主备切换操作

--备机操作(要升主的备机)
2节点
repmgr standby switchover --siblings-follow  --verbose
＞＝3节点
repmgr standby switchover --force-rewind --siblings-follow --verbose

查看集群状态

数据节点查看集群状态

repmgr cluster show

重点检查：Role、Status、Upstream、Sync、LSN_Lag。Status 为 running 表示正常；failed、? unreachable、running as primary/standby 等均需先处理。

查看集群高可用服务状态

repmgr service status

重 点检查：repmgrd 是否 running，Paused 是否 no。若 Paused 为 yes，可按实际情况使用 repmgr service unpause 恢复。

集群同步检查

只有在主节点查询有结果输出

ksql -U system test
select pid,usename,state,sync_state,write_lsn,flush_lsn,replay_lsn from sys_stat_replication;

node2/node3 sync_state 为 quorum，无延迟。  

扩展

查看kpatch工具帮助命令

通过执行 ./kpatch --help 查看帮助

cd /home/kingbase/cluster/zyzx/yxzx/Kpatch/bin
./kpatch --help

输出如下：

[kingbase@node1 bin]$ ./kpatch --help
Usage:
  kpatch [OPTIONS] ACTION [TYPE]
Action:
  apply               apply a patch
  rollback            rollback a patch
  status              show status
Type:
  single              used with KingbaseES
  cluster_rolling     used with KingbaseRWC and cluster is running
  cluster_parallel    used with KingbaseRWC and cluster is stopped
  auto                automatic to select type
General options:
  -k=kingbase_path    kingbase path, the parent of ./bin DIR
  -D=data_path        kingbase data path
  -t=target_version   target version
  -p=package_path     patch package path
  --check             just check
  --node=ip           set a data node or wintness node, acceptable for multiple
Other options:
  -?, --help          show this help, then exit
  -V, --version       display version
  -d, --detail        show detail log
Example:
    kpatch -k kingbase_path -D data_path -t target_version apply auto
    kpatch -k kingbase_path -D data_path -t target_version rollback auto

使用方法为： kpatch [OPTIONS] ACTION [TYPE]

• 其中ACTION，升级应该使用apply，回滚使用rollback，查看升级状态用status
• 其中TYPE：

1. single ，部署为 KingbaseES 单机时使用

2. cluster_rolling ，部署为 KingbaseRWC 集群时，且集群启动时使用

3. cluster_parallel ，部署为 KingbaseRWC 集群时，且集群停止时使用

4. auto ，让程序自动选择一个模式，如果不填写 TYPE ，默认为 auto

• 其中OPTIONS，

1. 需要指定-D 选项，为数据库的data目录

2. 升级需要填写-t 或-p 选项，-t 为升级目标版本会自动到Kpatch/packages目录下查询补丁包，-p为升级的补丁包路径

3. 回滚需要填写-t 选项，-t 为回滚目标版本

4. 有 --check 选项，仅仅只是检查是否可以升级或回退

5. 可以通过--node=ip选项来设置节点，可以使用多个选项来设置多个节点，包括witness节点

kpatch工具升级方式介绍

通过kpatch升级、回滚主要有三种方式，分别用于单机部署的KingbaseES，和读写分离集群KingbaseRWC。

单机升级

升级场景：部署为 KingbaseES 单机时使用。

升级影响：将短暂停止数据库，业务程序在这短暂时间将失去对数据库的连接。单机升级的停机时间 =

数据库关闭时间 + 数据库启动时间。

集群并行升级

升级场景：部署为 KingbaseRWC 集群时，且集群启动时使用。

升级影响：将短暂停止整个集群，停止数据库和集群管理进程，业务程序将失去数据库的连接。停机

时间取决于停止所有节点的数据库、集群管理进程的时间。集群并行升级停机时间 = 所有节点数据库关

闭时间 + 所有节点数据库启动时间 + 集群管理进程重启时间。如果不想影响业务时间太长，可以使用：

集群滚动升级。

集群滚动升级

升级场景：部署为 KingbaseRWC 集群时，且集群停止时使用。

升级影响：将滚动停止数据库，不停止整个集群。此种升级方式，业务程序可能会在升级过程中失去

某个节点数据库的连接，但是只需要重试当前语句，就可以在其他未执行升级的节点执行成功。在最

后升级主节点时，会将其他备节点提升为主节点，因此，两个节点影响时间为一个故障转移的时间

（大概 60s 以内），三个以上节点，影响业务 “ 写 ” 的时间为一个故障转移的时间。故障转移时间 = 旧主

节点数据库关闭时间+新主节点数据库启动时间。

三种升级方式区别

kpatch工具使用要求

使用版本要求

kpatch为独立工具，具体使用哪个kpatch版本，请根参考据数据库的升级手册中指定版本。一般 某个版本

的kpatch只能使用在某些数据库版本上 ，需要对应使用。

使用注意事项

1. 尽量在数据库空闲时间操作

2. 需要排除磁盘是否满，多节点间，网络是否通畅

3. 需要在物理备份和逻辑备份前后操作，不要同时进行

4. 执行kpatch失败，请不要强行启停集群，可能会导致未知错误

5. 使用 cluster_rolling 升级时，会做 switchover ，会停止主库，从而影响业务

6. 使用 cluster_rolling 升级时，主节点可能会变更

7. 确保当前PATH下有这些系统命令： cat,grep,awk,ls,mkdir,scp,sed,echo,service,chmod,chown,systemctl,test,which,cp,mv,tar,file

8. 请不要在集群的 witness 节点、物理备份外部 repo 节点执行 kpatch

9. 需要检查kingbase /bin目录下是否有data目录，是否启动了这个data的kingbase实例，如果有的话，需要停止这个实例，并自行移走data目录

10. 目前无法支持 es_sever 部署的集群。对于 V008R006C005B0023 及其之前的版本，打过 es_server 补

丁，也是不支持的，且需要手动检查是否打过 es_server 补丁。

11. kpatch仅支持特定提供的补丁包升级，且补丁包不能被改名。

其他说明

1. V008R006C003B0071 及其之前的版本，由于集群中没有 .nodes.info 配置文件，需要再执行 kpatch

时，使用--node=ip来指定有哪些节点。

2. V008R006C006B0013 及其之前的版本，由于 .nodes.info 配置文件中都没有 wintness 节点，需要在执

行kpatch时，使用--node=ip来指定wintness节点。

3. 其他情况导致.nodes.info配置文件没有包含全部节点，可以使用--node=ip来进行添加节点。

SQL兼容操作CompatibleOp.sh脚本

介绍

SQL兼容操作⼯具主要是⾃动化执⾏产品补丁复⽤data升级中SQL升级步骤，⽤户⽆需关注升级的数据库模式、 版本的升级路径，⽅便简洁的完成SQL升级过程。通过 手动执行CompatibleOp.sh脚本，解决未生效的BUG修改。

组成部分

位置：/home/kingbase/cluster/zyzx/yxzx/Kpatch/share/CompatibleOp，目录下包括以下内容：

内容说明：

• CompatibleOp.sh ：可执⾏脚本，接受传参。
• CompatibleOp.conf ：配置⽂件，需配置版本范围等。
• sql⽬录 ：sql⽬录下包含升级/回滚过程中可能需要执⾏的sql⽂件，并根据⽬录名区分不同的数据库模式中的sql⽂件。 注意：不同模式下的同名sql⽂件中包含的操作可能不⼀样，是由于模式修复的BUG不同⽽造成的。
• start.sql和end.sql ：保证sql操作可重⼊的⼀些辅助函数定义与删除。
• log⽬录 ：log⽬录下包含sql的执⾏⽇志和错误⽇志。

使⽤教程

查看帮助信息

位置：/home/kingbase/cluster/zyzx/yxzx/Kpatch/share/CompatibleOp

通 过 ./CompatibleOp.sh help 查 看帮助， 详细说 明 调 ⽤ Compatible.sh 可能需要 传 ⼊的参数。

[kingbase@node1 CompatibleOp]$ ./CompatibleOp.sh help
CompatibleOp 兼容性升级.
使用方法：
	CompatibleOp [选项]...
	CompatibleOp [命令]
选项：
	-u	数据库超级用户:[default system]
	-d	连接的数据库:[default test]
	-p	数据库端口:[default 54321]
	-D	数据目录
	-o	升级/回滚前数据库版本号
	-n	升级/回滚后数据库版本号
	-t	操作类型:[upgrade | rollback]
	-m	0:二进制替换前
		  1:二进制替换后，启动前
		  2:二进制替换后，启动后[default]
命令：
	help	显示帮助
	version	获取版本号

升级前须知

• 升级/回退的数据库需配置 免密登录
• 集群升级/回退只需 在主节点执⾏即可
• 数据 库 ⽤ 户 、数据 库 、端⼝号不 设 置默 认 与 Server ⼀致
• 默认升级/回退⼀个实例中的所有数据库， 如果需要选择性的设置某些数据库，可在CompatibleOp.conf 中配置

# 设置需要升级的数据库，默认升级所有数据库（用户可操作）
upgrade_database="all"
# 自定义升级test kingbase security数据库
# eg. upgrade_database="test kingbase security"

• ⼯具包统⼀放置在安装目录/share/Compatible⽬录下
• 升级操作可重⼊，需所有操作执⾏成功才表⽰SQL升级完成

使⽤命令⽰例

升级操作

./CompatibleOp.sh -u system -d test -p 54321 -o V008R006C008B0014 -n 
V008R006C008B0014PS018 -t upgrade

回滚操作

注意：⽬前不⽀持回滚。

./CompatibleOp.sh -u system -d test -p 54321 -o V008R006C008B0014PS018 -n 
V008R006C008B0014 -t rollback

升级/回滚⽇志

升级/回滚路径

打印路径，格式如下 :

upgrade/rollback path: V008R006C008B0014->V008R006C008B0014PS001- 
>V008R006C008B0014PS002->V008R006C008B0014PS003->V008R006C008B0014PS004- 
>V008R006C008B0014PS005->V008R006C008B0014PS006->V008R006C008B0014PS018

升级/回滚详细⽇志

显 ⽰数据 库 模式、升 级 的数据 库 、 执 ⾏的 sql ⽂件（ 对应 版本号）：

2024-11-21 17:31:28 upgrade database: test, database_mode: oracle 
execute sql-file (V008R006C008B0014PS001.sql), for version: V008R006C008B0014PS018 
execute sql-file (V008R006C008B0014PS002.sql), for version: V008R006C008B0014PS018 
execute sql-file (V008R006C008B0014PS003.sql), for version: V008R006C008B0014PS018 
execute sql-file (V008R006C008B0014PS004.sql), for version: V008R006C008B0014PS018 
execute sql-file (V008R006C008B0014PS005.sql), for version: V008R006C008B0014PS018 
execute sql-file (V008R006C008B0014PS006.sql), for version: V008R006C008B0014PS018 
execute sql-file (V008R006C008B0014PS018.sql), for version: V008R006C008B0014PS018

升级/回滚成功

所有操作必 须 全部 执 ⾏成功

2024-11-21 17:31:30 upgrade/rollback successfully.

升级/回滚失败

任⼀操作 执 ⾏失 败 ，如果失 败 ， 查 看 错误 ⽇志，排 错 后再次 执 ⾏

2024-11-21 17:35:50 upgrade/rollback failure, please check the error log.