Skip to content
铭师堂的云原生升级实践Know more

运维API

Nacos默认搭载了一整套专为管理控制台和运维人员设计的运维API,赋予运维专家更多的配置权限、更广阔的数据检索能力等。这些API为Nacos的运维团队提供了方便,使他们能够高效地处理故障、排查问题,以确保系统的稳定运行。

1. Nacos Core 运维 API

1.1. 获取当前节点连接

接口描述

通过该接口,可以获取连接到当前Nacos Server节点中的gRPC连接详情。

请求方式

GET

请求URL

/nacos/v2/core/loader/current

请求参数

返回数据

参数名参数类型描述
${connectionId}jsonString每条gRPC连接的连接id
${connectionId}.abilityTablejsonString该gRPC连接(即客户端)支持的能力列表
${connectionId}.metaInfo.clientIpString该gRPC连接的来源IP
${connectionId}.metaInfo.localPortint该Nacos Server的gRPC端口
${connectionId}.metaInfo.versionString该gRPC连接(即客户端)的版本
${connectionId}.metaInfo.createTimeString该gRPC连接的连接时间
${connectionId}.metaInfo.lastActiveTimetimestamp该gRPC连接的最后一次的心跳时间
${connectionId}.metaInfo.labels.sourceString该gRPC连接的模块,可选值为naming,configcluster分别代表注册中心、配置中心以及集群间的连接
${connectionId}.metaInfo.clusterSourceboolean该gRPC连接的是否为集群间连接,为true时,${connectionId}.metaInfo.labels.sourcecluster
${connectionId}.metaInfo.sdkSourceboolean该gRPC连接的是否为客户端来源连接,为true时,${connectionId}.metaInfo.labels.sourcenamingconfig

示例

  • 请求示例
Terminal window
curl -X GET 'http://127.0.0.1:8848/nacos/v2/core/loader/current'
  • 返回示例
{
"1709273546779_127.0.0.1_35042": {
"traced": false,
"abilityTable": {},
"metaInfo": {
"connectType": "GRPC",
"clientIp": "127.0.0.1",
"localPort": 9849,
"version": "Nacos-Java-Client:v2.4.2",
"connectionId": "1709273546779_127.0.0.1_35042",
"createTime": "2024-03-01T14:12:26.800+08:00",
"lastActiveTime": 1710754816373,
"appName": "-",
"tenant": null,
"labels": {
"source": "naming",
"tls.enable": "false"
},
"tag": null,
"clusterSource": false,
"sdkSource": true
},
"connected": true,
"labels": {
"source": "naming",
"tls.enable": "false"
}
}
}

1.2. 均衡指定数量的连接

接口描述

通过该接口,可以指定一定数量的连接到当前Nacos Server节点中的gRPC连接,将这部分连接断开后迁移到其他Nacos Server节点中。

请求方式

GET

请求URL

/nacos/v2/core/loader/reloadCurrent

请求参数

参数名类型必填参数描述
countInteger需要均衡的连接个数
redirectAddressString预期均衡的Nacos Server目标,仅提供给客户端参考。

返回数据

成功则返回success,失败则返回Nacos open API 统一返回体格式

示例

  • 请求示例
Terminal window
curl -X GET 'http://127.0.0.1:8848/nacos/v2/core/loader/reloadCurrent?count=100'
  • 返回示例
success

1.3. 均衡指定的单个连接

接口描述

通过该接口,可以指定某一条的连接到当前Nacos Server节点中的gRPC连接,将该连接断开后迁移到其他Nacos Server节点中。

请求方式

GET

请求URL

/nacos/v2/core/loader/reloadClient

请求参数

参数名类型必填参数描述
connectionIdString需要均衡的连接Id
redirectAddressString预期均衡的Nacos Server目标,仅提供给客户端参考。

返回数据

成功则返回success,失败则返回Nacos open API 统一返回体格式

示例

  • 请求示例
Terminal window
curl -X GET 'http://127.0.0.1:8848/nacos/v2/core/loader/reloadClient?connectionId=1709273546779_127.0.0.1_35042'
  • 返回示例
success

1.4. 获取集群连接概览信息

接口描述

通过该接口,查看Nacos Server集群中各节点的连接数概览。

请求方式

GET

请求URL

/nacos/v2/core/loader/cluster

请求参数

返回数据

参数名参数类型描述
totalInteger该集群中所有节点的连接数总和
minInteger该集群中所有节点的最小连接数
avgInteger该集群中所有节点的平均连接数
maxInteger该集群中所有节点的最大连接数
memberCountInteger该集群中所有节点的个数
metricsCountInteger该集群中已统计到概览信息的节点个数
detailjsonArray该集群中所有节点的概览信息,格式见下表
detail[].addressString节点地址
detail[].metric.loadDouble节点的负载率,主要对应节点的Load指标,参考值
detail[].metric.sdkConCountInteger连接到该节点的SDK连接数,主要对应客户端连接数
detail[].metric.conCountInteger连接到该节点的总连接数,包含了SDK和集群间的连接
detail[].metric.cpuDouble节点的CPU使用率,参考值

示例

  • 请求示例
Terminal window
curl -X GET 'http://127.0.0.1:8848/nacos/v2/core/loader/cluster'
  • 返回示例
{
"total": 0,
"min": 0,
"avg": 0,
"max": 0,
"memberCount": 3,
"metricsCount": 3,
"threshold": 0.0,
"detail": [{
"address": "nacos-node1:8848",
"metric": {
"load": "0.0",
"sdkConCount": "0",
"cpu": "0.0",
"conCount": "2"
}
}, {
"address": "nacos-node2:8848",
"metric": {
"load": "0.03",
"sdkConCount": "0",
"cpu": "-1.0",
"conCount": "2"
}
}, {
"address": "nacos-node3:8848",
"metric": {
"load": "0.0",
"sdkConCount": "0",
"cpu": "-1.0",
"conCount": "2"
}
}],
"completed": true
}

1.5. 获取本节点信息

接口描述

通过该接口,可以获取Nacos Server集群当前节点的详细信息。

请求方式

GET

请求URL

/nacos/v2/core/cluster/node/self

请求参数

返回数据

返回体遵循Nacos open API 统一返回体格式,下表只阐述data字段中的返回参数。

参数名参数类型描述
ipString节点IP
portInteger节点端口
stateString节点状态,可选值为UPDOWNSUSPICIOUS
extendInfojsonObject节点扩展信息,具体字段见下表
extendInfo.lastRefreshTimeLong节点上一次更新时间戳,单位毫秒
extendInfo.raftMetaDatajsonObject节点的Raft元数据, 包含每个Raft Group的 leaderterm等字段
extendInfo.raftPortInteger节点的Raft端口
extendInfo.versionString节点的版本
addressString节点地址,格式为ip:port
abilitiesjsonObject该节点所支持的能力
extendInfo.readyToUpgradeBoolean是否ready升级到Nacos2.0,于2.2版本后废弃,即将移除

示例

  • 请求示例
Terminal window
curl -X GET 'http://127.0.0.1:8848/nacos/v2/core/cluster/node/self'
  • 返回示例
{
"code": 0,
"message": "success",
"data": {
"ip": "nacos-node-0",
"port": 8848,
"state": "UP",
"extendInfo": {
"lastRefreshTime": 1709273550501,
"raftMetaData": {
"metaDataMap": {
"naming_instance_metadata": {
"leader": "nacos-node-2:7848",
"raftGroupMember": ["nacos-node-2:7848", "nacos-node-1:7848", "nacos-node-0:7848"],
"term": 3
},
"naming_persistent_service": {
"leader": "nacos-node-1:7848",
"raftGroupMember": ["nacos-node-2:7848", "nacos-node-1:7848", "nacos-node-0:7848"],
"term": 3
},
"naming_persistent_service_v2": {
"leader": "nacos-node-2:7848",
"raftGroupMember": ["nacos-node-2:7848", "nacos-node-1:7848", "nacos-node-0:7848"],
"term": 2
},
"naming_service_metadata": {
"leader": "nacos-node-2:7848",
"raftGroupMember": ["nacos-node-2:7848", "nacos-node-1:7848", "nacos-node-0:7848"],
"term": 3
}
}
},
"raftPort": "7848",
"readyToUpgrade": true,
"version": "2.4.2"
},
"address": "nacos-node-0:8848",
"failAccessCnt": 0,
"abilities": {
"remoteAbility": {
"supportRemoteConnection": true,
"grpcReportEnabled": true
},
"configAbility": {
"supportRemoteMetrics": false
},
"namingAbility": {
"supportJraft": true
}
},
"grpcReportEnabled": true
}
}

1.6. 获取集群所有节点信息

接口描述

通过该接口,可以获取Nacos Server集群中所有节点的详细信息。

请求方式

GET

请求URL

/nacos/v2/core/cluster/node/list

请求参数

参数名类型必填参数描述
addressString过滤的节点地址,支持前缀匹配,不输入时返回所有节点信息
nodeStateString返回的节点状态,可选值为UPDOWNSUSPICIOUS,不输入时返回所有节点信息

返回数据

返回体遵循Nacos open API 统一返回体格式data字段为获取本节点信息的返回数据的列表。

示例

  • 请求示例
Terminal window
curl -X GET 'http://127.0.0.1:8848/nacos/v2/core/cluster/node/list'
  • 返回示例
{
"code": 0,
"message": "success",
"data": [{
"ip": "nacos-node-0",
"port": 8848,
"state": "UP",
"extendInfo": {
"lastRefreshTime": 1709273550501,
"raftMetaData": {
"metaDataMap": {
"naming_instance_metadata": {
"leader": "nacos-node-2:7848",
"raftGroupMember": ["nacos-node-2:7848", "nacos-node-1:7848", "nacos-node-0:7848"],
"term": 3
},
"naming_persistent_service": {
"leader": "nacos-node-1:7848",
"raftGroupMember": ["nacos-node-2:7848", "nacos-node-1:7848", "nacos-node-0:7848"],
"term": 3
},
"naming_persistent_service_v2": {
"leader": "nacos-node-2:7848",
"raftGroupMember": ["nacos-node-2:7848", "nacos-node-1:7848", "nacos-node-0:7848"],
"term": 2
},
"naming_service_metadata": {
"leader": "nacos-node-2:7848",
"raftGroupMember": ["nacos-node-2:7848", "nacos-node-1:7848", "nacos-node-0:7848"],
"term": 3
}
}
},
"raftPort": "7848",
"readyToUpgrade": true,
"version": "2.4.2"
},
"address": "nacos-node-0:8848",
"failAccessCnt": 0,
"abilities": {
"remoteAbility": {
"supportRemoteConnection": true,
"grpcReportEnabled": true
},
"configAbility": {
"supportRemoteMetrics": false
},
"namingAbility": {
"supportJraft": true
}
},
"grpcReportEnabled": true
}, {
"ip": "nacos-node-2",
"port": 8848,
"state": "UP",
"extendInfo": {
"lastRefreshTime": 1710813796567,
"raftMetaData": {
....
},
....
},
....
}, {
"ip": "nacos-node-1",
"port": 8848,
"state": "UP",
"extendInfo": {
"lastRefreshTime": 1710813796567,
"raftMetaData": {
....
},
....
},
....
}]
}

1.7. 快速查询本节点健康状态

接口描述

通过该接口,可以快速查询本节点健康状态。

请求方式

GET

请求URL

/nacos/v2/core/cluster/node/self/health

请求参数

返回数据

返回体遵循Nacos open API 统一返回体格式

参数名参数类型描述
dataStringUP表示节点健康,DOWN表示节点不健康,SUSPICIOUS表示节点疑似不健康

示例

  • 请求示例
Terminal window
curl -X GET 'http://127.0.0.1:8848/nacos/v2/core/cluster/node/list'
  • 返回示例
{
"code": 0,
"message": "success",
"data": "UP"
}

1.8. 动态修改Server集群地址发现方式

接口描述

通过该接口,可以在不重启Nacos Server的情况下,动态切换Nacos Server集群地址发现的方式,目前支持两种方式:fileaddress-server

请求方式

PUT

请求URL

/nacos/v2/core/cluster/lookup

请求参数

参数名类型必填参数描述
typeString切换到的地址发现方式,可选值为fileaddress-server

返回数据

返回体遵循Nacos open API 统一返回体格式

参数名参数类型描述
dataBooleantrue表示更新成功,false表示更新失败。

示例

  • 请求示例
Terminal window
curl -X PUT 'http://127.0.0.1:8848/nacos/v2/core/cluster/lookup?type=file'
  • 返回示例
{
"code": 0,
"message": "success",
"data": true
}

1.9. Raft 相关操作

接口描述

通过该接口,可以对Nacos Server集群中的Raft协议进行部分运维操作,如执行快照,主动选主等。

请求方式

POST

请求URL

/nacos/v2/core/ops/raft

请求参数

该API需要以Json的方式,将请求参数放在请求体中,请求体格式如下:

参数名类型必填参数描述
commandStringRaft运维操作指令,具体的命令请参考下表。
valueString命令的参数,具体的命令内容请参考下表。
groupIdStringRaft集群的groupId,如果不输入则对所有Raft Group生效
commandvalue说明
doSnapshot${nacos-server-address}:${raft-port}执行快照,参数为要执行快照的节点地址。
transferLeader${nacos-server-address}:${raft-port}主动选主,参数为要期望的Leader的节点地址。
restRaftCluster${nacos-server-address}:${raft-port}[,${nacos-server-address}:${raft-port}]重置集群状态,参数为要重置节点地址列表,’,‘分割。
removePeer${nacos-server-address}:${raft-port}移除Raft Member节点,参数为要移除的节点地址。
removePeers${nacos-server-address}:${raft-port}[,${nacos-server-address}:${raft-port}]批量移除Raft Member节点,参数为要批量移除的节点地址列表,’,‘分割。
changePeers${nacos-server-address}:${raft-port}[,${nacos-server-address}:${raft-port}]修改Raft Member节点,参数为要修改后的节点地址列表,’,‘分割。

返回数据

返回体遵循Nacos open API 统一返回体格式

参数名参数类型描述
dataString固定为null

示例

  • 请求示例
Terminal window
curl -X POST -H 'Content-Type:application/json' 'http://127.0.0.1:8848/nacos/v2/core/ops/raft' -d '{"command":"doSnapshot","value":"nacos-node-0:7848"}'
  • 返回示例
{
"code": 200,
"message": null,
"data": null
}

1.10. 动态修改Nacos Core相关日志级别

接口描述

通过该接口,可以在不重启Nacos Server的情况下,动态修改Nacos Core相关日志级别的配置。

请求方式

PUT

请求URL

/nacos/v2/core/ops/log

请求参数

该API需要以Json的方式,将请求参数放在请求体中,请求体格式如下:

参数名类型必填参数描述
logNameString具体的日志文件的名称,具体支持的日志名称见下表。
logLevelString日志的级别,可选值为ALLTRACEDEBUGINFOWARNERROROFF
logName对应的具体日志文件
core-authcore-auth.log
core-raftprotocol-raft.log
core-distroprotocol-distro.log
core-clusternacos-cluster.log

返回数据

返回体遵循Nacos open API 统一返回体格式

参数名参数类型描述
dataString固定为null

示例

  • 请求示例
Terminal window
curl -X PUT -H 'Content-Type:application/json' 'http://127.0.0.1:8848/nacos/v2/core/ops/log' -d '{"logName":"core-distro","logLevel":"DEBUG"}'
  • 返回示例
{
"code": 200,
"message": null,
"data": null
}

2. Nacos Naming 运维 API

2.1. 查看Naming模块的相关开关

接口描述

通过该接口,可以查看Nacos Naming模块的相关开关。

请求方式

GET

请求URL

/nacos/v2/ns/operator/switches/nacos/v2/ns/ops/switches

请求参数

返回数据

返回体遵循Nacos open API 统一返回体格式,返回数据data字段为json格式,展示各个开关的和配置的具体内容:

参数名参数类型描述
clientBeatIntervalintNacos1.X客户端的默认心跳间隔
defaultCacheMillisint客户端订阅的服务列表的默认缓存时间
defaultPushCacheMillisint推送的服务列表的默认缓存时间,优先级高于defaultCacheMillis
distroEnabledboolean是否开启Distro协议同步,仅当集群压力过大,影响到集群稳定性时,临时修改为false缓解,改为false后可能导致部分数据不一致,需要尽快恢复
healthCheckEnabledboolean是否开启健康检查,仅当集群压力过大,影响到集群稳定性时,临时修改为false缓解,改为false后不会因为心跳过期,tcp/http探测超时而修改实例的健康状态,以及不会因过期删除实例,需要尽快恢复
lightBeatEnabledboolean是否开启轻量心跳,针对Nacos1.2.X~1.4.X版本客户端生效,修改为false后,Nacos1.2.X~1.4.X版本客户端将使用全量心跳进行续约
pushEnabledboolean是否开启推送功能,仅当集群压力过大,影响到集群稳定性时,临时修改为false,改为false后,Nacos客户端将不再收到服务端的主动推送
push${Language}VersionString可支持推送的最小客户端版本,当不希望针对小于某些版本进行数据推送时,可以修改该值,比如修改pushJavaVersion为2.0.0,则小于2.0.0的Java客户端将不会收到推送数据
${type}HealthParamsjson健康检查参数,设置健康检查的最大/最小间隔,随机间隔系数等,健康检查时将根据这几个值进行下一次健康检查流量的打散。

注意: 其余未列出的参数,均为Nacos旧版本的开关或配置内容,已废弃或即将废弃,请谨慎使用。

示例

  • 请求示例
Terminal window
curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/ops/switches'
  • 返回示例
{
"code": 0,
"data": {
"adWeightMap": {},
"autoChangeHealthCheckEnabled": true,
"checkTimes": 3,
"checksum": null,
"clientBeatInterval": 5000,
"defaultCacheMillis": 3000,
"defaultInstanceEphemeral": true,
"defaultPushCacheMillis": 10000,
"disableAddIP": false,
"distroEnabled": true,
"distroServerExpiredMillis": 10000,
"distroThreshold": 0.7,
"enableAuthentication": false,
"enableStandalone": true,
"healthCheckEnabled": true,
"healthCheckWhiteList": [],
"httpHealthParams": {
"factor": 0.85,
"max": 5000,
"min": 500
},
"incrementalList": [],
"lightBeatEnabled": true,
"limitedUrlMap": {},
"masters": null,
"mysqlHealthParams": {
"factor": 0.65,
"max": 3000,
"min": 2000
},
"name": "00-00---000-NACOS_SWITCH_DOMAIN-000---00-00",
"overriddenServerStatus": null,
"pushCSharpVersion": "0.9.0",
"pushCVersion": "1.0.12",
"pushEnabled": true,
"pushGoVersion": "0.1.0",
"pushJavaVersion": "0.1.0",
"pushPythonVersion": "0.4.3",
"sendBeatOnly": false,
"serverStatusSynchronizationPeriodMillis": 2000,
"serviceStatusSynchronizationPeriodMillis": 5000,
"tcpHealthParams": {
"factor": 0.75,
"max": 5000,
"min": 1000
}
},
"message": "success"
}

2.2. 修改Naming模块的相关开关

接口描述

通过该接口,可以修改Nacos Naming模块的相关开关。

请求方式

PUT

请求URL

/nacos/v2/ns/operator/switches/nacos/v2/ns/ops/switches

请求参数

参数名类型必填参数描述
entryString修改的开关或配置名称
valueObject开关或配置的新值,不同的开关或配置的类型不同,具体请参考开关和配置参数
debugboolean是否开启调试模式,开启后,修改的配置不会同步到集群其他节点中,仅在本节点生效,默认为false

返回数据

返回体遵循Nacos open API 统一返回体格式:

参数名参数类型描述
dataString成功为ok,否则为null

示例

  • 请求示例
Terminal window
curl -X PUT 'http://127.0.0.1:8848/nacos/v2/ns/ops/switches?entry=pushEnabled&value=false'
  • 返回示例
{
"code": 0,
"message": "success",
"data": "ok"
}

2.3. 查询系统当前数据指标

接口描述

通过该接口,可以查询系统当前数据指标

请求方式

GET

请求URL

/nacos/v2/ns/operator/metrics/nacos/v2/ns/ops/metrics

请求参数

参数名参数类型是否必填描述说明
onlyStatusboolean只显示状态,默认为true

onlyStatus设置为true时,只返回表示系统状态的字符串

返回数据

参数名参数类型描述说明
dataObject系统当前数据指标
data.statusString系统状态
data.serviceCountint服务数量
data.instanceCountint实例数量
data.subscribeCountint订阅数量
data.raftNotifyTaskCountintRaft通知任务数量
data.responsibleServiceCountint
data.responsibleInstanceCountint
data.clientCountint客户端数量
data.connectionBasedClientCountint连接数量
data.ephemeralIpPortClientCountint临时客户端数量
data.persistentIpPortClientCountint持久客户端数量
data.responsibleClientCountint
data.cpufloatcpu使用率
data.loadfloat负载
data.memfloat内存使用率

示例

  • 请求示例
Terminal window
curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/operator/metrics'
  • 返回示例
{
"code": 0,
"message": "success",
"data": {
"status": "UP",
"serviceCount": 2,
"instanceCount": 2,
"subscribeCount": 2,
"raftNotifyTaskCount": 0,
"responsibleServiceCount": 0,
"responsibleInstanceCount": 0,
"clientCount": 2,
"connectionBasedClientCount": 2,
"ephemeralIpPortClientCount": 0,
"persistentIpPortClientCount": 0,
"responsibleClientCount": 2,
"cpu": 0,
"load": -1,
"mem": 1
}
}

3. Nacos Config 运维 API

3.1. 查询指定命名空间下的配置列表

接口描述

获取指定命名空间下的配置信息列表

请求方式

GET

请求URL

/nacos/v2/cs/history/configs

请求参数

参数名类型必填参数描述
namespaceIdString命名空间

返回数据

参数名参数类型描述说明
dataObject[]配置信息列表
data.idString配置id
data.dataIdString配置名
data.groupString配置分组
data.contentString配置内容
data.md5String配置内容的md5值
data.encryptedDataKeyString
data.tenantString租户信息(命名空间)
data.appNameString应用名
data.typeString配置文件类型
data.lastModifiedlong上次修改时间

返回数据中的配置信息只有dataId, group, tenant, appName, type字段有效,其他字段为默认值

示例

  • 请求示例

    Terminal window
    curl -X GET 'http://127.0.0.1:8848/nacos/v2/cs/history/configs?namespaceId='
  • 返回示例

{
"code": 0,
"message": "success",
"data": [
{
"id": "0",
"dataId": "nacos.example",
"group": "com.alibaba.nacos",
"content": null,
"md5": null,
"encryptedDataKey": null,
"tenant": "",
"appName": "",
"type": "yaml",
"lastModified": 0
}
]
}