Upgrade Manual

1. Version Upgrade Compatibility

This document corresponds to version 3.2.0. The compatibility of upgrading from all Nacos versions to this version is as follows:

1.1 Client Compatibility

Compatibility between Nacos 3.x server and client versions is as follows:

2. Upgrade Steps

2.1. Distribution Upgrade

2.1.1 Verify Database Schema

Compare the mysql-schema.sql file of your currently deployed Nacos version with that of the target version to check for schema changes.

If there are schema changes, apply the database alterations first (MySQL example):

-- 从 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';

Version 3.2.0 introduces new AI-related tables. The following tables must be created when upgrading to 3.2.X from any previous version:

CREATE TABLE IF NOT EXISTS `pipeline_execution` (
    `execution_id`  varchar(64)  NOT NULL COMMENT '执行ID',
    `resource_type` varchar(32)  NOT NULL COMMENT '资源类型',
    `resource_name` varchar(256) NOT NULL COMMENT '资源名称',
    `namespace_id`  varchar(128) DEFAULT NULL COMMENT '命名空间ID',
    `version`       varchar(64)  DEFAULT NULL COMMENT '版本',
    `status`        varchar(32)  NOT NULL COMMENT '执行状态',
    `pipeline`      longtext     NOT NULL COMMENT 'pipeline节点结果JSON',
    `create_time`   bigint(20)   NOT NULL COMMENT '创建时间',
    `update_time`   bigint(20)   NOT NULL COMMENT '修改时间',
    PRIMARY KEY (`execution_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='AI资源发布审核Pipeline执行记录';

CREATE TABLE IF NOT EXISTS `ai_resource` (
    `id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT 'id',
    `gmt_create` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    `gmt_modified` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '修改时间',
    `name` varchar(256) NOT NULL COMMENT '资源名称',
    `type` varchar(32) NOT NULL COMMENT '资源类型',
    `c_desc` varchar(2048) DEFAULT NULL COMMENT '资源描述',
    `status` varchar(32) DEFAULT NULL COMMENT '资源状态',
    `namespace_id` varchar(128) NOT NULL DEFAULT '' COMMENT '命名空间ID',
    `biz_tags` varchar(1024) DEFAULT NULL COMMENT '业务标签',
    `ext` longtext DEFAULT NULL COMMENT '扩展信息(JSON)',
    `c_from` varchar(256) NOT NULL DEFAULT 'local' COMMENT '来源标识(导入/同步来源)',
    `version_info` longtext DEFAULT NULL COMMENT '版本信息(JSON)',
    `meta_version` bigint(20) NOT NULL DEFAULT 1 COMMENT '元数据版本(乐观锁)',
    `scope` varchar(16) NOT NULL DEFAULT 'PRIVATE' COMMENT '可见性: PUBLIC/PRIVATE',
    `owner` varchar(128) NOT NULL DEFAULT '' COMMENT '创建者用户名',
    `download_count` bigint(20) NOT NULL DEFAULT 0 COMMENT '下载次数',
    PRIMARY KEY (`id`),
    UNIQUE KEY `uk_ai_resource_ns_name_type` (`namespace_id`,`name`,`type`,`c_from`),
    KEY `idx_ai_resource_name` (`name`),
    KEY `idx_ai_resource_type` (`type`),
    KEY `idx_ai_resource_gmt_modified` (`gmt_modified`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='AI资源元数据表';

CREATE TABLE IF NOT EXISTS `ai_resource_version` (
    `id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT 'id',
    `gmt_create` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    `gmt_modified` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '修改时间',
    `type` varchar(32) NOT NULL COMMENT '资源类型',
    `author` varchar(128) DEFAULT NULL COMMENT '作者',
    `name` varchar(256) NOT NULL COMMENT '资源名称',
    `c_desc` varchar(2048) DEFAULT NULL COMMENT '版本描述',
    `status` varchar(32) NOT NULL COMMENT '版本状态',
    `version` varchar(64) NOT NULL COMMENT '版本号',
    `namespace_id` varchar(128) NOT NULL DEFAULT '' COMMENT '命名空间ID',
    `storage` longtext DEFAULT NULL COMMENT '存储信息(JSON)',
    `publish_pipeline_info` longtext DEFAULT NULL COMMENT '发布流水线信息(JSON)',
    `download_count` bigint(20) NOT NULL DEFAULT 0 COMMENT '下载次数',
    PRIMARY KEY (`id`),
    UNIQUE KEY `uk_ai_resource_ver_ns_name_type_ver` (`namespace_id`,`name`,`type`,`version`),
    KEY `idx_ai_resource_ver_name` (`name`),
    KEY `idx_ai_resource_ver_status` (`status`),
    KEY `idx_ai_resource_ver_gmt_modified` (`gmt_modified`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='AI资源版本表';

2.1.2. Download the New Version

2.1.3. Replace the Binary JAR

Extract the newly downloaded distribution package:

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

Then locate nacos/target/nacos-server.jar and replace the JAR in the old distribution. For example:

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

2.1.4. Update Configuration Files

Nacos 3.0.X has significant configuration changes compared to Nacos 2.X, including many new server and console related settings, as well as parameter reordering. Please carefully compare the configuration files between the new and old versions and reconfigure accordingly.

Key parameter changes:

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

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

2.1.5. Update Startup Parameters (Optional)

Compare the startup scripts (bin/startup.sh or bin/startup.cmd) between the old and new versions to check for new or modified parameters, and apply them to the old startup scripts. For example:

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

2.1.6. Restart Nacos Server

After all replacements are complete, restart Nacos Server:

# Cluster mode example
## 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. Config Namespace Migration

In Nacos 3.0, the empty namespace and public namespace for the config center have been unified. The namespace with namespaceId="public" is now the default namespace, and all config data previously under namespaceId="" has been migrated to namespaceId="public". Related ISSUE.

To enable smooth upgrade and downgrade, Nacos 3.0 enables a config namespace compatibility mode that bidirectionally syncs config data between the namespaceId="public" and namespaceId="" namespaces, which may have some performance impact. Once the cluster upgrade is complete and running stably, you can disable the compatibility mode. Note that disabling it will remove the ability to smoothly downgrade.

The namespace compatibility mode is enabled by default and can be disabled via the nacos.config.namespace.compatible.mode configuration.

2.1.7.1. How to Verify Config Namespace Migration is Complete

First, check logs/startup.log or logs/nacos.log in the Nacos directory for a successful startup log message such as Nacos started successfully in cluster mode. use xxx storage.

If you see the log [migrate] config_info namespace migrate insert failed, it indicates a config data conflict between namespaceId="public" and namespaceId="" — there are configs with the same dataId and group but different namespaceIds (empty and public). Please delete one of the conflicting configs and restart the node. If you see [migrate] config_info_gray namespace migrate insert failed, it indicates a gray config data conflict — configs with the same dataId, group, and grayName but different namespaceIds. Please delete one of the conflicting gray configs and restart.

If neither error appears and you instead see [migrate] finish migrate config namespacetotal time taken: xxx ms, it means the namespace migration is complete. After verifying your business configs are working correctly, you can disable the namespace compatibility mode.

2.1.7.2. Slow First Startup Due to Namespace Migration

During the upgrade, Nacos 3.0 performs a full migration of all configs under the namespaceId="" namespace. This may result in a longer startup time when first launching Nacos 3.0, depending on the volume of config data.

During migration, you can observe the following log in logs/nacos.log: [migrate] migrating config namespace from empty to public, finished:xxx.

Based on testing, with approximately 20,000 configs under namespaceId="", the migration takes about 2 minutes. This depends on the following configuration and your database’s processing capacity:

# Number of configs to migrate per batch. Default is 100. Increasing this value speeds up migration but increases database load.
nacos.namespace.migrate.batch.size=100

2.1.8. Migrate MCP Services (Optional)

If you are upgrading from version 3.0.0 and your cluster has MCP services, note that due to changes in the official MCP Registry API standard, the MCP Server metadata structure has changed. This incompatibility means that after upgrading from 3.0.0 to 3.0.1 or later, the console will be unable to read legacy MCP Server data. You need to use the MCP Migration Tool to migrate the existing MCP service data from version 3.0.0.

# java -jar ./mcp-migration-tool.jar ${nacos-server-host}:${nacos-server-port} ${username} ${password}
# Example
java -jar ./mcp-migration-tool.jar localhost:8848 nacos ${your_password}

2.2. Docker/Kubernetes Upgrade

2.2.1 Verify Database Schema

Please refer to 2.1.1 Verify Database Schema to compare and apply database schema changes.

2.2.2. Verify Environment Variables

Compare the environment variables of your current deployment with System Parameters - Image Environment Variables to check for changes. If there are any, update the Docker environment variable file or Kubernetes configmap/secret accordingly.

For example, add the following environment variables:

NACOS_AUTH_TOKEN=${Base64-encoded token from a custom string of 32+ characters}
NACOS_AUTH_IDENTITY_KEY=${any string}
NACOS_AUTH_IDENTITY_VALUE=${any string}

2.2.3. Update Image Version

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}

3. Legacy HTTP API Removal (Nacos 3.2.0+)

3.1 API Removal Notice

The old v1 and v2 HTTP APIs are no longer included in the default Nacos server distribution. These APIs have been migrated to a separate legacy adapter module.

Affected APIs:

• All v1 REST APIs (e.g., /nacos/v1/ns/instance, /nacos/v1/cs/configs)
• All v2 REST APIs

3.2 Migration Options

You have two options:

Option 1: Migrate to New APIs and Clients (Recommended)

• Use the new v3 APIs
  • v3 Admin API Documentation
  • v3 Console API Documentation
• Upgrade to the latest Nacos client SDK
  • Nacos Client Documentation

Option 2: Use Legacy API Adapter (Temporary Solution)

If you need time to migrate, you can temporarily restore the old APIs using the legacy adapter.

3.3 Installing the Legacy API Adapter

Step 1: Build or Download the Adapter

Option A: Download from Release

# Download from GitHub releases
wget https://github.com/nacos-group/nacos-api-legacy-adapter/releases/download/v${version}/nacos-api-legacy-adapter-${version}.jar

Option B: Build from Source

git clone https://github.com/nacos-group/nacos-api-legacy-adapter.git
cd nacos-api-legacy-adapter
mvn clean install
# Output: target/nacos-api-legacy-adapter-${version}.jar

Requirements:

• JDK 17+
• Maven 3.6+
• The nacos.version in pom.xml must match the target Nacos server version

Step 2: Install the Adapter

For Nacos Server Deployment:

1. Place the JAR file in the Nacos plugins directory:

cp nacos-api-legacy-adapter-${version}.jar ${NACOS_HOME}/plugins/

2. Restart Nacos server:

sh ${NACOS_HOME}/bin/shutdown.sh
sh ${NACOS_HOME}/bin/startup.sh -m standalone  # Standalone mode
# or
sh ${NACOS_HOME}/bin/startup.sh                # Cluster mode

3. The adapter will automatically load when the JAR is in the classpath.

For Embedded/Custom Applications:

Add the Maven dependency:

<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-api-legacy-adapter</artifactId>
    <version>${nacos.version}</version>
</dependency>

Step 3: Verify Installation

Check Nacos server logs for confirmation:

tail -f ${NACOS_HOME}/logs/nacos.log

Look for log messages indicating the legacy adapter has loaded.

Step 4: Test Legacy APIs

Test that your old v1/v2 API calls work again:

curl -X GET "http://localhost:8848/nacos/v1/ns/instance/list?serviceName=test"

3.4 Version Compatibility

Important: The adapter version must match your Nacos server version.

3.5 Planning Your Migration

While using the legacy adapter, plan your migration:

1. Audit your API usage - Identify all v1/v2 API calls
2. Review new v3 APIs - Understand the new API structure
3. Update clients - Upgrade to latest Nacos client SDKs
4. Test thoroughly - Test in staging environment
5. Migrate gradually - Use feature flags or canary deployments
6. Remove adapter - Once migration is complete, remove the adapter JAR

3.6 Getting Help

• Legacy Adapter Repository: https://github.com/nacos-group/nacos-api-legacy-adapter
• Nacos Main Repository: https://github.com/alibaba/nacos
• Community Support: Nacos Community