Admin API

Admin API

运维API

Nacos 3.X 版本将不再兼容1.X版本 和 2.X版本的 AdminAPI，请使用Nacos 3.X版本的AdminAPI进行替换。

若必须要使用1.X和2.X的Admin API，需要在配置文件中设置nacos.core.auth.admin.enabled=true开启，但此兼容也将在未来版本中移除，建议使用Nacos 3.X版本的AdminAPI进行替换。

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

0. 运维API 相关说明

0.1 统一路径格式

Nacos的运维API，使用统一的Path格式进行的规范。格式为[/$nacos.server.contextPath]/v3/admin/[module]/[subPath]..., 其中

  • $nacos.server.contextPath：运维API的根路径，默认为/nacos，可以通过nacos.server.contextPath配置项进行修改。
  • module：运维API模块名称，例如server、cs、ns、core等。
  • subPath：运维API的子路径，例如state、namespace、config等， 可能有多层子路径。

下列列出的运维API，采用默认$nacos.server.contextPath的情况进行展示，若已修改部署环境中的$nacos.server.contextPath 配置项，请自行修改调用API时的请求URL。

同时下列列出的运维API样例中，均采用默认Nacos Web Server的端口进行展示，若已修改部署环境中的$nacos.server.main.port 配置项，请自行修改调用API时的请求URL。

0.2. 鉴权认证

Nacos 3.X 版本的Admin API默认需要鉴权，请在请求时使用管理员用户nacos（使用默认鉴权插件时）。

若想要关闭鉴权，请设置nacos.core.auth.admin.enabled=false，然后重启Nacos Server。

0.3. Swagger 类型文档

Nacos 3.X 的运维 API 也提供了Swagger风格的文档，您可以通过访问Nacos Swagger运维 API查看。

1. Nacos Core 运维 API

1.1. 获取当前节点连接

接口描述

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

请求方式

GET

鉴权状态

需管理员权限

请求URL

/nacos/v3/admin/core/loader/current

请求参数

无

返回数据

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

参数名 参数类型 描述
${connectionId} jsonString 每条gRPC连接的连接id
${connectionId}.abilityTable jsonString 该gRPC连接（即客户端）支持的能力列表
${connectionId}.metaInfo.clientIp String 该gRPC连接的来源IP
${connectionId}.metaInfo.localPort int 该Nacos Server的gRPC端口
${connectionId}.metaInfo.version String 该gRPC连接（即客户端）的版本
${connectionId}.metaInfo.createTime String 该gRPC连接的连接时间
${connectionId}.metaInfo.lastActiveTime timestamp 该gRPC连接的最后一次的心跳时间
${connectionId}.metaInfo.labels.source String 该gRPC连接的模块，可选值为naming,config和cluster分别代表注册中心、配置中心以及集群间的连接
${connectionId}.metaInfo.clusterSource boolean 该gRPC连接的是否为集群间连接，为true时，${connectionId}.metaInfo.labels.source为 cluster
${connectionId}.metaInfo.sdkSource boolean 该gRPC连接的是否为客户端来源连接，为true时，${connectionId}.metaInfo.labels.source为 naming或config

示例

  • 请求示例

Terminal window

curl -X GET 'http://127.0.0.1:8848/nacos/v3/admin/core/loader/current'
  • 返回示例
{
  "code": 0,
  "message": "success",
  "data": {
    "1741687438640_127.0.0.1_58856": {
      "abilityTable": {
        "fuzzyWatch": true,
        "lock": true
      },
      "appLabels": {
        "AppName": "unknown",
        "ClientVersion": "Nacos-Java-Client:v3.0.0-BETA"
      },
      "connected": true,
      "labels": {
        "AppName": "unknown",
        "module": "naming",
        "source": "sdk",
        "tls.enable": "false"
      },
      "metaInfo": {
        "appLabels": {
          "AppName": "unknown",
          "ClientVersion": "Nacos-Java-Client:v3.0.0-BETA"
        },
        "appName": "unknown",
        "clientIp": "30.221.148.39",
        "clusterSource": false,
        "connectType": "GRPC",
        "connectionId": "1741687438640_127.0.0.1_58856",
        "createTime": "2025-03-11T10:03:58.731+00:00",
        "labels": {
          "AppName": "unknown",
          "module": "naming",
          "source": "sdk",
          "tls.enable": "false"
        },
        "lastActiveTime": 1741745293704,
        "localPort": 9848,
        "namespaceId": null,
        "remoteIp": "127.0.0.1",
        "remotePort": 58856,
        "sdkSource": true,
        "tag": null,
        "tlsProtected": false,
        "version": "Nacos-Java-Client:v3.0.0-BETA"
      },
      "traced": false
    }
  }
}

1.2. 均衡指定数量的连接

接口描述

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

请求方式

GET

鉴权状态

需管理员权限

请求URL

/nacos/v3/admin/core/loader/reloadCurrent

请求参数

参数名 类型 必填 参数描述
count Integer 是 需要均衡的连接个数
redirectAddress String 否 预期均衡的Nacos Server目标，仅提供给客户端参考。

返回数据

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

示例

  • 请求示例

Terminal window

curl -X GET 'http://127.0.0.1:8848/nacos/v3/admin/core/loader/reloadCurrent?count=100'
  • 返回示例
success

1.3. 均衡指定的单个连接

接口描述

通过该接口，可以将指定的客户端连接(gRPC连接)迁移到其他Nacos Server节点中。

请求方式

GET

鉴权状态

需管理员权限

请求URL

/nacos/v3/admin/core/loader/reloadClient

请求参数

参数名 类型 必填 参数描述
connectionId String 是 需要均衡的连接Id
redirectAddress String 否 预期均衡的Nacos Server目标。

返回数据

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

示例

  • 请求示例

Terminal window

curl -X GET 'http://127.0.0.1:8848/nacos/v3/admin/core/loader/reloadClient?connectionId=1709273546779_127.0.0.1_35042'
  • 返回示例

成功则返回:

{
  "code": 0,
  "message": "success",
  "data": null
}

失败则返回：

{
  "code": 30000,
  "message": "server error",
  "data": null
}

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

接口描述

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

请求方式

GET

鉴权状态

需管理员权限

请求URL

/nacos/v3/admin/core/loader/cluster

请求参数

无

返回数据

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

参数名 参数类型 描述
total Integer 该集群中所有节点的连接数总和
min Integer 该集群中所有节点的最小连接数
avg Integer 该集群中所有节点的平均连接数
max Integer 该集群中所有节点的最大连接数
memberCount Integer 该集群中所有节点的个数
metricsCount Integer 该集群中已统计到概览信息的节点个数
detail jsonArray 该集群中所有节点的概览信息，格式见下表
detail[].address String 节点地址
detail[].metric.load Double 节点的负载率，主要对应节点的Load指标，参考值
detail[].metric.sdkConCount Integer 连接到该节点的SDK连接数，主要对应客户端连接数
detail[].metric.conCount Integer 连接到该节点的总连接数，包含了SDK和集群间的连接
detail[].metric.cpu Double 节点的CPU使用率，参考值

示例

  • 请求示例

Terminal window

curl -X GET 'http://127.0.0.1:8848/nacos/v3/admin/core/loader/cluster'
  • 返回示例
{
  "code": 0,
  "message": "success",
  "data": {
    "avg": 1,
    "completed": true,
    "detail": [
      {
        "address": "127.0.0.1:8848",
        "conCount": 1,
        "cpu": "0.0",
        "load": "2.3842773",
        "sdkConCount": 1
      }
    ],
    "max": 1,
    "memberCount": 1,
    "metricsCount": 1,
    "min": 1,
    "threshold": "1.1",
    "total": 1
  }
}

1.5. 获取本节点信息

接口描述

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

请求方式

GET

请求URL

/nacos/v3/admin/core/cluster/node/self

请求参数

无

返回数据

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

参数名 参数类型 描述
ip String 节点IP
port Integer 节点端口
state String 节点状态，可选值为UP、DOWN、SUSPICIOUS
extendInfo jsonObject 节点扩展信息，具体字段见下表
extendInfo.lastRefreshTime Long 节点上一次更新时间戳，单位毫秒
extendInfo.raftMetaData jsonObject 节点的Raft元数据， 包含每个Raft Group的leader， term等字段
extendInfo.raftPort Integer 节点的Raft端口
extendInfo.supportGrayModel Boolean 是否支持灰度模型
extendInfo.version String 节点的版本
address String 节点地址，格式为ip:port
failAccessCnt Integer 探测失败的次数，及report失败的次数，超过一定次数state会被改为DOWN
abilities jsonObject 该节点所支持的能力
grpcReportEnabled Boolean 标记节点是否支持grpc上报心跳能力，用于适配老版本升级，后续将移除
~~extendInfo.readyToUpgrade~~ Boolean 是否ready升级到Nacos2.0，于2.2版本后废弃，即将移除

示例

  • 请求示例

Terminal window

curl -X GET 'http://127.0.0.1:8848/nacos/v3/admin/core/cluster/node/self'
  • 返回示例
{
  "code": 0,
  "data": {
    "abilities": {
      "configAbility": {
        "supportRemoteMetrics": false
      },
      "namingAbility": {
        "supportJraft": true
      },
      "remoteAbility": {
        "grpcReportEnabled": true,
        "supportRemoteConnection": true
      }
    },
    "address": "127.0.0.1:8848",
    "extendInfo": {
      "lastRefreshTime": 1741678398775,
      "raftMetaData": {
        "metaDataMap": {
          "lock_acquire_service_v2": {
            "leader": "127.0.0.1:7848",
            "raftGroupMember": [
              "127.0.0.1:7848"
            ],
            "term": 109
          },
          "naming_instance_metadata": {
            "leader": "127.0.0.1:7848",
            "raftGroupMember": [
              "127.0.0.1:7848"
            ],
            "term": 391
          },
          "naming_persistent_service": {
            "leader": "127.0.0.1:7848",
            "raftGroupMember": [
              "127.0.0.1:7848"
            ],
            "term": 387
          },
          "naming_persistent_service_v2": {
            "leader": "127.0.0.1:7848",
            "raftGroupMember": [
              "127.0.0.1:7848"
            ],
            "term": 391
          },
          "naming_service_metadata": {
            "leader": "127.0.0.1:7848",
            "raftGroupMember": [
              "127.0.0.1:7848"
            ],
            "term": 391
          }
        }
      },
      "raftPort": "7848",
      "readyToUpgrade": true,
      "supportGrayModel": true,
      "version": "3.0.0-BETA"
    },
    "failAccessCnt": 0,
    "grpcReportEnabled": true,
    "ip": "127.0.0.1",
    "port": 8848,
    "state": "UP"
  },
  "message": "success"
}

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

接口描述

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

请求方式

GET

鉴权状态

需管理员权限

请求URL

/nacos/v3/admin/core/cluster/node/list

请求参数

参数名 类型 必填 参数描述
address String 否 过滤的节点地址，支持前缀匹配，不输入时返回所有节点信息
state String 否 返回的节点状态，可选值为UP、DOWN、SUSPICIOUS，不输入时返回所有节点信息

返回数据

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

示例

  • 请求示例

Terminal window

curl -X GET 'http://127.0.0.1:8848/nacos/v3/admin/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,
        "supportGrayModel": true,
        "version": "3.0.0-ALPHA"
      },
      "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. 动态修改Server集群地址发现方式

接口描述

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

请求方式

PUT

鉴权状态

需管理员权限

请求URL

/nacos/v3/admin/core/cluster/lookup

请求参数

参数名 类型 必填 参数描述
type String 是 切换到地址发现方式，可选值为file和address-server

返回数据

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

参数名 参数类型 描述
data Boolean true表示更新成功，false表示更新失败。

示例

  • 请求示例

Terminal window

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

1.8. Raft 相关操作

接口描述

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

请求方式

POST

鉴权状态

需管理员权限

请求URL

/nacos/v3/admin/core/ops/raft

请求参数

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

参数名 类型 必填 参数描述
command String 是 Raft运维操作指令，具体的命令请参考下表。
value String 是 命令的参数，具体的命令内容请参考下表。
groupId String 否 Raft集群的groupId，如果不输入则对所有Raft Group生效
command value 说明
--- --- ---
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 统一返回体格式。

参数名 参数类型 描述
data String 固定为null。

示例

  • 请求示例

Terminal window

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

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

接口描述

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

请求方式

PUT

鉴权状态

需管理员权限

请求URL

/nacos/v3/admin/core/ops/log

请求参数

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

参数名 类型 必填 参数描述
logName String 是 具体的日志文件的名称，具体支持的日志名称见下表。
logLevel String 是 日志的级别，可选值为ALL、TRACE、DEBUG、INFO、WARN、ERROR、OFF。
logName 对应的具体日志文件
--- ---
core-auth core-auth.log
core-raft protocol-raft.log
core-distro protocol-distro.log
core-cluster nacos-cluster.log

返回数据

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

参数名 参数类型 描述
data String 固定为null。

示例

  • 请求示例

Terminal window

curl -X PUT -H 'Content-Type:application/json' 'http://127.0.0.1:8848/nacos/v3/admin/core/ops/log' -d '{"logName":"core-distro","logLevel":"DEBUG"}'
  • 返回示例
{
  "code": 0,
  "message": "success",
  "data": null
}

1.10. 自动均衡指定数量的连接

接口描述

通过该接口，可以根据负载因子(loaderFactor)自动均衡整个集群的客户端连接。

自动均衡逻辑：

  1. 根据整个集群的客户端连接数和Nacos Server节点数量计算平均连接数avg、节点连接数下限阈值lowLimitCount(=avg * ( 1-loaderFactor))、节点连接数上限阈值overLimitCount(=avg * (1+loaderFactor))
  2. 将高负载节点的部分客户端连接重定向到低负载节点。

请求方式

GET

鉴权状态

需管理员权限

请求URL

/nacos/v3/admin/core/loader/smartReloadCluster

请求参数

参数名 类型 必填 参数描述
loaderFactor String 否 负载因子，必须是一个数字

返回数据

成功则返回:

{
  "code": 0,
  "message": "success",
  "data": null
}

失败则返回：

{
  "code": 30000,
  "message": "server error",
  "data": null
}

示例

  • 请求示例

Terminal window

curl -X GET 'http://127.0.0.1:8848/nacos/v3/admin/core/loader/smartReloadCluster?loaderFactor=1.2'
  • 返回示例
success

1.11. 获取ID生成器信息

接口描述

通过该接口，获取ID生成器的当前ID,workerId. 只有使用内置数据库时该接口才会返回有效数据.

请求方式

GET

鉴权状态

需管理员权限

请求URL

/nacos/v3/admin/core/ops/ids

请求参数

无

返回数据

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

参数名 参数类型 描述
resource String 生产器名称
info Object 生产器详情
info.currentId int64 当前ID
info.workerId int64 workerID

成功则返回:

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "resource": "resourceName",
      "info": {
        "currentId": 1,
        "workerId": 2
      }
    }
  ]
}

失败则返回：

{
  "code": 30000,
  "message": "server error",
  "data": null
}

示例

  • 请求示例

Terminal window

curl -X GET 'http://127.0.0.1:8848/nacos/v3/admin/core/ops/ids'
  • 返回示例
success

2. Nacos Naming 运维 API

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

接口描述

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

请求方式

GET

鉴权状态

需管理员权限

请求URL

/nacos/v3/admin/ns/ops/switches

请求参数

无

返回数据

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

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

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

示例

  • 请求示例

Terminal window

curl -X GET 'http://127.0.0.1:8848/nacos/v3/admin/ns/ops/switches'
  • 返回示例
{
  "code": 0,
  "message": "success",
  "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
    }
  }
}

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

接口描述

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

请求方式

PUT

鉴权状态

需管理员权限

请求URL

/nacos/v3/admin/ns/ops/switches

请求参数

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

返回数据

参数名 参数类型 描述
data String 成功为ok

示例

  • 请求示例

Terminal window

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

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

接口描述

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

请求方式

GET

鉴权状态

需管理员权限

请求URL

/nacos/v3/admin/ns/ops/metrics

请求参数

参数名 参数类型 是否必填 默认值 参数描述
onlyStatus boolean 否 true 只显示状态

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

返回数据

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

参数名 参数类型 描述说明
status String 系统状态
serviceCount int 服务数量
instanceCount int 实例数量
subscribeCount int 订阅数量
clientCount int 客户端数量
connectionBasedClientCount int 连接数量
ephemeralIpPortClientCount int 临时客户端数量
persistentIpPortClientCount int 持久客户端数量
responsibleClientCount int 响应客户端数

示例

  • 请求示例

Terminal window

curl -X GET 'http://127.0.0.1:8848/nacos/v3/admin/ns/ops/metrics?onlyStatus=false'
  • 返回示例
{
  "code": 0,
  "message": "success",
  "data": {
    "clientCount": 3,
    "connectionBasedClientCount": 1,
    "ephemeralIpPortClientCount": 0,
    "instanceCount": 2,
    "persistentIpPortClientCount": 2,
    "responsibleClientCount": 3,
    "serviceCount": 2,
    "status": "UP",
    "subscribeCount": 1
  }
}

2.4. 修改日志级别

接口描述

通过该接口，可以动态修改指定日志的级别。

请求方式

PUT

鉴权状态

需管理员权限

请求URL

/nacos/v3/admin/ns/ops/log

请求参数

参数名 类型 必填 参数描述
logName String 是 需要修改的日志名称
logLevel String 是 日志级别的新值

返回数据

参数名 参数类型 描述
data String 成功为ok

示例

  • 请求示例

Terminal window

curl -X PUT 'http://127.0.0.1:8848/nacos/v3/admin/ns/ops/log?logName=com.example.Logger&logLevel=DEBUG'
  • 返回示例
{
  "code": 0,
  "message": "success",
  "data": "ok"
}

2.5 查询所有客户端列表

接口描述

查询所有客户端的列表。

请求方式

GET

鉴权状态

需对应命名空间的读权限

请求URL

/nacos/v3/admin/ns/client/list

请求参数

无

返回数据

参数名 参数类型 描述
data List<String> 客户端ID列表

示例

  • 请求示例

Terminal window

curl -X GET 'http://127.0.0.1:8848/nacos/v3/admin/ns/client/list'
``` ```
{
  "code": 0,
  "message": "success",
  "data": [
    "127.0.0.1:8080#false",
    "1741748952410_127.0.0.1_53863",
    "1.1.1.1:3306#false"
  ]
}

2.6 查询客户端详细信息

接口描述

根据客户端ID查询客户端的详细信息。

请求方式

GET

鉴权状态

需对应命名空间的读权限

请求URL

/nacos/v3/admin/ns/client

请求参数

参数名 参数类型 是否必填 描述
clientId String 是 客户端ID

返回数据

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

参数名 参数类型 描述
clientId String 客户端的唯一 ID。
ephemeral boolean 客户端是否为临时客户端
lastUpdatedTime long 客户端的最后更新时间（时间戳）
clientType String 客户端类型
connectType String 连接类型（仅适用于 2.x 客户端）
appName String 客户端所属的应用名称
version String 客户端的版本号
clientIp String 客户端的 IP 地址
clientPort String 客户端的端口号

示例

  • 请求示例

Terminal window

curl -X GET 'http://127.0.0.1:8848/nacos/v3/admin/ns/client?clientId=1741748952410_127.0.0.1_53863'
  • 返回示例
{
  "code": 0,
  "message": "success",
  "data": {
    "appName": "unknown",
    "clientId": "1741748952410_127.0.0.1_53863",
    "clientIp": "127.0.0.1",
    "clientPort": 53863,
    "clientType": "connection",
    "connectType": "GRPC",
    "ephemeral": true,
    "lastUpdatedTime": 1741748954789,
    "version": "Nacos-Java-Client:v3.0.0-BETA"
  }
}

若为持久化实例，则返回

{
  "code": 0,
  "message": "success",
  "data": {
    "appName": null,
    "clientId": "1.1.1.1:3306#false",
    "clientIp": null,
    "clientPort": 0,
    "clientType": "ipPort",
    "connectType": null,
    "ephemeral": false,
    "lastUpdatedTime": 1741748950046,
    "version": null
  }
}

2.7 查询客户端注册的服务列表

接口描述

查询指定客户端注册的服务列表。

请求方式

GET

鉴权状态

需对应命名空间的读权限

请求URL

/nacos/v3/admin/ns/client/publish/list

请求参数

参数名 参数类型 是否必填 描述
clientId String 是 客户端ID

返回数据

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

参数名 参数类型 描述说明
namespaceId String 命名空间
groupName String 分组名
serviceName String 服务名
publisherInfo Object 该服务下注册的实例
publisherInfo.ip String IP地址
publisherInfo.port int 端口号
publisherInfo.clusterName String 集群名

示例

  • 请求示例

Terminal window

curl -X GET 'http://127.0.0.1:8848/nacos/v3/admin/ns/client/publish/list?clientId=1664527081276_127.0.0.1_4400'
  • 返回示例
{
  "code": 0,
  "message": "success",
  "data": [
    {
      "groupName": "DEFAULT_GROUP",
      "namespaceId": "public",
      "publisherInfo": {
        "clientId": null,
        "clusterName": "DEFAULT",
        "ip": "1.1.1.1",
        "port": 3306
      },
      "serviceName": "test",
      "subscriberInfo": null
    }
  ]
}

2.8 查询客户端订阅的服务列表

接口描述

查询指定客户端订阅的服务列表。

请求方式

GET

鉴权状态

需对应命名空间的读权限

请求URL

/nacos/v3/admin/ns/client/subscribe/list

请求参数

参数名 参数类型 是否必填 描述
clientId String 是 客户端ID

返回数据

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

参数名 参数类型 描述说明
namespaceId String 命名空间
groupName String 分组名
serviceName String 服务名
subscriberInfo Object 订阅信息
subscriberInfo.appName String 应用
subscriberInfo.agent String 客户端信息
subscriberInfo.address String 地址

示例

  • 请求示例

Terminal window

curl -X GET 'http://127.0.0.1:8848/nacos/v3/admin/ns/client/subscribe/list?clientId=1664527081276_127.0.0.1_4400'
  • 返回示例
{
  "code": 0,
  "message": "success",
  "data": [
    {
      "groupName": "DEFAULT_GROUP",
      "namespaceId": "public",
      "publisherInfo": null,
      "serviceName": "com.test.SyncCallbackService",
      "subscriberInfo": {
        "address": "127.0.0.1",
        "agent": "Nacos-Java-Client:v3.0.0-BETA",
        "appName": "unknown",
        "clientId": null
      }
    }
  ]
}

2.9 查询注册指定服务的客户端列表

接口描述

查询注册指定服务的客户端列表。

请求方式

GET

鉴权状态

需对应命名空间的读权限

请求URL

/nacos/v3/admin/ns/client/service/publisher/list

请求参数

参数名 参数类型 是否必填 默认值 描述说明
namespaceId String 否 “public” 命名空间
groupName String 否 “DEFAULT_GROUP” 分组名
serviceName String 是 无 服务名
ephemeral boolean 否 true 是否为临时实例。
ip String 否 无 IP地址，默认为空，表示不限制IP地址。
port int 否 无 端口号，默认为空，表示不限制端口号。

返回数据

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

参数名 参数类型 描述说明
clientId String 客户端id
ip String 实例的IP
port int 实例的端口
clusterName String 实例的集群名

示例

  • 请求示例

Terminal window

curl -X GET 'http://127.0.0.1:8848/nacos/v3/admin/ns/client/service/publisher/list?serviceName=test'
  • 返回示例
{
  "code": 0,
  "message": "success",
  "data": [
    {
      "clientId": "1.1.1.1:3306#false",
      "clusterName": "DEFAULT",
      "ip": "1.1.1.1",
      "port": 3306
    }
  ]
}

2.10 查询订阅指定服务的客户端列表

接口描述

查询订阅指定服务的客户端列表。

请求方式

GET

鉴权状态

需对应命名空间的读权限

请求URL

/nacos/v3/admin/ns/client/service/subscriber/list

请求参数

参数名 参数类型 是否必填 默认值 描述说明
namespaceId String 否 “public” 命名空间
groupName String 否 “DEFAULT_GROUP” 分组名
serviceName String 是 无 服务名
ephemeral boolean 否 true 是否为临时实例。
ip String 否 无 IP地址，默认为空，表示不限制IP地址。
port int 否 无 端口号，默认为空，表示不限制端口号。

返回数据

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

参数名 参数类型 描述说明
clientId String 客户端id
address String 订阅者客户端的IP
agent String 订阅者客户端的版本
appName String 订阅者客户端的应用名，unknown表示未配置或客户端不支持

示例

  • 请求示例

Terminal window

curl -X GET 'http://127.0.0.1:8848/nacos/v3/admin/ns/client/service/subscriber/list?serviceName=service1'
  • 返回示例
{
  "code": 0,
  "message": "success",
  "data": [
    {
      "address": "127.0.0.1",
      "agent": "Nacos-Java-Client:v3.0.0-BETA",
      "appName": "unknown",
      "clientId": "1741748952410_127.0.0.1_53863"
    }
  ]
}

2.11 查询客户端的负责服务器

接口描述

根据客户端的IP和端口查询其负责的服务器，仅针对持久化服务实例或通过运维API注册的临时实例。使用2.X以上客户端注册的临时实例无法通过此接口定位负责服务器节点。

对于使用1.X客户端注册的实例也适用此接口， 但1.X客户端将在未来版本不再支持。

请求方式

GET

鉴权状态

需管理员权限

请求URL

/nacos/v3/admin/ns/client/distro

请求参数

参数名 参数类型 是否必填 描述
ip String 是 客户端IP
port String 是 客户端端口

返回数据

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

参数名 参数类型 描述
responsibleServer String 负责的服务器信息

示例

  • 请求示例

Terminal window

curl -X GET 'http://127.0.0.1:8848/nacos/v3/admin/ns/client/distro?ip=127.0.0.1&port=8080'
  • 返回示例
{
  "code": 0,
  "message": "success",
  "data": {
    "responsibleServer": "127.0.0.1:8848"
  }
}

2.12 更新集群信息

接口描述

更新指定集群的元数据信息。

请求方式

PUT

鉴权状态

需对应命名空间的写权限

请求URL

/nacos/v3/admin/ns/cluster

请求参数

参数名 参数类型 是否必填 描述
namespaceId String 否 命名空间ID
serviceName String 是 服务名称
clusterName String 是 集群名称
checkPort Integer 是 健康检查端口
useInstancePort4Check Boolean 是 是否使用实例端口进行健康检查
healthChecker String 是 健康检查器配置（JSON 字符串）
metadata Map<String, String> 否 集群的扩展元数据，默认为“”

返回数据

参数名 参数类型 描述
data String 操作结果信息

示例

  • 请求示例

Terminal window

curl -X PUT 'http://127.0.0.1:8848/nacos/v3/admin/ns/cluster' -d 'serviceName=test&clusterName=DEFAULT&checkPort=80&useInstancePort4Check=true&healthChecker={"type":"none"}'
  • 返回示例
{
  "code": 0,
  "message": "success",
  "data": "ok"
}

2.13 更新实例健康状态

接口描述

更新指定实例的健康状态。

仅对持久化服务的实例有效， 且该服务的健康检查方式为NONE。 临时实例的健康状态由连接（客户端）维护，其他健康检查类型的持久化服务，健康检查任务会自动维护健康状态，即使更新成功了，也很快会被健康检查任务重制。

请求方式

PUT

鉴权状态

需对应命名空间的写权限

请求URL

/nacos/v3/admin/ns/health/instance

请求参数

参数名 参数类型 是否必填 描述
namespaceId String 否 命名空间ID，默认为public
serviceName String 是 服务名称
groupName String 否 分组名称，默认为DEFAULT_GROUP
clusterName String 否 集群名称，默认DEFAULT
ip String 是 实例IP
port Integer 是 实例端口
healthy Boolean 是 健康状态（true 为健康）

返回数据

参数名 参数类型 描述
data String 操作结果信息

示例

  • 请求示例

Terminal window

curl -X PUT 'http://127.0.0.1:8848/nacos/v3/admin/ns/health/instance' -d 'namespaceId=public&serviceName=service1&groupName=DEFAULT_GROUP&clusterName=cluster1&ip=127.0.0.1&port=8080&healthy=true'
  • 返回示例
{
  "code": 0,
  "message": "success",
  "data": "ok"
}

2.14 获取所有健康检查器

接口描述

获取系统中支持的所有健康检查器类型及其配置。

请求方式

GET

鉴权状态

需对应命名空间的写权限

请求URL

/nacos/v3/admin/ns/health/checkers

请求参数

无

返回数据

参数名 参数类型 描述
data Map<String, AbstractHealthChecker> 健康检查器类型及其配置

示例

  • 请求示例

Terminal window

curl -X GET 'http://127.0.0.1:8848/nacos/v3/admin/ns/health/checkers'
  • 返回示例
{
  "code": 0,
  "message": "success",
  "data": {
    "HTTP": {
      "expectedResponseCode": 200,
      "headers": "",
      "path": ""
    },
    "MYSQL": {
      "cmd": null,
      "pwd": null,
      "user": null
    },
    "NONE": {},
    "TCP": {}
  }
}

2.15 注册实例

接口描述

注册一个新的实例到指定服务。

请求方式

POST

鉴权状态

需对应命名空间的写权限

请求URL

/nacos/v3/admin/ns/instance

请求参数

参数名 参数类型 是否必填 描述
namespaceId String 否 命名空间ID，默认为public
serviceName String 是 服务名称
groupName String 否 分组名称，默认为DEFAULT_GROUP
clusterName String 否 集群名称，默认为DEFAULT
ip String 是 实例IP
port Integer 是 实例端口
weight Double 否 实例权重，默认为1.0
healthy Boolean 否 健康状态，默认为true
enabled Boolean 否 是否启用，默认为true
metadata Map<String, String> 否 实例元数据
ephemeral Boolean 否 是否临时实例

返回数据

参数名 参数类型 描述
data String 操作结果信息

示例

  • 请求示例

Terminal window

curl -X POST 'http://127.0.0.1:8848/nacos/v3/admin/ns/instance' \
-d 'namespaceId=public&serviceName=service1&groupName=DEFAULT_GROUP&clusterName=cluster1&ip=127.0.0.1&port=8080&weight=1.0&healthy=true&enabled=true&metadata={"key1=value1"}&ephemeral=true'
  • 返回示例
{
  "code": 0,
  "message": "success",
  "data": "ok"
}

2.16 注销实例

接口描述

从指定服务中注销一个实例。

请求方式

DELETE

鉴权状态

需对应命名空间的写权限

请求URL

/nacos/v3/admin/ns/instance

请求参数

参数名 参数类型 是否必填 描述
namespaceId String 否 命名空间ID，默认为public
serviceName String 是 服务名称
groupName String 否 分组名称，默认为DEFAULT_GROUP
clusterName String 否 集群名称，默认为DEFAULT
ip String 是 实例IP
port Integer 是 实例端口
ephemeral Boolean 否 是否临时实例

返回数据

参数名 参数类型 描述
data String 操作结果信息

示例

  • 请求示例

Terminal window

curl -X DELETE 'http://127.0.0.1:8848/nacos/v3/admin/ns/instance?namespaceId=public&serviceName=service1&groupName=DEFAULT_GROUP&clusterName=cluster1&ip=127.0.0.1&port=8080&ephemeral=true'
  • 返回示例
{
  "code": 0,
  "message": "success",
  "data": "ok"
}

2.17 更新实例

接口描述

更新指定实例的信息。

通过该接口更新的元数据拥有更高的优先级（相比注册实例时的元数据），且具有记忆能力；会在对应实例删除后，依旧存在一段时间，如果在此期间实例重新注册，该元数据依旧生效；您可以通过nacos.naming.clean.expired-metadata.expired-time及nacos.naming.clean.expired-metadata.interval对记忆时间进行修改。

例如， 注册实例时的元数据为k1=v1， 此时使用更新实例接口更新元数据为k1=v2，此时读取到的元数据为v1=v2 ；此时注销后快速重新注册实例，元数据为k1=v2，而不是k1=v1。若注销后，等待expired-metadata.expired-time 时间后再次注册该实例，元数据为k1=v1。

同时该接口将会完全覆盖之前更新过的元数据信息，例如，先使用k1=v1更新元数据，再使用k2=v2 更新元数据，此时读取到的元数据为k2=v2，而不是k1=v1,k2=v2。

请求方式

PUT

鉴权状态

需对应命名空间的写权限

请求URL

/nacos/v3/admin/ns/instance

请求参数

参数名 参数类型 是否必填 描述
namespaceId String 否 命名空间ID，默认为public
serviceName String 是 服务名称
groupName String 否 分组名称，默认为DEFAULT_GROUP
clusterName String 否 集群名称，默认为DEFAULT
ip String 是 实例IP
port Integer 是 实例端口
weight Double 否 实例权重，默认为1.0
healthy Boolean 否 健康状态，默认为true
enabled Boolean 否 是否启用，默认为true
metadata Map<String, String> 否 实例元数据
ephemeral Boolean 否 是否临时实例

返回数据

参数名 参数类型 描述
data String 操作结果信息

示例

  • 请求示例

Terminal window

curl -X PUT 'http://127.0.0.1:8848/nacos/v3/admin/ns/instance' \
-d 'serviceName=test&clusterName=DEFAULT&groupName=DEFAULT_GROUP&ip=1.1.1.1&port=3306&ephemeral=true&weight=100&enabled=false&metadata=%7B%22%E5%95%A6%E5%95%A6%E5%95%A6%26%E5%95%B5%E5%95%B5%E5%95%B5%22%3A%22xxx%22%7D'
  • 返回示例
{
  "code": 0,
  "message": "success",
  "data": "ok"
}

2.18 批量更新实例元数据

接口描述

批量更新指定实例的元数据。

请求方式

PUT

鉴权状态

需对应命名空间的写权限

请求URL

/nacos/v3/admin/ns/instance/metadata/batch

请求参数

参数名 参数类型 是否必填 描述
namespaceId String 否 命名空间ID，默认为public
serviceName String 是 服务名称
groupName String 否 分组名称，默认为DEFAULT_GROUP
instances String 否 实例列表（JSON数组 字符串）默认为“”表示所有实例更新；若指定时，每个元素代表一个需要更新的实例，必须需要包含ip和port字段，clusterName字段为可选,
metadata Map<String, String> 是 元数据
consistencyType String 否 一致性类型ephemeral和persist，对应服务的ephemeral，默认为ephemeral

返回数据

参数名 参数类型 描述
updated List<String> 更新的实例列表

示例

  • 请求示例

Terminal window

curl -X PUT 'http://127.0.0.1:8848/nacos/v3/admin/ns/instance/metadata/batch' \
-d 'namespaceId=public&serviceName=service1&groupName=DEFAULT_GROUP&instances=[{"ip":"127.0.0.1","port":8080}]&metadata={"key1":"value1"}&consistencyType=ephemeral'
  • 返回示例
{
  "code": 0,
  "message": "success",
  "data": {
    "updated": [
      "127.0.0.1:8080:unknown:DEFAULT:ephemeral"
    ]
  }
}

2.19 批量删除实例元数据

接口描述

批量删除指定实例的元数据。

请求方式

DELETE

鉴权状态

需对应命名空间的写权限

请求URL

/nacos/v3/admin/ns/instance/metadata/batch

请求参数

参数名 参数类型 是否必填 描述
namespaceId String 否 命名空间ID，默认为public
serviceName String 是 服务名称
groupName String 否 分组名称，默认为DEFAULT_GROUP
instances String 否 实例列表（JSON 字符串），默认为“”
metadata Map<String, String> 是 元数据
consistencyType String 否 一致性类型，默认为“”

返回数据

参数名 参数类型 描述
data InstanceMetadataBatchOperationVo 操作结果信息
data.updated List<String> 更新的实例列表

示例

  • 请求示例

Terminal window

curl -X DELETE 'http://127.0.0.1:8848/nacos/v3/admin/ns/instance/metadata/batch?namespaceId=public&serviceName=service1&groupName=DEFAULT_GROUP&instances=%5B%7B%22ip%22%3A%22127.0.0.1%22%2C%22port%22%3A8080%7D%5D&metadata=%7B%22key1%22%3A%22value1%22%7D&consistencyType=ephemeral'
  • 返回示例
{
  "code": 0,
  "message": "success",
  "data": {
    "updated": [
      "127.0.0.1:8080:unknown:DEFAULT:ephemeral"
    ]
  }
}

2.20 部分更新实例

接口描述

部分更新指定实例的信息。

不同于更新实例，该接口支持部分更新实例信息，例如：先使用k1=v1更新元数据，再使用k2=v2 更新元数据，此时读取到的元数据为k1=v1,k2=v2。

请求方式

PUT

鉴权状态

需对应命名空间的写权限

请求URL

/nacos/v3/admin/ns/instance/partial

请求参数

参数名 参数类型 是否必填 描述
namespaceId String 否 命名空间ID，默认为public
serviceName String 是 服务名称
ip String 是 实例IP
port Integer 是 实例端口
clusterName String 否 集群名称，默认为DEFAULT
weight Double 否 实例权重，默认为1.0
enabled Boolean 否 是否启用，默认启用
metadata String 否 实例元数据（JSON 字符串）

返回数据

参数名 参数类型 描述
data String 操作结果信息

示例

  • 请求示例

Terminal window

curl -X PUT "http://localhost:8848/nacos/v3/admin/ns/instance/partial" -d 'namespaceId=public&serviceName=example-service&ip=127.0.0.1&clusterName=DEFAULT&port=8080&weight=1.0&enabled=true&metadata={"key":"value"}'
  • 返回示例
{
  "code": 0,
  "message": "success",
  "data": "ok"
}

2.21 查询服务实例列表

接口描述

查询指定服务的所有实例列表。

请求方式

GET

鉴权状态

需对应命名空间的读权限

请求URL

/nacos/v3/admin/ns/instance/list

请求参数

参数名 参数类型 是否必填 描述
namespaceId String 否 命名空间ID，默认public
groupName String 否 分组名称，默认为DEFAULT_GROUP
serviceName String 是 服务名称
clusterName String 否 集群名称，默认为“”
ip String 是 实例IP
port Integer 是 实例端口
healthyOnly Boolean 否 是否只返回健康实例，默认为false

返回数据

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

参数名 参数类型 描述说明
serviceName String 服务名,格式为groupName@@serviceName
clusterName String 实例所在的集群名称
ip String 实例IP
port int 实例端口号
weight double 实例权重
healthy boolean 实例是否健康
enabled boolean 实例是否可用
ephemeral boolean 是否为临时实例
metadata map 实例元数据
instanceId String 实例Id

关于心跳的参数instanceHeartBeatInterval, instanceHeartBeatTimeOut和ipDeleteTimeout 用于兼容1.X客户端的心跳模式数据，后续版本可能会移除对1.X客户端的支持，届时这3个参数将被废弃。

示例

  • 请求示例

Terminal window

curl -X GET 'http://127.0.0.1:8848/nacos/v3/admin/ns/instance/list?namespaceId=public&serviceName=service1&healthyOnly=true'
  • 返回示例
{
  "code": 0,
  "data": [
    {
      "clusterName": "DEFAULT",
      "enabled": true,
      "ephemeral": false,
      "healthy": false,
      "instanceHeartBeatInterval": 5000,
      "instanceHeartBeatTimeOut": 15000,
      "instanceId": "1.1.1.1#3306#DEFAULT#DEFAULT_GROUP@@service1",
      "ip": "1.1.1.1",
      "ipDeleteTimeout": 30000,
      "metadata": {
        "key": "value"
      },
      "port": 3306,
      "serviceName": "DEFAULT_GROUP@@service1",
      "weight": 1.0
    }
  ],
  "message": "success"
}

2.22 查询实例详情

接口描述

查询指定实例的详细信息。

请求方式

GET

鉴权状态

需对应命名空间的读权限

请求URL

/nacos/v3/admin/ns/instance

请求参数

参数名 参数类型 是否必填 描述说明
namespaceId String 否 命名空间Id，默认为public
groupName String 否 分组名，默认为DEFAULT_GROUP
serviceName String 是 服务名
clusterName String 否 集群名称，默认为DEFAULT
ip String 是 IP地址
port int 是 端口号

返回数据

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

参数名 参数类型 描述说明
serviceName String 服务名,格式为groupName@@serviceName
clusterName String 实例所在的集群名称
ip String 实例IP
port int 实例端口号
weight double 实例权重
healthy boolean 实例是否健康
enabled boolean 实例是否可用
ephemeral boolean 是否为临时实例
metadata map 实例元数据
instanceId String 实例Id

关于心跳的参数instanceHeartBeatInterval, instanceHeartBeatTimeOut和ipDeleteTimeout 用于兼容1.X客户端的心跳模式数据，后续版本可能会移除对1.X客户端的支持，届时这3个参数将被废弃。

示例

  • 请求示例

Terminal window

curl -X GET 'http://127.0.0.1:8848/nacos/v3/admin/ns/instance?namespaceId=public&serviceName=service1&ip=1.1.1.1&port=3306'
  • 返回示例
{
  "code": 0,
  "data": [
    {
      "clusterName": "DEFAULT",
      "enabled": true,
      "ephemeral": false,
      "healthy": false,
      "instanceHeartBeatInterval": 5000,
      "instanceHeartBeatTimeOut": 15000,
      "instanceId": "1.1.1.1#3306#DEFAULT#DEFAULT_GROUP@@service1",
      "ip": "1.1.1.1",
      "ipDeleteTimeout": 30000,
      "metadata": {
        "key": "value"
      },
      "port": 3306,
      "serviceName": "DEFAULT_GROUP@@service1",
      "weight": 1.0
    }
  ],
  "message": "success"
}

（本文超出站点单文档体积上限，已按小节截断）