From 38e11ea4025870ecd4b93b1458fe63aa2230623d Mon Sep 17 00:00:00 2001 From: Hazel0928 <55099364+Hazel0928@users.noreply.github.com> Date: Wed, 24 Jan 2024 14:37:11 +0800 Subject: [PATCH 1/4] FIx 404 (#518) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat: 🎸 fix link * fix: 🐛 fix descriptioin * feat: 🎸 老路由兼容 --- astro.config.mjs | 4 +- src/components/common/Header/navbar.ts | 2 +- src/content/docs/latest/en/auth.md | 220 +++++++++++++++++ .../latest/en/cluster-mode-quick-start.md | 165 +++++++++++++ src/content/docs/latest/en/console-guide.md | 181 ++++++++++++++ src/content/docs/latest/en/deployment.md | 100 ++++++++ src/content/docs/latest/zh-cn/auth.md | 228 ++++++++++++++++++ .../latest/zh-cn/cluster-mode-quick-start.md | 176 ++++++++++++++ .../docs/latest/zh-cn/console-guide.md | 187 ++++++++++++++ src/content/docs/latest/zh-cn/deployment.md | 99 ++++++++ src/i18n/en/ui.ts | 2 +- src/i18n/zh-cn/ui.ts | 2 +- template/404.startlight.tpl | 45 +++- template/index.startlight.tpl | 7 - 14 files changed, 1396 insertions(+), 22 deletions(-) create mode 100644 src/content/docs/latest/en/auth.md create mode 100644 src/content/docs/latest/en/cluster-mode-quick-start.md create mode 100644 src/content/docs/latest/en/console-guide.md create mode 100644 src/content/docs/latest/en/deployment.md create mode 100644 src/content/docs/latest/zh-cn/auth.md create mode 100644 src/content/docs/latest/zh-cn/cluster-mode-quick-start.md create mode 100644 src/content/docs/latest/zh-cn/console-guide.md create mode 100644 src/content/docs/latest/zh-cn/deployment.md diff --git a/astro.config.mjs b/astro.config.mjs index 8eff543a30a..c0ddab1261a 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -75,9 +75,9 @@ export default defineConfig({ }, redirects: { '/zh-cn/': '/', - '/en-us/': '/en', - '/zh-cn/[...slug].html': '/[...slug]', + '/en-us/': '/en/', '/[...slug].html': '/[...slug]', + '/en-us/[...slug]/': '/en/[...slug]/', '/zh-cn/[...slug]': '/[...slug]', } }); \ No newline at end of file diff --git a/src/components/common/Header/navbar.ts b/src/components/common/Header/navbar.ts index 608888a2683..e5362926e65 100644 --- a/src/components/common/Header/navbar.ts +++ b/src/components/common/Header/navbar.ts @@ -19,7 +19,7 @@ export default [ en: "NACOS CLOUD" }, trigger: "click", - route: "/cloud", + route: "/cloud/", target: "_self", activePath: ['/cloud'], }, diff --git a/src/content/docs/latest/en/auth.md b/src/content/docs/latest/en/auth.md new file mode 100644 index 00000000000..55e5d955b01 --- /dev/null +++ b/src/content/docs/latest/en/auth.md @@ -0,0 +1,220 @@ +--- +title: Authentication +keywords: [Authentication] +description: Authentication +sidebar: + order: 5 +--- + +> Attention +> - Nacos is an internal micro service component, which needs to run in a trusted internal network. It can not be exposed to the public network environment to prevent security risks. +> - Nacos provides a simple authentication implementation. It is a weak authentication system to prevent business misuse, not a strong authentication system to prevent malicious attacks. +> - If you are running in an untrusted network environment or have strong authentication demands, please refer to the official simple implementation to develop [Authentication plugin](../../plugin/auth-plugin.md). + + +# Authentication + +## Related Parameters + +|Parameter|Default|Versions|Description| +|-----|------|------|----| +|nacos.core.auth.enabled|false|1.2.0 ~ latest|Whether to enable the authentication| +|nacos.core.auth.system.type|nacos|1.2.0 ~ latest|Type of authentication| +|nacos.core.auth.plugin.nacos.token.secret.key|SecretKey012345678901234567890123456789012345678901234567890123456789(No default since 2.2.0.1)|2.1.0 ~ latest|Used to generate the key used by the user to login to the temporary accessToken in the default authentication plugin. **Using the default value is a security risk**.| +|nacos.core.auth.plugin.nacos.token.expire.seconds|18000|2.1.0 ~ latest|Expiration time of user login temporary accessToken| +|nacos.core.auth.enable.userAgentAuthWhite|false|1.4.1 ~ latest|Whether to use the useragent whitelist, mainly used to adapt to the upgrade of the old version, **Setting `true` is a security risk**| +|nacos.core.auth.server.identity.key|serverIdentity(No default since 2.2.1)|1.4.1 ~ latest|Used to replace the identification key of the useragent whitelist, **Using the default value is a security risk**| +|nacos.core.auth.server.identity.value|security(No default since 2.2.1)|1.4.1 ~ latest|It is used to replace the identification value of the useragent whitelist, **Using the default value is a security risk**| +|~~nacos.core.auth.default.token.secret.key~~|SecretKey012345678901234567890123456789012345678901234567890123456789|1.2.0 ~ 2.0.4|Same as `nacos.core.auth.plugin.nacos.token.secret.key`| +|~~nacos.core.auth.default.token.expire.seconds~~|18000|1.2.0 ~ 2.0.4|Same as `nacos.core.auth.plugin.nacos.token.expire.seconds`| + + +## Use Authentication in Servers + +### Without Docker +By default, no login is required to start following the official document configuration, which can expose the configuration center directly to the outside world. However, if the authentication is enabled, one can use nacos only after he configures the user name and password. + +Before enabling authentication, the configuration in application.properties is as follow: +```java +### If turn on auth system: +nacos.core.auth.enabled=false +``` + +After enabling authentication, the configuration in application.properties is as follow: +```java +### If turn on auth system: +nacos.core.auth.system.type=nacos +nacos.core.auth.enabled=true +``` + +#### Custom SecretKey + +After enabling authentication, you can customize the key used to generate JWT tokens，the configuration in application.properties is as follow： + +> Attention： +> 1. The secret key provided in the document is a public key. Please replace it with other secret key content during actual deployment to prevent security risks caused by secret key leakage. +> 2. After version 2.2.0.1, the community release version will remove the following value as the default value in the document, which needs to be filled in by yourself, otherwise the node cannot be started. +> 3. The secret key needs to be consistent between nodes, and if it is inconsistent for a long time, it may cause 403 invalid token error. + +```properties +### The default token(Base64 String): +nacos.core.auth.default.token.secret.key=SecretKey012345678901234567890123456789012345678901234567890123456789 + +### Since 2.1.0 +nacos.core.auth.plugin.nacos.token.secret.key=SecretKey012345678901234567890123456789012345678901234567890123456789 +``` + +When customizing the key, it is recommended to set the configuration item to a **Base64 encoded** string, +and **the length of the original key must not be less than 32 characters**. For example the following example: + +```properties +### The default token(Base64 String): +nacos.core.auth.default.token.secret.key=VGhpc0lzTXlDdXN0b21TZWNyZXRLZXkwMTIzNDU2Nzg= + +### Since 2.1.0 +nacos.core.auth.plugin.nacos.token.secret.key=VGhpc0lzTXlDdXN0b21TZWNyZXRLZXkwMTIzNDU2Nzg= +``` + +> Attention: the authentication switch takes effect immediately after the modification, and there is no need to restart the server. When dynamic modifing `token.secret.key`, Please make sure the new value is valid, otherwise the login and request will fail. + +### With Docker + +#### Official images + +If you choose to use official images, please add the following environment parameter when you start a docker container. + +```powershell +NACOS_AUTH_ENABLE=true +``` + +For example, you can run this command to run a docker container with Authentication: + +```powershell +docker run --env PREFER_HOST_MODE=hostname --env MODE=standalone --env NACOS_AUTH_ENABLE=true -p 8848:8848 nacos/nacos-server +``` + +Besides, you can also add the other related enviroment parameters: + +| name | description | option | +| ----------------------------- | -------------------------------------- | -------------------------------------- | +| NACOS_AUTH_ENABLE | If turn on auth system | default :false | +| NACOS_AUTH_TOKEN_EXPIRE_SECONDS | The token expiration in seconds | default :18000 | +| NACOS_AUTH_TOKEN | The default token | default :SecretKey012345678901234567890123456789012345678901234567890123456789 | +| NACOS_AUTH_CACHE_ENABLE | Turn on/off caching of auth information. By turning on this switch, the update of auth information would have a 15 seconds delay. | default : false | + + + +#### Custom images + +If you choose to use custom images, please modify the application.properties before you start nacos, change this line + +``` +nacos.core.auth.enabled=false +``` +into +``` +nacos.core.auth.system.type=nacos +nacos.core.auth.enabled=true +``` + +## Authentication in Clients + +### Authentication in Java SDK + +The user name and password should be set when creating a 'Properties' class. +```java +properties.put("username","${username}"); +properties.put("password","${password}"); +``` +#### Example Code +```java +try { + // Initialize the configuration service, and the console automatically obtains the following parameters through the sample code. + String serverAddr = "{serverAddr}"; + Properties properties = new Properties(); + properties.put("serverAddr", serverAddr); + + // if need username and password to login + properties.put("username","nacos"); + properties.put("password","nacos"); + + ConfigService configService = NacosFactory.createConfigService(properties); +} catch (NacosException e) { + // TODO Auto-generated catch block + e.printStackTrace(); +} +``` +### Authentication in Other languages SDK + +Pending... + +### Authentication in Open-API +Firstly, the user name and password should be provided to login. + +```plain +curl -X POST '127.0.0.1:8848/nacos/v1/auth/login' -d 'username=nacos&password=nacos' +``` + +If the user name and password are correct, the response will be: + +``` +{"accessToken":"eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJuYWNvcyIsImV4cCI6MTYwNTYyOTE2Nn0.2TogGhhr11_vLEjqKko1HJHUJEmsPuCxkur-CfNojDo","tokenTtl":18000,"globalAdmin":true} +``` + +Secondly, when using configuration services or naming services, accessToken in the previous response should be provided. To use the accessToken, 'accessToken=${accessToken}' should be appended at the end of request url, e.g., + +```plain +curl -X GET '127.0.0.1:8848/nacos/v1/cs/configs?accessToken=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJuYWNvcyIsImV4cCI6MTYwNTYyMzkyM30.O-s2yWfDSUZ7Svd3Vs7jy9tsfDNHs1SuebJB4KlNY8Q&dataId=nacos.example.1&group=nacos_group' +``` + +```plain +curl -X POST 'http://127.0.0.1:8848/nacos/v1/ns/instance?accessToken=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJuYWNvcyIsImV4cCI6MTYwNTYyMzkyM30.O-s2yWfDSUZ7Svd3Vs7jy9tsfDNHs1SuebJB4KlNY8Q&port=8848&healthy=true&ip=11.11.11.11&weight=1.0&serviceName=nacos.test.3&encoding=GBK&namespaceId=n1' +``` + +## Open feature for token cache + +Since version 2.2.1 of the server, the default authentication plug-in module supports the feature of token cache, see ISSUE #9906 +``` +https://github.com/alibaba/nacos/issues/9906 +``` +#### Background +Regardless of the client SDK or OpenAPI, after calling the `login` interface to obtain the accessToken, carry the accessToken to access the server, and the server parses the token for authentication. The action of token parsing is time-consuming. If you want to improve the performance of the server, you can consider enabling the feature of caching tokens, which using string comparison instead of token parsing. + +#### Way to open +``` +nacos.core.auth.plugin.nacos.token.cache.enable=true +``` + +#### Attention +Before enabling the feature of token cache, the server will generate a new token for each request carrying a username and password to access the `login` interface. The `tokenTtl` field in the return value of `login` interface is equal to the value set in the server configuration file. The configuration is as follows: +``` +nacos.core.auth.plugin.nacos.token.expire.seconds=18000 +``` +After enabling the feature of token cache, the server will first check whether the token corresponding to the username exists in cache for each request to access the `login` interface with username and password. If it does not exist, generate a new token, insert it into the cache and return it to requester; if it exists, return the token to requester, and the value of the `tokenTtl` field is the value set in the configuration file minus the duration of the token stored in the cache. +If the token stays in the cache for more than 90% of the value set in the configuration file, when the `login` interface receives a request, although the token corresponding to the username exists in the cache, the server will regenerate the token and return it to the requester, and update cache. Therefore, in the worst case, the `tokenTtl` received by the requester is only 10% of the value set in the configuration file. + +## Open feature for server identity + +After the authentication feature is enabled, requests between servers will also be affected by the authentication system. Considering that the communication between the servers should be credible, during the 1.2~1.4.0 version, Nacos server use whether the User-Agent includes Nacos-Server to determine whether the request comes from other servers. + +However, this implementation is too simple and fixed, leading to possible security issues. Therefore, since version 1.4.1, Nacos has added the server identification feature. Users can configure the identity of the server by themselves, and no longer use User-Agent as the judgment standard for server requests. + +Way to open server identity + +``` +### Open authentication +nacos.core.auth.enabled=true + +### Shutdown user-agent judgement for server request +nacos.core.auth.enable.userAgentAuthWhite=false + +### Config the server identity key(not empty) and value(not empty) +nacos.core.auth.server.identity.key=example +nacos.core.auth.server.identity.value=example +``` + +**Attention** All servers in cluster need to be configured with the same `server.identity` information, otherwise it may cause data inconsistency between servers or failure to delete instances. + +### Upgrade from old version + +Considering that users of the old version need to upgrade, users can turn on the `nacos.core.auth.enable.userAgentAuthWhite=true` during upgrading, and turn off it after the cluster is upgraded to 1.4.1 completely and runs stably. diff --git a/src/content/docs/latest/en/cluster-mode-quick-start.md b/src/content/docs/latest/en/cluster-mode-quick-start.md new file mode 100644 index 00000000000..dd50f34e954 --- /dev/null +++ b/src/content/docs/latest/en/cluster-mode-quick-start.md @@ -0,0 +1,165 @@ +--- +title: Cluster deployment instructions +keywords: [Cluster,deployment] +description: Cluster deployment instructions +sidebar: + order: 2 +--- + +# Cluster deployment instructions + +> Document optimizing... + +## Cluster Mode Deployment + +This Quick Start Manual is to help you quickly download, install and use Nacos on your computer to deploy the cluster mode for production use. + +### Cluster Deployment Architecture + +Therefore, when it is open source, it is recommended that users put all server lists under a vip and then hang under a domain name. + +Http://ip1:port/openAPI Directly connected to ip mode, the machine needs to be modified to use ip. + +Http://SLB:port/openAPI Mount the SLB mode(Intranet, do not expose internet to avoid security risks), directly connect to SLB, the following server ip real ip, readability is not good. + +Http://nacos.com:port/openAPI Domain name + SLB mode(Intranet, do not expose internet to avoid security risks), good readability, and easy to change ip, recommended mode + +![deployDnsVipMode.jpg](/img/deployDnsVipMode.jpg) + +## 1. Preparing for the Environment + +Make sure that it is installed and used in the environment: + +1. 64 bit OS Linux/Unix/Mac, recommended Linux system. +2. 64 bit JDK 1.8+; [Download](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html). [Configuration](https://docs.oracle.com/cd/E19182-01/820-7851/inst_cli_jdk_javome_t/). +3. Maven 3.2.x+; [Download](https://maven.apache.org/download.cgi). [Configuration](https://maven.apache.org/settings.html). +4. 3 or more Nacos Nodes; + +## 2. Download source code or installation package + +You can get Nacos in two ways. + +### Download source code from Github + +```bash +unzip nacos-source.zip +cd nacos/ +mvn -Prelease-nacos clean install -U +cd nacos/distribution/target/nacos-server-1.3.0/nacos/bin +``` + +### Download Compressed Packet after Compilation + +Download address + +Select the latest stable version from [releases](https://github.com/alibaba/nacos/releases) and download `nacos-server-$version.zip` or `nacos-server-$version.tar.gz` + +```bash + unzip nacos-server-$version.zip OR tar -xvf nacos-server-$version.tar.gz + cd nacos/bin +``` + +## 3. Configuration Cluster Profile + +In the Nacos decompression directory Nacos / conf directory, there is a configuration file cluster. conf, please configure each line as ip: port. + +```plain +# ip:port +200.8.9.16:8848 +200.8.9.17:8848 +200.8.9.18:8848 +``` + +### 3.1 Open Default auth plugin (Optional) + +Then Setting configuration file `application.properties` under `conf`. + +Setting + +```properties +nacos.core.auth.enabled=true +nacos.core.auth.system.type=nacos +nacos.core.auth.plugin.nacos.token.secret.key=${custom, make sure same in all nodes} +nacos.core.auth.server.identity.key=${custom, make sure same in all nodes} +nacos.core.auth.server.identity.value=${custom, make sure same in all nodes} +``` +Detail see [Authentication](../../plugin/auth-plugin.md). + +> Attention，Default value in Document `SecretKey012345678901234567890123456789012345678901234567890123456789` and `VGhpc0lzTXlDdXN0b21TZWNyZXRLZXkwMTIzNDU2Nzg=` is a public default, **only** should use in test temporary. Please **make sure** to replace it with another valid value when you actually deploy. + +## 4. Determine The DataSource + +### Using built-in data sources + +No configuration is required + +### Use an external data source + + +production and use recommendations at least backup mode, or high availability database. + +#### Initializes the MySQL database + +[sql statement source file](https://github.com/alibaba/nacos/blob/master/distribution/conf/mysql-schema.sql) + +### application. properties configuration + +[application.properties configuration file](https://github.com/alibaba/nacos/blob/master/distribution/conf/application.properties) + +## 5. start server + +### Linux/Unix/Mac + +#### Standalone mode + +```bash +sh startup.sh -m standalone +``` + +#### Cluster mode + +> Using built-in data sources + +```bash +sh startup.sh -p embedded +``` + +> Use an external data source + +```bash +sh startup.sh +``` + +## 6. Service Registration & Discovery and Configuration Management + +### Service registration + +`curl -X POST 'http://127.0.0.1:8848/nacos/v1/ns/instance?serviceName=nacos.naming.serviceName&ip=20.18.7.10&port=8080'` + +> Attention: If open default auth plugin, please call with username and password in header. + +### Service discovery + +`curl -X GET 'http://127.0.0.1:8848/nacos/v1/ns/instance/list?serviceName=nacos.naming.serviceName'` + +> Attention: If open default auth plugin, please call with username and password in header. + +### Publish configuration + +`curl -X POST "http://127.0.0.1:8848/nacos/v1/cs/configs?dataId=nacos.cfg.dataId&group=test&content=helloWorld"` + +> Attention: If open default auth plugin, please call with username and password in header. + +### get configuration + +`curl -X GET "http://127.0.0.1:8848/nacos/v1/cs/configs?dataId=nacos.cfg.dataId&group=test"` + +> Attention: If open default auth plugin, please call with username and password in header. + +## 7. shut down server + +### Linux/Unix/Mac + +```bash +sh shutdown.sh +``` diff --git a/src/content/docs/latest/en/console-guide.md b/src/content/docs/latest/en/console-guide.md new file mode 100644 index 00000000000..45a31d4a109 --- /dev/null +++ b/src/content/docs/latest/en/console-guide.md @@ -0,0 +1,181 @@ +--- +title: Console Guide +keywords: [console,guide] +description: Nacos console aims to enhance the console for service list, health management, service management, a distributed configuration management control ability. +sidebar: + order: 5 +--- + +# Console Guide + +[Nacos console](http://console.nacos.io/nacos/index.html) aims to enhance the console for service list, health management, service management, a distributed configuration management control ability, in order to help users reduce the cost of micro management service application architecture, will provide basic functions include the following: + +* Service management + * Service list and health status display + * Service metadata storage and editing + * Service flow weight adjustment + * Service elegant line up and down +* Configuration management + * More configuration format editing + * Edit DIFF + * Sample code + * Push status query + * Configure version and rolled back +* Namespace +* Login management + +## Features + +### Service management + +Developer or operations staff often require after service registry, through friendly interface to view the service registration situation, the current system, including the registration of all of the details of the services and each service.And in a case, with access control service of some of the configuration editor.Nacos in this version of open service found that part of the console, main is to provide users a basic operations page, to view, edit, the current registration services. + +#### Service list management + +Service list to help users with a unified view management of all its service and health status.The overall layout is the upper left corner services and search box to search button, the page is the central service list.Service main display service name list, the cluster number, number of instances, health instance number and details button five columns. + +![image.png | left | 747x281](https://cdn.nlark.com/lark/0/2018/png/15356/1540536911804-3660f0e9-855f-4439-ac23-e76f6f644360.png "") + +In the service list page click details, you can see details of the service.Can look at the service, the basic information of the cluster and examples. + +#### Service flow weighted support and protection + +Nacos flow provides the user with the ability of weight control, open the threshold of service flow protection at the same time, in order to help users better protection service cluster service providers are not accidentally break.The diagram below so, click the edit button instance, modify instance weights.If you want to increase the flow of instance, to turn up the weight, if you don't want to flow method receives the instance, the weight can be set to 0. + +![image.png | left | 747x266](https://cdn.nlark.com/lark/0/2018/png/15356/1540537029452-dffbb078-4ae5-4397-9f70-083e0ebbb5be.png "") + +#### Service metadata management + +Nacos provide multiple dimensions of service metadata exposed, help users to store the information of the custom.This information is based on data storage structure, K - V on the console, as to the k1 = v1, k2 = v2 show such format.Similarly, edit the metadata can be performed by the same format.Such as service metadata editing, first click on the service details in the top right corner of the page "edit service" button, and then in the metadata input: input box version = 1.0, env = prod. + +![image.png | left | 747x271](https://cdn.nlark.com/lark/0/2018/png/15356/1540537359751-217d7500-c19c-4bad-8508-27f347f48a2f.png "") + +Click on the confirmation, you can in the service details page, see the service metadata has been updated. + +![image.png | left | 747x145](https://cdn.nlark.com/lark/0/2018/png/15356/1540537452673-01dc6c92-329a-4b6f-a616-36dc546c3355.png "") + +#### Service elegant line up and down + +Nacos also offers the service instance line operation, up and down in the service details page, you can click on the instance of "on-line" or "off" button, the offline instance, cases of health will not be included in the list. + +![image.png | left | 747x142](https://cdn.nlark.com/lark/0/2018/png/15356/1540537640435-b28cb279-75af-4965-8a9a-54cee213f1a5.png "") + +### Configuration management + +Nacos support Group configuration based on the Namespace and Group management, so that users more flexible according to their own needs in accordance with the environment or application, module, such as grouping management services as well as the configuration of Spring, in the configuration management major provides configuration version history, rollback, subscriber query such as the core management abilities. + +![image.png | left | 747x297](https://cdn.nlark.com/lark/0/2018/png/9687/1540458893745-219a46a8-ebd9-405b-9e8f-226f3f0c7e76.png "") + +#### More configuration format editor + +Nacos support YAML, Properties, TEXT, JSON, XML, HTML and other common configuration format online editing, syntax highlighting, format check, help users efficiently edit at the same time greatly reduced the risks of format error. + +Nacos support configuration tag ability, help users better and more flexible to the configuration of the classification and management based on the tag.Description of configuration and its change is support users at the same time, people or cross team collaboration management configuration. + +![image.png | left | 747x426](https://cdn.nlark.com/lark/0/2018/png/9687/1540458995051-b3e67fd4-c905-4552-9e52-f54b6ef59941.png "") + +#### Edit DIFF + +Nacos supports editing a DIFF ability, help the user to check the changes, and reduce the risks of correction. + +![image.png | left | 747x338](https://cdn.nlark.com/lark/0/2018/png/9687/1540457990344-a60e1db3-ca1a-47ed-a03e-f92e37745247.png "") + +#### Sample code + +Nacos provide sample code ability, can let a novice quickly using client-side programming consumption this configuration, novice slash barriers. + +![image.png | left | 747x223](https://cdn.nlark.com/lark/0/2018/png/9687/1540456991412-01acc11c-8b48-48d8-9032-589ebb9388d9.png "") + +![image.png | left | 747x380](https://cdn.nlark.com/lark/0/2018/png/9687/1540532899571-ccea6b6f-a1e1-44d1-a130-f9afaba01c51.png "") + +#### Listener query + +Nacos provide configuration subscriber is the listener query ability, at the same time provide Client MD5 checksum value of the current configuration, in order to help users better check configuration changes pushed to the Client side. + +![image.png | left | 747x185](https://cdn.nlark.com/lark/0/2018/png/9687/1540459212236-0abdc558-68b9-4585-b11e-c9a1924ce7ef.png "") + +#### Configure version and rolled back + +Nacos by providing a key roll back configuration version management and its ability, help users can configure to quick recovery, reduce the micro service system in configuration management will meet the availability of the risk. + +![image.png | left | 747x242](https://cdn.nlark.com/lark/0/2018/png/9687/1540459226967-a258b9a7-f95f-41b0-874f-2a0a5da2fc5c.png "") + +![image.png | left | 747x493](https://cdn.nlark.com/lark/0/2018/png/9687/1540459237821-d4c06d16-b356-4953-a6e7-da949b1f3aec.png "") + +## Namespace management + +Nacos based in Namespace helps users logic isolation based multiple namespaces, this can help users better management testing, service and configure the pretest, production environment, so that the same configuration environment (such as database data sources) can define different values. + +![image.png | left | 747x298](https://cdn.nlark.com/lark/0/2018/png/9687/1540519411777-74908cc2-29bc-4270-be58-aed62605228f.png "") + +![image.png | left | 747x206](https://cdn.nlark.com/lark/0/2018/png/9687/1540519427066-effd5153-02c9-4e21-ae9f-1a2e9ae7713e.png "") + +## Login management + +Nacos 0.8 version supports simple login function, the default username/password for: `nacos/nacos`. + +![login](https://cdn.nlark.com/yuque/0/2019/jpeg/338441/1561262748106-4fc05174-bf70-4806-bcbd-90296c5bcbaa.jpeg) + +### Change the default username/password method + +1. Generate encrypted password in `com.alibaba.nacos.console.utils.PasswordEncoderUtil.main` function, change nacos to you want to change the password, running with encryption algorithm.Note that salt is random, so the generated password every time may be different, please don't worry about it. + +``` +public class PasswordEncoderUtil { + + public static void main(String[] args) { + System.out.println(new BCryptPasswordEncoder().encode("nacos")); + } +} +``` + +2. Create a user name or password, use specify a user name password. +``` +INSERT INTO users (username, password, enabled) VALUES ('nacos', '$2a$10$EuWPZHzz32dJN7jexM34MOeYirDdFAZm2kuWj7VEOJhhZkDrxfvUu', TRUE); +INSERT INTO roles (username, role) VALUES ('nacos', 'ROLE_ADMIN'); +``` + +### Close the login function + +As part of its own development console, do not want to be nacos security filter interceptor.Therefore nacos support custom close the login functionFind the configuration file `${nacoshome}/conf/application.properties`. The properties, replace the following content. + +``` +## spring security config +### turn off security +spring.security.enabled=false +management.security=false +security.basic.enabled=false +nacos.security.ignore.urls=/** + +#nacos.security.ignore.urls=/,/**/*.css,/**/*.js,/**/*.html,/**/*.map,/**/*.svg,/**/*.png,/**/*.ico,/console-fe/public/**,/v1/auth/login,/v1/console/health,/v1/cs/**,/v1/ns/**,/v1/cmdb/**,/actuator/** + +``` + +### Session time + +The default session to keep time for 30 minutes.After 30 minutes need to login authentication.Temporarily does not support to modify the default time. + +## Community participation in the front end of the building + +In Nacos front style, the layout of the discussion, the community vote, finally choose the style of the classic black and white and blue skin, and through our UED Yao Cheng design, layout, make interaction is very natural. + +In the development of the console, we recruited through community many front students to participate in the development of the front-end code, in this especially thank Chen Li, Qing Wang, Yanmin Wang Nacos front-end development process in the strong support! + +## Adhere to the community development, welcome to join and contribute to the community + +> DISS is cheap, show me your hand! + +To join Nacos WeChat community discussion Nacos the evolution of the product, you can sweep through **xuechaos** WeChat QRcode, let "xuechaos" help you pull in "Nacos community communication group". + +![Screen Shot 2018-06-27 at 13.39.09.png | left](https://cdn.yuque.com/lark/0/2018/png/15914/1530077965587-8f4e3100-bdd4-469a-9ea0-7af7061bc9ef.png "") + +More Nacos related open source project information: + +* [Nacos](https://github.com/alibaba/nacos) +* [Nacos Spring Project](https://github.com/nacos-group/nacos-spring-project) +* [Nacos Spring Boot](https://github.com/nacos-group/nacos-spring-boot-project) +* [Spring Cloud Alibaba](https://github.com/spring-cloud-incubator/spring-cloud-alibaba) +* [Dubbo](https://github.com/apache/dubbo) +* [Sentinel](https://github.com/alibaba/Sentinel) +* [Spring Cloud](https://projects.spring.io/spring-cloud/) +* [Nepxion Discovery](https://github.com/Nepxion/Discovery) diff --git a/src/content/docs/latest/en/deployment.md b/src/content/docs/latest/en/deployment.md new file mode 100644 index 00000000000..89283227912 --- /dev/null +++ b/src/content/docs/latest/en/deployment.md @@ -0,0 +1,100 @@ +--- +title: Nacos supports three types of deployment modes +keywords: [Nacos,deployment modes] +description: Nacos supports three types of deployment modes +sidebar: + order: 1 +--- + +> Document optimizing... + +# Nacos deployment environment + +Nacos is defined as an IDC internal application component, not a product for the public network environment. It is not recommended expose it to the public network environment directly. + +All network related concepts such as VIP and network interface mentioned in the following documents are in the **internal network environment**. + +# Nacos supports three types of deployment modes + +* Standalone Mode - used in DEV or TEST environment. +* Cluster Mode - used in production environment to ensure high-availability. +* Multi-Cluster Mode - in complicated production mode, you may want to deploy multi-cluster mode to support different business units. + +# Environment preparation +- JDK installed, 1.8 and above are required +- Recommendation: 2 core CPU / 4G RAM and above +- Recommendation: Production environment with 3 nodes and above + +## Running Nacos in Standalone Mode + +### Linux/Unix/Mac + +* Standalone means it is non-cluster Mode. * +sh startup.sh -m standalone + +### Windows + +* Standalone means it is non-cluster Mode. * +cmd startup.cmd -m standalone + +### Running Nacos with mysql in Standalone Mode + +#### Initialize MySQL database + +[sql statement source file](https://github.com/alibaba/nacos/blob/master/distribution/conf/mysql-schema.sql) + +#### application.properties configuration + +[application.properties configuration file](https://github.com/alibaba/nacos/blob/master/distribution/conf/application.properties) + +add mysql datasource and configure url, user and password + +``` +spring.datasource.platform=mysql + +db.num=1 +db.url.0=jdbc:mysql://11.162.196.16:3306/nacos_devtest?characterEncoding=utf8&connectTimeout=1000&socketTimeout=3000&autoReconnect=true +db.user=nacos_devtest +db.password=youdontknow +``` + +## Running Nacos in Multi-Node Cluster Mode + +[Nacos in Multi-Node Cluster Mode](./cluster-mode-quick-start.md) + + +## Deploy Nacos in Multi-Cluster Mode + +Nacos support a NameServer route request mode， by which you can design a useful mapping rule to control the request forward to the corresponding cluster, in the mapping rule you can sharding the request by namespace or by tenant etc... + +to setup a NameServer: + +## IP Selection of Multiple Network Cards + +When the local environment is complex, the Nacos service needs to choose IP or network card to use at runtime when it starts up. Nacos Gets IP Reference Spring Cloud Design from Multiple Network Cards. With the nacos.inetutils parameter, you can specify the network card and IP address used by Nacos. The configuration parameters currently supported are: + +- ip-address parameter can set Nacos IP directly + +``` +nacos.inetutils.ip-address=10.11.105.155 +``` + +- use-only-site-local-interfaces parameter allows Nacos to use LAN ip, which is useful when Nacos deploys a machine with multiple network cards + +``` +nacos.inetutils.use-only-site-local-interfaces=true +``` + +- ignored-interfaces parameter support network card arrays, allowing Nacos to ignore multiple network cards + +``` +nacos.inetutils.ignored-interfaces[0]=eth0 +nacos.inetutils.ignored-interfaces[1]=eth1 +``` + +- preferred-networks parameter allow Nacos to select the matching IP preferentially and support regular matching and prefix matching + +``` +nacos.inetutils.preferred-networks[0]=30.5.124. +nacos.inetutils.preferred-networks[0]=30.5.124.(25[0-5]|2[0-4]\\d|((1d{2})|([1-9]?\\d))),30.5.124.(25[0-5]|2[0-4]\\d|((1d{2})|([1-9]?\\d))) +``` diff --git a/src/content/docs/latest/zh-cn/auth.md b/src/content/docs/latest/zh-cn/auth.md new file mode 100644 index 00000000000..8c315327bd2 --- /dev/null +++ b/src/content/docs/latest/zh-cn/auth.md @@ -0,0 +1,228 @@ +--- +title: Authorization +keywords: [Authorization] +description: Authorization +sidebar: + order: 5 +--- + +> 注意 +> - Nacos是一个内部微服务组件，需要在可信的内部网络中运行，不可暴露在公网环境，防止带来安全风险。 +> - Nacos提供简单的鉴权实现，为防止业务错用的弱鉴权体系，不是防止恶意攻击的强鉴权体系。 +> - 如果运行在不可信的网络环境或者有强鉴权诉求，请参考官方简单实现做进行[自定义插件开发](../../plugin/auth-plugin.md)。 + +# 鉴权 + +## 相关参数 + +|参数名|默认值|启止版本|说明| +|-----|------|------|----| +|nacos.core.auth.enabled|false|1.2.0 ~ latest|是否开启鉴权功能| +|nacos.core.auth.system.type|nacos|1.2.0 ~ latest|鉴权类型| +|nacos.core.auth.plugin.nacos.token.secret.key|SecretKey012345678901234567890123456789012345678901234567890123456789(2.2.0.1后无默认值)|2.1.0 ~ latest|默认鉴权插件用于生成用户登陆临时accessToken所使用的密钥，**使用默认值有安全风险**| +|nacos.core.auth.plugin.nacos.token.expire.seconds|18000|2.1.0 ~ latest|用户登陆临时accessToken的过期时间| +|nacos.core.auth.enable.userAgentAuthWhite|false|1.4.1 ~ latest|是否使用useragent白名单，主要用于适配老版本升级，**置为true时有安全风险**| +|nacos.core.auth.server.identity.key|serverIdentity(2.2.1后无默认值)|1.4.1 ~ latest|用于替换useragent白名单的身份识别key，**使用默认值有安全风险**| +|nacos.core.auth.server.identity.value|security(2.2.1后无默认值)|1.4.1 ~ latest|用于替换useragent白名单的身份识别value，**使用默认值有安全风险**| +|~~nacos.core.auth.default.token.secret.key~~|SecretKey012345678901234567890123456789012345678901234567890123456789|1.2.0 ~ 2.0.4|同`nacos.core.auth.plugin.nacos.token.secret.key`| +|~~nacos.core.auth.default.token.expire.seconds~~|18000|1.2.0 ~ 2.0.4|同`nacos.core.auth.plugin.nacos.token.expire.seconds`| + +## 默认控制台登录页 + +2.2.2版本之前的Nacos默认控制台，无论服务端是否开启鉴权，都会存在一个登录页；这导致很多用户被**误导**认为Nacos默认是存在鉴权的。在社区安全工程师的建议下，Nacos自**2.2.2**版本开始，在未开启鉴权时，默认控制台将不需要登录即可访问，同时在控制台中给予提示，提醒用户当前集群未开启鉴权。 + +在用户开启鉴权后，控制台才需要进行登录访问。 同时针对不同的鉴权插件，提供新的接口方法，用于提示控制台是否开启登录页；同时在`2.2.3`版本后，Nacos可支持关闭开源控制台，并引导到用户自定义的Nacos控制台，详情可查看[Nacos鉴权插件-服务端插件](../../plugin/auth-plugin.md)及[控制台手册-关闭登录功能](../admin/console-guide.md#1.1) +## 服务端如何开启鉴权 + +### 非Docker环境 + +按照官方文档配置启动,默认是不需要登录的，这样会导致配置中心对外直接暴露。而启用鉴权之后，需要在使用用户名和密码登录之后，才能正常使用nacos。 + +开启鉴权之前，application.properties中的配置信息为： +```java +### If turn on auth system: +nacos.core.auth.enabled=false +``` +开启鉴权之后，application.properties中的配置信息为： +```java +### If turn on auth system: +nacos.core.auth.system.type=nacos +nacos.core.auth.enabled=true +``` + +#### 自定义密钥 + +开启鉴权之后，你可以自定义用于生成JWT令牌的密钥，application.properties中的配置信息为： + +> 注意： +> 1. 文档中提供的密钥为公开密钥，在实际部署时请更换为其他密钥内容，防止密钥泄漏导致安全风险。 +> 2. 在2.2.0.1版本后，社区发布版本将移除以文档如下值作为默认值，需要自行填充，否则无法启动节点。 +> 3. 密钥需要保持节点间一致，长时间不一致可能导致403 invalid token错误。 + +```properties +### The default token(Base64 String): +nacos.core.auth.default.token.secret.key=SecretKey012345678901234567890123456789012345678901234567890123456789 + +### 2.1.0 版本后 +nacos.core.auth.plugin.nacos.token.secret.key=SecretKey012345678901234567890123456789012345678901234567890123456789 +``` + +自定义密钥时，推荐将配置项设置为**Base64编码**的字符串，且**原始密钥长度不得低于32字符**。例如下面的的例子： + +```properties +### The default token(Base64 String): +nacos.core.auth.default.token.secret.key=VGhpc0lzTXlDdXN0b21TZWNyZXRLZXkwMTIzNDU2Nzg= + +### 2.1.0 版本后 +nacos.core.auth.plugin.nacos.token.secret.key=VGhpc0lzTXlDdXN0b21TZWNyZXRLZXkwMTIzNDU2Nzg= +``` + +> 注意：鉴权开关是修改之后立马生效的，不需要重启服务端。动态修改`token.secret.key`时，请确保token是有效的，如果修改成无效值，会导致后续无法登录，请求访问异常。 + +### Docker环境 + +#### 官方镜像 + +如果使用官方镜像，请在启动docker容器时，添加如下环境变量 + +```powershell +NACOS_AUTH_ENABLE=true +``` + +例如，可以通过如下命令运行开启了鉴权的容器: + +```powershell +docker run --env PREFER_HOST_MODE=hostname --env MODE=standalone --env NACOS_AUTH_ENABLE=true -p 8848:8848 nacos/nacos-server +``` + +除此之外，还可以添加其他鉴权相关的环境变量信息： + +| name | description | option | +| ----------------------------- | -------------------------------------- | -------------------------------------- | +| NACOS_AUTH_ENABLE | 是否开启权限系统 | 默认:false| +| NACOS_AUTH_TOKEN_EXPIRE_SECONDS | token 失效时间 | 默认:18000 | +| NACOS_AUTH_TOKEN | token | 默认:SecretKey012345678901234567890123456789012345678901234567890123456789 | +| NACOS_AUTH_CACHE_ENABLE | 权限缓存开关 ,开启后权限缓存的更新默认有15秒的延迟 | 默认 : false | + + +然后运行docker-compose构建命令,例如 +```powershell +docker-compose -f example/standalone-derby.yaml up +``` + +#### 自定义镜像 + +如果选择自定义镜像，请在构建镜像之前，修改nacos工程中的application.properties文件， + +将下面这一行配置信息 +``` +nacos.core.auth.enabled=false +``` +修改为 +``` +nacos.core.auth.system.type=nacos +nacos.core.auth.enabled=true +``` +然后再配置nacos启动命令。 + +## 客户端如何进行鉴权 + +### Java SDK鉴权 + +在构建“Properties”类时,需传入用户名和密码。 +```java +properties.put("username","${username}"); +properties.put("password","${password}"); +``` +#### 示例代码 +```java +try { + // Initialize the configuration service, and the console automatically obtains the following parameters through the sample code. + String serverAddr = "{serverAddr}"; + Properties properties = new Properties(); + properties.put("serverAddr", serverAddr); + + // if need username and password to login + properties.put("username","nacos"); + properties.put("password","nacos"); + + ConfigService configService = NacosFactory.createConfigService(properties); +} catch (NacosException e) { + // TODO Auto-generated catch block + e.printStackTrace(); +} +``` +### 其他语言的SDK鉴权 + +待补充 + +### Open-API鉴权 +首先需要使用用户名和密码登陆nacos。 + +```plain +curl -X POST '127.0.0.1:8848/nacos/v1/auth/login' -d 'username=nacos&password=nacos' +``` + +若用户名和密码正确,返回信息如下: + +``` +{"accessToken":"eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJuYWNvcyIsImV4cCI6MTYwNTYyOTE2Nn0.2TogGhhr11_vLEjqKko1HJHUJEmsPuCxkur-CfNojDo","tokenTtl":18000,"globalAdmin":true} +``` + +接下来进行配置信息或服务信息时,应当使用该accessToken鉴权,在url后添加参数accessToken=${accessToken},其中${accessToken}为登录时返回的token信息，例如 + +```plain +curl -X GET '127.0.0.1:8848/nacos/v1/cs/configs?accessToken=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJuYWNvcyIsImV4cCI6MTYwNTYyMzkyM30.O-s2yWfDSUZ7Svd3Vs7jy9tsfDNHs1SuebJB4KlNY8Q&dataId=nacos.example.1&group=nacos_group' +``` + +```plain +curl -X POST 'http://127.0.0.1:8848/nacos/v1/ns/instance?accessToken=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJuYWNvcyIsImV4cCI6MTYwNTYyMzkyM30.O-s2yWfDSUZ7Svd3Vs7jy9tsfDNHs1SuebJB4KlNY8Q&port=8848&healthy=true&ip=11.11.11.11&weight=1.0&serviceName=nacos.test.3&encoding=GBK&namespaceId=n1' +``` + +## 开启Token缓存功能 + +服务端自2.2.1版本后，默认鉴权插件模块支持token缓存功能，可参见ISSUE #9906 +``` +https://github.com/alibaba/nacos/issues/9906 +``` +#### 背景 +无论是客户端SDK还是OpenAPI，在调用login接口获取accessToken之后，携带accessToken访问服务端，服务端解析Token进行鉴权。解析的动作比较耗时，如果想要提升接口的性能，可以考虑开启缓存Token的功能，用字符串比较代替Token解析。 + +#### 开启方式 +``` +nacos.core.auth.plugin.nacos.token.cache.enable=true +``` + +#### 注意事项 +在开启Token缓存功能之前，服务端对每一个携带用户名密码访问login接口的请求都会生成新的token，接口的返回值中的tokenTtl字段跟服务端配置文件中设置的值相等，配置如下： +``` +nacos.core.auth.plugin.nacos.token.expire.seconds=18000 +``` +在开启Token缓存功能之后，服务端对每一个携带用户名密码访问login接口的请求，会先检查缓存中是否存在该用户名对应的token。若不存在，生成新的Token，插入缓存再返回；若存在，返回该token，此时tokenTtl字段的值为配置文件中设置的值减去该Token在缓存中存留的时长。 +如果Token在缓存中存留的时长超过配置文件设置的值的90%，当login接口收到请求时，尽管缓存中存在该用户名对应的Token，服务端会重新生成Token返回给请求方，并更新缓存。因此，最差情况下，请求方收到的tokenTtl只有配置文件设置的值的10%。 + +## 开启服务身份识别功能 + +开启鉴权功能后，服务端之间的请求也会通过鉴权系统的影响。考虑到服务端之间的通信应该是可信的，因此在1.2~1.4.0版本期间，通过User-Agent中是否包含Nacos-Server来进行判断请求是否来自其他服务端。 + +但这种实现由于过于简单且固定，导致可能存在安全问题。因此从1.4.1版本开始，Nacos添加服务身份识别功能，用户可以自行配置服务端的Identity，不再使用User-Agent作为服务端请求的判断标准。 + +开启方式: + +``` +### 开启鉴权 +nacos.core.auth.enabled=true + +### 关闭使用user-agent判断服务端请求并放行鉴权的功能 +nacos.core.auth.enable.userAgentAuthWhite=false + +### 配置自定义身份识别的key（不可为空）和value（不可为空） +nacos.core.auth.server.identity.key=example +nacos.core.auth.server.identity.value=example +``` + +** 注意 ** 所有集群均需要配置相同的`server.identity`信息，否则可能导致服务端之间数据不一致或无法删除实例等问题。 + +### 旧版本升级 + +考虑到旧版本用户需要升级，可以在升级期间，开启`nacos.core.auth.enable.userAgentAuthWhite=true`功能，待集群整体升级到1.4.1并稳定运行后，再关闭此功能。 diff --git a/src/content/docs/latest/zh-cn/cluster-mode-quick-start.md b/src/content/docs/latest/zh-cn/cluster-mode-quick-start.md new file mode 100644 index 00000000000..e185d15979b --- /dev/null +++ b/src/content/docs/latest/zh-cn/cluster-mode-quick-start.md @@ -0,0 +1,176 @@ +--- +title: 集群部署说明 +keywords: [集群,部署] +description: 集群部署说明 +sidebar: + order: 2 +--- + + + +> 文档优化中...... + +## 集群模式部署 + +这个快速开始手册是帮忙您快速在你的电脑上，下载安装并使用Nacos，部署生产使用的集群模式。 + +### 集群部署架构图 + +因此开源的时候推荐用户把所有服务列表放到一个vip下面，然后挂到一个域名下面 + + 直连ip模式，机器挂则需要修改ip才可以使用。 + + 挂载SLB模式(内网SLB，不可暴露到公网，以免带来安全风险)，直连SLB即可，下面挂server真实ip，可读性不好。 + + 域名 + SLB模式(内网SLB，不可暴露到公网，以免带来安全风险)，可读性好，而且换ip方便，推荐模式 + +![deployDnsVipMode.jpg](/img/deployDnsVipMode.jpg) + +|端口|与主端口的偏移量|描述| +|--|--|--| +|8848|0|主端口，客户端、控制台及OpenAPI所使用的HTTP端口| +|9848|1000|客户端gRPC请求服务端端口，用于客户端向服务端发起连接和请求| +|9849|1001|服务端gRPC请求服务端端口，用于服务间同步等| +|7848|-1000|Jraft请求服务端端口，用于处理服务端间的Raft相关请求| + +**使用VIP/nginx请求时，需要配置成TCP转发，不能配置http2转发，否则连接会被nginx断开。** +**9849和7848端口为服务端之间的通信端口，请勿暴露到外部网络环境和客户端测。** + +## 1. 预备环境准备 + +请确保是在环境中安装使用: + +1. 64 bit OS Linux/Unix/Mac，推荐使用Linux系统。 +2. 64 bit JDK 1.8+；[下载](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html). [配置](https://docs.oracle.com/cd/E19182-01/820-7851/inst_cli_jdk_javahome_t/)。 +3. Maven 3.2.x+；[下载](https://maven.apache.org/download.cgi). [配置](https://maven.apache.org/settings.html)。 +4. 3个或3个以上Nacos节点才能构成集群。 + +## 2. 下载源码或者安装包 + +你可以通过两种方式来获取 Nacos。 + +### 从 Github 上下载源码方式 + +```bash +unzip nacos-source.zip +cd nacos/ +mvn -Prelease-nacos clean install -U +cd nacos/distribution/target/nacos-server-1.3.0/nacos/bin +``` + +### 下载编译后压缩包方式 + +下载地址 + +您可以从 [最新稳定版本](https://github.com/alibaba/nacos/releases) 下载 `nacos-server-$version.zip` 包 或 `nacos-server-$version.tar.gz`。 + +```bash + unzip nacos-server-$version.zip 或者 tar -xvf nacos-server-$version.tar.gz + cd nacos/bin +``` + +## 3. 配置集群配置文件 + +在nacos的解压目录nacos/的conf目录下，有配置文件cluster.conf，请每行配置成ip:port。（请配置3个或3个以上节点） + +```plain +# ip:port +200.8.9.16:8848 +200.8.9.17:8848 +200.8.9.18:8848 +``` + +### 3.1 开启默认鉴权插件（可选） + +之后修改`conf`目录下的`application.properties`文件。 + +设置其中 + +```properties +nacos.core.auth.enabled=true +nacos.core.auth.system.type=nacos +nacos.core.auth.plugin.nacos.token.secret.key=${自定义，保证所有节点一致} +nacos.core.auth.server.identity.key=${自定义，保证所有节点一致} +nacos.core.auth.server.identity.value=${自定义，保证所有节点一致} +``` + +上述内容详情可查看[权限认证](../../plugin/auth-plugin.md). + +> 注意，文档中的默认值`SecretKey012345678901234567890123456789012345678901234567890123456789`和`VGhpc0lzTXlDdXN0b21TZWNyZXRLZXkwMTIzNDU2Nzg=`为公开默认值，可用于临时测试，实际使用时请**务必**更换为自定义的其他有效值。 + +## 4. 确定数据源 + +### 使用内置数据源 + +无需进行任何配置 + +### 使用外置数据源 + + +生产使用建议至少主备模式，或者采用高可用数据库。 + +#### 初始化 MySQL 数据库 + +[sql语句源文件](https://github.com/alibaba/nacos/blob/master/distribution/conf/mysql-schema.sql) + +#### application.properties 配置 + +[application.properties配置文件](https://github.com/alibaba/nacos/blob/master/distribution/conf/application.properties) + +## 5. 启动服务器 + +### Linux/Unix/Mac + +#### Stand-alone mode + +```bash +sh startup.sh -m standalone +``` + +#### 集群模式 + +> 使用内置数据源 + +```bash +sh startup.sh -p embedded +``` + +> 使用外置数据源 + +```bash +sh startup.sh +``` + +## 6. 服务注册&发现和配置管理 + +### 服务注册 + +`curl -X POST 'http://127.0.0.1:8848/nacos/v1/ns/instance?serviceName=nacos.naming.serviceName&ip=20.18.7.10&port=8080'` + +> 注意：如果开启默认鉴权插件，需要在Header中带上用户名密码。 + +### 服务发现 + +`curl -X GET 'http://127.0.0.1:8848/nacos/v1/ns/instance/list?serviceName=nacos.naming.serviceName'` + +> 注意：如果开启默认鉴权插件，需要在Header中带上用户名密码。 + +### 发布配置 + +`curl -X POST "http://127.0.0.1:8848/nacos/v1/cs/configs?dataId=nacos.cfg.dataId&group=test&content=helloWorld"` + +> 注意：如果开启默认鉴权插件，需要在Header中带上用户名密码。 + +### 获取配置 + +`curl -X GET "http://127.0.0.1:8848/nacos/v1/cs/configs?dataId=nacos.cfg.dataId&group=test"` + +> 注意：如果开启默认鉴权插件，需要在Header中带上用户名密码。 + +## 7. 关闭服务器 + +Linux/Unix/Mac + +```bash +sh shutdown.sh +``` diff --git a/src/content/docs/latest/zh-cn/console-guide.md b/src/content/docs/latest/zh-cn/console-guide.md new file mode 100644 index 00000000000..6aa7bf39d0c --- /dev/null +++ b/src/content/docs/latest/zh-cn/console-guide.md @@ -0,0 +1,187 @@ +--- +title: 控制台手册 +keywords: [控制台,手册] +description: Nacos 控制台主要旨在于增强对于服务列表，健康状态管理，服务治理，分布式配置管理等方面的管控能力。 +sidebar: + order: 5 +--- + +# 控制台手册 + +[Nacos 控制台](http://console.nacos.io/nacos/index.html)主要旨在于增强对于服务列表，健康状态管理，服务治理，分布式配置管理等方面的管控能力，以便进一步帮助用户降低管理微服务应用架构的成本，将提供包括下列基本功能: + +* 服务管理 + * 服务列表及服务健康状态展示 + * 服务元数据存储及编辑 + * 服务流量权重的调整 + * 服务优雅上下线 +* 配置管理 + * 多种配置格式编辑 + * 编辑DIFF + * 示例代码 + * 推送状态查询 + * 配置版本及一键回滚 +* 命名空间 +* 登录管理 + +## 特性详解 + +### 服务管理 + +开发者或者运维人员往往需要在服务注册后，通过友好的界面来查看服务的注册情况，包括当前系统注册的所有服务和每个服务的详情。并在有权限控制的情况下，进行服务的一些配置的编辑操作。Nacos在这个版本开放的控制台的服务发现部分，主要就是提供用户一个基本的运维页面，能够查看、编辑当前注册的服务。 + +#### 服务列表管理 + +服务列表帮助用户以统一的视图管理其所有的微服务以及服务健康状态。整体界面布局是左上角有服务的搜索框和搜索按钮，页面中央是服务列表的展示。服务列表主要展示服务名、集群数目、实例数目、健康实例数目和详情按钮五个栏目。 + +![image.png | left | 747x281](https://cdn.nlark.com/lark/0/2018/png/15356/1540536911804-3660f0e9-855f-4439-ac23-e76f6f644360.png "") + +在服务列表页面点击详情，可以看到服务的详情。可以查看服务、集群和实例的基本信息。 + +#### 服务流量权重支持及流量保护 + +Nacos 为用户提供了流量权重控制的能力，同时开放了服务流量的阈值保护，以帮助用户更好的保护服务服务提供者集群不被意外打垮。如下图所以，可以点击实例的编辑按钮，修改实例的权重。如果想增加实例的流量，可以将权重调大，如果不想实例接收流量，则可以将权重设为0。 + +![image.png | left | 747x266](https://cdn.nlark.com/lark/0/2018/png/15356/1540537029452-dffbb078-4ae5-4397-9f70-083e0ebbb5be.png "") + +#### 服务元数据管理 + +Nacos提供多个维度的服务元数据的暴露，帮助用户存储自定义的信息。这些信息都是以K-V的数据结构存储，在控制台上，会以k1=v1,k2=v2这样的格式展示。类似的，编辑元数据可以通过相同的格式进行。例如服务的元数据编辑，首先点击服务详情页右上角的“编辑服务”按钮，然后在元数据输入框输入：version=1.0,env=prod。 + +![image.png | left | 747x271](https://cdn.nlark.com/lark/0/2018/png/15356/1540537359751-217d7500-c19c-4bad-8508-27f347f48a2f.png "") + +点击确认，就可以在服务详情页面，看到服务的元数据已经更新了。 + +![image.png | left | 747x145](https://cdn.nlark.com/lark/0/2018/png/15356/1540537452673-01dc6c92-329a-4b6f-a616-36dc546c3355.png "") + +#### 服务优雅上下线 + +Nacos还提供服务实例的上下线操作，在服务详情页面，可以点击实例的“上线”或者“下线”按钮，被下线的实例，将不会包含在健康的实例列表里。 + +![image.png | left | 747x142](https://cdn.nlark.com/lark/0/2018/png/15356/1540537640435-b28cb279-75af-4965-8a9a-54cee213f1a5.png "") + +### 配置管理 + +Nacos支持基于Namespace和Group的配置分组管理，以便用户更灵活的根据自己的需要按照环境或者应用、模块等分组管理微服务以及Spring的大量配置，在配置管理中主要提供了配置历史版本、回滚、订阅者查询等核心管理能力。 + +![image.png | left | 747x297](https://cdn.nlark.com/lark/0/2018/png/9687/1540458893745-219a46a8-ebd9-405b-9e8f-226f3f0c7e76.png "") + +#### 多配置格式编辑器 + +Nacos支持 YAML、Properties、TEXT、JSON、XML、HTML 等常见配置格式在线编辑、语法高亮、格式校验，帮助用户高效编辑的同时大幅降低格式错误带来的风险。 + +Nacos支持配置标签的能力，帮助用户更好、更灵活的做到基于标签的配置分类及管理。同时支持用户对配置及其变更进行描述，方便多人或者跨团队协作管理配置。 + +![image.png | left | 747x426](https://cdn.nlark.com/lark/0/2018/png/9687/1540458995051-b3e67fd4-c905-4552-9e52-f54b6ef59941.png "") + +#### 编辑DIFF + +Nacos支持编辑DIFF能力，帮助用户校验修改内容，降低改错带来的风险。 + +![image.png | left | 747x338](https://cdn.nlark.com/lark/0/2018/png/9687/1540457990344-a60e1db3-ca1a-47ed-a03e-f92e37745247.png "") + +#### 示例代码 + +Nacos提供示例代码能力，能够让新手快速使用客户端编程消费该配置，大幅降低新手使用门槛。 + +![image.png | left | 747x223](https://cdn.nlark.com/lark/0/2018/png/9687/1540456991412-01acc11c-8b48-48d8-9032-589ebb9388d9.png "") + +![image.png | left | 747x380](https://cdn.nlark.com/lark/0/2018/png/9687/1540532899571-ccea6b6f-a1e1-44d1-a130-f9afaba01c51.png "") + +#### 监听者查询 + +Nacos提供配置订阅者即监听者查询能力，同时提供客户端当前配置的MD5校验值，以便帮助用户更好的检查配置变更是否推送到 Client 端。 + +![image.png | left | 747x185](https://cdn.nlark.com/lark/0/2018/png/9687/1540459212236-0abdc558-68b9-4585-b11e-c9a1924ce7ef.png "") + +#### 配置的版本及一键回滚 + +Nacos通过提供配置版本管理及其一键回滚能力，帮助用户改错配置的时候能够快速恢复，降低微服务系统在配置管理上的一定会遇到的可用性风险。 + +![image.png | left | 747x242](https://cdn.nlark.com/lark/0/2018/png/9687/1540459226967-a258b9a7-f95f-41b0-874f-2a0a5da2fc5c.png "") + +![image.png | left | 747x493](https://cdn.nlark.com/lark/0/2018/png/9687/1540459237821-d4c06d16-b356-4953-a6e7-da949b1f3aec.png "") + +## 命名空间管理 + +Nacos 基于Namespace 帮助用户逻辑隔离多个命名空间，这可以帮助用户更好的管理测试、预发、生产等多环境服务和配置，让每个环境的同一个配置（如数据库数据源）可以定义不同的值。 + +![image.png | left | 747x298](https://cdn.nlark.com/lark/0/2018/png/9687/1540519411777-74908cc2-29bc-4270-be58-aed62605228f.png "") + +![image.png | left | 747x206](https://cdn.nlark.com/lark/0/2018/png/9687/1540519427066-effd5153-02c9-4e21-ae9f-1a2e9ae7713e.png "") + +## 登录管理 + +Nacos0.8 版本支持简单登录功能，默认用户名/密码为： `nacos/nacos`。 + +![login](https://cdn.nlark.com/yuque/0/2019/jpeg/338441/1561262748106-4fc05174-bf70-4806-bcbd-90296c5bcbaa.jpeg) + +### 修改默认用户名/密码方法 + +1. 生成加密密码， 在`com.alibaba.nacos.console.utils.PasswordEncoderUtil.main`函数中，将 nacos 改成你要改成的密码，运行即可得到加密有算法。注意盐值是随机的，所以生成密码每次可能不一样，请不要担心。 + +``` +public class PasswordEncoderUtil { + + public static void main(String[] args) { + System.out.println(new BCryptPasswordEncoder().encode("nacos")); + } +} +``` + +2. 创建用户名或者密码的时候，用指定用户名密码即可。 +``` +INSERT INTO users (username, password, enabled) VALUES ('nacos', '$2a$10$EuWPZHzz32dJN7jexM34MOeYirDdFAZm2kuWj7VEOJhhZkDrxfvUu', TRUE); +INSERT INTO roles (username, role) VALUES ('nacos', 'ROLE_ADMIN'); +``` + +

+ +### 关闭登录功能 + +Nacos默认控制台在`2.2.2`版本前，无论是否开启[鉴权](../user/auth.md)功能，默认控制台都会跳转到登录页，导致用户被误导认为控制台存在鉴权功能，实际没有开启鉴权，存在安全隐患。 + +经过社区和安全工程师协商讨论，需要在使用Nacos默认控制台时，鉴权开关关闭时将会自动关闭控制台登录功能。 + +因此从`2.2.2`版本开始，当鉴权开关`nacos.core.auth.enabled`关闭时，Nacos默认控制台将不再跳转登录页，同时添加页面提示，提示当前集群未开启鉴权功能。 + +同时针对自定义的[鉴权插件](../../plugin/auth-plugin.md)添加新接口`com.alibaba.nacos.plugin.auth.spi.server.AuthPluginService#isLoginEnabled(默认返回false)`来对自定义插件进行登录页控制。 + +

+ +### 关闭默认控制台 + +部分公司或用户希望关闭默认控制台，使用公司的统一平台进行Nacos的配置和服务管理；或将控制台鉴权和客户端访问的鉴权分离，即控制台操作进行鉴权但客户端请求不进行鉴权。 + +从`2.3.0`版本开始，可以通过`${nacoshome}/conf/application.properties`中的`nacos.console.ui.enabled`来开启或关闭Nacos默认控制台，默认为开启。 + +同时在关闭默认控制台时，默认控制台会读取`${nacoshome}/conf/console-guide.conf`文件中的内容，并在默认控制台中生成引导页，让维护者自定义将使用默认控制台的用户引导向自定义的统一平台上进行操作。 + +### 会话时间 + +默认会话保持时间为30分钟。30分钟后需要重新登录认证。 暂时不支持修改该默认时间。 + +## 社区参与的前端共建 + +在Nacos前端风格、布局的讨论中，社区踊跃投票，最终选择了这套经典黑白蓝风格的皮肤，并且通过我们UED程瑶同学的设计，布局，让交互变得十分自然流畅。 + +在控制台的开发之前，我们通过社区招募到了很多前端同学一起参与了前端代码的开发，在此尤其感谢李晨、王庆、王彦民同学在Nacos前端开发过程中的大力支持！ + +## 坚持社区化发展，欢迎加入并贡献社区 + +> 比吐槽更重要的是搭把手，参与社区一起发展Nacos！ + +要加入Nacos 微信社区讨论 Nacos 产品的演进，你可以通过扫**超哥**的微信二维码，让“超哥” 帮你拉入 “Nacos社区交流群”。 + +![Screen Shot 2018-06-27 at 13.39.09.png | left](https://cdn.yuque.com/lark/0/2018/png/15914/1530077965587-8f4e3100-bdd4-469a-9ea0-7af7061bc9ef.png "") + +更多与 Nacos 相关的开源项目信息： + +* [Nacos](https://github.com/alibaba/nacos) +* [Nacos Spring Project](https://github.com/nacos-group/nacos-spring-project) +* [Nacos Spring Boot](https://github.com/nacos-group/nacos-spring-boot-project) +* [Spring Cloud Alibaba](https://github.com/spring-cloud-incubator/spring-cloud-alibaba) +* [Dubbo](https://github.com/apache/dubbo) +* [Sentinel](https://github.com/alibaba/Sentinel) +* [Spring Cloud](https://projects.spring.io/spring-cloud/) +* [Nepxion Discovery](https://github.com/Nepxion/Discovery) \ No newline at end of file diff --git a/src/content/docs/latest/zh-cn/deployment.md b/src/content/docs/latest/zh-cn/deployment.md new file mode 100644 index 00000000000..90dca2646bc --- /dev/null +++ b/src/content/docs/latest/zh-cn/deployment.md @@ -0,0 +1,99 @@ +--- +title: Nacos支持三种部署模式 +keywords: [Nacos,部署模式] +description: Nacos支持三种部署模式 +sidebar: + order: 1 +--- + +> 文档优化中...... + +# Nacos部署环境 + +Nacos定义为一个IDC内部应用组件，并非面向公网环境的产品，建议在内部隔离网络环境中部署，强烈不建议部署在公共网络环境。 + +以下文档中提及的VIP，网卡等所有网络相关概念均处于内部网络环境。 + +# Nacos支持三种部署模式 + +* 单机模式 - 用于测试和单机试用。 +* 集群模式 - 用于生产环境，确保高可用。 +* 多集群模式 - 用于多数据中心场景。 + +# 环境准备 +- 安装好 JDK，需要 1.8 及其以上版本 +- 建议: 2核 CPU / 4G 内存 及其以上 +- 建议: 生产环境 3 个节点 及其以上 + +## 单机模式下运行Nacos + +### Linux/Unix/Mac + +```shell +# Standalone means it is non-cluster Mode. +$ sh startup.sh -m standalone +``` + +### Windows + +```shell +# Standalone means it is non-cluster Mode. +$ cmd startup.cmd -m standalone +``` + +### 单机模式支持mysql + +在0.7版本之前，在单机模式时nacos使用嵌入式数据库实现数据的存储，不方便观察数据存储的基本情况。0.7版本增加了支持mysql数据源能力，具体的操作步骤： + +- 1.安装数据库，版本要求：5.6.5+ +- 2.初始化mysql数据库，数据库初始化文件：mysql-schema.sql +- 3.修改conf/application.properties文件，增加支持mysql数据源配置（目前只支持mysql），添加mysql数据源的url、用户名和密码。 + +``` +spring.datasource.platform=mysql + +db.num=1 +db.url.0=jdbc:mysql://11.162.196.16:3306/nacos_devtest?characterEncoding=utf8&connectTimeout=1000&socketTimeout=3000&autoReconnect=true +db.user=nacos_devtest +db.password=youdontknow +``` + +再以单机模式启动nacos，nacos所有写嵌入式数据库的数据都写到了mysql + +## 集群模式下运行Nacos + +[集群模式下运行Nacos](./cluster-mode-quick-start.md) + +## 多集群模式 + +Nacos支持NameServer路由请求模式，通过它您可以设计一个有用的映射规则来控制请求转发到相应的集群，在映射规则中您可以按命名空间或租户等分片请求... + +## 多网卡IP选择 + +当本地环境比较复杂的时候，Nacos服务在启动的时候需要选择运行时使用的IP或者网卡。Nacos从多网卡获取IP参考Spring Cloud设计，通过nacos.inetutils参数，可以指定Nacos使用的网卡和IP地址。目前支持的配置参数有: + +- ip-address参数可以直接设置nacos的ip + +``` +nacos.inetutils.ip-address=10.11.105.155 +``` + +- use-only-site-local-interfaces参数可以让nacos使用局域网ip，这个在nacos部署的机器有多网卡时很有用，可以让nacos选择局域网网卡 + +``` +nacos.inetutils.use-only-site-local-interfaces=true +``` + +- ignored-interfaces支持网卡数组，可以让nacos忽略多个网卡 + +``` +nacos.inetutils.ignored-interfaces[0]=eth0 +nacos.inetutils.ignored-interfaces[1]=eth1 +``` + +- preferred-networks参数可以让nacos优先选择匹配的ip，支持正则匹配和前缀匹配 + +``` +nacos.inetutils.preferred-networks[0]=30.5.124. +nacos.inetutils.preferred-networks[0]=30.5.124.(25[0-5]|2[0-4]\\d|((1d{2})|([1-9]?\\d))),30.5.124.(25[0-5]|2[0-4]\\d|((1d{2})|([1-9]?\\d))) +``` diff --git a/src/i18n/en/ui.ts b/src/i18n/en/ui.ts index e65bd904ed6..4fbe0a577ee 100644 --- a/src/i18n/en/ui.ts +++ b/src/i18n/en/ui.ts @@ -20,7 +20,7 @@ export default { 'commmon.header.comm.leftcut': 'Key to service-centric (for example microservice or cloud-native) architectures.', 'commmon.header.comm.rightcut': 'An easy-to-use platform for building cloud native applications', 'commmon.header.comm.contact': 'CONTACT US', - 'commmon.header.contact.git': 'Github', + 'commmon.header.contact.git': 'GitHub', 'commmon.header.contact.ding': 'DingDing', 'commmon.header.contact.mail': 'E-mail', 'commmon.ebook.click.download':'Click to download', diff --git a/src/i18n/zh-cn/ui.ts b/src/i18n/zh-cn/ui.ts index c7a10ccc490..508f056ee8e 100644 --- a/src/i18n/zh-cn/ui.ts +++ b/src/i18n/zh-cn/ui.ts @@ -20,7 +20,7 @@ export default { 'commmon.header.comm.leftcut': '服务为中心（例如微服务或云原生）架构的关键。', 'commmon.header.comm.rightcut': '一个易于使用的构建云原生应用程序的平台。', 'commmon.header.comm.contact': '联系我们', - 'commmon.header.contact.git': 'Github', + 'commmon.header.contact.git': 'GitHub', 'commmon.header.contact.ding': '钉钉', 'commmon.header.contact.mail': '电子邮箱', 'commmon.ebook.click.download':'点击下载', diff --git a/template/404.startlight.tpl b/template/404.startlight.tpl index 9ab48d43bc0..70806bc3052 100644 --- a/template/404.startlight.tpl +++ b/template/404.startlight.tpl @@ -42,22 +42,47 @@ const route = generateRouteData({ props: { ...entryMeta, entryMeta, headings, entry, id: entry.id, slug: entry.slug }, url: Astro.url, }); - --- - \ No newline at end of file + // console.log('-------',redirect) + // const newUrl = params.toString() === '' ? baseUrl : `${baseUrl}?${params}`; + // window.history.replaceState({}, '', newUrl); + + diff --git a/template/index.startlight.tpl b/template/index.startlight.tpl index a7ac99a5074..bfe2c50505b 100644 --- a/template/index.startlight.tpl +++ b/template/index.startlight.tpl @@ -84,12 +84,5 @@ const { Content, headings } = await Astro.props.entry.render(); const route = generateRouteData({ props: { ...Astro.props, headings, categories: categories }, url: Astro.url }); - -const regexs = /\/docs\/(latest|ebook|next|v[0-9]\.[0-9]\.[0-9]|v[0-9]\.[0-9]|v[0-9]|[0-9]\.[0-9]\.[0-9]|[0-9]\.[0-9]|[0-9])\/.+/; - -const match = regexs.exec(Astro.url.pathname) -if(!match) { - return Astro.redirect('/docs'+ '/latest' + Astro.url.pathname.split('/docs').join('')); -} --- From 2ca792efc249eca7e2eb8a22c00768167387babc Mon Sep 17 00:00:00 2001 From: shonen <83808926@qq.com> Date: Wed, 24 Jan 2024 14:49:12 +0800 Subject: [PATCH 2/4] Develop astro nacos (#519) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * fix: 设置star+fork组件为client:load * fix: 取消starAndFork组件client:load * feat: 添加打包时候的请求仓库贡献者，并写入对应json文件的js，增加contributors组件 --- gitHubData.js | 29 ++ package.json | 2 +- src/components/contributors/gitHubData.json | 402 ++++++++++++++++++++ src/components/home/Contributors.astro | 61 +++ src/components/home/HomeIntroduce.astro | 2 +- src/components/home/StarAndFork.astro | 13 +- 6 files changed, 505 insertions(+), 4 deletions(-) create mode 100644 gitHubData.js create mode 100644 src/components/contributors/gitHubData.json create mode 100644 src/components/home/Contributors.astro diff --git a/gitHubData.js b/gitHubData.js new file mode 100644 index 00000000000..958d8ca1dc3 --- /dev/null +++ b/gitHubData.js @@ -0,0 +1,29 @@ +import fs from "fs/promises"; +import path from "path"; +import { fileURLToPath } from 'url'; + +const request = async (url, headers={}) => { + const res = await fetch(url, {headers}); + if (!res.ok) throw new Error(res.statusText); + const data = await res.json(); + if (data.error) { + throw new Error(data.error) + } else { + return data; + } +}; + +let res = await request("https://api.github.com/repos/alibaba/nacos/contributors?per_page=100") + +let contributors = res.map(v => { + return { + login: v.login, + avatar_url: v.avatar_url + } +}) + + +const curFilename = fileURLToPath(import.meta.url); +const curDirname = path.dirname(curFilename); +const runtimePath = path.join(curDirname, 'src/components/contributors/gitHubData.json'); +await fs.writeFile(runtimePath, JSON.stringify(contributors)); diff --git a/package.json b/package.json index c552448bfa1..9a2fcea2f82 100644 --- a/package.json +++ b/package.json @@ -5,7 +5,7 @@ "scripts": { "dev": "astro dev", "start": "astro dev", - "build": "node runtime.js && astro build", + "build": "node runtime.js && node gitHubData.js && astro build", "preview": "astro preview", "astro": "astro" }, diff --git a/src/components/contributors/gitHubData.json b/src/components/contributors/gitHubData.json new file mode 100644 index 00000000000..3711ce283e6 --- /dev/null +++ b/src/components/contributors/gitHubData.json @@ -0,0 +1,402 @@ +[ + { + "login": "nkorange", + "avatar_url": "https://avatars.githubusercontent.com/u/4593375?v=4" + }, + { + "login": "KomachiSion", + "avatar_url": "https://avatars.githubusercontent.com/u/37170243?v=4" + }, + { + "login": "chuntaojun", + "avatar_url": "https://avatars.githubusercontent.com/u/23445172?v=4" + }, + { + "login": "loadchange", + "avatar_url": "https://avatars.githubusercontent.com/u/10842824?v=4" + }, + { + "login": "yanlinly", + "avatar_url": "https://avatars.githubusercontent.com/u/17695352?v=4" + }, + { + "login": "xuechaos", + "avatar_url": "https://avatars.githubusercontent.com/u/3983999?v=4" + }, + { + "login": "jameslcj", + "avatar_url": "https://avatars.githubusercontent.com/u/11494059?v=4" + }, + { + "login": "li-xiao-shuang", + "avatar_url": "https://avatars.githubusercontent.com/u/34903552?v=4" + }, + { + "login": "KeRan213539", + "avatar_url": "https://avatars.githubusercontent.com/u/1195743?v=4" + }, + { + "login": "hxy1991", + "avatar_url": "https://avatars.githubusercontent.com/u/2517258?v=4" + }, + { + "login": "shiyiyue1102", + "avatar_url": "https://avatars.githubusercontent.com/u/20452676?v=4" + }, + { + "login": "brotherlu-xcq", + "avatar_url": "https://avatars.githubusercontent.com/u/25661357?v=4" + }, + { + "login": "horizonzy", + "avatar_url": "https://avatars.githubusercontent.com/u/22524871?v=4" + }, + { + "login": "Daydreamer-ia", + "avatar_url": "https://avatars.githubusercontent.com/u/83362909?v=4" + }, + { + "login": "Maijh97", + "avatar_url": "https://avatars.githubusercontent.com/u/37288946?v=4" + }, + { + "login": "onewe", + "avatar_url": "https://avatars.githubusercontent.com/u/38708836?v=4" + }, + { + "login": "hujun-w-2", + "avatar_url": "https://avatars.githubusercontent.com/u/39894911?v=4" + }, + { + "login": "MajorHe1", + "avatar_url": "https://avatars.githubusercontent.com/u/53824889?v=4" + }, + { + "login": "pbting", + "avatar_url": "https://avatars.githubusercontent.com/u/11469671?v=4" + }, + { + "login": "zhaoyuguang", + "avatar_url": "https://avatars.githubusercontent.com/u/10150229?v=4" + }, + { + "login": "zongtanghu", + "avatar_url": "https://avatars.githubusercontent.com/u/5010883?v=4" + }, + { + "login": "IanCao", + "avatar_url": "https://avatars.githubusercontent.com/u/32847163?v=4" + }, + { + "login": "mercyblitz", + "avatar_url": "https://avatars.githubusercontent.com/u/533114?v=4" + }, + { + "login": "ZZQ001010", + "avatar_url": "https://avatars.githubusercontent.com/u/33930711?v=4" + }, + { + "login": "chenhao26-nineteen", + "avatar_url": "https://avatars.githubusercontent.com/u/35129699?v=4" + }, + { + "login": "paderlol", + "avatar_url": "https://avatars.githubusercontent.com/u/7919984?v=4" + }, + { + "login": "karsonto", + "avatar_url": "https://avatars.githubusercontent.com/u/31433550?v=4" + }, + { + "login": "realJackSun", + "avatar_url": "https://avatars.githubusercontent.com/u/58767027?v=4" + }, + { + "login": "rushsky518", + "avatar_url": "https://avatars.githubusercontent.com/u/20531420?v=4" + }, + { + "login": "wfnuser", + "avatar_url": "https://avatars.githubusercontent.com/u/8191686?v=4" + }, + { + "login": "shalk", + "avatar_url": "https://avatars.githubusercontent.com/u/2435781?v=4" + }, + { + "login": "pixystone", + "avatar_url": "https://avatars.githubusercontent.com/u/3050696?v=4" + }, + { + "login": "haoyann", + "avatar_url": "https://avatars.githubusercontent.com/u/43994656?v=4" + }, + { + "login": "YunWZ", + "avatar_url": "https://avatars.githubusercontent.com/u/3894771?v=4" + }, + { + "login": "The-Gamer-01", + "avatar_url": "https://avatars.githubusercontent.com/u/58755323?v=4" + }, + { + "login": "yangyshdan", + "avatar_url": "https://avatars.githubusercontent.com/u/6780076?v=4" + }, + { + "login": "wangweizZZ", + "avatar_url": "https://avatars.githubusercontent.com/u/5856574?v=4" + }, + { + "login": "alios-studio", + "avatar_url": "https://avatars.githubusercontent.com/u/33740552?v=4" + }, + { + "login": "ZhangShenao", + "avatar_url": "https://avatars.githubusercontent.com/u/24444502?v=4" + }, + { + "login": "Oliverwqcwrw", + "avatar_url": "https://avatars.githubusercontent.com/u/31796988?v=4" + }, + { + "login": "universefeeler", + "avatar_url": "https://avatars.githubusercontent.com/u/5143424?v=4" + }, + { + "login": "stone-98", + "avatar_url": "https://avatars.githubusercontent.com/u/35629966?v=4" + }, + { + "login": "Bo-Qiu", + "avatar_url": "https://avatars.githubusercontent.com/u/46370663?v=4" + }, + { + "login": "david6969xin", + "avatar_url": "https://avatars.githubusercontent.com/u/86217945?v=4" + }, + { + "login": "jifengnan", + "avatar_url": "https://avatars.githubusercontent.com/u/29351596?v=4" + }, + { + "login": "xiaoheng1", + "avatar_url": "https://avatars.githubusercontent.com/u/12539730?v=4" + }, + { + "login": "liqipeng", + "avatar_url": "https://avatars.githubusercontent.com/u/6264774?v=4" + }, + { + "login": "godhth", + "avatar_url": "https://avatars.githubusercontent.com/u/63696328?v=4" + }, + { + "login": "985492783", + "avatar_url": "https://avatars.githubusercontent.com/u/73023513?v=4" + }, + { + "login": "Wuyunfan-BUPT", + "avatar_url": "https://avatars.githubusercontent.com/u/30968107?v=4" + }, + { + "login": "Roger3581321", + "avatar_url": "https://avatars.githubusercontent.com/u/23419065?v=4" + }, + { + "login": "ly641921791", + "avatar_url": "https://avatars.githubusercontent.com/u/36787490?v=4" + }, + { + "login": "Nicholas2015", + "avatar_url": "https://avatars.githubusercontent.com/u/15233929?v=4" + }, + { + "login": "CherishCai", + "avatar_url": "https://avatars.githubusercontent.com/u/16837364?v=4" + }, + { + "login": "mingyixu", + "avatar_url": "https://avatars.githubusercontent.com/u/31835543?v=4" + }, + { + "login": "ljhrot", + "avatar_url": "https://avatars.githubusercontent.com/u/20163361?v=4" + }, + { + "login": "TsingLiang", + "avatar_url": "https://avatars.githubusercontent.com/u/13382535?v=4" + }, + { + "login": "XCXCXCXCX", + "avatar_url": "https://avatars.githubusercontent.com/u/32658071?v=4" + }, + { + "login": "dependabot[bot]", + "avatar_url": "https://avatars.githubusercontent.com/in/29110?v=4" + }, + { + "login": "yongchao9", + "avatar_url": "https://avatars.githubusercontent.com/u/43985780?v=4" + }, + { + "login": "wuchubuzai2018", + "avatar_url": "https://avatars.githubusercontent.com/u/42382506?v=4" + }, + { + "login": "Sunrisea", + "avatar_url": "https://avatars.githubusercontent.com/u/49605583?v=4" + }, + { + "login": "wyp12", + "avatar_url": "https://avatars.githubusercontent.com/u/4252147?v=4" + }, + { + "login": "Ax-For", + "avatar_url": "https://avatars.githubusercontent.com/u/46378075?v=4" + }, + { + "login": "beldon", + "avatar_url": "https://avatars.githubusercontent.com/u/6863578?v=4" + }, + { + "login": "Albert-Hugo", + "avatar_url": "https://avatars.githubusercontent.com/u/33504588?v=4" + }, + { + "login": "drgnchan", + "avatar_url": "https://avatars.githubusercontent.com/u/40224023?v=4" + }, + { + "login": "hanxie-crypto", + "avatar_url": "https://avatars.githubusercontent.com/u/4457084?v=4" + }, + { + "login": "myifeng", + "avatar_url": "https://avatars.githubusercontent.com/u/26652657?v=4" + }, + { + "login": "zhenxianyimeng", + "avatar_url": "https://avatars.githubusercontent.com/u/15272909?v=4" + }, + { + "login": "binbin0325", + "avatar_url": "https://avatars.githubusercontent.com/u/28588342?v=4" + }, + { + "login": "jzdayz", + "avatar_url": "https://avatars.githubusercontent.com/u/35563513?v=4" + }, + { + "login": "stackisok", + "avatar_url": "https://avatars.githubusercontent.com/u/22807749?v=4" + }, + { + "login": "catcherwong", + "avatar_url": "https://avatars.githubusercontent.com/u/8394988?v=4" + }, + { + "login": "slievrly", + "avatar_url": "https://avatars.githubusercontent.com/u/8758457?v=4" + }, + { + "login": "MisterChangRay", + "avatar_url": "https://avatars.githubusercontent.com/u/16421384?v=4" + }, + { + "login": "DarrenLuo", + "avatar_url": "https://avatars.githubusercontent.com/u/6427009?v=4" + }, + { + "login": "showkawa", + "avatar_url": "https://avatars.githubusercontent.com/u/18094436?v=4" + }, + { + "login": "IJiaPu", + "avatar_url": "https://avatars.githubusercontent.com/u/110883801?v=4" + }, + { + "login": "kevinw66", + "avatar_url": "https://avatars.githubusercontent.com/u/31196226?v=4" + }, + { + "login": "corey89757", + "avatar_url": "https://avatars.githubusercontent.com/u/17606982?v=4" + }, + { + "login": "zrlw", + "avatar_url": "https://avatars.githubusercontent.com/u/40652892?v=4" + }, + { + "login": "JianweiWang", + "avatar_url": "https://avatars.githubusercontent.com/u/6915507?v=4" + }, + { + "login": "xianlaioy", + "avatar_url": "https://avatars.githubusercontent.com/u/5875104?v=4" + }, + { + "login": "lidaoyang", + "avatar_url": "https://avatars.githubusercontent.com/u/26211950?v=4" + }, + { + "login": "lzp0412", + "avatar_url": "https://avatars.githubusercontent.com/u/10192658?v=4" + }, + { + "login": "maoling", + "avatar_url": "https://avatars.githubusercontent.com/u/11016631?v=4" + }, + { + "login": "tian-qingzhao", + "avatar_url": "https://avatars.githubusercontent.com/u/57293296?v=4" + }, + { + "login": "robynron", + "avatar_url": "https://avatars.githubusercontent.com/u/38815080?v=4" + }, + { + "login": "lin-mt", + "avatar_url": "https://avatars.githubusercontent.com/u/58337359?v=4" + }, + { + "login": "E1se2t", + "avatar_url": "https://avatars.githubusercontent.com/u/67528597?v=4" + }, + { + "login": "secbr", + "avatar_url": "https://avatars.githubusercontent.com/u/7844205?v=4" + }, + { + "login": "pengzhengfa", + "avatar_url": "https://avatars.githubusercontent.com/u/33858082?v=4" + }, + { + "login": "lkxiaolou", + "avatar_url": "https://avatars.githubusercontent.com/u/6935924?v=4" + }, + { + "login": "nanamikon", + "avatar_url": "https://avatars.githubusercontent.com/u/2010632?v=4" + }, + { + "login": "anjia0532", + "avatar_url": "https://avatars.githubusercontent.com/u/15098916?v=4" + }, + { + "login": "SpecialYang", + "avatar_url": "https://avatars.githubusercontent.com/u/33012260?v=4" + }, + { + "login": "FlyingLambrog", + "avatar_url": "https://avatars.githubusercontent.com/u/70271172?v=4" + }, + { + "login": "liugddx", + "avatar_url": "https://avatars.githubusercontent.com/u/48236177?v=4" + }, + { + "login": "caojiele", + "avatar_url": "https://avatars.githubusercontent.com/u/29936718?v=4" + } +] \ No newline at end of file diff --git a/src/components/home/Contributors.astro b/src/components/home/Contributors.astro new file mode 100644 index 00000000000..d1cbc11e86c --- /dev/null +++ b/src/components/home/Contributors.astro @@ -0,0 +1,61 @@ +--- +import members from "../contributors/gitHubData.json"; +--- + + +
+ {members.length} +
+
+ { + members.map((v) => { + return ( +
+ {v.login} +
+ ); + }) + } +
+ + + + + diff --git a/src/components/home/HomeIntroduce.astro b/src/components/home/HomeIntroduce.astro index e361704496c..ad6d2a6f2d1 100644 --- a/src/components/home/HomeIntroduce.astro +++ b/src/components/home/HomeIntroduce.astro @@ -20,7 +20,7 @@ const ifzh = isChinese(Astro); > {t("home.introduce.title")} - +
diff --git a/src/components/home/StarAndFork.astro b/src/components/home/StarAndFork.astro index 3a1d8768cca..8274c2d04c8 100644 --- a/src/components/home/StarAndFork.astro +++ b/src/components/home/StarAndFork.astro @@ -10,7 +10,7 @@ const { stargazers_count: startCount = 0, forks_count: forkCount = 0 } = data || { stargazers_count: 0, forks_count: 0 }; --- -
+ -
+ + + \ No newline at end of file From c77c64a5db978575de6fdac515221df345d3d989 Mon Sep 17 00:00:00 2001 From: Hazel0928 <55099364+Hazel0928@users.noreply.github.com> Date: Wed, 24 Jan 2024 14:54:41 +0800 Subject: [PATCH 3/4] FIX 404 (#520) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat: 🎸 fix link * fix: 🐛 fix descriptioin * feat: 🎸 老路由兼容 * feat: 🎸 404 fix --- astro.config.mjs | 1 + src/components/home/HomeIntroduce.astro | 2 +- src/components/starlight/Head.astro | 2 +- src/content/docs/latest/en/open-api.md | 2807 +++++++++++++++++++++ src/content/docs/latest/zh-cn/open-api.md | 2529 +++++++++++++++++++ template/404.startlight.tpl | 36 +- 6 files changed, 5362 insertions(+), 15 deletions(-) create mode 100644 src/content/docs/latest/en/open-api.md create mode 100644 src/content/docs/latest/zh-cn/open-api.md diff --git a/astro.config.mjs b/astro.config.mjs index c0ddab1261a..50fa630f94d 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -79,5 +79,6 @@ export default defineConfig({ '/[...slug].html': '/[...slug]', '/en-us/[...slug]/': '/en/[...slug]/', '/zh-cn/[...slug]': '/[...slug]', + '/docs/': '/docs/latest/what-is-nacos/', } }); \ No newline at end of file diff --git a/src/components/home/HomeIntroduce.astro b/src/components/home/HomeIntroduce.astro index ad6d2a6f2d1..1c73352521e 100644 --- a/src/components/home/HomeIntroduce.astro +++ b/src/components/home/HomeIntroduce.astro @@ -20,7 +20,7 @@ const ifzh = isChinese(Astro); > {t("home.introduce.title")}
- +
diff --git a/src/components/starlight/Head.astro b/src/components/starlight/Head.astro index 35d07c6bee0..1cec0b9173e 100644 --- a/src/components/starlight/Head.astro +++ b/src/components/starlight/Head.astro @@ -151,7 +151,7 @@ const head = createHead(headDefaults, config.head, data.head); t.type = 'text/javascript'; t.async = true; t.src = - '//g.alicdn.com/aes/??tracker/3.3.3/index.js,tracker-plugin-pv/3.0.5/index.js,tracker-plugin-event/3.0.0/index.js,tracker-plugin-autolog/3.0.3/index.js,tracker-plugin-survey/3.0.3/index.js'; + '//g.alicdn.com/aes/??tracker/3.3.4/index.js,tracker-plugin-pv/3.0.5/index.js,tracker-plugin-event/3.0.0/index.js,tracker-plugin-autolog/3.0.3/index.js,tracker-plugin-survey/3.0.3/index.js'; t.onload = function () { if (window.location.hostname !== 'nacos.io') { return; diff --git a/src/content/docs/latest/en/open-api.md b/src/content/docs/latest/en/open-api.md new file mode 100644 index 00000000000..d4aad0963f9 --- /dev/null +++ b/src/content/docs/latest/en/open-api.md @@ -0,0 +1,2807 @@ +--- +title: Open API Guide +keywords: [Open API,Guide] +description: Open API Guide +sidebar: + order: 3 +--- + +# Open API Guide + +Nacos 2.X is compatible with Nacos 1.X OpenAPI, please refer to the document [Nacos1.X OpenAPI](https://nacos.io/en/docs/1.X/open-api). + +> Attension: OpenAPIs which do not specify a supported version, will be supported since 2.2.0. + +- Documentation Conventions + - [API unified return body format](#0.1) + - [API error code summary](#0.2) + +- Configuration Management + - [Get configuration](#1.1) + - [Publish configuration](#1.2) + - [Delete configuration](#1.3) + - [Query list of history configuration](#1.4) + - [Query the history details of the configuration](#1.5) + - [Query the previous version of the configuration](#1.6) + - [Query the list of configurations under the specified namespace](#1.7) + +- Service Discovery + - [Register instance](#2.1) + - [Deregister instance](#2.2) + - [Modify instance](#2.3) + - [Query instance detail](#2.4) + - [Query instances](#2.5) + - [Batch update instance metadata(Beta)](#2.6) + - [Batch delete instance metadata(Beta)](#2.7) + - [Create service](#2.8) + - [Delete service](#2.9) + - [Update service](#2.10) + - [Query service](#2.11) + - [Query service list](#2.12) + - [Query system switches](#2.13) + - [Update system switch](#2.14) + - [Query system metrics](#2.15) + - [Update instance health status](#2.16) + - [Query client list (new)](#2.17) + - [Query client (new)](#2.18) + - [Query the registration information of the client (new)](#2.19) + - [Query the subscription information of the client (new)](#2.20) + - [Query the client that registered the specified service (new)](#2.21) + - [Query the information of clients subscribed to the specified service (new)](#2.22) + +- Namespace + - [Query namespaces](#3.1) + - [Query namespace](#3.2) + - [Create namespace](#3.3) + - [Update namespace](#3.4) + - [Delete namespace](#3.5) + +- Cluster + - [Query the current node](#4.1) + - [Query the list of cluster nodes](#4.2) + - [Query the current node health status](#4.3) + - [Switch addressing modes](#4.4) +- Connection Load Management + - [Query the List of Current Node Client Connections](#5.1) + - [Reload the Number of Current Node Client Connections](#5.2) + - [Intelligently Balance the Number of Client Connections in the Cluster](#5.3) + - [Reset a Specific Client Connection](#5.4) + - [Get SDK Metrics for the Cluster](#5.5) + + +## Documentation Conventions + +

API unified return body format

+ +In Nacos 2.X, the response to all interface requests is a return body of type `json`, which has the same format + +```json +{ + "code": 0, + "message": "success", + "data": {} +} +``` + +The meanings of the fields in the return body are shown in the following table + +| name | type | description | +|:---------:|:--------:|------------------------------------------------------------------------------------------------------| +| `code ` | `int` | Error code，`0` means the execution succeeded, non-`0` means the execution failed in one of the cases | +| `message` | `String` | Error code prompt message, execution success as "`success`" | +| `data` | `Any` | Return data, detailed error message in case of execution failure | + +> Since the `code` field is the same as the message field in case of successful execution, only the `data` field of the returned data will be introduced in the subsequent introduction of the returned results of the interface + +

API error code summary

+ +The error codes and corresponding prompt messages in the return body of the API interface are summarized in the following table + +| Error Code | message | meaning | +|------------|------------------------------|--------------------------------------------------| +| `0` | `success` | Successful execution | +| `10000` | `parameter missing` | Missing parameters | +| `10001` | `access denied` | Access Denied | +| `10002` | `data access error` | Data access error | +| `20001` | `'tenant' parameter error` | `tenant` parameter error | +| `20002` | `parameter validate error` | Parameter validation error | +| `20003` | `MediaType Error` | `MediaType` error for HTTP requests | +| `20004` | `resource not found` | Resource not found | +| `20005` | `resource conflict` | Resource access conflicts | +| `20006` | `config listener is null` | Listening configuration is empty | +| `20007` | `config listener error` | Listening configuration error | +| `20008` | `invalid dataId` | Invalid `dataId` (authentication failure) | +| `20009` | `parameter mismatch` | Request parameter mismatch | +| `21000` | `service name error` | `serviceName` error | +| `21001` | `weight error` | `weight` error | +| `21002` | `instance metadata error` | Instance `metadata` error | +| `21003` | `instance not found` | `instance` not found | +| `21004` | `instance error` | `instance` error | +| `21005` | `service metadata error` | Service `metadata` error | +| `21006` | `selector error` | `selector` error | +| `21007` | `service already exist` | Service already exists | +| `21008` | `service not exist` | Service does not exist | +| `21009` | `service delete failure` | Service instance exists, service deletion failed | +| `21010` | `healthy param miss` | `healthy` parameter miss | +| `21011` | `health check still running` | Health check is still running | +| `22000` | `illegal namespace` | `namespace` is illegal | +| `22001` | `namespace not exist` | Namespace does not exist | +| `22002` | `namespace already exist` | Namespace already exists | +| `23000` | `illegal state` | `state` is illegal | +| `23001` | `node info error` | Node information error | +| `23002` | `node down failure` | Node offline operation error | +| ... | ... | ... | +| 30000 | `server error` | Other internal errors | + +## Configuration Management + +

Get configuration

+ +### Description + +Get the specified configuration + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/cs/config` + +### Request Parameters + +| Parameter | Type | Required | Description | +|---------------|----------|----------|--------------------------------| +| `namespaceId` | `String` | N | Namespace, default is `public` | +| `group` | `String` | **Y** | Config group name | +| `dataId` | `String` | **Y** | Config name | +| `tag` | `String` | N | Tag | + +### Return Data + +| Parameter | Type | Description | +|-----------|----------|----------------| +| `data` | `String` | Config content | + +### Example + +* Request Example + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/cs/config?dataId=nacos.example&group=DEFAULT_GROUP&namespaceId=public' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": "contentTest" + } + ``` + +

Publish configuration

+ +### Description + +Publish the specified configuration + +> Update the configuration when it already exists + +### Request Method + +`POST` + +`Content-Type:application/x-www-form-urlencoded` + +### Request URL + +`/nacos/v2/cs/config` + +### Request Body + +| Parameter | Type | Required | Description | +|---------------|----------|----------|------------------------------------------------------| +| `namespaceId` | `String` | N | Namespace, default is `public` | +| `group` | `String` | **Y** | Config group | +| `dataId` | `String` | **Y** | Config name | +| `content` | `String` | **Y** | Config content | +| `tag` | `String` | N | Tag | +| `appName` | `String` | N | Application name | +| `srcUser` | `String` | N | Source user | +| `configTags` | `String` | N | Configure Tag list, can be multiple, comma separated | +| `desc` | `String` | N | Config description | +| `use` | `String` | N | - | +| `effect` | `String` | N | - | +| `type` | `String` | N | Config type | +| `schema` | `String` | N | - | + +### Return Data + +| Parameter | Type | Description | +|-----------|-----------|-------------------------------------| +| `data` | `boolean` | Whether the execution is successful | + +### Example + +* Request Example + + ```shell + curl -d 'dataId=nacos.example' \ + -d 'group=DEFAULT_GROUP' \ + -d 'namespaceId=public' \ + -d 'content=contentTest' \ + -X POST 'http://127.0.0.1:8848/nacos/v2/cs/config' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +

Delete configuration

+ +### Description + +Delete the specified configuration + +### Request Method + +`DELETE` + +### Request URL + +`/nacos/v2/cs/config` + +### Request Parameters + +| Parameter | Type | Required | Description | +|---------------|----------|----------|--------------------------------| +| `namespaceId` | `String` | N | Namespace, default is `public` | +| `group` | `String` | **Y** | Config group name | +| `dataId` | `String` | **Y** | Config name | +| `tag` | `String` | N | Tag | + +### Return Data + +| Parameter | Type | Description | +|-----------|-----------|-------------------------------------| +| `data` | `boolean` | Whether the execution is successful | + +### Example + +* Request Example + + ```shell + curl -X DELETE 'http://127.0.0.1:8848/nacos/v2/cs/config?dataId=nacos.example&group=DEFAULT_GROUP&namespaceId=public' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +

Query list of history configuration

+ +### Description + +Get a list of historical versions of the specified configuration + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/cs/history/list` + +### Request Parameters + +| Parameter | Type | Required | Description | +|---------------|----------|----------|------------------------------------------------------------| +| `namespaceId` | `String` | N | Namespace, default is `public` | +| `group` | `String` | **Y** | Config group name | +| `dataId` | `String` | **Y** | Config name | +| `pageNo` | `int` | N | Current page, default is `1` | +| `pageSize` | `int` | N | Number of page entries, default is `100`, maximum is `500` | + +### Return Data + +| Parameter | Type | Description | +|-----------------------|------------|--------------------------------------------------------------------------------| +| `data` | `Object` | Paging Search Results | +| `data.totalCount` | `int` | Total | +| `data.pageNumber` | `int` | Current page | +| `data.pagesAvailable` | `int` | Total number of pages | +| `data.pageItems` | `Object[]` | List of historical configuration items, refer to [Historical configuration item](#ConfigHistoryInfo) | + +### Example + +* Request Example + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/cs/history/list?dataId=nacos.example&group=com.alibaba.nacos&namespaceId=' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": { + "totalCount": 1, + "pageNumber": 1, + "pagesAvailable": 1, + "pageItems": [ + { + "id": "203", + "lastId": -1, + "dataId": "nacos.example", + "group": "com.alibaba.nacos", + "tenant": "", + "appName": "", + "md5": "9f67e6977b100e00cab385a75597db58", + "content": "contentTest", + "srcIp": "0:0:0:0:0:0:0:1", + "srcUser": null, + "opType": "I", + "createdTime": "2010-05-04T16:00:00.000+0000", + "lastModifiedTime": "2020-12-05T01:48:03.380+0000" + } + ] + } + } + ``` + +

Query the history details of the configuration

+ +### Description + +Get the historical configuration of the specified version + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/cs/history` + +### Request Parameters + +| Parameter | Type | Required | Description | +|---------------|----------|----------|--------------------------------| +| `namespaceId` | `String` | N | Namespace, default is `public` | +| `group` | `String` | **Y** | Config group name | +| `dataId` | `String` | **Y** | Config name | +| `nid` | `long` | **Y** | History configuration id | + +

Return Data

+ +| Parameter | Type | Description | +|-------------------------|----------|---------------------------------| +| `data` | `Object` | Historical configuration item | +| `data.id` | `String` | Config `id` | +| `data.lastId` | `int` | | +| `data.dataId` | `String` | Config name | +| `data.group` | `String` | config group | +| `data.tenant` | `String` | Tenant (namespace) | +| `data.appName` | `String` | Application name | +| `data.md5` | `String` | The md5 value of config content | +| `data.content` | `String` | Config content | +| `data.srcIp` | `String` | Source ip | +| `data.srcUser` | `String` | Source user | +| `data.opType` | `String` | Operator type | +| `data.createdTime` | `String` | Creation time | +| `data.lastModifiedTime` | `String` | Last modified time | +| `data.encryptedDataKey` | `String` | | + +### Example + +* Request Example + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/cs/history?dataId=nacos.example&group=com.alibaba.nacos&namespaceId=&nid=203' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": { + "id": "203", + "lastId": -1, + "dataId": "nacos.example", + "group": "com.alibaba.nacos", + "tenant": "", + "appName": "", + "md5": "9f67e6977b100e00cab385a75597db58", + "content": "contentTest", + "srcIp": "0:0:0:0:0:0:0:1", + "srcUser": null, + "opType": "I", + "createdTime": "2010-05-04T16:00:00.000+0000", + "lastModifiedTime": "2020-12-05T01:48:03.380+0000" + } + } + ``` + +

Query the previous version of the configuration

+ +### Description + +Get the previous version of the specified configuration + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/cs/history/previous` + +### Request Parameters + +| Parameter | Type | Required | Description | +|---------------|----------|----------|--------------------------------| +| `namespaceId` | `String` | N | Namespace, default is `public` | +| `group` | `String` | **Y** | Config group name | +| `dataId` | `String` | **Y** | Config name | +| `id` | `long` | **Y** | config id | + +

Return Data

+ +| Parameter | Type | Description | +|-----------|----------|---------------------------------------------------------------------------------------------| +| `data` | `Object` | Historical configuration item, refer to [Historical configuration item](#ConfigHistoryInfo) | + +### Example + +* Request Example + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/cs/history/previous?id=309135486247505920&dataId=nacos.example&group=com.alibaba.nacos&namespaceId=' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": { + "id": "203", + "lastId": -1, + "dataId": "nacos.example", + "group": "com.alibaba.nacos", + "tenant": "", + "appName": "", + "md5": "9f67e6977b100e00cab385a75597db58", + "content": "contentTest", + "srcIp": "0:0:0:0:0:0:0:1", + "srcUser": null, + "opType": "I", + "createdTime": "2010-05-04T16:00:00.000+0000", + "lastModifiedTime": "2020-12-05T01:48:03.380+0000" + } + } + ``` + +

Query the list of configurations under the specified namespace

+ +### Description + +Get the list of configurations under the specified namespace + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/cs/history/configs` + +### Request Parameters + +| Parameter | Type | Required | Description | +|---------------|----------|----------|-------------| +| `namespaceId` | `String` | **Y** | Namespace | + +### Return Data + +| Parameter | Type | Description | +|-------------------------|------------|---------------------------------| +| `data` | `Object[]` | Config list | +| `data.id` | `String` | config `id` | +| `data.dataId` | `String` | Config name | +| `data.group` | `String` | Config group | +| `data.content` | `String` | Config content | +| `data.md5` | `String` | the md5 value of config content | +| `data.encryptedDataKey` | `String` | | +| `data.tenant` | `String` | Tenant (namespace) | +| `data.appName` | `String` | Application name | +| `data.type` | `String` | config file Type | +| `data.lastModified` | `long` | Last modified time | + +> Only the `dataId`, `group`, `tenant`, `appName`, `type` fields are valid for the configuration information in the returned data, the other fields are default values + +### Example + +* Request Example + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/cs/history/configs?namespaceId=' + ``` + +* Response Example + + ```json + { + "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 + } + ] + } + ``` + +## Service Discovery + +

Register instance

+ +### Description + +Register an instance + +### Request Method + +`POST` + +`Content-Type:application/x-www-form-urlencoded` + +### Request URL + +`/nacos/v2/ns/instance` + +### Request Body + +| Parameter | Type | Required | Description | +|---------------|----------------------|----------|-----------------------------------------------------------| +| `namespaceId` | `String` | N | Namespace`Id`, default is `public` | +| `groupName` | `String` | N | Group name, default is `DEFAULT_GROUP` | +| `serviceName` | `String` | **Y** | Service name | +| `ip` | `String` | **Y** | `IP` address | +| `port` | `int` | **Y** | Port number | +| `clusterName` | `String` | N | Cluster name, default is `DEFAULT` | +| `healthy` | `boolean` | N | Whether to find only healthy instances, default is `true` | +| `weight` | `double` | N | Instance weights, default is `1.0` | +| `enabled` | `boolean` | N | Enable or not, default is `true` | +| `metadata` | `JSON format String` | N | Instance metadata | +| `ephemeral` | `boolean` | N | Whether it is a temporary instance | + +### Return Data + +| Parameter | Type | Description | +|-----------|-----------|-------------------------------------| +| `data` | `boolean` | Whether the execution is successful | + +### Example + +* Request Example + + ```shell + curl -d 'serviceName=test_service' \ + -d 'ip=127.0.0.1' \ + -d 'port=8090' \ + -d 'weight=0.9' \ + -d 'ephemeral=true' \ + -X POST 'http://127.0.0.1:8848/nacos/v2/ns/instance' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +

Deregister instance

+ +### Description + +Deregister a specified instance + +### Request Method + +`DELETE` + +`Content-Type:application/x-www-form-urlencoded` + +### Request URL + +`/nacos/v2/ns/instance` + +### Request Body + +| Parameter | Type | Required | Description | +|---------------|----------------------|----------|-----------------------------------------------------------| +| `namespaceId` | `String` | N | Namespace`Id`, default is `public` | +| `groupName` | `String` | N | Group name, default is `DEFAULT_GROUP` | +| `serviceName` | `String` | **Y** | Service name | +| `ip` | `String` | **Y** | `IP` address | +| `port` | `int` | **Y** | Port number | +| `clusterName` | `String` | N | Cluster name, default is `DEFAULT` | +| `healthy` | `boolean` | N | Whether to find only healthy instances, default is `true` | +| `weight` | `double` | N | Instance weights, default is `1.0` | +| `enabled` | `boolean` | N | Enable or not, default is `true` | +| `metadata` | `JSON format String` | N | Instance metadata | +| `ephemeral` | `boolean` | N | Whether it is a temporary instance | + +### Return Data + +| Parameter | Type | Description | +|-----------|-----------|-------------------------------------| +| `data` | `boolean` | Whether the execution is successful | + +### Example + +* Request Example + + ```shell + curl -d 'serviceName=test_service' \ + -d 'ip=127.0.0.1' \ + -d 'port=8090' \ + -d 'weight=0.9' \ + -d 'ephemeral=true' \ + -X DELETE 'http://127.0.0.1:8848/nacos/v2/ns/instance' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +

Modify instance

+ +### Description + +Modify instance information + +> The metadata updated through this interface has a higher priority and has the ability to remember. After the instance removed, it will still exist for a period of time. If the instance is re-registered during this period, the metadata will still be Effective. You can modify the memory time through `nacos.naming.clean.expired-metadata.expired-time` **and** `nacos.naming.clean.expired-metadata.interval` + +### Request Method + +`PUT` + +`Content-Type:application/x-www-form-urlencoded` + +### Request URL + +`/nacos/v2/ns/instance` + +### Request Body + +| Parameter | Type | Required | Description | +|---------------|----------------------|----------|-----------------------------------------------------------| +| `namespaceId` | `String` | N | Namespace`Id`, default is `public` | +| `groupName` | `String` | N | Group name, default is `DEFAULT_GROUP` | +| `serviceName` | `String` | **Y** | Service name | +| `ip` | `String` | **Y** | `IP` address | +| `port` | `int` | **Y** | Port number | +| `clusterName` | `String` | N | Cluster name, default is `DEFAULT` | +| `healthy` | `boolean` | N | Whether to find only healthy instances, default is `true` | +| `weight` | `double` | N | Instance weights, default is `1.0` | +| `enabled` | `boolean` | N | Enable or not, default is `true` | +| `metadata` | `JSON format String` | N | Instance metadata | +| `ephemeral` | `boolean` | N | Whether it is a temporary instance | + +### Return Data + +| Parameter | Type | Description | +|-----------|-----------|-------------------------------------| +| `data` | `boolean` | Whether the execution is successful | + +### Example + +* Request Example + + ```shell + curl -d 'serviceName=test_service' \ + -d 'ip=127.0.0.1' \ + -d 'port=8090' \ + -d 'weight=0.9' \ + -d 'ephemeral=true' \ + -X PUT 'http://127.0.0.1:8848/nacos/v2/ns/instance' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +

Query instance detail

+ +### Description + +Query the details of a specific instance + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/ns/instance` + +### Request Parameters + +| Parameter | Type | Required | Description | +|---------------|----------|----------|----------------------------------------| +| `namespaceId` | `String` | N | Namespace`Id`, default is `public` | +| `groupName` | `String` | N | Group name, default is `DEFAULT_GROUP` | +| `serviceName` | `String` | **Y** | Service name | +| `clusterName` | `String` | N | Cluster name, default is `DEFAULT` | +| `ip` | `String` | **Y** | `IP` address | +| `port` | `int` | **Y** | Port number | + +### Return Data + +| Parameter | Type | Description | +|--------------------|-----------|------------------------------| +| `data` | `Object` | Instance details information | +| `data.serviceName` | `String` | Service name | +| `data.ip` | `String` | `IP` address | +| `data.port` | `int` | Port number | +| `data.clusterName` | `String` | Cluster name | +| `data.weight` | `double` | Instance weight | +| `data.healthy` | `boolean` | healthy | +| `data.instanceId` | `String` | Instance `id` | +| `data.metadata` | `map` | Instance metadata | + +### Example + +* Request Example + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/instance?namespaceId=public&groupName=&serviceName=test_service&ip=127.0.0.1&port=8080' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": { + "serviceName": "DEFAULT_GROUP@@test_service", + "ip": "127.0.0.1", + "port": 8080, + "clusterName": "DEFAULT", + "weight": 1.0, + "healthy": true, + "instanceId": null, + "metadata": { + "value": "1" + } + } + } + ``` + +

Query instances

+ +### Description + +Query the list of instances under the specified service + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/ns/instance/list` + +### Request Header + +| Parameter | Type | Required | Description | +|------------------|----------|----------|----------------------------------| +| `User-Agent` | `String` | N | User agent, default is empty | +| `Client-Version` | `String` | N | Client version, default is empty | + +### Request Parameters + +| Parameter | Type | Required | Description | +|---------------|-----------|----------|---------------------------------------------------------------------------------| +| `namespaceId` | `String` | N | Namespace`Id`, default is `public` | +| `groupName` | `String` | N | Group name, default is empty | +| `serviceName` | `String` | **Y** | Service name | +| `clusterName` | `String` | N | Cluster name, default is `DEFAULT` | +| `ip` | `String` | N | `IP` address, the default is empty, which means no restrictions on `IP` address | +| `port` | `int` | N | Port numberThe default is `0`, which means no restriction on port number | +| `healthyOnly` | `boolean` | N | Whether to get only healthy instances, default is `false` | +| `app` | `String` | N | Application name, default is empty | + +### Return Data + +| Parameter | Type | Description | +|----------------------------------------|------------|---------------------------------------------------| +| `data` | | List of instances of the specified service | +| `data.name` | `String` | Group name@@Service name | +| `data.groupName` | `String` | Group name | +| `data.clusters` | `String` | Cluster name | +| `data.cacheMillis` | `int` | Cache name | +| `data.hosts` | `Object[]` | Instance list | +| `data.hosts.ip` | `String` | Instance `IP` | +| `data.hosts.port` | `int` | Instance Port number | +| `data.hosts.weight` | `double` | Instance weight | +| `data.hosts.healthy` | `boolean` | Instance healthy | +| `data.hosts.enabled` | `boolean` | Instance is enabled | +| `data.hosts.ephemeral` | `boolean` | Whether it is a temporary instance | +| `data.hosts.clusterName` | `String` | Name of the cluster where the instance is located | +| `data.hosts.serviceName` | `String` | Service name | +| `data.hosts.metadata` | `map` | Instance metadata | +| `data.hosts.instanceHeartBeatTimeOut` | `int` | Instance heartbeat timeout time | +| `data.hosts.ipDeleteTimeout` | `int` | Instance delete timeout time | +| `data.hosts.instanceHeartBeatInterval` | `int` | Instance heartbeat interval | +| `data.lastRefTime` | `int` | last refresh time | +| `data.checksum` | `int` | checksum | +| `data.allIPs` | `boolean` | | +| `data.reachProtectionThreshold` | `boolean` | Whether the protection threshold is reached | +| `data.valid` | `boolean` | Valid | + +### Example + +* Request Example + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/instance/list?serviceName=test_service&ip=127.0.0.1' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": { + "name": "DEFAULT_GROUP@@test_service", + "groupName": "DEFAULT_GROUP", + "clusters": "", + "cacheMillis": 10000, + "hosts": [ + { + "ip": "127.0.0.1", + "port": 8080, + "weight": 1.0, + "healthy": true, + "enabled": true, + "ephemeral": true, + "clusterName": "DEFAULT", + "serviceName": "DEFAULT_GROUP@@test_service", + "metadata": { + "value": "1" + }, + "instanceHeartBeatTimeOut": 15000, + "ipDeleteTimeout": 30000, + "instanceHeartBeatInterval": 5000 + } + ], + "lastRefTime": 1662554390814, + "checksum": "", + "allIPs": false, + "reachProtectionThreshold": false, + "valid": true + } + } + ``` + +

Batch update instance metadata

+ +### Description + +Batch update instance metadata + +> If the key corresponding to the metadata does not exist, add the corresponding metadata. + +### Request Method + +`PUT` + +`Content-Type:application/x-www-form-urlencoded` + +### Request URL + +`/nacos/v2/ns/instance/metadata/batch` + +### Request Body + +| Parameter | Type | Required | Description | +|-------------------|----------------------|----------|----------------------------------------| +| `namespaceId` | `String` | N | Namespace`Id`, default is `public` | +| `groupName` | `String` | N | Group name, default is `DEFAULT_GROUP` | +| `serviceName` | `String` | **Y** | Service name | +| `consistencyType` | `String` | N | Persistence type, default is empty | +| `instances` | `JSON format String` | N | Instance list, default is empty | +| `metadata` | `JSON format String` | **Y** | Instance metadata | + +### Parameter Description + +> - `consistencyType`: Persistence type of Instance, when ``persist`'' means update the metadata of persistent Instance; otherwise means update the metadata of temporary Instance +> - `instances`: Instance list to be updated, `json` array, locate an instance by `ip+port+ephemeral+cluster`, null means update the metadata of all instances under the specified service + +### Return Data + +| Parameter | Type | Description | +|-----------|-----------|-------------------------------------| +| `data` | `boolean` | Whether the execution is successful | + +### Example + +* Request Example + + ```shell + curl -d 'serviceName=test_service' \ + -d 'consistencyType=ephemeral' \ + -d 'instances=[{"ip":"3.3.3.3","port": "8080","ephemeral":"true","clusterName":"xxxx-cluster"},{"ip":"2.2.2.2","port":"8080","ephemeral":"true","clusterName":"xxxx-cluster"}]' \ + -d 'metadata={"age":"20","name":"cocolan"}' \ + -X PUT 'http://127.0.0.1:8848/nacos/v2/ns/instance/metadata/batch' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +

Batch delete instance metadata

+ +### Description + +Batch delete instance metadata + +> If the key corresponding to the metadata does not exist, then no operation is performed + +### Request Method + +`DELETE` + +`Content-Type:application/x-www-form-urlencoded` + +### Request URL + +`/nacos/v2/ns/instance/metadata/batch` + +### Request Body + +| Parameter | Type | Required | Description | +|-------------------|----------------------|----------|----------------------------------------| +| `namespaceId` | `String` | N | Namespace`Id`, default is `public` | +| `groupName` | `String` | N | Group name, default is `DEFAULT_GROUP` | +| `serviceName` | `String` | **Y** | Service name | +| `consistencyType` | `String` | N | Persistence type, default is empty | +| `instances` | `JSON format String` | N | Instance list, default is empty | +| `metadata` | `JSON format String` | **Y** | Instance metadata | + +### Parameter Description + +> - `consistencyType`: Persistence type of Instance, when ``persist`'' means update the metadata of persistent Instance; otherwise means update the metadata of temporary Instance +> - `instances`: Instance list to be updated, `json` array, locate an instance by `ip+port+ephemeral+cluster`, null means update the metadata of all instances under the specified service + +### Return Data + +| Parameter | Type | Description | +|-----------|-----------|-------------------------------------| +| `data` | `boolean` | Whether the execution is successful | + +### Example + +* Request Example + + ```shell + curl -d 'serviceName=test_service' \ + -d 'consistencyType=ephemeral' \ + -d 'instances=[{"ip":"3.3.3.3","port": "8080","ephemeral":"true","clusterName":"xxxx-cluster"},{"ip":"2.2.2.2","port":"8080","ephemeral":"true","clusterName":"xxxx-cluster"}]' \ + -d 'metadata={"age":"20","name":"cocolan"}' \ + -X DELETE 'http://127.0.0.1:8848/nacos/v2/ns/instance/metadata/batch' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +

Create service

+ +### Description + +Create a service + +> Failed to create when service already exists + +### Request Method + +`POST` + +`Content-Type:application/x-www-form-urlencoded` + +### Request URL + +`/nacos/v2/ns/service` + +### Request Body + +| Parameter | Type | Required | Description | +|--------------------|----------------------|----------|--------------------------------------------------------| +| `namespaceId` | `String` | N | Namespace`Id`, default is `public` | +| `groupName` | `String` | N | Group name, default is `DEFAULT_GROUP` | +| `serviceName` | `String` | **Y** | Service name | +| `metadata` | `JSON format String` | N | Service metadata, default is empty | +| `ephemeral` | `boolean` | N | Whether it is a temporary instance, default is `false` | +| `protectThreshold` | `float` | N | Protection threshold, default is `0` | +| `selector` | `JSON format String` | N | Selector, default is empty | + +### Return Data + +| Parameter | Type | Description | +|-----------|-----------|-------------------------------------| +| `data` | `boolean` | Whether the execution is successful | + +### Example + +* Request Example + + ```shell + curl -d 'serviceName=nacos.test.1' \ + -d 'ephemeral=true' \ + -d 'metadata={"k1":"v1"}' \ + -X POST 'http://127.0.0.1:8848/nacos/v2/ns/service' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +

Delete service

+ +### Description + +Delete the specified service + +> An error is reported when the service does not exist, and deletion fails when an instance of the service still exists + +### Request Method + +`DELETE` + +### Request URL + +`/nacos/v2/ns/service` + +### Request Parameters + +| Parameter | Type | Required | Description | +|---------------|----------|----------|----------------------------------------| +| `namespaceId` | `String` | N | Namespace`Id`, default is `public` | +| `groupName` | `String` | N | Group name, default is `DEFAULT_GROUP` | +| `serviceName` | `String` | **Y** | Service name | + +### Return Data + +| Parameter | Type | Description | +|-----------|-----------|-------------------------------------| +| `data` | `boolean` | Whether the execution is successful | + +### Example + +* Request Example + + ```shell + curl -X DELETE 'http://127.0.0.1:8848/nacos/v2/ns/service?serviceName=nacos.test.1' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +

Update service

+ +### Description + +Update the specified service + +> Error when service does not exist + +### Request Method + +`POST` + +`Content-Type:application/x-www-form-urlencoded` + +### Request URL + +`/nacos/v2/ns/service` + +### Request Parameters + +| Parameter | Type | Required | Description | +|--------------------|----------------------|----------|----------------------------------------| +| `namespaceId` | `String` | N | Namespace`Id`, default is `public` | +| `groupName` | `String` | N | Group name, default is `DEFAULT_GROUP` | +| `serviceName` | `String` | **Y** | Service name | +| `metadata` | `JSON format String` | N | Service metadata, default is empty | +| `protectThreshold` | `float` | N | Protection threshold, default is `0` | +| `selector` | `JSON format String` | N | Selector, default is empty | + +### Return Data + +| Parameter | Type | Description | +|-----------|-----------|-------------------------------------| +| `data` | `boolean` | Whether the execution is successful | + +### Example + +* Request Example + + ```shell + curl -d 'serviceName=nacos.test.1' \ + -d 'metadata={"k1":"v2"}' \ + -X PUT 'http://127.0.0.1:8848/nacos/v2/ns/service' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +

Query service

+ +### Description + +Query detailed information about a specific service + +> Error when service does not exist + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/ns/service` + +### Request Parameters + +| Parameter | Type | Required | Description | +|---------------|----------|----------|------------------------------------| +| `namespaceId` | `String` | N | Namespace`Id`, default is `public` | +| `groupName` | `String` | N | Group name, default is empty | +| `serviceName` | `String` | **Y** | Service name | + +### Return Data + +| Parameter | Type | Description | +|-------------------------|-----------|------------------------------------| +| `data` | | Service information | +| `data.namespace` | `String` | Namespace | +| `data.groupName` | `String` | Group name | +| `data.serviceName` | `String` | Service name | +| `data.clusterMap` | `map` | Cluster information | +| `data.metadata` | `map` | Service metadata | +| `data.protectThreshold` | `float` | Protection threshold | +| `data.selector` | `Object` | Selector | +| `data.ephemeral` | `Boolean` | Whether it is a temporary instance | + +### Example + +* Request Example + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/service?serviceName=nacos.test.1' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": { + "namespace": "public", + "serviceName": "nacos.test.1", + "groupName": "DEFAULT_GROUP", + "clusterMap": {}, + "metadata": {}, + "protectThreshold": 0, + "selector": { + "type": "none", + "contextType": "NONE" + }, + "ephemeral": false + } + } + ``` + +

Query service list

+ +### Description + +Check the list of eligible services + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/ns/service/list` + +### Request Parameters + +| Parameter | Type | Required | Description | +|---------------|----------------------|----------|----------------------------------------------| +| `namespaceId` | `String` | N | Namespace`Id`, default is `public` | +| `groupName` | `String` | N | Group name, default is empty | +| `selector` | `JSON format String` | **Y** | Selector | +| `pageNo` | `int` | N | Current page, default is `1` | +| `pageSize` | `int` | N | Number of page, default is `20`, Up to `500` | + +### Return Data + +| Parameter | Type | Description | +|-----------------|------------|---------------------------| +| `data` | | Service list | +| `data.count` | `String` | Number of services | +| `data.services` | `String[]` | Service list after paging | + +### Example + +* Request Example + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/service/list' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": { + "count": 2, + "services": [ + "nacos.test.1", + "nacos.test.2" + ] + } + } + ``` + +

Query system switches

+ +### Description + +Query system switches + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/ns/operator/switches` + +### Return Data + +| Parameter | Type | Description | +|-----------|----------|---------------------------| +| `data` | `Object` | System switch information | + +### Example + +* Request Example + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/operator/switches' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": { + "masters": null, + "adWeightMap": {}, + "defaultPushCacheMillis": 10000, + "clientBeatInterval": 5000, + "defaultCacheMillis": 3000, + "distroThreshold": 0.7, + "healthCheckEnabled": true, + "autoChangeHealthCheckEnabled": true, + "distroEnabled": true, + "enableStandalone": true, + "pushEnabled": true, + "checkTimes": 3, + "httpHealthParams": { + "max": 5000, + "min": 500, + "factor": 0.85 + }, + "tcpHealthParams": { + "max": 5000, + "min": 1000, + "factor": 0.75 + }, + "mysqlHealthParams": { + "max": 3000, + "min": 2000, + "factor": 0.65 + }, + "incrementalList": [], + "serverStatusSynchronizationPeriodMillis": 2000, + "serviceStatusSynchronizationPeriodMillis": 5000, + "disableAddIP": false, + "sendBeatOnly": false, + "lightBeatEnabled": true, + "doubleWriteEnabled": false, + "limitedUrlMap": {}, + "distroServerExpiredMillis": 10000, + "pushGoVersion": "0.1.0", + "pushJavaVersion": "0.1.0", + "pushPythonVersion": "0.4.3", + "pushCVersion": "1.0.12", + "pushCSharpVersion": "0.9.0", + "enableAuthentication": false, + "overriddenServerStatus": null, + "defaultInstanceEphemeral": true, + "healthCheckWhiteList": [], + "name": "00-00---000-NACOS_SWITCH_DOMAIN-000---00-00", + "checksum": null + } + } + ``` + +

Update system switch

+ +### Description + +Update system switch + +### Request Method + +`PUT` + +`Content-Type:application/x-www-form-urlencoded` + +### Request URL + +`/nacos/v2/ns/operator/switches` + +### Request Body + +| Parameter | Type | Required | Description | +|-----------|-----------|----------|--------------------------------------------------------------------------------------------------------------------------------------| +| `entry` | `String` | **Y** | Entry | +| `value` | `String` | **Y** | Value | +| `debug` | `boolean` | N | Whether it takes effect on local machine only,`true` means it takes effect on local machine,`false` means it takes effect on cluster | + +### Return Data + +| Parameter | Type | Description | +|-----------|----------|-------------------------------------| +| `data` | `String` | "ok" indicates successful execution | + +### Example + +* Request Example + + ```shell + curl -d 'entry=pushEnabled' \ + -d 'value=false' \ + -d 'debug=true' \ + -X PUT 'http://127.0.0.1:8848/nacos/v2/ns/operator/switches' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": "ok" + } + ``` + +

Query system metrics

+ +### Description + +Query system metrics + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/ns/operator/metrics` + +### Request Parameters + +| Parameter | Type | Required | Description | +|--------------|-----------|----------|-------------------------------------| +| `onlyStatus` | `boolean` | N | Show status only, default is `true` | + +> When `onlyStatus` is set to `true`, only the string indicating the system status is returned + +### Return Data + +| Parameter | Type | Description | +|------------------------------------|----------|----------------------------------| +| `data` | `Object` | System metrics | +| `data.status` | `String` | System status | +| `data.serviceCount` | `int` | Number of services | +| `data.instanceCount` | `int` | Number of instances | +| `data.subscribeCount` | `int` | Number of subscriptions | +| `data.raftNotifyTaskCount` | `int` | Number of `Raft` notify task | +| `data.responsibleServiceCount` | `int` | | +| `data.responsibleInstanceCount` | `int` | | +| `data.clientCount` | `int` | Number of client | +| `data.connectionBasedClientCount` | `int` | Number of connectionBasedClient | +| `data.ephemeralIpPortClientCount` | `int` | Number of ephemeralIpPortClient | +| `data.persistentIpPortClientCount` | `int` | Number of persistentIpPortClient | +| `data.responsibleClientCount` | `int` | | +| `data.cpu` | `float` | `cpu` utilization | +| `data.load` | `float` | load | +| `data.mem` | `float` | Memory usage | + +### Example + +* Request Example + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/operator/metrics' + ``` + +* Response Example + + ```json + { + "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 + } + } + ``` + +

Update instance health status

+ +### Description + +Update the health status of the instance + +### Request Method + +`PUT` + +`Content-Type:application/x-www-form-urlencoded` + +### Request URL + +`/nacos/v2/ns/health/instance` + +### Request Body + +| Parameter | Type | Required | Description | +|---------------|-----------|----------|----------------------------------------| +| `namespaceId` | `String` | N | Namespace`Id`, default is `public` | +| `groupName` | `String` | N | Group name, default is `DEFAULT_GROUP` | +| `serviceName` | `String` | **Y** | Service name | +| `clusterName` | `String` | N | Cluster name, default is `DEFAULT` | +| `ip` | `String` | **Y** | `IP` address | +| `port` | `int` | **Y** | Port number | +| `healthy` | `boolean` | **Y** | healthy | + +### Return Data + +| Parameter | Type | Description | +|-----------|----------|---------------------------------------| +| `data` | `String` | "`ok`" indicates successful execution | + +### Example + +* Request Example + + ```shell + curl -d 'serviceName=nacos.test.1' \ + -d 'ip=127.0.0.1' \ + -d 'port=8080' \ + -d 'healthy=false' \ + -X PUT 'http://127.0.0.1:8848/nacos/v2/ns/health/instance' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": "ok" + } + ``` + +

Query client list (new)

+ +### Description + +Query the current list of all clients + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/ns/client/list` + +### Return Data + +| Parameter | Type | Description | +|-----------|------------|------------------| +| `data` | `String[]` | Client `id` list | + +### Example + +* Request Example + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/client/list' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": [ + "10.128.164.35:9956#true", + "1664358687402_127.0.0.1_2300", + "1664358642902_127.0.0.1_2229", + "192.168.139.1:49825#true", + "10.128.164.35:9954#true", + "192.168.139.1:53556#true" + ] + } + ``` + +> For different versions of the nacos client, there are different ways to create clients. +> +> For `nacos client` in `1.x` version, each Instance will create two clients based on `ip+port`, corresponding to Instance registration and service subscription, respectively, with `clientId` in the format `ip:port#ephemeral` +> +> For `nacos client` in `2.x` version, each Instance establishes a `RPC` connection, which corresponds to an `RPC` connection-based client with both registration and subscription functions, with `clientId` in the format `time_ip_port` + + +

Query client (new)

+ +### Description + +Query the details of the specified client + +> Error when client does not exist + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/ns/client` + +### Request Parameters + +| Parameter | Type| Required | Description | +|------------|----------|----------|------------| +| `clientId` | `String` | **Y** | Client `id` | + +### Return Data + +| Parameter | Type | Description | +|------------------------|-----------|------------------------------------| +| `data` | `Object` | Client Information | +| `data.clientId` | `String` | Client `id` | +| `data.ephemeral` | `boolean` | Whether it is a temporary instance | +| `data.lastUpdatedTime` | `int` | Last update time | +| `data.clientType` | `String` | Client type | +| `data.clientIp` | `String` | Client `IP` | +| `data.clientPort` | `String` | Client `port` | +| `data.connectType` | `String` | Connection type | +| `data.appName` | `String` | Application name | +| `data.Version` | `String` | Client version | + +> Only when `clientType` is `connection`, the `connectType`, `appName` and `appName` fields will be displayed + +### Example + +* Request Example + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/client?clientId=1664527081276_127.0.0.1_4400' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": { + "clientId": "1664527081276_127.0.0.1_4400", + "ephemeral": true, + "lastUpdatedTime": 1664527081642, + "clientType": "connection", + "connectType": "GRPC", + "appName": "-", + "version": "Nacos-Java-Client:v2.1.0", + "clientIp": "10.128.164.35", + "clientPort": "4400" + } + } + ``` + +

Query the registration information of the client (new)

+ +### Description + +Query the registration information of the specified client + +> Error when client does not exist + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/ns/client/publish/list` + +### Request Parameters + +| Parameter | Type | Required | Description | +|------------|----------|----------|-------------| +| `clientId` | `String` | **Y** | Client `id` | + +### Return Data + +| Parameter | Type | Description | +|-----------------------------------|------------|-------------------------------------------| +| `data` | `Object[]` | List of services registered by the client | +| `data.namespace` | `String` | Namespace | +| `data.group` | `String` | Group name | +| `data.serviceName` | `String` | Service name | +| `data.registeredInstance` | `Object` | Instances registered under this service | +| `data.registeredInstance.ip` | `String` | `IP` address | +| `data.registeredInstance.port` | `int` | Port number | +| `data.registeredInstance.cluster` | `String` | Cluster name | + +### Example + +* Request Example + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/client/publish/list?clientId=1664527081276_127.0.0.1_4400' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": [ + { + "namespace": "public", + "group": "DEFAULT_GROUP", + "serviceName": "nacos.test.1", + "registeredInstance": { + "ip": "10.128.164.35", + "port": 9950, + "cluster": "DEFAULT" + } + } + ] + } + ``` + +

Query the subscription information of the client (new)

+ +### Description + +Query the subscription information of the specified client + +> Error when client does not exist + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/ns/client/subscribe/list` + +### Request Parameters + +| Parameter | Type | Required | Description | +|------------|----------|----------|-------------| +| `clientId` | `String` | **Y** | Client `id` | + +### Return Data + +| Parameter | Type | Description | +|-----------------------------|------------|----------------------------------------------------| +| `data` | `Object[]` | List of services to which the client is subscribed | +| `data.namespace` | `String` | Namespace | +| `data.group` | `String` | Group name | +| `data.serviceName` | `String` | Service name | +| `data.subscriberInfo` | `Object` | Subscription Information | +| `data.subscriberInfo.app` | `String` | Application | +| `data.subscriberInfo.agent` | `String` | Client Information | +| `data.subscriberInfo.addr` | `String` | Address | + +### Example + +* Request Example + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/client/subscribe/list?clientId=1664527081276_127.0.0.1_4400' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": [ + { + "namespace": "public", + "group": "DEFAULT_GROUP", + "serviceName": "nacos.test.1", + "subscriberInfo": { + "app": "unknown", + "agent": "Nacos-Java-Client:v2.1.0", + "addr": "10.128.164.35" + } + } + ] + } + ``` + +

Query the client that registered the specified service (new)

+ +### Description + +Query the client information of the registered specified service + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/ns/client/service/publisher/list` + +### Request Parameters + +| Parameter | Type | Required | Description | +|---------------|-----------|----------|---------------------------------------------------------------------| +| `namespaceId` | `String` | N | Namespace`Id`, default is `public` | +| `groupName` | `String` | N | Group name, default is `DEFAULT_GROUP` | +| `serviceName` | `String` | **Y** | Service name | +| `ephemeral` | `boolean` | N | Whether it is a temporary instance | +| `ip` | `String` | N | `IP` address, default is empty, indicates unrestricted `IP` address | +| `port` | `int` | N | Port number, default is empty, Indicates unrestricted `Port` number | + +### Return Data + +| Parameter | Type | Description | +|-----------------|----------|---------------| +| `data` | | Client list | +| `data.clientId` | `String` | Client `id` | +| `data.ip` | `String` | Client `IP` | +| `data.port` | `int` | Client `port` | + +### Example + +* Request Example + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/client/service/publisher/list?serviceName=nacos.test.1&ip=&port=' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": [ + { + "clientId": "1664527081276_127.0.0.1_4400", + "ip": "10.128.164.35", + "port": 9950 + }, + { + "clientId": "10.128.164.35:9954#true", + "ip": "10.128.164.35", + "port": 9954 + } + ] + } + ``` + +

Query the information of clients subscribed to the specified service (new)

+ +### Description + +Query the clients subscribed to the specified service + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/ns/client/service/subscriber/list` + +### Request Parameters + +| Parameter | Type | Required | Description | +|---------------|---------|----------|---------------------------------------------------------------------| +| `namespaceId` | String | N | Namespace`Id`, default is `public` | +| `groupName` | String | N | Group name, default is `DEFAULT_GROUP` | +| `serviceName` | String | **Y** | Service name | +| `ephemeral` | boolean | N | Whether it is a temporary instance | +| `ip` | String | N | `IP` address, default is empty, indicates unrestricted `IP` address | +| `port` | int | N | Port number, default is empty, Indicates unrestricted `Port` number | + +### Return Data + +| Parameter | Type | Description | +|-----------------|----------|---------------| +| `data` | | Client list | +| `data.clientId` | `String` | Client `id` | +| `data.ip` | `String` | Client `IP` | +| `data.port` | `int` | Client `port` | + +### Example + +* Request Example + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/client/service/subscriber/list?serviceName=nacos.test.1&ip=&port=' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": [ + { + "clientId": "1664527125645_127.0.0.1_4443", + "ip": "10.128.164.35", + "port": 0 + }, + { + "clientId": "172.24.144.1:54126#true", + "ip": "172.24.144.1", + "port": 54126 + } + ] + } + ``` + +## Namespace + +

Query namespaces

+ +### Description + +Query all namespaces + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/console/namespace/list` + +### Return Data + +| Parameter | Type | Description | +|--------------------------|------------|-----------------------------------| +| `data` | `Object[]` | Namespaces | +| `data.namespace` | `String` | Namespace`ID` | +| `data.namespaceShowName` | `String` | Namespace name | +| `data.namespaceDesc` | `String` | Namespace description | +| `data.quota` | `int` | the capacity of Namespace | +| `data.configCount` | `int` | Number of configs under namespace | +| `data.type` | `int` | Namespace type | + +> There are 3 types of Namespace, `0 ` - Global Namespace `1 ` - Default Private Namespace `2 ` - Custom Namespace + +### Example + +* Request Example + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/console/namespace/list' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": [ + { + "namespace": "", + "namespaceShowName": "public", + "namespaceDesc": null, + "quota": 200, + "configCount": 1, + "type": 0 + } + ] + } + ``` + +

Query namespace

+ +### Description + +Query information about a specific Namespace + +> Error when namespace does not exist + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/console/namespace` + +### Request Parameters + +| Parameter | Type | Required | Description | +|---------------|----------|----------|---------------| +| `namespaceId` | `String` | **Y** | Namespace`Id` | + +### Return Data + +| Parameter | Type | Description | +|--------------------------|----------|-----------------------------------| +| `data` | `Object` | Namespace | +| `data.namespace` | `String` | Namespace `ID` | +| `data.namespaceShowName` | `String` | Namespace name | +| `data.namespaceDesc` | `String` | Namespace description | +| `data.quota` | `int` | the capacity of Namespace | +| `data.configCount` | `int` | Number of configs under namespace | +| `data.type` | `int` | Namespace type | + +> There are 3 types of Namespace, `0 ` - Global Namespace `1 ` - Default Private Namespace `2 ` - Custom Namespace + +### Example + +* Request Example + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/console/namespace?namespaceId=test_namespace' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": { + "namespace": "test_namespace", + "namespaceShowName": "test", + "namespaceDesc": null, + "quota": 200, + "configCount": 0, + "type": 2 + } + } + ``` + +

Create namespace

+ +### Description + +Create a namespace + +> Error when namespace already exists + +### Request Method + +`POST` + +`Content-Type:application/x-www-form-urlencoded` + +### Request URL + +`/nacos/v2/console/namespace` + +### Request Body + +| Parameter | Type | Required | Description | +|-----------------|----------|----------|-----------------------| +| `namespaceId` | `String` | **Y** | Namespace`Id` | +| `namespaceName` | `String` | **Y** | Namespace name | +| `namespaceDesc` | `String` | N | Namespace Description | + +### Return Data + +| Parameter | Type | Description | +|-----------|-----------|-------------------------------------| +| `data` | `boolean` | Whether the execution is successful | + +### Example + +* Request Example + + ```shell + curl -d 'namespaceId=test_namespace' \ + -d 'namespaceName=test' \ + -X POST 'http://127.0.0.1:8848/nacos/v2/console/namespace' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +

Update namespace

+ +### Description + +Edit namespace + +### Request Method + +`PUT` + +`Content-Type:application/x-www-form-urlencoded` + +### Request URL + +`/nacos/v2/console/namespace` + +### Request Body + +| Parameter | Type | Required | Description | +|-----------------|----------|----------|-----------------------| +| `namespaceId` | `String` | **Y** | Namespace`Id` | +| `namespaceName` | `String` | **Y** | Namespace name | +| `namespaceDesc` | `String` | N | Namespace Description | + +### Return Data + +| Parameter | Type | Description | +|-----------|-----------|-------------------------------------| +| `data` | `boolean` | Whether the execution is successful | + +### Example + +* Request Example + + ```shell + curl -d 'namespaceId=test_namespace' \ + -d 'namespaceName=test.nacos' \ + -X PUT 'http://127.0.0.1:8848/nacos/v2/console/namespace' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +

Delete namespace

+ +### Description + +Delete the specified namespace + +### Request Method + +`DELETE` + +### Request URL + +`/nacos/v2/console/namespace` + +### Request Parameters + +| Parameter | Type | Required | Description | +|---------------|----------|----------|---------------| +| `namespaceId` | `String` | **Y** | Namespace`Id` | + +### Return Data + +| Parameter | Type | Description | +|-----------|-----------|-------------------------------------| +| `data` | `boolean` | Whether the execution is successful | + +### Example + +* Request Example + + ```shell + curl -d 'namespaceId=test_namespace' \ + -X DELETE 'http://127.0.0.1:8848/nacos/v2/console/namespace' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +## Cluster + +

Query the current node

+ +### Description + +Query the current `nacos` node + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/core/cluster/node/self` + +

Return Data

+ +| Parameter | Type | Description | +|----------------------|----------|--------------------------| +| `data` | `Object` | Current node | +| `data.ip` | `String` | Node `IP` address | +| `data.port` | `int` | Node port | +| `data.state` | `String` | Node status | +| `data.extendInfo` | `Object` | Node extend information | +| `data.address` | `String` | Node address （`IP:port`） | +| `data.failAccessCnt` | `int` | Number of failed access | +| `data.abilities` | `Object` | | + +### Example + +* Request Example + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/core/cluster/node/self' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": { + "ip": "10.128.164.35", + "port": 8848, + "state": "UP", + "extendInfo": { + "lastRefreshTime": 1664521263623, + "raftMetaData": { + "metaDataMap": { + "naming_instance_metadata": { + "leader": "10.128.164.35:7848", + "raftGroupMember": [ + "10.128.164.35:7848" + ], + "term": 12 + }, + "naming_persistent_service_v2": { + "leader": "10.128.164.35:7848", + "raftGroupMember": [ + "10.128.164.35:7848" + ], + "term": 12 + }, + "naming_service_metadata": { + "leader": "10.128.164.35:7848", + "raftGroupMember": [ + "10.128.164.35:7848" + ], + "term": 12 + } + } + }, + "raftPort": "7848", + "readyToUpgrade": true, + "version": "2.1.0" + }, + "address": "10.128.164.35:8848", + "failAccessCnt": 0, + "abilities": { + "remoteAbility": { + "supportRemoteConnection": true + }, + "configAbility": { + "supportRemoteMetrics": false + }, + "namingAbility": { + "supportJraft": true + } + } + } + } + ``` + +

Query the list of cluster nodes

+ +### Description + +Query the information of all nodes in the cluster + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/core/cluster/node/list` + +### Request Parameters + +| Parameter | Type | Required | Description | +|-----------|----------|----------|--------------------------------| +| `address` | `String` | N | Node address, default is empty | +| `state` | `String` | N | Node status, default is empty | + +> `address`corresponds to the prefix match condition of the Node address to be queried, and is not restricted when it is empty +> +> `state`corresponds to the filter condition of node status and is not restricted when it is empty + +### Return Data + +| Parameter | Type | Description | +|-----------|------------|------------------------------------------| +| `data` | `Object[]` | Node list, refer to [Node info](#Member) | + +### Example + +* Request Example + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/core/cluster/node/list' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": [ + { + "ip": "10.128.164.35", + "port": 8848, + "state": "UP", + "extendInfo": { + "lastRefreshTime": 1664521263623, + "raftMetaData": { + "metaDataMap": { + "naming_instance_metadata": { + "leader": "10.128.164.35:7848", + "raftGroupMember": [ + "10.128.164.35:7848" + ], + "term": 12 + }, + "naming_persistent_service_v2": { + "leader": "10.128.164.35:7848", + "raftGroupMember": [ + "10.128.164.35:7848" + ], + "term": 12 + }, + "naming_service_metadata": { + "leader": "10.128.164.35:7848", + "raftGroupMember": [ + "10.128.164.35:7848" + ], + "term": 12 + } + } + }, + "raftPort": "7848", + "readyToUpgrade": true, + "version": "2.1.0" + }, + "address": "10.128.164.35:8848", + "failAccessCnt": 0, + "abilities": { + "remoteAbility": { + "supportRemoteConnection": true + }, + "configAbility": { + "supportRemoteMetrics": false + }, + "namingAbility": { + "supportJraft": true + } + } + } + ] + } + ``` + +

Query the current node health status

+ +### Description + +Query the current `nacos` node health status + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/core/cluster/node/self/health` + +

Return Data

+ +| Parameter | Type | Description | +|-----------|----------|----------------------------| +| `data` | `String` | Current node health status | + +> Node has five states: `STARTING`, `UP`, `SUSPICIOUS`, `DOWN` and `ISOLATION`. + +### Example + +* Request Example + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/core/cluster/node/self/health' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": "UP" + } + ``` + + +

Switch addressing modes

+ +### Description + +Switch addressing modes + +### Request Method + +`PUT` + +`Content-Type:application/x-www-form-urlencoded` + +### Request URL + +`/nacos/v2/core/cluster/lookup` + +### Request Body + +| Parameter | Type | Required | Description | +|-----------|----------|----------|-----------------| +| `type` | `String` | **Y** | Addressing mode | + +> There are two addressing modes: `file` (file configuration) and `address-server` (address server) + +### Return Data + +| Parameter | Type | Description | +|-----------|-----------|-------------------------------------| +| `data` | `boolean` | Whether the execution is successful | + +### Example + +* Request Example + + ```shell + curl -d 'type=file' \ + -X PUT 'http://127.0.0.1:8848/nacos/v2/core/cluster/lookup' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +## Connection Load Management + +###

Query the List of Current Node Client Connections

+ +#### Description + +Query the list of client connections on the current `Nacos` node. + +#### Request Method + +`GET` + +#### Request URL + +`/nacos/v2/core/loader/current` + +#### Return Data + +| Parameter | Type | Description | +|----------------|-----------|----------------------| +| `traced` | `Boolean` | Monitoring indicator | +| `abilityTable` | `Map` | Capability table | +| `metaInfo` | `Object` | Metadata | +| `connected` | `Integer` | Connection status | +| `labels` | `Map` | Labels | + +#### Example + +* Request Example + +```shell +curl -X GET 'http://localhost:8848/nacos/v2/core/loader/current' +``` + +* Response Example + +```json +{ + "1697424543845_127.0.0.1_11547": { + "traced": false, + "abilityTable": null, + "metaInfo": { + "connectType": "GRPC", + "clientIp": "192.168.49.1", + "localPort": 9848, + "version": "Nacos-Java-Client:v2.1.0", + "connectionId": "1697424543845_127.0.0.1_11547", + "createTime": "2023-10-16T10:49:03.907+08:00", + "lastActiveTime": 1697424869827, + "appName": "unknown", + "tenant": "", + "labels": { + "source": "sdk", + "taskId": "0", + "module": "config", + "AppName": "unknown" + }, + "tag": null, + "sdkSource": true, + "clusterSource": false + }, + "connected": true, + "labels": { + "source": "sdk", + "taskId": "0", + "module": "config", + "AppName": "unknown" + } + } +} + +``` + +

Reload the Number of Current Node Client Connections

+ +### Description + +Reload the number of client connections on the current `Nacos` node. + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/core/loader/current/reloadCurrent` + +### Request Parameters + +| Parameter | Type | Required | Description | +|-------------------|-----------|----------|-------------------| +| `count` | `Integer` | **Y** | ID of connections | +| `redirectAddress` | `String` | N | Redirect address | + +### Return Data + +| Parameter | Type | Description | +|-----------|----------|------------------| +| `data` | `String` | Execution result | + +### Example + +* Request Example + + ```shell + curl -X GET 'http://localhost:8848/nacos/v2/core/loader/reloadCurrent?count=1&redirectAddress=127.0.0.1:8848' + ``` + +* Response Example + + ```text + success + ``` + +

Intelligently Balance the Number of Client Connections in the Cluster

+ +### Description + +Intelligently balance the client connections among all nodes in the `Nacos` cluster. + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/core/loader/current/smartReloadCluster` + +### Request Parameters + +| Parameter | Type | Required | Description | +|----------------|----------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `loaderFactor` | `Float` | N | The loading factor, with a default value of 0.1, determines the number of SDKs per node, calculated as (1 - loaderFactor) * avg ~ (1 + loaderFactor) * avg. | +| `force` | `String` | N | Force flag | + +### Return Data + +| Parameter | Type | Description | +|-----------|----------|------------------| +| `data` | `String` | Execution result | + +### Example + +* Request Example + + ```shell + curl -X GET 'http://localhost:8848/nacos/v2/core/loader/smartReloadCluster?loaderFactor=1' + ``` + +* Response Example + + ```text + Ok + ``` + +

Reset a Specific Client Connection

+ +### Description + +Send a connection reset request based on the `SDK` connection ID. + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/core/loader/current/reloadClient` + +### Request Body + +| Parameter | Type | Required | Description | +|-------------------|----------|----------|---------------| +| `connectionId` | `String` | **Y** | Connection ID | +| `redirectAddress` | `String` | N | Reset address | + +### Return Data + +| Parameter | Type | Description | +|-----------|----------|------------------| +| `data` | `String` | Execution result | + +### Example + +* Request Example + + ```shell + curl -X GET 'http://localhost:8848/nacos/v2/core/loader/reloadClient?connectionId=1&redirectAddress=127.0.0.1:8848' + ``` + +* Response Example + + ```text + success + ``` + +

Get SDK Metrics for the Cluster

+ +### Description + +Get SDK metrics for all nodes in the `Nacos` cluster. + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/core/loader/current/cluster` + +### Return Data + +| Parameter | Type | Description | +|------------------|-----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `total` | `Integer` | Current number of cluster nodes | +| `min` | `Integer` | Minimum load value | +| `avg` | `Integer` | Average load value | +| `max` | `Integer` | Maximum load value | +| `memberCount` | `Integer` | Number of members in the current node | +| `metricsCount` | `Integer` | Number of load information | +| `threshold` | `Float` | Load threshold. The threshold is calculated as: Average load value * 1.1 | +| `detail` | `String` | Contains detailed load information for each node | +| `detail.address` | `Map` | Node address | +| `detail.metric` | `Map` | Metric information | +| `completed` | `Boolean` | Indicates whether the collection of load information has been completed. If true, it means that load information for all nodes has been collected, otherwise, it is false | + +### Example + +* Request Example + + ```shell + curl -X GET 'http://localhost:8848/nacos/v2/core/loader/cluster' + ``` + +* Response Example + + ```json + { + "1697424543845_127.0.0.1_11547": { + "traced": false, + "abilityTable": null, + "metaInfo": { + "connectType": "GRPC", + "clientIp": "192.168.49.1", + "localPort": 9848, + "version": "Nacos-Java-Client:v2.1.0", + "connectionId": "1697424543845_127.0.0.1_11547", + "createTime": "2023-10-16T10:49:03.907+08:00", + "lastActiveTime": 1697424869827, + "appName": "unknown", + "tenant": "", + "labels": { + "source": "sdk", + "taskId": "0", + "module": "config", + "AppName": "unknown" + }, + "tag": null, + "sdkSource": true, + "clusterSource": false + }, + "connected": true, + "labels": { + "source": "sdk", + "taskId": "0", + "module": "config", + "AppName": "unknown" + } + } + } + ``` \ No newline at end of file diff --git a/src/content/docs/latest/zh-cn/open-api.md b/src/content/docs/latest/zh-cn/open-api.md new file mode 100644 index 00000000000..a683e39264d --- /dev/null +++ b/src/content/docs/latest/zh-cn/open-api.md @@ -0,0 +1,2529 @@ +--- +title: Open API 指南 +keywords: [Open API,指南] +description: Open API 指南 +sidebar: + order: 3 +--- + +# Open API 指南 + +Nacos 2.X 版本兼容 Nacos1.X 版本的OpenAPI, 请参考文档[Nacos1.X OpenAPI](https://nacos.io/zh-cn/docs/1.X/open-api)使用。 + +> 注意：未特殊注明支持版本的OpenAPI均从2.2.0版本开始支持。 + +- 文档约定 + - [API 统一返回体格式](#0.1) + - [API 错误码汇总](#0.2) + +- 配置管理 + - [获取配置](#1.1) + - [发布配置](#1.2) + - [删除配置](#1.3) + - [查询配置历史版本列表](#1.4) + - [查询具体版本的历史配置](#1.5) + - [查询配置上一版本信息](#1.6) + - [查询指定命名空间下的配置列表](#1.7) +- 服务发现 + - [注册实例](#2.1) + - [注销实例](#2.2) + - [更新实例](#2.3) + - [查询实例详情](#2.4) + - [查询指定服务下的实例列表](#2.5) + - [批量更新实例元数据(Beta)](#2.6) + - [批量删除实例元数据(Beta)](#2.7) + - [创建服务](#2.8) + - [删除服务](#2.9) + - [修改服务](#2.10) + - [查询服务详情](#2.11) + - [查询服务列表](#2.12) + - [查询系统开关](#2.13) + - [修改系统开关](#2.14) + - [查看系统当前数据指标](#2.15) + - [更新实例的健康状态](#2.16) + - [查询客户端列表（新）](#2.17) + - [查询客户端信息（新）](#2.18) + - [查询客户端的注册信息（新）](#2.19) + - [查询客户端的订阅信息（新）](#2.20) + - [查询注册指定服务的客户端信息（新）](#2.21) + - [查询订阅指定服务的客户端信息（新）](#2.22) +- 命名空间 + - [查询命名空间列表](#3.1) + - [查询具体命名空间](#3.2) + - [新增命名空间](#3.3) + - [编辑命名空间](#3.4) + - [删除命名空间](#3.5) +- 集群管理 + - [查询当前节点信息](#4.1) + - [查询集群节点列表](#4.2) + - [查询当前节点健康状态](#4.3) + - [切换寻址模式](#4.4) + +## 文档规定 + +

API 统一返回体格式

+ +2.0版本Open API，所有接口请求的响应均为`json`类型的返回体，返回体具有相同的格式 + +```json +{ + "code": 0, + "message": "success", + "data": {} +} +``` + +返回体中各字段的含义如下表所示 + +| 名称 | 类型 | 描述 | +|:---------:|:--------:|--------------------------------------------------------| +| `code ` | `int` | 错误码，`0`代表执行成功，非`0`代表执行失败的某一种情况 | +| `message` | `String` | 错误码提示信息，执行成功为"`success`" | +| `data` | 任意类型 | 返回数据，执行失败时为详细出错信息 | + +> 由于执行成功的情况下code字段与message字段相同，后续在介绍接口的返回结果时，只介绍返回数据的data字段 + +

API 错误码汇总

+ +API接口返回体中的错误码及对应提示信息汇总见下表 + +| 错误码 | 提示信息 | 含义 | +|---------|------------------------------|----------------------------| +| `0` | `success` | 成功执行 | +| `10000` | `parameter missing` | 参数缺失 | +| `10001` | `access denied` | 访问拒绝 | +| `10002` | `data access error` | 数据访问错误 | +| `20001` | `'tenant' parameter error` | `tenant`参数错误 | +| `20002` | `parameter validate error` | 参数验证错误 | +| `20003` | `MediaType Error` | 请求的`MediaType`错误 | +| `20004` | `resource not found` | 资源未找到 | +| `20005` | `resource conflict` | 资源访问冲突 | +| `20006` | `config listener is null` | 监听配置为空 | +| `20007` | `config listener error` | 监听配置错误 | +| `20008` | `invalid dataId` | 无效的`dataId`（鉴权失败） | +| `20009` | `parameter mismatch` | 请求参数不匹配 | +| `21000` | `service name error` | `serviceName`服务名错误 | +| `21001` | `weight error` | `weight`权重参数错误 | +| `21002` | `instance metadata error` | 实例`metadata`元数据错误 | +| `21003` | `instance not found` | `instance`实例不存在 | +| `21004` | `instance error` | `instance`实例信息错误 | +| `21005` | `service metadata error` | 服务`metadata`元数据错误 | +| `21006` | `selector error` | 访问策略`selector`错误 | +| `21007` | `service already exist` | 服务已存在 | +| `21008` | `service not exist` | 服务不存在 | +| `21009` | `service delete failure` | 存在服务实例，服务删除失败 | +| `21010` | `healthy param miss` | `healthy`参数缺失 | +| `21011` | `health check still running` | 健康检查仍在运行 | +| `22000` | `illegal namespace` | 命名空间`namespace`不合法 | +| `22001` | `namespace not exist` | 命名空间不存在 | +| `22002` | `namespace already exist` | 命名空间已存在 | +| `23000` | `illegal state` | 状态`state`不合法 | +| `23001` | `node info error` | 节点信息错误 | +| `23002` | `node down failure` | 节点离线操作出错 | +| ... | ... | ... | +| 30000 | `server error` | 其他内部错误 | + +## 配置管理 + +

获取配置

+ +### 接口描述 + +获取指定配置 + +### 请求方式 + +`GET` + +### 请求URL + +`/nacos/v2/cs/config` + +### 请求参数 + +| 参数名 | 类型 | 必填 | 参数描述 | +|---------------|----------|--------|--------------------------| +| `namespaceId` | `String` | 否 | 命名空间，默认为`public`与 `''`相同 | +| `group` | `String` | **是** | 配置分组名 | +| `dataId` | `String` | **是** | 配置名 | +| `tag` | `String` | 否 | 标签 | + +### 返回数据 + +| 参数名 | 参数类型 | 描述 | +|--------|----------|----------| +| `data` | `String` | 配置内容 | + +### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/cs/config?dataId=nacos.example&group=DEFAULT_GROUP&namespaceId=public' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": "contentTest" + } + ``` + +

发布配置

+ +### 接口描述 + +发布指定配置 + +> 当配置已存在时，则对配置进行更新 + +### 请求方式 + +`POST` + +`Content-Type:application/x-www-form-urlencoded` + +### 请求URL + +`/nacos/v2/cs/config` + +### 请求Body + +| 参数名 | 类型 | 必填 | 参数描述 | +|---------------|----------|--------|--------------------------------| +| `namespaceId` | `String` | 否 | 命名空间，默认为`public`与 `''`相同 | +| `group` | `String` | **是** | 配置组名 | +| `dataId` | `String` | **是** | 配置名 | +| `content` | `String` | **是** | 配置内容 | +| `tag` | `String` | 否 | 标签 | +| `appName` | `String` | 否 | 应用名 | +| `srcUser` | `String` | 否 | 源用户 | +| `configTags` | `String` | 否 | 配置标签列表，可多个，逗号分隔 | +| `desc` | `String` | 否 | 配置描述 | +| `use` | `String` | 否 | - | +| `effect` | `String` | 否 | - | +| `type` | `String` | 否 | 配置类型 | +| `schema` | `String` | 否 | - | + +### 返回数据 + +| 参数名 | 参数类型 | 描述 | +|--------|-----------|--------------| +| `data` | `boolean` | 是否执行成功 | + +### 示例 + +* 请求示例 + + ```shell + curl -d 'dataId=nacos.example' \ + -d 'group=DEFAULT_GROUP' \ + -d 'namespaceId=public' \ + -d 'content=contentTest' \ + -X POST 'http://127.0.0.1:8848/nacos/v2/cs/config' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +

删除配置

+ +### 接口描述 + +删除指定配置 + +### 请求方式 + +`DELETE` + +### 请求URL + +`/nacos/v2/cs/config` + +### 请求参数 + +| 参数名 | 类型 | 必填 | 参数描述 | +|---------------|----------|--------|--------------------------| +| `namespaceId` | `String` | 否 | 命名空间，默认为`public`与 `''`相同 | +| `group` | `String` | **是** | 配置分组名 | +| `dataId` | `String` | **是** | 配置名 | +| `tag` | `String` | 否 | 标签 | + +### 返回数据 + +| 参数名 | 参数类型 | 描述 | +|--------|-----------|--------------| +| `data` | `boolean` | 是否执行成功 | + +### 示例 + +* 请求示例 + + ```shell + curl -X DELETE 'http://127.0.0.1:8848/nacos/v2/cs/config?dataId=nacos.example&group=DEFAULT_GROUP&namespaceId=public' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +

查询配置历史列表

+ +### 接口描述 + +获取指定配置的历史版本列表 + +### 请求方式 + +`GET` + +### 请求URL + +`/nacos/v2/cs/history/list` + +### 请求参数 + +| 参数名 | 类型 | 必填 | 参数描述 | +|---------------|----------|--------|------------------------------------| +| `namespaceId` | `String` | 否 | 命名空间，默认为`public`与 `''`相同 | +| `group` | `String` | **是** | 配置分组名 | +| `dataId` | `String` | **是** | 配置名 | +| `pageNo` | `int` | 否 | 当前页，默认为`1` | +| `pageSize` | `int` | 否 | 页条目数，默认为`100`，最大为`500` | + +### 返回数据 + +| 参数名 | 参数类型 | 描述说明 | +|-----------------------|------------|----------------------------------------------------------| +| `data` | `Object` | 分页查询结果 | +| `data.totalCount` | `int` | 总数 | +| `data.pageNumber` | `int` | 当前页 | +| `data.pagesAvailable` | `int` | 总页数 | +| `data.pageItems` | `Object[]` | 历史配置项列表，参见[历史配置项信息](#ConfigHistoryInfo) | + +### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/cs/history/list?dataId=nacos.example&group=com.alibaba.nacos&namespaceId=' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": { + "totalCount": 1, + "pageNumber": 1, + "pagesAvailable": 1, + "pageItems": [ + { + "id": "203", + "lastId": -1, + "dataId": "nacos.example", + "group": "com.alibaba.nacos", + "tenant": "", + "appName": "", + "md5": "9f67e6977b100e00cab385a75597db58", + "content": "contentTest", + "srcIp": "0:0:0:0:0:0:0:1", + "srcUser": null, + "opType": "I", + "createdTime": "2010-05-04T16:00:00.000+0000", + "lastModifiedTime": "2020-12-05T01:48:03.380+0000" + } + ] + } + } + ``` + +

查询具体版本的历史配置

+ +### 接口描述 + +获取指定版本的历史配置 + +### 请求方式 + +`GET` + +### 请求URL + +`/nacos/v2/cs/history` + +### 请求参数 + +| 参数名 | 类型 | 必填 | 参数描述 | +|---------------|----------|--------|------------------------| +| `namespaceId` | `String` | 否 | 命名空间，默认为`public`与 `''`相同 | +| `group` | `String` | **是** | 配置分组名 | +| `dataId` | `String` | **是** | 配置名 | +| `nid` | `long` | **是** | 历史配置id | + +

返回数据

+ +| 参数名 | 参数类型 | 描述说明 | +|-------------------------|----------|------------| +| `data` | `Object` | 历史配置项 | +| `data.id` | `String` | 配置`id` | +| `data.lastId` | `int` | | +| `data.dataId` | `String` | 配置名 | +| `data.group` | `String` | 配置分组 | +| `data.tenant` | `String` | 租户信息（命名空间） | +| `data.appName` | `String` | 应用名 | +| `data.md5` | `String` | 配置内容的md5值 | +| `data.content` | `String` | 配置内容 | +| `data.srcIp` | `String` | 源ip | +| `data.srcUser` | `String` | 源用户 | +| `data.opType` | `String` | 操作类型 | +| `data.createdTime` | `String` | 创建时间 | +| `data.lastModifiedTime` | `String` | 上次修改时间 | +| `data.encryptedDataKey` | `String` | | + +### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/cs/history?dataId=nacos.example&group=com.alibaba.nacos&namespaceId=&nid=203' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": { + "id": "203", + "lastId": -1, + "dataId": "nacos.example", + "group": "com.alibaba.nacos", + "tenant": "", + "appName": "", + "md5": "9f67e6977b100e00cab385a75597db58", + "content": "contentTest", + "srcIp": "0:0:0:0:0:0:0:1", + "srcUser": null, + "opType": "I", + "createdTime": "2010-05-04T16:00:00.000+0000", + "lastModifiedTime": "2020-12-05T01:48:03.380+0000" + } + } + ``` + +

查询配置上一版本信息

+ +### 接口描述 + +获取指定配置的上一版本 + +### 请求方式 + +`GET` + +### 请求URL + +`/nacos/v2/cs/history/previous` + +### 请求参数 + +| 参数名 | 类型 | 必填 | 参数描述 | +|---------------|----------|--------|------------------------| +| `namespaceId` | `String` | 否 | 命名空间，默认为`public`与 `''`相同 | +| `group` | `String` | **是** | 配置分组名 | +| `dataId` | `String` | **是** | 配置名 | +| `id` | `long` | **是** | 配置id | + +

返回数据

+ +| 参数名 | 参数类型 | 描述说明 | +|--------|----------|------------------------------------------------------| +| `data` | `Object` | 历史配置项，参见[历史配置项信息](#ConfigHistoryInfo) | + +### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/cs/history/previous?id=309135486247505920&dataId=nacos.example&group=com.alibaba.nacos&namespaceId=' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": { + "id": "203", + "lastId": -1, + "dataId": "nacos.example", + "group": "com.alibaba.nacos", + "tenant": "", + "appName": "", + "md5": "9f67e6977b100e00cab385a75597db58", + "content": "contentTest", + "srcIp": "0:0:0:0:0:0:0:1", + "srcUser": null, + "opType": "I", + "createdTime": "2010-05-04T16:00:00.000+0000", + "lastModifiedTime": "2020-12-05T01:48:03.380+0000" + } + } + ``` + +

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

+ +### 接口描述 + +获取指定命名空间下的配置信息列表 + +### 请求方式 + +`GET` + +### 请求URL + +`/nacos/v2/cs/history/configs` + +### 请求参数 + +| 参数名 | 类型 | 必填 | 参数描述 | +|---------------|----------|--------|----------| +| `namespaceId` | `String` | **是** | 命名空间 | + +### 返回数据 + +| 参数名 | 参数类型 | 描述说明 | +|-------------------------|------------|----------------------| +| `data` | `Object[]` | 配置信息列表 | +| `data.id` | `String` | 配置`id` | +| `data.dataId` | `String` | 配置名 | +| `data.group` | `String` | 配置分组 | +| `data.content` | `String` | 配置内容 | +| `data.md5` | `String` | 配置内容的md5值 | +| `data.encryptedDataKey` | `String` | | +| `data.tenant` | `String` | 租户信息（命名空间） | +| `data.appName` | `String` | 应用名 | +| `data.type` | `String` | 配置文件类型 | +| `data.lastModified` | `long` | 上次修改时间 | + +> 返回数据中的配置信息只有`dataId`, `group`, `tenant`, `appName`, `type`字段有效，其他字段为默认值 + +### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/cs/history/configs?namespaceId=' + ``` + +* 返回示例 + + ```json + { + "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 + } + ] + } + ``` + +## 服务发现 + +

注册实例

+ +### 接口描述 + +注册一个实例 + +### 请求方式 + +`POST` + +`Content-Type:application/x-www-form-urlencoded` + +### 请求URL + +`/nacos/v2/ns/instance` + +### 请求Body + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|---------------|------------------|----------|----------------------------------| +| `namespaceId` | `String` | 否 | 命名空间`Id`，默认为`public` | +| `groupName` | `String` | 否 | 分组名，默认为`DEFAULT_GROUP` | +| `serviceName` | `String` | **是** | 服务名 | +| `ip` | `String` | **是** | `IP`地址 | +| `port` | `int` | **是** | 端口号 | +| `clusterName` | `String` | 否 | 集群名称，默认为`DEFAULT` | +| `healthy` | `boolean` | 否 | 是否只查找健康实例，默认为`true` | +| `weight` | `double` | 否 | 实例权重，默认为`1.0` | +| `enabled` | `boolean` | 否 | 是否可用，默认为`true` | +| `metadata` | `JSON格式String` | 否 | 实例元数据 | +| `ephemeral` | `boolean` | 否 | 是否为临时实例 | + +### 返回数据 + +| 参数名 | 参数类型 | 描述 | +|--------|-----------|--------------| +| `data` | `boolean` | 是否执行成功 | + +### 示例 + +* 请求示例 + + ```shell + curl -d 'serviceName=test_service' \ + -d 'ip=127.0.0.1' \ + -d 'port=8090' \ + -d 'weight=0.9' \ + -d 'ephemeral=true' \ + -X POST 'http://127.0.0.1:8848/nacos/v2/ns/instance' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +

注销实例

+ +### 接口描述 + +注销指定实例 + +### 请求方式 + +`DELETE` + +`Content-Type:application/x-www-form-urlencoded` + +### 请求URL + +`/nacos/v2/ns/instance` + +### 请求Body + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|---------------|------------------|----------|----------------------------------| +| `namespaceId` | `String` | 否 | 命名空间`Id`，默认为`public` | +| `groupName` | `String` | 否 | 分组名，默认为`DEFAULT_GROUP` | +| `serviceName` | `String` | **是** | 服务名 | +| `ip` | `String` | **是** | `IP`地址 | +| `port` | `int` | **是** | 端口号 | +| `clusterName` | `String` | 否 | 集群名称，默认为`DEFAULT` | +| `healthy` | `boolean` | 否 | 是否只查找健康实例，默认为`true` | +| `weight` | `double` | 否 | 实例权重，默认为`1.0` | +| `enabled` | `boolean` | 否 | 是否可用，默认为`true` | +| `metadata` | `JSON格式String` | 否 | 实例元数据 | +| `ephemeral` | `boolean` | 否 | 是否为临时实例 | + +### 返回数据 + +| 参数名 | 参数类型 | 描述 | +|--------|-----------|--------------| +| `data` | `boolean` | 是否执行成功 | + +### 示例 + +* 请求示例 + + ```shell + curl -d 'serviceName=test_service' \ + -d 'ip=127.0.0.1' \ + -d 'port=8090' \ + -d 'weight=0.9' \ + -d 'ephemeral=true' \ + -X DELETE 'http://127.0.0.1:8848/nacos/v2/ns/instance' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +

更新实例

+ +### 接口描述 + +修改实例信息 + +> 通过该接口更新的元数据拥有更高的优先级，且具有记忆能力；会在对应实例删除后，依旧存在一段时间，如果在此期间实例重新注册，该元数据依旧生效；您可以通过`nacos.naming.clean.expired-metadata.expired-time`及`nacos.naming.clean.expired-metadata.interval`对记忆时间进行修改 + +### 请求方式 + +`PUT` + +`Content-Type:application/x-www-form-urlencoded` + +### 请求URL + +`/nacos/v2/ns/instance` + +### 请求Body + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|---------------|------------------|----------|----------------------------------| +| `namespaceId` | `String` | 否 | 命名空间`Id`，默认为`public` | +| `groupName` | `String` | 否 | 分组名，默认为`DEFAULT_GROUP` | +| `serviceName` | `String` | **是** | 服务名 | +| `ip` | `String` | **是** | `IP`地址 | +| `port` | `int` | **是** | 端口号 | +| `clusterName` | `String` | 否 | 集群名称，默认为`DEFAULT` | +| `healthy` | `boolean` | 否 | 是否只查找健康实例，默认为`true` | +| `weight` | `double` | 否 | 实例权重，默认为`1.0` | +| `enabled` | `boolean` | 否 | 是否可用，默认为`true` | +| `metadata` | `JSON格式String` | 否 | 实例元数据 | +| `ephemeral` | `boolean` | 否 | 是否为临时实例 | + +### 返回数据 + +| 参数名 | 参数类型 | 描述 | +|--------|-----------|--------------| +| `data` | `boolean` | 是否执行成功 | + +### 示例 + +* 请求示例 + + ```shell + curl -d 'serviceName=test_service' \ + -d 'ip=127.0.0.1' \ + -d 'port=8090' \ + -d 'weight=0.9' \ + -d 'ephemeral=true' \ + -X PUT 'http://127.0.0.1:8848/nacos/v2/ns/instance' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +

查询实例详情

+ +### 接口描述 + +查询某个具体实例的详情信息 + +### 请求方式 + +`GET` + +### 请求URL + +`/nacos/v2/ns/instance` + +### 请求参数 + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|---------------|----------|----------|-------------------------------| +| `namespaceId` | `String` | 否 | 命名空间`Id`，默认为`public` | +| `groupName` | `String` | 否 | 分组名，默认为`DEFAULT_GROUP` | +| `serviceName` | `String` | **是** | 服务名 | +| `clusterName` | `String` | 否 | 集群名称，默认为`DEFAULT` | +| `ip` | `String` | **是** | `IP`地址 | +| `port` | `int` | **是** | 端口号 | + +### 返回数据 + +| 参数名 | 参数类型 | 描述说明 | +|--------------------|-----------|--------------| +| `data` | `Object` | 实例详情信息 | +| `data.serviceName` | `String` | 服务名 | +| `data.ip` | `String` | `IP`地址 | +| `data.port` | `int` | 端口号 | +| `data.clusterName` | `String` | 集群名称 | +| `data.weight` | `double` | 实例权重 | +| `data.healthy` | `boolean` | 是否健康 | +| `data.instanceId` | `String` | 实例`id` | +| `data.metadata` | `map` | 实例元数据 | + +### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/instance?namespaceId=public&groupName=&serviceName=test_service&ip=127.0.0.1&port=8080' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": { + "serviceName": "DEFAULT_GROUP@@test_service", + "ip": "127.0.0.1", + "port": 8080, + "clusterName": "DEFAULT", + "weight": 1.0, + "healthy": true, + "instanceId": null, + "metadata": { + "value": "1" + } + } + } + ``` + +

查询指定服务的实例列表

+ +### 接口描述 + +查询指定服务下的实例详情信息列表 + +### 请求方式 + +`GET` + +### 请求URL + +`/nacos/v2/ns/instance/list` + +### 请求头 + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|------------------|----------|----------|----------------------| +| `User-Agent` | `String` | 否 | 用户代理，默认为空 | +| `Client-Version` | `String` | 否 | 客户端版本，默认为空 | + +### 请求参数 + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|---------------|-----------|----------|----------------------------------------| +| `namespaceId` | `String` | 否 | 命名空间`Id`，默认为`public` | +| `groupName` | `String` | 否 | 分组名，默认为`DEFAULT_GROUP` | +| `serviceName` | `String` | **是** | 服务名 | +| `clusterName` | `String` | 否 | 集群名称，默认为`DEFAULT` | +| `ip` | `String` | 否 | `IP`地址，默认为空，表示不限制`IP`地址 | +| `port` | `int` | 否 | 端口号，默认为`0`，表示不限制端口号 | +| `healthyOnly` | `boolean` | 否 | 是否只获取健康实例，默认为`false` | +| `app` | `String` | 否 | 应用名，默认为空 | + +### 返回数据 + +| 参数名 | 参数类型 | 描述说明 | +|----------------------------------------|------------|-----------| +| `data` | | 指定服务的实例列表 | +| `data.name` | `String` | 分组名@@服务名 | +| `data.groupName` | `String` | 分组名 | +| `data.clusters` | `String` | 集群名 | +| `data.cacheMillis` | `int` | 缓存时间 | +| `data.hosts` | `Object[]` | 实例列表 | +| `data.hosts.ip` | `String` | 实例`IP` | +| `data.hosts.port` | `int` | 实例端口号 | +| `data.hosts.weight` | `double` | 实例权重 | +| `data.hosts.healthy` | `boolean` | 实例是否健康 | +| `data.hosts.enabled` | `boolean` | 实例是否可用 | +| `data.hosts.ephemeral` | `boolean` | 是否为临时实例 | +| `data.hosts.clusterName` | `String` | 实例所在的集群名称 | +| `data.hosts.serviceName` | `String` | 服务名 | +| `data.hosts.metadata` | `map` | 实例元数据 | +| `data.hosts.instanceHeartBeatTimeOut` | `int` | 实例心跳超时时间 | +| `data.hosts.ipDeleteTimeout` | `int` | 实例删除超时时间 | +| `data.hosts.instanceHeartBeatInterval` | `int` | 实例心跳间隔 | +| `data.lastRefTime` | `int` | 上次刷新时间 | +| `data.checksum` | `int` | 校验码 | +| `data.allIPs` | `boolean` | | +| `data.reachProtectionThreshold` | `boolean` | 是否到达保护阈值 | +| `data.valid` | `boolean` | 是否有效 | + +### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/instance/list?serviceName=test_service&ip=127.0.0.1' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": { + "name": "DEFAULT_GROUP@@test_service", + "groupName": "DEFAULT_GROUP", + "clusters": "", + "cacheMillis": 10000, + "hosts": [ + { + "ip": "127.0.0.1", + "port": 8080, + "weight": 1.0, + "healthy": true, + "enabled": true, + "ephemeral": true, + "clusterName": "DEFAULT", + "serviceName": "DEFAULT_GROUP@@test_service", + "metadata": { + "value": "1" + }, + "instanceHeartBeatTimeOut": 15000, + "ipDeleteTimeout": 30000, + "instanceHeartBeatInterval": 5000 + } + ], + "lastRefTime": 1662554390814, + "checksum": "", + "allIPs": false, + "reachProtectionThreshold": false, + "valid": true + } + } + ``` + +

批量更新实例元数据

+ +### 接口描述 + +批量更新实例的元数据, + +> 对应元数据的键不存在时，则添加对应元数据 + +### 请求方式 + +`PUT` + +`Content-Type:application/x-www-form-urlencoded` + +### 请求URL + +`/nacos/v2/ns/instance/metadata/batch` + +### 请求Body + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|-------------------|------------------|----------|-------------------------------| +| `namespaceId` | `String` | 否 | 命名空间`Id`，默认为`public` | +| `groupName` | `String` | 否 | 分组名，默认为`DEFAULT_GROUP` | +| `serviceName` | `String` | **是** | 服务名 | +| `consistencyType` | `String` | 否 | 持久化类型，默认为空 | +| `instances` | `JSON格式String` | 否 | 需要更新的实例列表，默认为空 | +| `metadata` | `JSON格式String` | **是** | 实例元数据 | + +### 参数说明 + +> - `consistencyType`: 实例的持久化类型，当为‘`persist`’，表示对持久化实例的元数据进行更新；否则表示对临时实例的元数据进行更新 +> - `instances`: 待更新的实例列表，`json`数组，通过`ip+port+ephemeral+cluster`定位到某一实例，为空则表示更新指定服务下所有实例的元数据 + +### 返回数据 + +| 参数名 | 参数类型 | 描述 | +|--------|-----------|--------------| +| `data` | `boolean` | 是否执行成功 | + +### 示例 + +* 请求示例 + + ```shell + curl -d 'serviceName=test_service' \ + -d 'consistencyType=ephemeral' \ + -d 'instances=[{"ip":"3.3.3.3","port": "8080","ephemeral":"true","clusterName":"xxxx-cluster"},{"ip":"2.2.2.2","port":"8080","ephemeral":"true","clusterName":"xxxx-cluster"}]' \ + -d 'metadata={"age":"20","name":"cocolan"}' \ + -X PUT 'http://127.0.0.1:8848/nacos/v2/ns/instance/metadata/batch' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +

批量删除实例元数据

+ +### 接口描述 + +批量删除实例的元数据, + +> 对应元数据的键不存在时，则不做操作 + +### 请求方式 + +`DELETE` + +`Content-Type:application/x-www-form-urlencoded` + +### 请求URL + +`/nacos/v2/ns/instance/metadata/batch` + +### 请求Body + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|-------------------|------------------|----------|-------------------------------| +| `namespaceId` | `String` | 否 | 命名空间`Id`，默认为`public` | +| `groupName` | `String` | 否 | 分组名，默认为`DEFAULT_GROUP` | +| `serviceName` | `String` | **是** | 服务名 | +| `consistencyType` | `String` | 否 | 持久化类型，默认为空 | +| `instances` | `JSON格式String` | 否 | 需要更新的实例列表，默认为空 | +| `metadata` | `JSON格式String` | **是** | 实例元数据 | + +### 参数说明 + +> - `consistencyType`: 实例的持久化类型，当为‘`persist`’，表示对持久化实例的元数据进行删除；否则表示对临时实例的元数据进行 +> - `instances`: 待更新的实例列表，`json`数组，通过`ip+port+ephemeral+cluster`定位到某一实例，为空则表示更新指定服务下所有实例的元数据 + +### 返回数据 + +| 参数名 | 参数类型 | 描述 | +|--------|-----------|--------------| +| `data` | `boolean` | 是否执行成功 | + +### 示例 + +* 请求示例 + + ```shell + curl -d 'serviceName=test_service' \ + -d 'consistencyType=ephemeral' \ + -d 'instances=[{"ip":"3.3.3.3","port": "8080","ephemeral":"true","clusterName":"xxxx-cluster"},{"ip":"2.2.2.2","port":"8080","ephemeral":"true","clusterName":"xxxx-cluster"}]' \ + -d 'metadata={"age":"20","name":"cocolan"}' \ + -X DELETE 'http://127.0.0.1:8848/nacos/v2/ns/instance/metadata/batch' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +

创建服务

+ +### 接口描述 + +创建一个服务 + +> 服务已存在时会创建失败 + +### 请求方式 + +`POST` + +`Content-Type:application/x-www-form-urlencoded` + +### 请求URL + +`/nacos/v2/ns/service` + +### 请求Body + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|--------------------|------------------|----------|-------------------------------| +| `namespaceId` | `String` | 否 | 命名空间`Id`，默认为`public` | +| `groupName` | `String` | 否 | 分组名，默认为`DEFAULT_GROUP` | +| `serviceName` | `String` | **是** | 服务名 | +| `metadata` | `JSON格式String` | 否 | 服务元数据，默认为空 | +| `ephemeral` | `boolean` | 否 | 是否为临时实例，默认为`false` | +| `protectThreshold` | `float` | 否 | 保护阈值，默认为`0` | +| `selector` | `JSON格式String` | 否 | 访问策略，默认为空 | + +### 返回数据 + +| 参数名 | 参数类型 | 描述 | +|--------|-----------|--------------| +| `data` | `boolean` | 是否执行成功 | + +### 示例 + +* 请求示例 + + ```shell + curl -d 'serviceName=nacos.test.1' \ + -d 'ephemeral=true' \ + -d 'metadata={"k1":"v1"}' \ + -X POST 'http://127.0.0.1:8848/nacos/v2/ns/service' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +

删除服务

+ +### 接口描述 + +删除指定服务 + +> 服务不存在时会报错，且服务还存在实例时会删除失败 + +### 请求方式 + +`DELETE` + +### 请求URL + +`/nacos/v2/ns/service` + +### 请求参数 + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|---------------|----------|----------|-------------------------------| +| `namespaceId` | `String` | 否 | 命名空间`Id`，默认为`public` | +| `groupName` | `String` | 否 | 分组名，默认为`DEFAULT_GROUP` | +| `serviceName` | `String` | **是** | 服务名 | + +### 返回数据 + +| 参数名 | 参数类型 | 描述 | +|--------|-----------|--------------| +| `data` | `boolean` | 是否执行成功 | + +### 示例 + +* 请求示例 + + ```shell + curl -X DELETE 'http://127.0.0.1:8848/nacos/v2/ns/service?serviceName=nacos.test.1' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +

修改服务

+ +### 接口描述 + +更新指定服务 + +> 服务不存在时会报错 + +### 请求方式 + +`POST` + +`Content-Type:application/x-www-form-urlencoded` + +### 请求URL + +`/nacos/v2/ns/service` + +### 请求参数 + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|--------------------|------------------|----------|-------------------------------| +| `namespaceId` | `String` | 否 | 命名空间`Id`，默认为`public` | +| `groupName` | `String` | 否 | 分组名，默认为`DEFAULT_GROUP` | +| `serviceName` | `String` | **是** | 服务名 | +| `metadata` | `JSON格式String` | 否 | 服务元数据，默认为空 | +| `protectThreshold` | `float` | 否 | 保护阈值，默认为`0` | +| `selector` | `JSON格式String` | 否 | 访问策略，默认为空 | + +### 返回数据 + +| 参数名 | 参数类型 | 描述 | +|--------|-----------|--------------| +| `data` | `boolean` | 是否执行成功 | + +### 示例 + +* 请求示例 + + ```shell + curl -d 'serviceName=nacos.test.1' \ + -d 'metadata={"k1":"v2"}' \ + -X PUT 'http://127.0.0.1:8848/nacos/v2/ns/service' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +

查询服务详情

+ +### 接口描述 + +查询某个具体服务的详情信息 + +> 服务不存在时会报错 + +### 请求方式 + +`GET` + +### 请求URL + +`/nacos/v2/ns/service` + +### 请求参数 + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|---------------|----------|----------|---------------------------------| +| `namespaceId` | `String` | 否 | 命名空间`Id`，默认为`public` | +| `groupName` | `String` | 否 | 分组名，默认为`DEFAULT_GROUP` | +| `serviceName` | `String` | **是** | 服务名 | + +### 返回数据 + +| 参数名 | 参数类型 | 描述说明 | +|-------------------------|-----------|----------------| +| `data` | | 服务信息 | +| `data.namespace` | `String` | 命名空间 | +| `data.groupName` | `String` | 分组名 | +| `data.serviceName` | `String` | 服务名 | +| `data.clusterMap` | `map` | 集群信息 | +| `data.metadata` | `map` | 服务元数据 | +| `data.protectThreshold` | `float` | 保护阈值 | +| `data.selector` | `Object` | 访问策略 | +| `data.ephemeral` | `Boolean` | 是否为临时实例 | + +### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/service?serviceName=nacos.test.1' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": { + "namespace": "public", + "serviceName": "nacos.test.1", + "groupName": "DEFAULT_GROUP", + "clusterMap": {}, + "metadata": {}, + "protectThreshold": 0, + "selector": { + "type": "none", + "contextType": "NONE" + }, + "ephemeral": false + } + } + ``` + +

查询服务列表

+ +### 接口描述 + +查询符合条件的服务列表 + +### 请求方式 + +`GET` + +### 请求URL + +`/nacos/v2/ns/service/list` + +### 请求参数 + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|---------------|------------------|----------|-----------------------------------| +| `namespaceId` | `String` | 否 | 命名空间`Id`，默认为`public` | +| `groupName` | `String` | 否 | 分组名，默认为`DEFAULT_GROUP` | +| `selector` | `JSON格式String` | **是** | 访问策略 | +| `pageNo` | `int` | 否 | 当前页，默认为`1` | +| `pageSize` | `int` | 否 | 页条目数，默认为`20`，最大为`500` | + +### 返回数据 + +| 参数名 | 参数类型 | 描述说明 | +|-----------------|------------|------------------| +| `data` | | 服务列表信息 | +| `data.count` | `String` | 服务数目 | +| `data.services` | `String[]` | 分页后的服务列表 | + +### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/service/list' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": { + "count": 2, + "services": [ + "nacos.test.1", + "nacos.test.2" + ] + } + } + ``` + +

查询系统开关

+ +### 接口描述 + +查询系统开关 + +### 请求方式 + +`GET` + +### 请求URL + +`/nacos/v2/ns/operator/switches` + +### 返回数据 + +| 参数名 | 参数类型 | 描述说明 | +|--------|----------|--------------| +| `data` | `Object` | 系统开关信息 | + +### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/operator/switches' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": { + "masters": null, + "adWeightMap": {}, + "defaultPushCacheMillis": 10000, + "clientBeatInterval": 5000, + "defaultCacheMillis": 3000, + "distroThreshold": 0.7, + "healthCheckEnabled": true, + "autoChangeHealthCheckEnabled": true, + "distroEnabled": true, + "enableStandalone": true, + "pushEnabled": true, + "checkTimes": 3, + "httpHealthParams": { + "max": 5000, + "min": 500, + "factor": 0.85 + }, + "tcpHealthParams": { + "max": 5000, + "min": 1000, + "factor": 0.75 + }, + "mysqlHealthParams": { + "max": 3000, + "min": 2000, + "factor": 0.65 + }, + "incrementalList": [], + "serverStatusSynchronizationPeriodMillis": 2000, + "serviceStatusSynchronizationPeriodMillis": 5000, + "disableAddIP": false, + "sendBeatOnly": false, + "lightBeatEnabled": true, + "doubleWriteEnabled": false, + "limitedUrlMap": {}, + "distroServerExpiredMillis": 10000, + "pushGoVersion": "0.1.0", + "pushJavaVersion": "0.1.0", + "pushPythonVersion": "0.4.3", + "pushCVersion": "1.0.12", + "pushCSharpVersion": "0.9.0", + "enableAuthentication": false, + "overriddenServerStatus": null, + "defaultInstanceEphemeral": true, + "healthCheckWhiteList": [], + "name": "00-00---000-NACOS_SWITCH_DOMAIN-000---00-00", + "checksum": null + } + } + ``` + +

修改系统开关

+ +### 接口描述 + +修改系统开关 + +### 请求方式 + +`PUT` + +`Content-Type:application/x-www-form-urlencoded` + +### 请求URL + +`/nacos/v2/ns/operator/switches` + +### 请求Body + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|---------|-----------|-------|---------------------------------------------------------| +| `entry` | `String` | **是** | 开关名 | +| `value` | `String` | **是** | 开关值 | +| `debug` | `boolean` | 否 | 是否只在本机生效,`true`表示本机生效,`false`表示集群生效 | + +### 返回数据 + +| 参数名 | 参数类型 | 描述 | +|--------|----------|------------------| +| `data` | `String` | “`ok`”表示执行成功 | + +### 示例 + +* 请求示例 + + ```shell + curl -d 'entry=pushEnabled' \ + -d 'value=false' \ + -d 'debug=true' \ + -X PUT 'http://127.0.0.1:8848/nacos/v2/ns/operator/switches' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": "ok" + } + ``` + +

查询系统当前数据指标

+ +### 接口描述 + +查询系统当前数据指标 + +### 请求方式 + +`GET` + +### 请求URL + +`/nacos/v2/ns/operator/metrics` + +### 请求参数 + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|--------------|-----------|----------|--------------------------| +| `onlyStatus` | `boolean` | 否 | 只显示状态，默认为`true` | + +> 当`onlyStatus`设置为`true`时，只返回表示系统状态的字符串 + +### 返回数据 + +| 参数名 | 参数类型 | 描述说明 | +|------------------------------------|----------|--------------------| +| `data` | `Object` | 系统当前数据指标 | +| `data.status` | `String` | 系统状态 | +| `data.serviceCount` | `int` | 服务数量 | +| `data.instanceCount` | `int` | 实例数量 | +| `data.subscribeCount` | `int` | 订阅数量 | +| `data.raftNotifyTaskCount` | `int` | `Raft`通知任务数量 | +| `data.responsibleServiceCount` | `int` | | +| `data.responsibleInstanceCount` | `int` | | +| `data.clientCount` | `int` | 客户端数量 | +| `data.connectionBasedClientCount` | `int` | 连接数量 | +| `data.ephemeralIpPortClientCount` | `int` | 临时客户端数量 | +| `data.persistentIpPortClientCount` | `int` | 持久客户端数量 | +| `data.responsibleClientCount` | `int` | | +| `data.cpu` | `float` | `cpu`使用率 | +| `data.load` | `float` | 负载 | +| `data.mem` | `float` | 内存使用率 | + +### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/operator/metrics' + ``` + +* 返回示例 + + ```json + { + "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 + } + } + ``` + +

更新实例健康状态

+ +### 接口描述 + +更新实例的健康状态 + +### 请求方式 + +`PUT` + +`Content-Type:application/x-www-form-urlencoded` + +### 请求URL + +`/nacos/v2/ns/health/instance` + +### 请求Body + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|---------------|-----------|----------|-------------------------------| +| `namespaceId` | `String` | 否 | 命名空间`Id`，默认为`public` | +| `groupName` | `String` | 否 | 分组名，默认为`DEFAULT_GROUP` | +| `serviceName` | `String` | **是** | 服务名 | +| `clusterName` | `String` | 否 | 集群名，默认为`DEFAULT` | +| `ip` | `String` | **是** | `IP`地址 | +| `port` | `int` | **是** | 端口号 | +| `healthy` | `boolean` | **是** | 是否健康 | + +### 返回数据 + +| 参数名 | 参数类型 | 描述 | +|--------|----------|--------------------| +| `data` | `String` | “`ok`”表示执行成功 | + +### 示例 + +* 请求示例 + + ```shell + curl -d 'serviceName=nacos.test.1' \ + -d 'ip=127.0.0.1' \ + -d 'port=8080' \ + -d 'healthy=false' \ + -X PUT 'http://127.0.0.1:8848/nacos/v2/ns/health/instance' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": "ok" + } + ``` + +

查询客户端列表（新）

+ +### 接口描述 + +查询当前所有的客户端列表 + +### 请求方式 + +`GET` + +### 请求URL + +`/nacos/v2/ns/client/list` + +### 返回数据 + +| 参数名 | 参数类型 | 描述说明 | +|--------|------------|----------------| +| `data` | `String[]` | 客户端`id`列表 | + +### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/client/list' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": [ + "10.128.164.35:9956#true", + "1664358687402_127.0.0.1_2300", + "1664358642902_127.0.0.1_2229", + "192.168.139.1:49825#true", + "10.128.164.35:9954#true", + "192.168.139.1:53556#true" + ] + } + ``` + +> 对于不同版本的nacos client，建立客户端的方式不同。 +> +> 对于`1.x`版本，每个实例会建立两个基于`ip+port`的客户端，分别对应实例注册与服务订阅，`clientId`格式为 `ip:port#ephemeral` +> +> 对于`2.x`版本的`nacos client`, 每个实例会建立一个`RPC`连接，对应一个基于`RPC`连接的客户端，兼具注册与订阅功能，`clientId` +> 格式为`time_ip_port` + + + +

查询客户端信息（新）

+ +### 接口描述 + +查询指定客户端的详细信息 + +> 客户端不存在时会报错 + +### 请求方式 + +`GET` + +### 请求URL + +`/nacos/v2/ns/client` + +### 请求参数 + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|------------|----------|----------|------------| +| `clientId` | `String` | **是** | 客户端`id` | + +### 返回数据 + +| 参数名 | 参数类型 | 描述说明 | +|------------------------|-----------|----------------| +| `data` | `Object` | 客户端信息 | +| `data.clientId` | `String` | 客户端`id` | +| `data.ephemeral` | `boolean` | 是否为临时实例 | +| `data.lastUpdatedTime` | `int` | 上次更新时间 | +| `data.clientType` | `String` | 客户端类型 | +| `data.clientIp` | `String` | 客户端`IP` | +| `data.clientPort` | `String` | 客户端端口 | +| `data.connectType` | `String` | 连接类型 | +| `data.appName` | `String` | 应用名 | +| `data.Version` | `String` | 客户端版本 | + +> 只有当`clientType`为`connection`时，会显示`connectType`，`appName`和`appName`字段 + +### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/client?clientId=1664527081276_127.0.0.1_4400' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": { + "clientId": "1664527081276_127.0.0.1_4400", + "ephemeral": true, + "lastUpdatedTime": 1664527081642, + "clientType": "connection", + "connectType": "GRPC", + "appName": "-", + "version": "Nacos-Java-Client:v2.1.0", + "clientIp": "10.128.164.35", + "clientPort": "4400" + } + } + ``` + +

查询客户端的注册信息（新）

+ +### 接口描述 + +查询指定客户端的注册信息 + +> 客户端不存在时会报错 + +### 请求方式 + +`GET` + +### 请求URL + +`/nacos/v2/ns/client/publish/list` + +### 请求参数 + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|------------|----------|----------|------------| +| `clientId` | `String` | **是** | 客户端`id` | + +### 返回数据 + +| 参数名 | 参数类型 | 描述说明 | +|-----------------------------------|------------|----------------------| +| `data` | `Object[]` | 客户端注册的服务列表 | +| `data.namespace` | `String` | 命名空间 | +| `data.group` | `String` | 分组名 | +| `data.serviceName` | `String` | 服务名 | +| `data.registeredInstance` | `Object` | 该服务下注册的实例 | +| `data.registeredInstance.ip` | `String` | `IP`地址 | +| `data.registeredInstance.port` | `int` | 端口号 | +| `data.registeredInstance.cluster` | `String` | 集群名 | + +### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/client/publish/list?clientId=1664527081276_127.0.0.1_4400' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": [ + { + "namespace": "public", + "group": "DEFAULT_GROUP", + "serviceName": "nacos.test.1", + "registeredInstance": { + "ip": "10.128.164.35", + "port": 9950, + "cluster": "DEFAULT" + } + } + ] + } + ``` + +

查询客户端的订阅信息（新）

+ +### 接口描述 + +查询指定客户端的订阅信息 + +> 客户端不存在时会报错 + +### 请求方式 + +`GET` + +### 请求URL + +`/nacos/v2/ns/client/subscribe/list` + +### 请求参数 + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|------------|----------|----------|------------| +| `clientId` | `String` | **是** | 客户端`id` | + +### 返回数据 + +| 参数名 | 参数类型 | 描述说明 | +|-----------------------------|------------|----------------------| +| `data` | `Object[]` | 客户端订阅的服务列表 | +| `data.namespace` | `String` | 命名空间 | +| `data.group` | `String` | 分组名 | +| `data.serviceName` | `String` | 服务名 | +| `data.subscriberInfo` | `Object` | 订阅信息 | +| `data.subscriberInfo.app` | `String` | 应用 | +| `data.subscriberInfo.agent` | `String` | 客户端信息 | +| `data.subscriberInfo.addr` | `String` | 地址 | + +### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/client/subscribe/list?clientId=1664527081276_127.0.0.1_4400' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": [ + { + "namespace": "public", + "group": "DEFAULT_GROUP", + "serviceName": "nacos.test.1", + "subscriberInfo": { + "app": "unknown", + "agent": "Nacos-Java-Client:v2.1.0", + "addr": "10.128.164.35" + } + } + ] + } + ``` + +

查询注册指定服务的客户端信息（新）

+ +### 接口描述 + +查询注册指定服务的客户端信息 + +### 请求方式 + +`GET` + +### 请求URL + +`/nacos/v2/ns/client/service/publisher/list` + +### 请求参数 + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|---------------|-----------|----------|------------------------------------| +| `namespaceId` | `String` | 否 | 命名空间`Id`，默认为`public` | +| `groupName` | `String` | 否 | 分组名，默认为`DEFAULT_GROUP` | +| `serviceName` | `String` | **是** | 服务名 | +| `ephemeral` | `boolean` | 否 | 是否为临时实例 | +| `ip` | `String` | 否 | `IP`地址，默认为空，不限制`IP`地址 | +| `port` | `int` | 否 | 端口号，默认为空，表示不限制端口号 | + +### 返回数据 + +| 参数名 | 参数类型 | 描述说明 | +|-----------------|----------|------------| +| `data` | | 客户端列表 | +| `data.clientId` | `String` | 客户端`id` | +| `data.ip` | `String` | 客户端`IP` | +| `data.port` | `int` | 客户端端口 | + +### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/client/service/publisher/list?serviceName=nacos.test.1&ip=&port=' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": [ + { + "clientId": "1664527081276_127.0.0.1_4400", + "ip": "10.128.164.35", + "port": 9950 + }, + { + "clientId": "10.128.164.35:9954#true", + "ip": "10.128.164.35", + "port": 9954 + } + ] + } + ``` + +

查询订阅指定服务的客户端信息（新）

+ +### 接口描述 + +查询订阅指定服务的客户端信息 + +### 请求方式 + +`GET` + +### 请求URL + +`/nacos/v2/ns/client/service/subscriber/list` + +### 请求参数 + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|---------------|----------|----------|------------------------------------| +| `namespaceId` | String | 否 | 命名空间`Id`，默认为`public` | +| `groupName` | String | 否 | 分组名，默认为`DEFAULT_GROUP` | +| `serviceName` | String | **是** | 服务名 | +| `ephemeral` | boolean | 否 | 是否为临时实例 | +| `ip` | String | 否 | `IP`地址，默认为空，不限制`IP`地址 | +| `port` | int | 否 | 端口号，默认为空，表示不限制端口号 | + +### 返回数据 + +| 参数名 | 参数类型 | 描述说明 | +|-----------------|----------|------------| +| `data` | | 客户端列表 | +| `data.clientId` | `String` | 客户端`id` | +| `data.ip` | `String` | 客户端`IP` | +| `data.port` | `int` | 客户端端口 | + +### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/client/service/subscriber/list?serviceName=nacos.test.1&ip=&port=' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": [ + { + "clientId": "1664527125645_127.0.0.1_4443", + "ip": "10.128.164.35", + "port": 0 + }, + { + "clientId": "172.24.144.1:54126#true", + "ip": "172.24.144.1", + "port": 54126 + } + ] + } + ``` + +## 命名空间 + +

查询命名空间列表

+ +### 接口描述 + +查询当前所有的命名空间 + +### 请求方式 + +`GET` + +### 请求URL + +`/nacos/v2/console/namespace/list` + +### 返回数据 + +| 参数名 | 参数类型 | 描述说明 | +|--------------------------|------------|----------------------| +| `data` | `Object[]` | 命名空间列表 | +| `data.namespace` | `String` | 命名空间`ID` | +| `data.namespaceShowName` | `String` | 命名空间名称 | +| `data.namespaceDesc` | `String` | 命名空间描述 | +| `data.quota` | `int` | 命名空间的容量 | +| `data.configCount` | `int` | 命名空间下的配置数量 | +| `data.type` | `int` | 命名空间类型 | + +> 命名空间分为3种类型，`0 `- 全局命名空间 `1` - 默认私有命名空间 `2 `- 自定义命名空间 + +### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/console/namespace/list' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": [ + { + "namespace": "", + "namespaceShowName": "public", + "namespaceDesc": null, + "quota": 200, + "configCount": 1, + "type": 0 + } + ] + } + ``` + +

查询具体命名空间

+ +### 接口描述 + +查询具体命名空间的信息 + +> 命名空间不存在时会报错 + +### 请求方式 + +`GET` + +### 请求URL + +`/nacos/v2/console/namespace` + +### 请求参数 + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|---------------|----------|----------|--------------| +| `namespaceId` | `String` | **是** | 命名空间`Id` | + +### 返回数据 + +| 参数名 | 参数类型 | 描述说明 | +|--------------------------|----------|----------------------| +| `data` | `Object` | 命名空间信息 | +| `data.namespace` | `String` | 命名空间`ID` | +| `data.namespaceShowName` | `String` | 命名空间名称 | +| `data.namespaceDesc` | `String` | 命名空间描述 | +| `data.quota` | `int` | 命名空间的容量 | +| `data.configCount` | `int` | 命名空间下的配置数量 | +| `data.type` | `int` | 命名空间类型 | + +> 命名空间分为3种类型，`0` - 全局命名空间 `1` - 默认私有命名空间 `2` - 自定义命名空间 + +### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/console/namespace?namespaceId=test_namespace' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": { + "namespace": "test_namespace", + "namespaceShowName": "test", + "namespaceDesc": null, + "quota": 200, + "configCount": 0, + "type": 2 + } + } + ``` + +

创建命名空间

+ +### 接口描述 + +创建一个命名空间 + +> 命名空间已存在时会报错 + +### 请求方式 + +`POST` + +`Content-Type:application/x-www-form-urlencoded` + +### 请求URL + +`/nacos/v2/console/namespace` + +### 请求Body + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|-----------------|----------|----------|--------------| +| `namespaceId` | `String` | **是** | 命名空间`Id` | +| `namespaceName` | `String` | **是** | 命名空间名称 | +| `namespaceDesc` | `String` | 否 | 命名空间描述 | + +### 返回数据 + +| 参数名 | 参数类型 | 描述 | +|--------|-----------|--------------| +| `data` | `boolean` | 是否执行成功 | + +### 示例 + +* 请求示例 + + ```shell + curl -d 'namespaceId=test_namespace' \ + -d 'namespaceName=test' \ + -X POST 'http://127.0.0.1:8848/nacos/v2/console/namespace' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +

编辑命名空间

+ +### 接口描述 + +编辑命名空间信息 + +### 请求方式 + +`PUT` + +`Content-Type:application/x-www-form-urlencoded` + +### 请求URL + +`/nacos/v2/console/namespace` + +### 请求Body + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|-----------------|----------|----------|--------------| +| `namespaceId` | `String` | **是** | 命名空间`Id` | +| `namespaceName` | `String` | **是** | 命名空间名称 | +| `namespaceDesc` | `String` | 否 | 命名空间描述 | + +### 返回数据 + +| 参数名 | 参数类型 | 描述 | +|--------|-----------|--------------| +| `data` | `boolean` | 是否执行成功 | + +### 示例 + +* 请求示例 + + ```shell + curl -d 'namespaceId=test_namespace' \ + -d 'namespaceName=test.nacos' \ + -X PUT 'http://127.0.0.1:8848/nacos/v2/console/namespace' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +

删除命名空间

+ +### 接口描述 + +删除指定命名空间 + +### 请求方式 + +`DELETE` + +### 请求URL + +`/nacos/v2/console/namespace` + +### 请求参数 + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|---------------|----------|----------|--------------| +| `namespaceId` | `String` | **是** | 命名空间`Id` | + +### 返回数据 + +| 参数名 | 参数类型 | 描述 | +|--------|-----------|--------------| +| `data` | `boolean` | 是否执行成功 | + +### 示例 + +* 请求示例 + + ```shell + curl -d 'namespaceId=test_namespace' \ + -X DELETE 'http://127.0.0.1:8848/nacos/v2/console/namespace' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +## 集群管理 + +

查询当前节点信息

+ +### 接口描述 + +查询当前`nacos`节点信息 + +### 请求方式 + +`GET` + +### 请求URL + +`/nacos/v2/core/cluster/node/self` + +

返回数据

+ +| 参数名 | 参数类型 | 描述说明 | +|----------------------|----------|-----------------------| +| `data` | `Object` | 当前节点信息 | +| `data.ip` | `String` | 节点`IP`地址 | +| `data.port` | `int` | 节点端口 | +| `data.state` | `String` | 节点状态 | +| `data.extendInfo` | `Object` | 节点扩展信息 | +| `data.address` | `String` | 节点地址（`IP:port`） | +| `data.failAccessCnt` | `int` | 失败访问次数 | +| `data.abilities` | `Object` | | + +### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/core/cluster/node/self' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": { + "ip": "10.128.164.35", + "port": 8848, + "state": "UP", + "extendInfo": { + "lastRefreshTime": 1664521263623, + "raftMetaData": { + "metaDataMap": { + "naming_instance_metadata": { + "leader": "10.128.164.35:7848", + "raftGroupMember": [ + "10.128.164.35:7848" + ], + "term": 12 + }, + "naming_persistent_service_v2": { + "leader": "10.128.164.35:7848", + "raftGroupMember": [ + "10.128.164.35:7848" + ], + "term": 12 + }, + "naming_service_metadata": { + "leader": "10.128.164.35:7848", + "raftGroupMember": [ + "10.128.164.35:7848" + ], + "term": 12 + } + } + }, + "raftPort": "7848", + "readyToUpgrade": true, + "version": "2.1.0" + }, + "address": "10.128.164.35:8848", + "failAccessCnt": 0, + "abilities": { + "remoteAbility": { + "supportRemoteConnection": true + }, + "configAbility": { + "supportRemoteMetrics": false + }, + "namingAbility": { + "supportJraft": true + } + } + } + } + ``` + +

查询集群节点列表

+ +### 接口描述 + +查询集群节点列表 + +### 请求方式 + +`GET` + +### 请求URL + +`/nacos/v2/core/cluster/node/list` + +### 请求参数 + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|-----------|----------|----------|--------------------| +| `address` | `String` | 否 | 节点地址，默认为空 | +| `state` | `String` | 否 | 节点状态，默认为空 | + +> `address `对应于需要查询的节点地址的前缀匹配条件，为空时不做限制 +> +> `state`对应节点状态的筛选条件，为空时不做限制 + +### 返回数据 + +| 参数名 | 参数类型 | 描述说明 | +|--------|------------|---------------------------------------| +| `data` | `Object[]` | 节点列表，详情参见[节点详情](#Member) | + +### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/core/cluster/node/list' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": [ + { + "ip": "10.128.164.35", + "port": 8848, + "state": "UP", + "extendInfo": { + "lastRefreshTime": 1664521263623, + "raftMetaData": { + "metaDataMap": { + "naming_instance_metadata": { + "leader": "10.128.164.35:7848", + "raftGroupMember": [ + "10.128.164.35:7848" + ], + "term": 12 + }, + "naming_persistent_service_v2": { + "leader": "10.128.164.35:7848", + "raftGroupMember": [ + "10.128.164.35:7848" + ], + "term": 12 + }, + "naming_service_metadata": { + "leader": "10.128.164.35:7848", + "raftGroupMember": [ + "10.128.164.35:7848" + ], + "term": 12 + } + } + }, + "raftPort": "7848", + "readyToUpgrade": true, + "version": "2.1.0" + }, + "address": "10.128.164.35:8848", + "failAccessCnt": 0, + "abilities": { + "remoteAbility": { + "supportRemoteConnection": true + }, + "configAbility": { + "supportRemoteMetrics": false + }, + "namingAbility": { + "supportJraft": true + } + } + } + ] + } + ``` + +

查询当前节点健康状态

+ +### 接口描述 + +查询当前`nacos`节点健康状态 + +### 请求方式 + +`GET` + +### 请求URL + +`/nacos/v2/core/cluster/node/self/health` + +

返回数据

+ +| 参数名 | 参数类型 | 描述说明 | +|--------|----------|------------------| +| `data` | `String` | 当前节点健康状态 | + +> 节点共有 `STARTING`， `UP`，`SUSPICIOUS`，`DOWN`，`ISOLATION`五种状态 + +### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/core/cluster/node/self/health' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": "UP" + } + ``` + + +

切换集群寻址模式

+ +### 接口描述 + +切换集群寻址模式 + +### 请求方式 + +`PUT` + +`Content-Type:application/x-www-form-urlencoded` + +### 请求URL + +`/nacos/v2/core/cluster/lookup` + +### 请求Body + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|--------|----------|----------|----------| +| `type` | `String` | **是** | 寻址模式 | + +> 寻址模式有两种：`file`（文件配置）和 `address-server`（地址服务器） + +### 返回数据 + +| 参数名 | 参数类型 | 描述 | +|--------|-----------|--------------| +| `data` | `boolean` | 是否执行成功 | + +### 示例 + +* 请求示例 + + ```shell + curl -d 'type=file' \ + -X PUT 'http://127.0.0.1:8848/nacos/v2/core/cluster/lookup' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + + diff --git a/template/404.startlight.tpl b/template/404.startlight.tpl index 70806bc3052..5655c1498cc 100644 --- a/template/404.startlight.tpl +++ b/template/404.startlight.tpl @@ -49,19 +49,32 @@ const route = generateRouteData({ From fc2385dbe181cbe1851989a09f2288b0321401ee Mon Sep 17 00:00:00 2001 From: Hazel0928 <55099364+Hazel0928@users.noreply.github.com> Date: Wed, 24 Jan 2024 15:01:11 +0800 Subject: [PATCH 4/4] Develop astro nacos (#521) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat: 🎸 fix link * fix: 🐛 fix descriptioin * feat: 🎸 老路由兼容 * feat: 🎸 404 fix * fix: 🐛 fix en-us --- astro.config.mjs | 1 - 1 file changed, 1 deletion(-) diff --git a/astro.config.mjs b/astro.config.mjs index 50fa630f94d..e439de25549 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -77,7 +77,6 @@ export default defineConfig({ '/zh-cn/': '/', '/en-us/': '/en/', '/[...slug].html': '/[...slug]', - '/en-us/[...slug]/': '/en/[...slug]/', '/zh-cn/[...slug]': '/[...slug]', '/docs/': '/docs/latest/what-is-nacos/', }