数据库升级

概述

本节介绍 KaiwuDB 数据库的升级方法。请根据实际部署拓扑完成升级准备，再按安装时选择的部署方式执行对应的升级步骤。

升级路径

部署拓扑	当前版本	目标版本	升级方式
单机部署	3.0.x、3.1.x	3.2.0	脚本和命令行部署：升级程序 容器镜像部署：容器镜像升级
	1.x、2.x	3.2.0	导入导出
多副本集群	3.0.x、3.1.x	3.2.0	脚本和命令行部署：升级程序 容器镜像部署：容器镜像升级
	1.x、2.x	3.2.0	导入导出
单副本集群	3.0.x、3.1.x	3.2.0	脚本和命令行部署：升级程序 容器镜像部署：容器镜像升级
	1.x、2.x	3.2.0	导入导出

说明

• 从 3.0.0 升级至 3.2.0 时，如需使用 3.0.1 以后新增的时序 raft log 存储引擎，请先部署全新集群，再导入历史数据。
• 3.2.0 版本将 ts.raft_log.sync_period 默认值从 10s 改为 0s（实时落盘）。多副本集群从 3.0.x 或 3.1.x 升级至 3.2.0 前，需要提前在旧版本节点将该参数切换为 0s 并等待生效，否则可能导致升级异常。具体操作，参见集群部署升级准备中的相关步骤。

注意事项

• 升级后无法简单降级至之前版本。如果需要降级，必须先卸载当前版本，再使用原有版本安装 KaiwuDB，然后使用卸载前创建的备份将数据还原到数据库。有关卸载数据库的详细信息，参见卸载 KaiwuDB。

• 三权分立模式下，如需从历史版本升级到 KaiwuDB 2.1.1 及后续版本，升级前需要删除已有的 secroot、sysroot、auditroot、secadmin、sysadmin、auditadmin 用户。如未删除，启动新版本时，系统报错：

  failed to run migration "disallow exist separate user": 
  found users [auditadmin, auditroot, secadmin, secroot, sysadmin, sysroot] which are now reserved names. 
  Please drop the role using a previous version of KaiwuDB and try 
  

• KaiwuDB 支持通过导入导出方式将之前任一版本升级至最新版本。具体操作，参见数据导出和数据导入。注意：从 2.x 版本升级时，导出的 meta.sql 文件中包含时序表的 PARTITION INTERVAL 语法。由于 3.1.0 及以后版本的时序表已废弃该语法（注：时序库仍然支持），导入前需手动删除文件中的相关语法，否则会导致导入失败；使用导入导出升级方式升级后，多副本集群的高可用性可能会受到影响。

升级准备

单机部署

1. 确认新版本高于已安装版本。

2. 停止 KaiwuDB 服务：

   systemctl stop kaiwudb
   

3. 备份用户数据目录。

集群部署

1. 确认新版本高于已安装版本。

2. 如果是多副本集群，在升级前完成以下操作：

   1. 将 ts.raft_log.sync_period 切换为 0s：

      SET CLUSTER SETTING ts.raft_log.sync_period = '0s';
      

   2. 等待 5 分钟以上，待集群完成参数切换。

   3. 查询分片状态，确认集群运行正常，如果状态异常，可多次重试上述操作。

      SELECT * FROM kwdb_internal.ranges;
      

3. 检查集群状态：

   • 通过 KaiwuDB 监控平台的总览页面：

     • 在节点状态下检查是否有异常节点或不可用节点。集群中存在异常或不可用节点时，将无法进行升级。
     • 在副本状态下检查是否有不可用分区或副本数不足分区。
     • 在 Nodes 下检查各节点版本是否一致，内存和 CPU 等资源是否有足够余量。如果资源紧张，需要先添加节点到集群中，再进行升级操作。

   • 通过命令：

     • 查看集群状态：

       kw-status
       

     • 查看副本状态：

       SELECT sum((metrics->>'ranges.unavailable')::DECIMAL)::INT AS ranges_unavailable,
           sum((metrics->>'ranges.underreplicated')::DECIMAL)::INT As ranges_underreplicated
       FROM kwdb_internal.kv_store_status;
       

4. 检查是否存在正在执行的模式更改或批量导入操作：

   • 通过 KaiwuDB 监控平台的事件页面
   • 通过 SHOW JOBS SQL 命令

5. 检查集群内表的 leaseholder 和副本的分布是否均匀：

   SELECT * from kwdb_internal.ranges
   

6. 备份集群。如果升级失败，可以使用备份将集群还原到之前的状态。

执行升级

安装程序升级

使用安装程序升级过程中，如果出现节点未安装 KaiwuDB、KaiwuDB 仍在运行中、版本有误或部署方式有误等错误，系统将中止升级并给予相应提示。

前提条件

• 已获取新版本的 KaiwuDB 安装程序（.run 文件）。
• 待升级节点已安装 KaiwuDB。
• 已备份待升级节点的用户数据目录。
• 执行节点（集群内任一节点）可通过 SSH 登录至待升级节点，并对待升级节点的安装目录拥有写入权限。
• 不同模式对用户的要求不同：
  • 命令行模式或终端图形交互模式：用户为 root 用户或已配置 sudo 免密的普通用户。
  • 可视化 GUI 模式：用户为 root 用户或拥有 sudo 权限的普通用户。
• 容器部署方式下，如果用户为非 root 用户，需要通过 sudo usermod -aG docker $USER 命令将用户添加到 docker 组。

命令行模式

1. 将新版本安装程序复制至执行升级操作的集群节点，并赋予执行权限：

   chmod +x KaiwuDB-*.run
   

2. 在待升级节点，停止 KaiwuDB 服务：

   sudo systemctl stop kaiwudb
   

3. 在执行节点，以命令行模式启动安装程序：

   ./KaiwuDB-*.run -c
   # 或者
   ./KaiwuDB-*.run --cli
   

4. 在主功能菜单中，输入 4 选择升级节点：

   1. 安装 KaiwuDB
   2. 卸载 KaiwuDB
   3. 安装 KaiwuDB 并加入集群
   4. 升级节点
   5. 退出
   
   请输入操作 [1-5]:
   

5. 将待升级的节点数量设置为 1。

6. 安装程序自动生成升级配置文件并打开编辑器，将 host 地址修改为待升级节点的 IP 地址，确认其余配置无误后保存退出，系统自动开始升级。

   [node1]
   host=192.168.122.224
   port=22
   user=admin
   passwd=*******
   

7. 在待升级节点，根据部署方式修改相关配置文件：

   • 裸机部署：修改以下配置文件，将 IP 地址替换为实际节点 IP：

     sudo vim /etc/systemd/system/kaiwudb.service
     sudo vim /usr/local/kaiwudb/bin/kw-status.sh
     sudo vim /usr/local/kaiwudb/bin/kw-sql.sh
     

   • 容器部署：

     1. 修改 /etc/kaiwudb/script/docker-compose.yml：

        1. 删除 ports 配置块和 deploy.resources 配置块。
        2. 将 networks 改为 host 模式：

           network_mode: host
           

        3. 将 command 中的 IP 改为实际节点 IP。

     2. 修改以下脚本中的节点 IP：

        sudo vim /etc/kaiwudb/script/kw-status.sh
        sudo vim /etc/kaiwudb/script/kw-sql.sh
        

8. 在待升级节点，重新加载系统服务配置并启动 KaiwuDB：

   sudo systemctl daemon-reload
   sudo systemctl start kaiwudb
   

9. 在待升级节点，检查节点状态：

   kw-status
   

10. 对集群中的其余节点重复步骤 2–9，逐一完成升级。

11. 完成所有节点升级后，重新申请并配置许可证，参见升级后重新申请许可证。

12. 许可证配置完成后，验证数据是否完整。多副本集群还需查询分片状态，确认集群状态正常。

    SELECT * FROM kwdb_internal.ranges;
    

终端图形交互模式

1. 将新版本安装程序复制至执行升级操作的集群节点，并赋予执行权限：

   chmod +x KaiwuDB-*.run
   

2. 在待升级节点，停止 KaiwuDB 服务：

   sudo systemctl stop kaiwudb
   

3. 在执行节点，以终端图形交互模式启动安装程序：

   ./KaiwuDB-*.run -i
   # 或者
   ./KaiwuDB-*.run --interact
   

4. 在主功能菜单中，使用方向键选中升级节点，按回车确认。

5. 进入升级参数设置菜单，点击设置升级节点，依次填写待升级节点的 IP、端口、用户名和密码，点击保存。选中开始升级，按回车开始升级。

6. 在待升级节点，根据部署方式修改相关配置文件：

   • 裸机部署：修改以下配置文件，将 IP 地址替换为实际节点 IP：

     sudo vim /etc/systemd/system/kaiwudb.service
     sudo vim /usr/local/kaiwudb/bin/kw-status.sh
     sudo vim /usr/local/kaiwudb/bin/kw-sql.sh
     

   • 容器部署：

     1. 修改 /etc/kaiwudb/script/docker-compose.yml：

        1. 删除 ports 配置块和 deploy.resources 配置块。
        2. 将 networks 改为 host 模式：

           network_mode: host
           

        3. 将 command 中的 IP 改为实际节点 IP。

     2. 修改以下脚本中的节点 IP：

        sudo vim /etc/kaiwudb/script/kw-status.sh
        sudo vim /etc/kaiwudb/script/kw-sql.sh
        

7. 在待升级节点，重新加载系统服务配置并启动 KaiwuDB：

   sudo systemctl daemon-reload
   sudo systemctl start kaiwudb
   

8. 在待升级节点，检查节点状态：

   kw-status
   

9. 对集群中的其余节点重复步骤 2–8，逐一完成升级。

10. 完成所有节点升级后，重新申请并配置许可证，参见升级后重新申请许可证。

11. 许可证配置完成后，验证数据是否完整。多副本集群还需查询分片状态，确认集群状态正常。

    SELECT * FROM kwdb_internal.ranges;
    

可视化 GUI 模式

1. 将新版本安装程序复制至执行升级操作的集群节点，并赋予执行权限：

   chmod +x KaiwuDB-*.run
   

2. 在待升级节点，停止 KaiwuDB 服务：

   sudo systemctl stop kaiwudb
   

3. 在执行节点，以可视化 GUI 模式启动安装程序：

   sudo ./KaiwuDB-*.run -g
   # 或者
   sudo ./KaiwuDB-*.run --gui
   

4. 在操作向导页面，选中版本升级，点击下一步。

5. 在节点管理页面，点击增加节点，填写待升级节点的 IP、端口、用户名和密码，点击保存。

6. 点击下一步，等待升级完成。

7. 点击结束退出安装程序。

8. 在待升级节点，根据部署方式修改相关配置文件：

   • 裸机部署：修改以下配置文件，将 IP 地址替换为实际节点 IP：

     sudo vim /etc/systemd/system/kaiwudb.service
     sudo vim /usr/local/kaiwudb/bin/kw-status.sh
     sudo vim /usr/local/kaiwudb/bin/kw-sql.sh
     

   • 容器部署：

     1. 修改 /etc/kaiwudb/script/docker-compose.yml：

        1. 删除 ports 配置块和 deploy.resources 配置块。
        2. 将 networks 改为 host 模式：

           network_mode: host
           

        3. 将 command 中的 IP 改为实际节点 IP。

     2. 修改以下脚本中的节点 IP：

        sudo vim /etc/kaiwudb/script/kw-status.sh
        sudo vim /etc/kaiwudb/script/kw-sql.sh
        

9. 在待升级节点，重新加载系统服务配置并启动 KaiwuDB：

   sudo systemctl daemon-reload
   sudo systemctl start kaiwudb
   

10. 在待升级节点，检查节点状态：

    kw-status
    

11. 对集群中的其余节点重复步骤 2–10，逐一完成升级。

12. 完成所有节点升级后，重新申请并配置许可证，参见升级后重新申请许可证。

13. 许可证配置完成后，验证数据是否完整。多副本集群还需查询分片状态，确认集群状态正常。

    SELECT * FROM kwdb_internal.ranges;
    

容器镜像升级

使用 Docker 容器镜像部署的 KaiwuDB 实例，可以通过更新容器镜像的方式进行升级。

Docker Compose

前提条件

• 已完成数据和配置备份。
• 已获取新版本容器镜像。

步骤

1. 加载新版本容器镜像：

   docker load < KaiwuDB.tar
   

2. 停止并移除现有容器：

   docker-compose down
   

3. 删除旧版本镜像：

   docker rmi ${image_name}
   

4. 修改 docker-compose.yml 文件，更新镜像版本。

5. 启动新版本 KaiwuDB：

   docker-compose up -d
   

6. 检查容器是否已正常运行：

   docker-compose ps
   

Docker Run

前提条件

• 已完成数据和配置备份。
• 已获取新版本容器镜像。

步骤

1. 停止 KaiwuDB 容器。容器名称为运行容器时通过 --name 参数指定的容器名称。

   docker stop <kaiwudb_container>
   

2. 删除容器：

   docker rm <kaiwudb_container>
   

3. 加载新版本镜像：

   docker load < KaiwuDB.tar
   

4. 启动新版本容器。除镜像名称外，其余参数应与原容器保持一致：

   docker run -d --name <kaiwudb_container> \
     [原容器参数] \
     <new_image_name>
   

5. 检查容器是否已正常运行：

   docker ps