说明： 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时，业务流量由节点2承载；修补完成后，节点1重新加入集群，再对节点2进行同样操作。
- 并行升级：需要先停止集群，在集群停止的情况下，并行同时升级集群的两个节点。
适用范围
目前只适配了V8R6及后续版本（含R版本和M版本），部署架构上，目前只适配了单机和RWC集群，RAC暂不支持。
升级限制
- 升级与回滚时，版本号相匹配是否匹配，是指判断PSxxx前的版本号是否相同。比如：
V008R006C003B0071PS001应该和V008R006C003B0071匹配
V008R006C003B0071PS002应该和V008R006C003B0071PS001匹配
V008R006C003B0071PS001应该和V008R006C003B0072不匹配
- 升级时，不能往小的版本号升级：只能往大的版本号升级（比如：V8R6B23PS001可升级到V8R6B23PS001，V8R6B23可升级到V8R6B23PS001）
- 回滚时，不能往大的版本号回滚，：只能往小的版本号升级（比如：V8R6B23PS003可回滚到V8R6B23PS001，V8R6B23PS001可回滚到V8R6B23）
准备工作
集群信息收集和需求
收集现场集群信息，实现将金仓数据库从 KingbaseES_V008R006C009B0014 升级到 KingbaseES_V008R006C009B0014PS058 版本。
注意：数据data路径（例如/home/kingbase/cluster/test/data，data目录不能在bin、lib、share、include目录下，如果在上述目录请更改）
参数说明 | 参数值 |
主节点IP | 192.168.40.111 |
备节点IP | 192.168.40.112 |
备节点IP | 192.168.40.113 |
软件包路径(soft_dir) | /home/kingbase/software |
集群安装路径(install_dir) | /home/kingbase/cluster/zyzx/yxzx/kingbase |
二进制文件路径 | /home/kingbase/cluster/zyzx/yxzx/kingbase/bin |
数据目录 | /home/kingbase/cluster/zyzx/yxzx/kingbase/data |
端口 | 54321 |
操作系统超级用户 | root |
操作系统集群用户 | kingbase |
集群当前版本 | V008R006C009B0014 |
集群目标版本 | V008R006C009B0014PS058 |
状态检查
滚动升级方式要求集群必须是启动状态。
数据节点查看集群状态
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.