Admin API

Standard Nacos 3.x Admin APIs use the /v3/admin/* path. The current version has removed v1/v2 Admin APIs. Use Nacos 3.x Admin APIs instead.

If you still need v1/v2 Admin APIs temporarily during migration, read Compatibility and Deprecation first, and evaluate the legacy adapter approach described in the upgrading manual.

Nacos provides Admin APIs for administrators, operations platforms, release platforms, audit tools, and automation scripts. These APIs expose broader management capabilities than runtime client APIs, including range queries, resource management, server state inspection, and operational diagnostics.

0. Admin API Notes

0.1. Scope

Admin APIs are intended for management-plane callers. They are suitable for operations platforms, release platforms, audit tools, automation scripts, and administrators.

Business applications should prefer Java SDK, other language SDKs, or Client API. Custom console UI should prefer Console API.

0.2. Unified Path Format

Nacos Admin APIs use a unified path format: [/$nacos.server.contextPath]/v3/admin/[module]/[subPath]....

• $nacos.server.contextPath: Root path of Admin APIs. The default value is /nacos, and it can be changed with the nacos.server.contextPath configuration item.
• module: Admin API module name, such as server, cs, ns, or core.
• subPath: Admin API subpath, such as state, namespace, or config. It may contain multiple path levels.

The Admin APIs listed below use the default $nacos.server.contextPath. If the deployment changes $nacos.server.contextPath, update the request URL accordingly when calling the API.

The examples below also use the default Nacos Web Server port. If the deployment changes $nacos.server.main.port, update the request URL accordingly when calling the API.

0.3. Authentication

Nacos 3.X Admin APIs require authentication by default. When using the default auth plugin, use an administrator identity such as nacos.

To disable Admin API authentication, set nacos.core.auth.admin.enabled=false and restart Nacos Server.

0.4. Swagger Documentation

Nacos 3.X Admin APIs also provide Swagger-style documentation. You can view it at Nacos Swagger Admin API.

1. Nacos Core 运维 API

1.1. 获取当前节点连接

Description

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

Since

3.0.0

Request Method

GET

Authorization

Administrator permissions required.

Request URL

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

Request Parameters

无

Response Data

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

Examples

• Request example

curl -X GET 'http://127.0.0.1:8848/nacos/v3/admin/core/loader/current'

• Response example

{
  "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. 均衡指定数量的连接

Description

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

Since

3.0.0

Request Method

POST

Authorization

Administrator permissions required.

Request URL

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

Request Parameters

Response Data

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

Examples

• Request example

curl -X POST 'http://127.0.0.1:8848/nacos/v3/admin/core/loader/reloadCurrent' -d "count=100"

• Response example

success

1.3. 均衡指定的单个连接

Description

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

Since

3.0.0

Request Method

POST

Authorization

Administrator permissions required.

Request URL

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

Request Parameters

Response Data

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

Examples

• Request example

curl -X POST 'http://127.0.0.1:8848/nacos/v3/admin/core/loader/reloadClient' -d "connectionId=1709273546779_127.0.0.1_35042"

• Response example

成功则返回:

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

失败则返回：

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

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

Description

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

Since

3.0.0

Request Method

GET

Authorization

Administrator permissions required.

Request URL

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

Request Parameters

无

Response Data

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

Examples

• Request example

curl -X GET 'http://127.0.0.1:8848/nacos/v3/admin/core/loader/cluster'

• Response example

{
  "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. 获取本节点信息

Description

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

Since

3.0.0

Request Method

GET

Request URL

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

Request Parameters

无

Response Data

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

Examples

• Request example

curl -X GET 'http://127.0.0.1:8848/nacos/v3/admin/core/cluster/node/self'

• Response example

{
  "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. 获取集群所有节点信息

Description

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

Since

3.0.0

Request Method

GET

Authorization

Administrator permissions required.

Request URL

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

Request Parameters

Response Data

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

Examples

• Request example

curl -X GET 'http://127.0.0.1:8848/nacos/v3/admin/core/cluster/node/list'

• Response example

{
  "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集群地址发现方式

Description

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

Since

3.0.0

Request Method

PUT

Authorization

Administrator permissions required.

Request URL

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

Request Parameters

Response Data

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

Examples

• Request example

curl -X PUT 'http://127.0.0.1:8848/nacos/v3/admin/core/cluster/lookup' -d "type=file"

• Response example

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

1.8. Raft 相关操作

Description

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

Since

3.0.0

Request Method

POST

请求体类型：application/json，参数放在请求体中。

Authorization

Administrator permissions required.

Request URL

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

Request Parameters

命令说明（Swagger 暂不支持该子参数结构，文档保留）：

• doSnapshot: ${nacos-server-address}:${raft-port}
• transferLeader: ${nacos-server-address}:${raft-port}
• restRaftCluster: ${nacos-server-address}:${raft-port}[,${nacos-server-address}:${raft-port}]
• removePeer: ${nacos-server-address}:${raft-port}
• removePeers: ${nacos-server-address}:${raft-port}[,${nacos-server-address}:${raft-port}]
• changePeers: ${nacos-server-address}:${raft-port}[,${nacos-server-address}:${raft-port}]

Response Data

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

Examples

• Request example

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"}'

• Response example

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

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

Description

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

Since

3.0.0

Request Method

PUT

请求体类型：application/json，参数放在请求体中。

Authorization

Administrator permissions required.

Request URL

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

Request Parameters

Response Data

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

Examples

• Request example

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"}'

• Response example

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

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

Description

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

自动均衡逻辑：

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

Since

3.0.0

Request Method

POST

Authorization

Administrator permissions required.

Request URL

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

Request Parameters

Response Data

成功则返回:

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

失败则返回：

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

Examples

• Request example

curl -X POST 'http://127.0.0.1:8848/nacos/v3/admin/core/loader/smartReloadCluster' -d "loaderFactor=0.1"

• Response example

success

1.11. 获取ID生成器信息

Description

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

Since

3.0.0

Request Method

GET

Authorization

Administrator permissions required.

Request URL

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

Request Parameters

无

Response Data

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

成功则返回:

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

失败则返回：

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

Examples

• Request example

curl -X GET 'http://127.0.0.1:8848/nacos/v3/admin/core/ops/ids'

• Response example

success

1.12. 更新集群节点信息

Description

通过该接口，可以更新当前节点中的Nacos节点列表的详细信息。注意： 该接口会覆盖当前节点中列表中的详细信息，仅更新传入的节点中存在于集群中的节点，并不能通过此接口添加和减少集群中的节点。同时，Nacos自身的健康探测report任务也会对当前节点中列表中的节点进行健康探测及更新详细信息，若调用此接口后，探测任务发现节点信息有变更，则任务也会覆盖当前节点中列表中的节点信息。

Since

3.0.0

Request Method

PUT

Authorization

Administrator permissions required.

Request URL

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

Request Parameters

请求体为 JSON 数组，数组元素为节点信息（Member），包含 ip、port、state、extendInfo 等字段。

Response Data

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

Examples

• Request example

curl -X PUT 'http://127.0.0.1:8848/nacos/v3/admin/core/cluster/node/list' \
  -H 'Content-Type: application/json' \
  -d '[{"ip":"127.0.0.1","port":8848,"state":"UP","address":"127.0.0.1:8848"}]'

• Response example

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

1.13. 获取命名空间详情

Description

通过该接口，可以获取指定命名空间的详情。

Since

3.0.0

Request Method

GET

Authorization

Administrator permissions required.

Request URL

/nacos/v3/admin/core/namespace

Request Parameters

Response Data

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

Examples

• Request example

curl -X GET 'http://127.0.0.1:8848/nacos/v3/admin/core/namespace?namespaceId=public'

• Response example

{
  "code": 0,
  "message": "success",
  "data": {
    "namespace": "public",
    "namespaceShowName": "public",
    "namespaceDesc": "Default Namespace",
    "quota": 200,
    "configCount": 0,
    "type": 0
  }
}

1.14. 更新命名空间

Description

通过该接口，可以更新命名空间的信息，无法更新命名空间ID，仅能更新命名空间的Name和Description。

Since

3.0.0

Request Method

PUT

Authorization

Administrator permissions required.

Request URL

/nacos/v3/admin/core/namespace

Request Parameters

Response Data

成功则返回统一返回体，data 为 true 表示成功；失败则返回Nacos open API 统一返回体格式。

Examples

• Request example

curl -X PUT 'http://127.0.0.1:8848/nacos/v3/admin/core/namespace' \
  -d 'namespaceId=test' -d 'namespaceName=test' -d 'namespaceDesc=test'

• Response example

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

1.15. 创建新命名空间

Description

通过该接口，可以创建新的命名空间。

Since

3.0.0

Request Method

POST

Authorization

Administrator permissions required.

Request URL

/nacos/v3/admin/core/namespace

Request Parameters

Response Data

成功则返回统一返回体，data 为 true 表示成功；失败则返回Nacos open API 统一返回体格式。

Examples

• Request example

curl -X POST 'http://127.0.0.1:8848/nacos/v3/admin/core/namespace' \
  -d 'namespaceName=test' -d 'namespaceDesc=test'

• Response example

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

1.16. 删除命名空间

Description

通过该接口，可以删除命名空间。默认命名空间public无法被删除。

Since

3.0.0

Request Method

DELETE

Authorization

Administrator permissions required.

Request URL

/nacos/v3/admin/core/namespace

Request Parameters

Response Data

成功则返回统一返回体，data 为 true 表示成功；失败则返回Nacos open API 统一返回体格式。

Examples

• Request example

curl -X DELETE 'http://127.0.0.1:8848/nacos/v3/admin/core/namespace?namespaceId=test'

• Response example

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

1.17. 检查命名空间是否存在

Description

通过该接口，可以检查命名空间ID是否存在。应该在创建命名空间前调用，确认自定义的命名空间ID是否已经存在，以防冲突。

Since

3.0.0

Request Method

GET

Authorization

Administrator permissions required.

Request URL

/nacos/v3/admin/core/namespace/check

Request Parameters

Response Data

返回体遵循Nacos open API 统一返回体格式，data 为 true 表示已存在，false 表示不存在。

Examples

• Request example

curl -X GET 'http://127.0.0.1:8848/nacos/v3/admin/core/namespace/check?namespaceId=public'

• Response example

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

1.18. 获取Nacos命名空间列表

Description

通过该接口，可以获取当前Nacos集群的命名空间列表。

Since

3.0.0

Request Method

GET

Authorization

Administrator permissions required.

Request URL

/nacos/v3/admin/core/namespace/list

Request Parameters

无

Response Data

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。data 为命名空间对象数组，每项包含 namespace、namespaceShowName、namespaceDesc、quota、configCount、type 等字段。

Examples

• Request example

curl -X GET 'http://127.0.0.1:8848/nacos/v3/admin/core/namespace/list'

• Response example

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "namespace": "public",
      "namespaceShowName": "public",
      "namespaceDesc": "Default Namespace",
      "quota": 200,
      "configCount": 0,
      "type": 0
    }
  ]
}

1.19. 获取Nacos集群状态信息

Description

通过该接口，可以获取到Nacos 集群的基础状态和开关信息，例如：版本号，运行模式，鉴权是否开启等；该接口不会返回Nacos 集群的节点信息。

Since

3.0.0

Request Method

GET

Authorization

公开接口，无需身份信息。

Request URL

/nacos/v3/admin/core/state

Request Parameters

无

Response Data

返回体遵循Nacos open API 统一返回体格式，data 为键值对，包含版本号（version）、运行模式（startup_mode）、鉴权开关（auth_enabled）等集群状态与配置项。

Examples

• Request example

curl -X GET 'http://127.0.0.1:8848/nacos/v3/admin/core/state'

• Response example

{
  "defaultMaxSize": "102400",
  "auth_system_type": "nacos",
  "auth_enabled": "false",
  "version": "3.0.0-SNAPSHOT",
  "startup_mode": "standalone",
  "server_port": "8848"
}

1.20. 获取Nacos集群的存活状态

Description

通过该接口，可以获取Nacos集群的存活状态，Nacos集群是否可正常接受和响应请求。

Since

3.0.0

Request Method

GET

Authorization

公开接口，无需身份信息。

Request URL

/nacos/v3/admin/core/state/liveness

Request Parameters

无

Response Data

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

Examples

• Request example

curl -X GET 'http://127.0.0.1:8848/nacos/v3/admin/core/state/liveness'

• Response example

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

1.21. 获取Nacos集群的可读状态

Description

通过该接口，可以获取Nacos集群的是否处于可读取状态，即Nacos集群是否可以读取到数据。

Since

3.0.0

Request Method

GET

Authorization

公开接口，无需身份信息。

Request URL

/nacos/v3/admin/core/state/readiness

Request Parameters

无

Response Data

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

Examples

• Request example

curl -X GET 'http://127.0.0.1:8848/nacos/v3/admin/core/state/readiness'

• Response example

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

1.22. 更新插件配置

Description

通过该接口，可以更新插件的配置。需要提供插件类型、名称及配置内容。支持 localOnly 仅作用于当前节点。

Since

3.2.0

Request Method

PUT

请求体类型：application/json。

Authorization

Administrator permissions required.

Request URL

/nacos/v3/admin/core/plugin/config

Request Parameters

请求体为 JSON，包含以下字段：

Response Data

返回体遵循Nacos open API 统一返回体格式，data 为字符串表示操作结果。

Examples

• Request example

curl -X PUT 'http://127.0.0.1:8848/nacos/v3/admin/core/plugin/config' \
  -H 'Content-Type: application/json' -d '{}'

• Response example

{
  "code": 0,
  "message": "success",
  "data": "Plugin configuration updated successfully"
}

1.23. 获取插件详情

Description

通过该接口，可以按类型和名称获取指定插件的详情信息。

Since

3.2.0

Request Method

GET

Authorization

Administrator permissions required.

Request URL

/nacos/v3/admin/core/plugin/detail

Request Parameters

Response Data

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

Examples

• Request example

curl -X GET 'http://127.0.0.1:8848/nacos/v3/admin/core/plugin/detail?pluginType=auth&pluginName=nacos-default-auth-plugin'

• Response example

{
  "code": 0,
  "message": "success",
  "data": {
    "pluginId": "auth:nacos-default-auth-plugin",
    "pluginType": "auth",
    "pluginName": "nacos-default-auth-plugin",
    "enabled": true,
    "critical": true,
    "configurable": true,
    "config": {},
    "configDefinitions": []
  }
}

1.24. 获取插件列表

Description

通过该接口，可以获取所有插件列表，可按插件类型筛选。

Since

3.2.0

Request Method

GET

Authorization

Administrator permissions required.

Request URL

/nacos/v3/admin/core/plugin/list

Request Parameters

Response Data

返回体遵循Nacos open API 统一返回体格式，data 为插件对象数组。

Examples

• Request example

curl -X GET 'http://127.0.0.1:8848/nacos/v3/admin/core/plugin/list?pluginType=auth'

• Response example

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "pluginId": "auth:nacos-default-auth-plugin",
      "pluginType": "auth",
      "pluginName": "nacos-default-auth-plugin",
      "enabled": true,
      "critical": true,
      "configurable": true,
      "exclusive": true
    }
  ]
}

1.25. 启用或禁用插件

Description

通过该接口，可以更新插件的启用状态（启用或禁用）。支持 localOnly 仅作用于当前节点。

Since

3.2.0

Request Method

PUT

请求体类型：application/json。

Authorization

Administrator permissions required.

Request URL

/nacos/v3/admin/core/plugin/status

Request Parameters

请求体为 JSON，包含以下字段：

Response Data

返回体遵循Nacos open API 统一返回体格式，data 为字符串表示操作结果。

Examples

• Request example

curl -X PUT 'http://127.0.0.1:8848/nacos/v3/admin/core/plugin/status' \
  -H 'Content-Type: application/json' -d '{}'

• Response example

{
  "code": 0,
  "message": "success",
  "data": "Plugin status updated successfully"
}

2. Nacos Naming 运维 API

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

Description

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

Since

3.0.0

Request Method

GET

Authorization

Administrator permissions required.

Request URL

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

Request Parameters

无

Response Data

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

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

Examples

• Request example

curl -X GET 'http://127.0.0.1:8848/nacos/v3/admin/ns/ops/switches'

• Response example

{
  "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模块的相关开关

Description

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

Since

3.0.0

Request Method

PUT

Authorization

Administrator permissions required.

Request URL

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

Request Parameters

Response Data

Examples

• Request example

curl -X PUT 'http://127.0.0.1:8848/nacos/v3/admin/ns/ops/switches' -d "entry=pushEnabled&value=false"

• Response example

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

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

Description

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

Since

3.0.0

Request Method

GET

Authorization

Administrator permissions required.

Request URL

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

Request Parameters

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

Response Data

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

Examples

• Request example

curl -X GET 'http://127.0.0.1:8848/nacos/v3/admin/ns/ops/metrics?onlyStatus=false'

• Response example

{
  "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. 修改日志级别

Description

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

Since

3.0.0

Request Method

PUT

请求体类型：application/json。

Authorization

Administrator permissions required.

Request URL

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

Request Parameters

请求体字段：

Response Data

Examples

• Request example

curl -X PUT 'http://127.0.0.1:8848/nacos/v3/admin/ns/ops/log' -H 'Content-Type: application/json' -d '{"logName":"com.example.Logger","logLevel":"DEBUG"}'

• Response example

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

2.5 查询所有客户端列表

Description

查询所有客户端的列表。

Since

3.0.0

Request Method

GET

Authorization

需对应命名空间的读权限

Request URL

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

Request Parameters

无

Response Data

Examples

• Request example

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 查询客户端详细信息

Description

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

Since

3.0.0

Request Method

GET

Authorization

需对应命名空间的读权限

Request URL

/nacos/v3/admin/ns/client

Request Parameters

Response Data

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

Examples

• Request example

curl -X GET 'http://127.0.0.1:8848/nacos/v3/admin/ns/client?clientId=1741748952410_127.0.0.1_53863'

• Response example

{
  "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 查询客户端注册的服务列表

Description

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

Since

3.0.0

Request Method

GET

Authorization

需对应命名空间的读权限

Request URL

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

Request Parameters

Response Data

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

Examples

• Request example

curl -X GET 'http://127.0.0.1:8848/nacos/v3/admin/ns/client/publish/list?clientId=1664527081276_127.0.0.1_4400'

• Response example

{
  "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 查询客户端订阅的服务列表

Description

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

Since

3.0.0

Request Method

GET

Authorization

需对应命名空间的读权限

Request URL

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

Request Parameters

Response Data

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

Examples

• Request example

curl -X GET 'http://127.0.0.1:8848/nacos/v3/admin/ns/client/subscribe/list?clientId=1664527081276_127.0.0.1_4400'

• Response example

{
  "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 查询注册指定服务的客户端列表

Description

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

Since

3.0.0

Request Method

GET

Authorization

需对应命名空间的读权限

Request URL

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

Request Parameters

Response Data

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

Examples

• Request example

curl -X GET 'http://127.0.0.1:8848/nacos/v3/admin/ns/client/service/publisher/list?serviceName=test'

• Response example

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "clientId": "1.1.1.1:3306#false",
      "clusterName": "DEFAULT",
      "ip": "1.1.1.1",
      "port": 3306
    }
  ]
}

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

Description

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

Since

3.0.0

Request Method

GET

Authorization

需对应命名空间的读权限

Request URL

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

Request Parameters

Response Data

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

Examples

• Request example

curl -X GET 'http://127.0.0.1:8848/nacos/v3/admin/ns/client/service/subscriber/list?serviceName=service1'

• Response example

{
  "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 查询客户端的负责服务器

Description

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

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

Since

3.0.0

Request Method

GET

Authorization

Administrator permissions required.

Request URL

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

Request Parameters

Response Data

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

Examples

• Request example

curl -X GET 'http://127.0.0.1:8848/nacos/v3/admin/ns/client/distro?ip=127.0.0.1&port=8080'

• Response example

{
  "code": 0,
  "message": "success",
  "data": {
    "responsibleServer": "127.0.0.1:8848"
  }
}

2.12 更新集群信息

Description

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

Since

3.0.0

Request Method

PUT

Authorization

需对应命名空间的写权限

Request URL

/nacos/v3/admin/ns/cluster

Request Parameters

Response Data

Examples

• Request example

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"}'

• Response example

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

2.13 更新实例健康状态

Description

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

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

Since

3.0.0

Request Method

PUT

Authorization

需对应命名空间的写权限

Request URL

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

Request Parameters

Response Data

Examples

• Request example

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'

• Response example

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

2.14 获取所有健康检查器

Description

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

Since

3.0.0

Request Method

GET

Authorization

需对应命名空间的写权限

Request URL

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

Request Parameters

无

Response Data

Examples

• Request example

curl -X GET 'http://127.0.0.1:8848/nacos/v3/admin/ns/health/checkers'

• Response example

{
  "code": 0,
  "message": "success",
  "data": {
    "HTTP": {
      "expectedResponseCode": 200,
      "headers": "",
      "path": ""
    },
    "MYSQL": {
      "cmd": null,
      "pwd": null,
      "user": null
    },
    "NONE": {},
    "TCP": {}
  }
}

2.15 注册实例

Description

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

Since

3.0.0

Request Method

POST

Authorization

需对应命名空间的写权限

Request URL

/nacos/v3/admin/ns/instance

Request Parameters

Response Data

Examples

• Request example

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'

• Response example

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

2.16 注销实例

Description

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

Since

3.0.0

Request Method

DELETE

Authorization

需对应命名空间的写权限

Request URL

/nacos/v3/admin/ns/instance

Request Parameters

Response Data

Examples

• Request example

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'

• Response example

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

2.17 更新实例

Description

更新指定实例的信息。

通过该接口更新的元数据拥有更高的优先级（相比注册实例时的元数据），且具有记忆能力；会在对应实例删除后，依旧存在一段时间，如果在此期间实例重新注册，该元数据依旧生效；您可以通过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。

Since

3.0.0

Request Method

PUT

Authorization

需对应命名空间的写权限

Request URL

/nacos/v3/admin/ns/instance

Request Parameters

Response Data

Examples

• Request example

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'

• Response example

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

2.18 批量更新实例元数据

Description

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

Since

3.0.0

Request Method

PUT

Authorization

需对应命名空间的写权限

Request URL

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

Request Parameters

Response Data

Examples

• Request example

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'

• Response example

{
  "code": 0,
  "message": "success",
  "data": {
    "updated": [
      "127.0.0.1:8080:unknown:DEFAULT:ephemeral"
    ]
  }
}

2.19 批量删除实例元数据

Description

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

Since

3.0.0

Request Method

DELETE

Authorization

需对应命名空间的写权限

Request URL

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

Request Parameters

Response Data

Examples

• Request example

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'

• Response example

{
  "code": 0,
  "message": "success",
  "data": {
    "updated": [
      "127.0.0.1:8080:unknown:DEFAULT:ephemeral"
    ]
  }
}

2.20 部分更新实例

Description

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

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

Since

3.0.0

Request Method

PUT

Authorization

需对应命名空间的写权限

Request URL

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

Request Parameters

Response Data

Examples

• Request example

curl -X PUT "http://127.0.0.1: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"}'

• Response example

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

2.21 查询服务实例列表

Description

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

Since

3.0.0

Request Method

GET

Authorization

需对应命名空间的读权限

Request URL

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

Request Parameters

Response Data

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

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

Examples

• Request example

curl -X GET 'http://127.0.0.1:8848/nacos/v3/admin/ns/instance/list?namespaceId=public&serviceName=service1&healthyOnly=true'

• Response example

{
  "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 查询实例详情

Description

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

Since

3.0.0

Request Method

GET

Authorization

需对应命名空间的读权限

Request URL

/nacos/v3/admin/ns/instance

Request Parameters

Response Data

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

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

Examples

• Request example

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'

• Response example

{
  "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"
}