Nacos 2.0.0 部署及升级文档

本文档包含两个部分：的部署，以及如何从平滑升级至。

部署部分，适用于直接部署以上版本的用户。

升级部分，适用于从版本平滑升级到版本（以及2.0.0-BETA版本）的用户。版本无法进行平滑升级，请勿参照本文档进行升级。

由于和的数据结构发生了变化，为了能够完成平滑升降级，需要将数据进行双写，分别生成Nacos1和Nacos2的数据结构进行存储。因此会对性能有一定影响。当集群升级并稳定运行后，可以关闭双写，关闭双写后将会失去平滑降级的功能。

部署步骤

本部分，适用于直接部署以上版本的用户。

1.预备环境准备

Nacos依赖Java环境来运行。如果您是从代码开始构建并运行Nacos，还需要为此配置Maven环境，请确保是在以下版本环境中安装使用:

64bitOS，支持Linux/Unix/Mac/Windows，推荐选用Linux/Unix/Mac。

64+；下载配置。

+；下载配置。

2.下载源码或者安装包

你可以通过源码和发行包两种方式来获取Nacos。

从Github上下载源码方式

gitclone$versiontoyouractualpathcddistribution/target/nacos-server-$version/nacos/bin

下载编译后压缩包方式

您可以从最新稳定版本下载nacos-server-$包。

unzipnacos-server-$或者tar-xvfnacos-server-$/bin

3.启动服务器Linux/Unix/Mac

单机启动命令(standalone代表着单机模式运行):

如果您使用的是ubuntu系统，或者运行脚本报错提示[[符号找不到，可尝试如下运行：

单机启动，使用内置数据库（注：使用内置Derby数据库需要保证~/nacos/data/derby-data文件夹下无残留数据）：

集群启动（使用内嵌数据库）：

集群启动（使用外置数据库）：

4.启动后自检

集群中所有机器部署为2.0.X版本并启动时，应当进行启动之后的检查。

当集群中所有节点logs/日志中观察到upgradecheckresulttrue及，便判定为集群准备完毕时，此时才可以使用。

5.关闭双写

为了节省性能开销，当集群部署完成后，可以先观察一段时间运行情况，当确认无误后，可以关闭双写，从而释放性能，具体的关闭方式是通过API进行：

curl-XPUT'localhost:8848/nacos/v1/ns/operator/switches?entry=doubleWriteEnabledvalue=false'

关闭后可以从logs/日志中观察到DisableDoublewrite,字样。说明关闭双写。

注意，关闭双写后无法在进行平滑降级，请先确认关闭前集群正确运行。

6.关闭服务器Linux/Unix/MacWindows

或者双击运行文件。

升级步骤

以linux系统为例。window系统请自行替换sh脚本为cmd脚本。

1.停止旧节点

选择集群中一台节点，使用Nacos目录下nacos/bin/进行停止。

2.替换文件

下载并解压缩，将其下的bin，conf，target目录覆盖原的安装目录下。

3.修改配置

自行修改nacos/bin/中的JVM参数，conf/中的集群列表以及conf/中数据库或其他相关参数。

4.启动

使用nacos目录下nacos/bin/启动，其他更多启动指令请查看Nacos部署环境。

5.观察是否启动成功

首先查看nacos目录下logs/或logs/观察到nacos启动成功的日志，如说明程序已启动成功。

之后在观察logs/中，可以看到有upgradecheckresultfalse以及Checkwhetherclosedoublewrite等日志信息。

属于正常现象。

6.升级其他节点

待该节点的服务及实例信息已经同步完毕后（可从控制台进行确认）。重复1～5步骤，将其他的nacos节点也进行升级。

7.确认升级完成

当集群中最后一个节点也升级到2.0.X版本时，集群会开始进行升级检测。每个节点会对该节点的服务信息和实例信息进行校验，并检测是否还有未完成的双写任务。

当该节点的服务信息和实例信息已经核对成功，并且没有双写任务存在时，该节点会判定自己已经做好升级准备，并修改自己的状态且通知其他Nacos节点。每台节点是否完成升级准备可以从控制台的集群管理中元数据信息中看到"readyToUpgrade":false/true。

当集群中所有节点均判定为准备完毕时。Nacos集群中的节点会进行升级切换，自动升级到的处理逻辑。

可以从logs/日志中观察到upgradecheckresulttrue及。

8.1关闭双写

当集群升级完成后，可以先观察一段时间运行情况，当确认无误后，可以关闭双写，从而释放性能，具体的关闭方式是通过API进行：

curl-XPUT'localhost:8848/nacos/v1/ns/operator/switches?entry=doubleWriteEnabledvalue=false'

关闭后可以从logs/日志中观察到DisableDoublewrite,字样。说明关闭双写。

注意，关闭双写后无法在进行平滑降级，请先确认关闭前集群正确运行。

8.2降级

集群升级完毕后，依旧会进行双写，当升级后发现存在问题时，可以快速进行降级，降级流程为重复步骤1～6，只是将版本改为对应的1.X版本。

当第一台降级完成后，集群即可观察到logs/中的upgradecheckresultfalse，且控制台集群管理中，所有新版本"readyToUpgrade":false。

升级相关的openAPI

在2.0.2版本中，nacos-server提供了一些方便查看升级状态及不同版本中的数据区别，方便用户排查升级中的问题。

查看统计描述

查看当前升级状态

请求类型

GET

请求URL

/nacos/v1/ns/upgrade/ops/metrics

请求参数

无

返回参数

参数类型

描述

string

升级状态

示例

upgraded=trueisAll20XVersion=trueisDoubleWriteEnabled=falsedoubleWriteDelayTaskCount=0serviceCountV1=0instanceCountV1=0serviceCountV2=0instanceCountV2=0subscribeCountV2=0responsibleServiceCountV1=0responsibleInstanceCountV1=0ephemeralServiceCountV2=0persistentServiceCountV2=0ephemeralInstanceCountV2=0persistentInstanceCountV2=0==

查询服务描述

查询对应Nacos版本中一个服务内容

请求类型

GET

请求路径

/nacos/v1/ns/upgrade/ops/service

请求参数

名称

类型

是否必选

描述

serviceName

字符串

是

服务名

groupName

字符串

否

分组名

namespaceId

字符串

否

命名空间ID

ver

字符串

否

版本v1或者v2,默认v2

示例请求

curl-XGET'127.0.0.1:8848/nacos/v1/ns/upgrade/ops/service?serviceName='

示例返回

{metadata:{},groupName:"DEFAULT_GROUP",namespaceId:"public",name:"",selector:{type:"none"},protectThreshold:0,clusters:[{healthChecker:{type:"TCP"},metadata:{},name:"c1"}]}

查询服务列表描述

查询对应Nacos版本的服务列表

请求类型

GET

请求路径

/nacos/v1/ns/upgrade/ops/service/list

请求参数

名称

类型

是否必选

描述

pageNo

int

是

当前页码

pageSize

int

是

分页大小

groupName

字符串

否

分组名

namespaceId

字符串

否

命名空间ID

ver

字符串

否

版本v1或者v2,默认v2

示例请求

curl-XGET'127.0.0.1:8848/nacos/v1/ns/upgrade/ops/service/list?pageNo=1pageSize=2'

示例返回

{"count":148,"doms":["",""]}

查询实例列表描述

查询对应Nacos版本中某个服务下的实例列表

请求类型

GET

请求路径

/nacos/v1/ns/upgrade/ops/instance/list

请求参数

名称

类型

是否必选

描述

serviceName

字符串

是

服务名

groupName

字符串

否

分组名

namespaceId

字符串

否

命名空间ID

clusters

字符串，多个集群用逗号分隔

否

集群名称

healthyOnly

boolean

否，默认为false

是否只返回健康实例

ver

字符串

否

版本v1或者v2,默认v2

示例请求

curl-XGET'127.0.0.1:8848/nacos/v1/ns/upgrade/ops/instance/list?serviceName='

示例返回

{"dom":"","cacheMillis":1000,"useSpecifiedURL":false,"hosts":[{"valid":true,"marked":false,"instanceId":"10.10.10.10-8888-","port":8888,"ip":"10.10.10.10","weight":1.0,"metadata":{}}],"checksum":"3bbcf6dd1175203a8afdade0e77a27cd94","lastRefTime":94,"env":"","clusters":""}

查询实例详情描述

查询一个对应Nacos版本中某个服务下个某个实例详情。

请求类型

GET

请求路径

/nacos/v1/ns/upgrade/ops/instance

请求参数

名称

类型

是否必选

描述

serviceName

字符串

是

服务名

groupName

字符串

否

分组名

字符串

是

实例IP

port

字符串

是

实例端口

namespaceId

字符串

否

命名空间ID

cluster

字符串

否

集群名称

healthyOnly

boolean

否，默认为false

是否只返回健康实例

ephemeral

boolean

否

是否临时实例

ver

字符串

否

版本v1或者v2,默认v2

示例请求

curl-XGET'127.0.0.1:8848/nacos/v1/ns/upgrade/ops/instance?serviceName==10.10.10.10port=8888cluster=DEFAULT'

示例返回

{"metadata":{},"instanceId":"10.10.10.10-8888-","port":8888,"service":"","healthy":false,"ip":"10.10.10.10","clusterName":"DEFAULT","weight":1.0}

添加服务描述

补充添加一个服务到对应Nacos版本下

请求类型

POST

请求路径

/nacos/v1/ns/upgrade/ops/service

请求参数

名称

类型

是否必选

描述

serviceName

字符串

是

服务名

groupName

字符串

否

分组名

namespaceId

字符串

否

命名空间ID

protectThreshold

浮点数

否

保护阈值,取值0到1,默认0

metadata

字符串

否

元数据

selector

JSON格式字符串

否

访问策略

ver

字符串

否

版本v1或者v2,默认v2

示例请求

curl-XPOST'127.0.0.1:8848/nacos/v1/ns/service?serviceName==k1%3dv1'

示例返回

ok

删除服务描述

从对应Nacos版本中删除一个服务,如果删除v2服务，只有当服务下实例数为0时允许删除。

请求类型

DELETE

请求路径

/nacos/v1/ns/upgrade/ops/service

请求参数

名称

类型

是否必选

描述

serviceName

字符串

是

服务名

groupName

字符串

否

分组名

namespaceId

字符串

否

命名空间ID

ver

字符串

否

版本v1或者v2,默认v2

示例请求

curl-XDELETE'127.0.0.1:8848/nacos/v1/ns/service?serviceName='

示例返回

ok

注册实例描述

注册一个实例到对应Nacos版本的服务下。

请求类型

POST

请求路径

/nacos/v1/ns/upgrade/ops/instance

请求参数

名称

类型

是否必选

描述

字符串

是

服务实例IP

port

int

是

服务实例port

namespaceId

字符串

否

命名空间ID

weight

double

否

权重

enabled

boolean

否

是否上线

healthy

boolean

否

是否健康

metadata

字符串

否

扩展信息

clusterName

字符串

否

集群名

serviceName

字符串

是

服务名

groupName

字符串

否

分组名

ephemeral

boolean

否

是否临时实例

ver

字符串

否

版本v1或者v2,默认v2

示例请求

curl-XPOST';healthy=trueip=11.11.11.11weight=1.0serviceName==GBKnamespaceId=n1'

示例返回

注销实例描述

删除对应Nacos版本服务下的一个实例。

请求类型

DELETE

请求路径

/nacos/v1/ns/upgrade/ops/instance

请求参数

名称

类型

是否必选

描述

serviceName

字符串

是

服务名

groupName

字符串

否

分组名

字符串

是

服务实例IP

port

int

是

服务实例port

clusterName

字符串

否

集群名称

namespaceId

字符串

否

命名空间ID

ephemeral

boolean

否

是否临时实例

ver

字符串

否

版本v1或者v2,默认v2

示例请求

curl-XDELETE'127.0.0.1:8848/nacos/v1/ns/instance?serviceName==1.1.1.1port=8888clusterName=TEST1'

示例返回

升级过程中可能遇到的问题1.最后一台节点升级完成时，注册的服务出现波动（变成不健康或暂时被摘除）

升级过程中，为了节约性能，双写的内容仅是内容发生变更时的状态，心跳等内容不会被双写，因此切换版本时，可能有部分实例的心跳过久而健康检查又刚好开始执行，从而被标记非健康或摘除。

后续心跳处理将会把数据补充回来，最终会一致。

2.升级完成后，升级的最后一台服务端报错ServerisDOWN

这可能是因为Raft选主失败导致的，解决方法是重启最后一台升级的服务端。或先将最后一台服务端降级，之后再重新进行一次升级即可。