数据库升级

本节介绍了 KaiwuDB 数据库在不同部署方式下的升级方法，包括使用部署脚本及容器镜像部署的升级流程。升级前请务必仔细阅读相关注意事项，并根据实际部署方式选择合适的升级方案。

使用部署脚本升级

部署脚本升级是 KaiwuDB 最常用的升级方式，适用于通过部署脚本安装的 KaiwuDB 实例。根据部署拓扑的不同，可分为单机升级、多副本集群升级和单副本集群场景。 不同部署方式支持的升级方式有所不同：

• 单机部署：

  • 使用升级脚本将 2.1.1 或 2.2.0 离线升级至 2.2.1，有关详细信息，参见单机升级。
  • 使用升级和标签调整脚本将 2.0.4 或 2.0.4.1 升级至 2.1.0，有关详细信息，参见 2.1.0 版本数据库升级。

• 多副本集群：

  • 通过逐一升级集群节点将 2.1.1 或 2.2.0 在线升级至 2.2.1，有关详细信息，参见多副本集群升级。
  • 使用升级和标签调整脚本将 2.0.4 或 2.0.4.1 在线升级至 2.1.0，有关详细信息，参见 2.1.0 版本集群升级。

• 单副本集群：

  • 使用升级脚本将 2.1.1 或 2.2.0 离线升级至 2.2.1，有关详细信息，参见单副本集群升级。

说明

• 升级后无法简单降级至之前版本。如果需要降级，必须先卸载当前版本，再使用原有版本安装 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.1.1 或 2.2.0 单机版本离线升级至 2.2.1 版本。

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

升级过程中，如果因新版本导入失败导致升级失败，系统将保留数据目录、证书和配置文件，删除节点中的新版本安装文件，用户可以选择手动安装新版本或旧版本。

前提条件

• 待升级节点已安装 KaiwuDB。
• 已备份待升级节点的用户数据目录。
• 已获取新版本的 KaiwuDB 安装包，且新版本高于已安装版本。
• 用户为 root 用户或者拥有 sudo 权限的普通用户。
  • root 用户和配置 sudo 免密的普通用户在执行命令时无需输入密码。
  • 未配置 sudo 免密的普通用户在执行命令时，需要输入密码进行提权。
  • 容器部署方式下，如果用户为非 root 用户，需要通过 sudo usermod -aG docker $USER 命令将用户添加到 docker 组。

步骤

1. 将新版本安装包拷贝至待升级的节点，解压安装包。

2. 检查 KaiwuDB 服务是否已停止。如果 KaiwuDB 服务仍在运行中，执行 systemctl stop kaiwudb 命令停止服务。

   systemctl status kaiwudb
   

3. 切换至新版本的安装包目录。

4. 执行本地升级命令。

   ./deploy.sh upgrade -l
   

   或者

   ./deploy.sh upgrade --local
   

   执行成功后，控制台输出以下信息：

   UPGRADE COMPLETED: KaiwuDB has been upgraded successfully! 
   

5. 启动 KaiwuDB。

   systemctl start kaiwudb
   

6. 启动成功后，检查数据库是否已正常运行。

   systemctl status kaiwudb
   

多副本集群升级

本节介绍了如何通过逐一升级集群节点将 2.1.1 或 2.2.0 版本的多副本集群在线升级至 2.2.1 版本。

在升级过程中，升级节点上的压缩与生命周期可能会执行失败，在升级完成后恢复正常。如果升级过程中出现错误，例如节点未安装 KaiwuDB、节点状态异常或部署方式有误，系统将中止升级，并给与相应提示。

准备升级

步骤：

1. 确保客户端与多个节点通信，避免单节点升级时客户端通信中断。

2. 查看集群状态。

   • 在 KaiwuDB 监控平台的总览页面查看集群状态：

     1. 在节点状态下检查是否有异常节点或不可用节点，如果有，需要确认原因，重新启动或者停用该节点。集群中存在异常或不可用节点时，将无法进行升级。

     2. 在副本状态下检查是否有不可用分区或副本数不足分区。

     3. 在Nodes下检查各节点版本是否一致，内存和 CPU 等资源是否有足够的余量，如果资源紧张，需要先添加节点到集群中，再进行升级操作，以避免升级后的版本可能使用更多的资源。

   • 通过命令查看集群状态：

     1. 检查集群节点状态。

        <kwbase_path>/kwbase node status [--host=<ip:port>] [--insecure | --certs-dir=<path>]
        

     2. 查看副本状态。

        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;
        

3. 在 KaiwuDB 监控平台的事件页面或使用 SHOW JOBS SQL 命令检查是否存在正在执行的模式更改或批量导入操作。

4. 使用 SELECT * from kwdb_internal.ranges SQL 命令检查集群内表的 leaseholder（租约持有者）和副本的分布是否均匀。

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

执行升级

为集群中的每个节点，执行以下升级操作。确保每次只升级一个节点。该节点重新加入集群后，确认节点版本、状态无误后，再升级下一个节点。

前提条件：

• 待升级节点已安装 KaiwuDB，且节点状态为存活状态（is_available和is_live均为true）。
• 已备份待升级节点的用户数据目录。
• 已获取新版本的 KaiwuDB 安装包，且新版本高于已安装版本。
• 用户为 root 用户或者拥有 sudo 权限的普通用户。
  • root 用户和配置 sudo 免密的普通用户在执行命令时无需输入密码。
  • 未配置 sudo 免密的普通用户在执行命令时，需要输入密码进行提权。
  • 容器部署方式下，如果用户为非 root 用户，需要通过 sudo usermod -aG docker $USER 命令将用户添加到 docker 组。

步骤：

1. 将新版本的安装包拷贝到待升级的节点，解压安装包。

2. 检查 KaiwuDB 服务是否已停止。如果 KaiwuDB 服务仍在运行中，执行 systemctl stop kaiwudb 命令停止服务。

   systemctl status kaiwudb
   

3. 切换至新版本的安装包目录。

4. 执行本地升级命令。

   ./deploy.sh upgrade -l
   

   或者

   ./deploy.sh upgrade --local
   

   执行成功后，控制台输出以下信息：

   UPGRADE COMPLETED: KaiwuDB has been upgraded successfully! ...
   

5. 启动 KaiwuDB。

   systemctl start kaiwudb
   

6. 启动成功后，检查数据库是否已正常运行。

   systemctl status kaiwudb
   

单副本集群升级

本节介绍了如何将 2.1.1 或 2.2.0 版本的单副本集群离线升级至 2.2.1 版本。

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

升级过程中，如果因新版本导入失败导致升级失败，系统将保留数据目录、证书和配置文件，删除节点中的新版本安装文件，用户可以选择手动安装新版本或旧版本。

前提条件

• 待升级节点已安装 KaiwuDB。
• 已备份所有节点的用户数据目录。
• 已获取新版本的 KaiwuDB 安装包，且新版本高于已安装版本。
• 用户为 root 用户或者拥有 sudo 权限的普通用户。
  • root 用户和配置 sudo 免密的普通用户在执行命令时无需输入密码。
  • 未配置 sudo 免密的普通用户在执行命令时，需要输入密码进行提权。
  • 容器部署方式下，如果用户为非 root 用户，需要通过 sudo usermod -aG docker $USER 命令将用户添加到 docker 组。

步骤

1. 在集群所有节点执行停止数据库命令。

   systemctl stop kaiwudb
   

2. 在每个节点执行以下升级操作：

   1. 将新版本安装包拷贝至待升级的节点，解压安装包。

   2. 切换至新版本的安装包目录。

   3. 执行本地升级命令。

      ./deploy.sh upgrade -l
      

      或者

      ./deploy.sh upgrade --local
      

      执行成功后，控制台输出以下信息：

      UPGRADE COMPLETED: KaiwuDB has been upgraded successfully! 
      

3. 所有节点完成升级后，在每个节点执行以下命令启动数据库。

   1. 启动数据库。

      systemctl start kaiwudb
      

   2. 启动成功后，检查数据库是否已正常运行。

      systemctl status kaiwudb
      

容器镜像部署升级

使用 Docker 容器镜像部署的 KaiwuDB 实例，可以通过更新容器镜像的方式进行升级。具体升级方式包括 Docker Compose 升级和 Docker Run 升级。

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
   

Docker Run 升级

前提条件

• 已完成数据和配置备份

步骤

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

   docker stop kaiwudb-container
   

2. 删除容器。

   docker rm kaiwudb-container
   

3. 加载新版本镜像。

   docker load < KaiwuDB.tar
   

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