升级手册

1. 升级版本兼容性

当前文档所对应的版本为3.0.0，所有Nacos版本可升级到该版本的兼容性如下：

2. 升级步骤

2.1. 发行版升级

2.1.1 确认表结构

先对比部署的旧版本Nacos版本的mysql-schema.sql文件和将升级版本的mysql-schema.sql文件，确认表结构是否有变化。

若文件中表结构存在变化，请先进行数据库变更，例如：

-- 从 2.0.X 升级时需要执行下列所有SQL, 从2.1.X之后版本升级仅需执行最后三行。
ALTER TABLE `config_info` ADD COLUMN `encrypted_data_key` varchar(1024) NOT NULL DEFAULT '' COMMENT '密钥';
ALTER TABLE `config_info_gray` ADD COLUMN `encrypted_data_key` varchar(1024) NOT NULL DEFAULT '' COMMENT '密钥';
ALTER TABLE `config_info_beta` ADD COLUMN `encrypted_data_key` varchar(1024) NOT NULL DEFAULT '' COMMENT '密钥';
ALTER TABLE `his_config_info` ADD COLUMN `encrypted_data_key` varchar(1024) NOT NULL DEFAULT '' COMMENT '密钥';
ALTER TABLE `his_config_info` ADD COLUMN `publish_type` varchar(50)  DEFAULT 'formal' COMMENT 'publish type gray or formal';
ALTER TABLE `his_config_info` ADD COLUMN `gray_name` varchar(50)  DEFAULT NULL COMMENT 'gray name';
ALTER TABLE `his_config_info` ADD COLUMN `ext_info`  longtext DEFAULT NULL COMMENT 'ext info';

2.1.2. 下载新版本

2.1.3. 替换二进制jar包

解压新下载的发行版压缩包

  unzip nacos-server-$version.zip
  # 或者 tar -xvf nacos-server-$version.tar.gz

然后 找到nacos/targer/nacos-server.jar 将该jar包替换到旧的发行版中，例如：

cp nacos/target/nacos-server.jar ${old.nacos.home}/target/

2.1.4. 修改配置文件

Nacos 3.0.X 版本相比Nacos 2.X版本有较大的配置文件内容改动，除了新增大量关于server和console的相关配置，还对参数的顺序进行了改动，因此请务必仔细对比新版本和旧版本的配置文件，并重新设置Nacos的配置文件。

主要的参数改动如下：

server.port —> nacos.server.main.port

server.servlet.contextPath —> nacos.server.contextPath

2.1.5. 修改启动参数（可选）

对比部署的旧版本的启动脚本和新版本的启动脚本bin/startup.sh或bin/startup.cmd，确认是否有新增或修改的配置项，将这些配置项添加到旧的启动脚本件中，例如：

diff nacos/bin/startup.sh ${old.nacos.home}/bin/startup.sh

2.1.6. 重启Nacos Server

均替换完成后，重启Nacos Server:

# 以集群模式为例
## Linux
${nacos.home}/bin/shutdown.sh
${nacos.home}/bin/startup.sh

## Windows
${nacos.home}/bin/shutdown.cmd
${nacos.home}/bin/startup.cmd

2.1.7. 配置中心命名空间迁移

Nacos 3.0 中对于配置中心的空命名空间和public命名空间进行了统一，将namespaceId="public"的命名空间作为默认命名空间，并将原先namespaceId=""的命名空间的配置数据全部统一到namespaceId="public"的命名空间中。 相关ISSUE。

为了能够完成平滑升降级，Nacos 3.0 将会开启配置中心命名空间兼容模式，将namespaceId="public"的命名空间和namespaceId=""的命名空间的配置数据进行双向同步，因此会对性能有一定影响。当集群升级并稳定运行后，可以关闭配置中心命名空间兼容模式，关闭兼容模式后将会失去平滑降级的功能。

命名空间的兼容模式默认为开启状态，可以通过nacos.config.namespace.compatible.mode配置项关闭。

2.1.7.1. 如何确认配置命名空间迁移已经完成

首先查看nacos目录下 logs/start.out或logs/nacos.log 观察到nacos启动成功的日志，如 Nacos started successfully in cluster mode. use xxx storage 说明程序已启动成功。

如果观察到[migrate] config_info namespace migrate insert failed 日志，则说明数据库中namespaceId="public"的命名空间和namespaceId=""的命名空间下存在配置数据冲突的情况，即存在dataId、group相同，但是namespaceId分别为空和public的两份配置，请删除其中一份配置数据后再尝试启动节点。 如果观察到[migrate] config_info_gray namespace migrate insert failed日志，则说明数据库中namespaceId="public"的命名空间和namespaceId=""的命名空间下存在灰度配置数据冲突的情况，即存在dataId、group、grayName相同，但是namespaceId分别为空和public的两份配置，请删除其中一份灰度配置数据后再尝试启动节点。

如果没有观察到上述两个错误信息，而是[migrate] finish migrate config namespacetotal time taken: xxx ms 那么说明此时配置命名空间迁移已经完成，再进行业务配置使用验证无误后，可以关闭命名空间兼容模式。

2.1.7.2. 配置命名空间迁移导致首次启动较慢

在升级过程中，Nacos 3.0会对配置中的namespaceId=""的命名空间下存在配置进行全量迁移，因此升级过程中，首次启动Nacos 3.0版本时，可能会存在较长的启动时间，具体时间由配置数据量决定。

迁移过程中，您可以从logs/nacos.log日志中观察到如下日志[migrate] migrating config namespace from empty to public, finished:xxx.

根据测试 配置namespaceId=""的命名空间下若存在 20000个左右配置时， 迁移过程会在2分钟左右结束， 这依赖于如下配置及数据库的处理能力大小：

# 迁移时，每批迁移的配置数量，默认100，增加此值可提高迁移速度，但也会随之增加对数据库的压力。
nacos.namespace.migrate.batch.size=100

2.2. Docker/Kubernetes升级

3.0.0-BETA 版本暂时未提供docker镜像，以下内容仍然为旧版，将在3.0.0 正式发布后更新。

2.2.1 确认表结构

先对比部署的旧版本Nacos版本的mysql-schema.sql文件和将升级版本的mysql-schema.sql文件，确认表结构是否有变化。

若文件中表结构存在变化，请先进行数据库变更，例如：

ALTER TABLE `config_info` ADD COLUMN `encrypted_data_key` varchar(255) NOT NULL COMMENT '密钥',

2.2.2. 确认环境变量

可以对比当前部署版本的环境变量与系统参数-镜像环境变量中的环境变量是否有变化，如有，需要修改Docker的环境变量文件或Kubernetes的regcenter中的环境变量。

2.2.3. 修改镜像版本

services:
    nacos:
        image:
            nacos/nacos-server:${target_version}

  docker-compose pull
  docker-compose up -d --remove-orphans

    kubectl set image deployment/nacos-deployment ${container_name}=nacos/nacos-server:${target_version}