O Nacos do Microservices Engine (MSE) oferece registro e descoberta de serviços, além de gerenciamento de configurações, por meio de SDKs para diversas linguagens. Use este guia e escolha o SDK ideal para a sua stack de tecnologia, evitando versões do SDK com problemas conhecidos de estabilidade.
Versões mínimas recomendadas do SDK
Para garantir estabilidade e compatibilidade, use no mínimo as seguintes versões:
|
SDK |
Versão mínima recomendada |
|
Java (Nacos Client) |
2.3.2 ou superior |
|
Go (nacos-sdk-go) |
2.3.3 ou superior (Professional Edition), 1.1.6 ou superior (Basic Edition) |
|
Python (nacos-sdk-python) |
2.0.7 ou superior |
|
Dubbo |
2.7.20 ou superior (2.x), 3.1.6 ou superior (3.x) |
|
Spring Cloud Alibaba |
2.2.6.RELEASE ou superior |
Para mais detalhes sobre quais versões específicas evitar, consulte a seção Versões restritas do SDK abaixo.
Selecione um SDK para a sua stack de tecnologia
Java
|
Integração |
Descrição |
Referência |
|
SDK nativo |
Conecte-se diretamente por meio do Nacos Java SDK. |
|
|
Spring Boot |
Use o Nacos como registro de serviços e centro de configurações no Spring Boot. |
|
|
Spring Cloud |
Integre o Nacos ao Spring Cloud para o gerenciamento de configurações. |
|
|
Dubbo |
Registre serviços do Dubbo no Nacos para chamadas de procedimento remoto (RPC) de alta performance. |
Go
| Integração | Descrição | Referência |
|---|---|---|
| SDK nativo | Configure um registro de serviços e um centro de configurações com o Go SDK. | nacos-sdk-go |
| Dubbo-Go | Desenvolva serviços RPC em Go com o Apache Dubbo-Go e o Nacos. | Dubbo-Go |
| Kitex | Use o Kitex, um framework RPC para microsserviços em Go com suporte nativo a registro de serviços do Nacos. | - |
Node.js
|
Integração |
Descrição |
Referência |
|
SDK nativo |
Implemente o registro e a descoberta de serviços com o Node.js SDK. |
Python
|
Integração |
Descrição |
Referência |
|
SDK nativo |
Desenvolva um sistema de microsserviços com o Python SDK. |
Service mesh (Istio)
O Nacos do MSE se integra ao ecossistema de service mesh do Istio por meio do padrão Mesh Configuration Protocol (MCP). Para conectar o Nacos ao service mesh, consulte Crie uma fonte de serviço.
Versões restritas do SDK
Algumas versões do SDK possuem bugs conhecidos que podem causar indisponibilidade de serviços, degradação de performance ou problemas de dados. Evite as versões listadas abaixo e atualize para as alternativas recomendadas.
Java SDK (Nacos Client)
|
Versões restritas |
Problema |
Ação |
|
0.x - 1.1.x |
Sem suporte para heartbeats leves de serviços. Pacotes de heartbeat excessivamente grandes degradam a performance. Detalhes. |
Atualize para a versão 1.2.0 ou superior. |
|
1.4.0 e anteriores |
Nas versões 1.4.0 e anteriores, quando ocorre perda de pacotes de rede ou outros erros inesperados, a thread de heartbeat encerra de forma inesperada. O serviço fica offline e não consegue se recuperar automaticamente. Detalhes. |
Atualize para a versão 1.4.3 ou superior. |
|
1.4.1 - 1.4.2 |
1.4.1: Se o DNS estiver indisponível e a resolução de nomes de domínio falhar, a thread de heartbeat encerra de forma inesperada. O serviço fica offline e não consegue se recuperar automaticamente. Detalhes. 1.4.2: A API |
Atualize para a versão 1.4.3 ou superior. |
|
2.0.0 - 2.0.1 |
Não é possível transmitir informações de identidade do RAM. Caso ative a autenticação de cliente no engine, o cliente não consegue obter configurações, registrar serviços nem descobrir serviços, mesmo que as informações necessárias estejam configuradas. |
Atualize para a versão 2.0.2 ou superior. |
|
2.2.0 - 2.2.1 |
Ao implantar por meio do EDAS ou SAE, os parâmetros da JVM |
Atualize para a versão 2.2.2 ou superior. |
|
2.3.1 |
O servidor envia atualizações de configuração repetidamente, mesmo quando a configuração não foi alterada. Isso causa sobrecarga desnecessária de CPU e rede, podendo afetar a estabilidade. Detalhes. |
Atualize para a versão 2.3.2 ou superior. |
Go SDK (nacos-sdk-go)
|
Versões restritas |
Problema |
Ação |
|
1.0.1 - 1.1.3 |
O cliente sempre reporta sua versão como 1.0.1, o que impede a identificação precisa da versão. Dois bugs críticos podem causar notificações frequentes de alteração ou interrupções de heartbeat. |
Basic Edition: atualize para a versão 1.1.6 ou superior. Professional Edition: atualize para a versão 2.3.2 ou superior. |
|
1.1.4 |
Caso você exclua uma configuração assinada, o cliente consulta continuamente o serviço inexistente. O fluxo resultante de requisições de consulta de configuração pode acionar o limite de taxa (rate limiting) e afetar outras aplicações. Detalhes. |
Atualize para uma versão posterior à 1.1.4. Para as versões mínimas recomendadas, consulte a tabela Versões mínimas recomendadas do SDK acima. |
|
2.0.0 - 2.1.0 |
O cliente sempre reporta sua versão como 2.0.0, o que impede a identificação precisa da versão. Após uma reconexão, as instâncias não se registram novamente nem reassinam os serviços automaticamente. O serviço fica offline e não consegue se recuperar. Detalhes. |
Atualize para a versão 2.3.3 ou superior. |
|
2.2.7 - 2.3.1 |
O cliente sempre reporta sua versão como 2.2.7, o que impede a identificação precisa da versão. Dois bugs críticos podem causar falha ao receber notificações de alteração de serviços ou perda de serviços após uma interrupção de conexão. |
Atualize para a versão 2.3.3 ou superior. |
Se você confirmou que sua aplicação não depende diretamente do cliente Nacos para Go (nacos-sdk-go), mas ainda assim uma versão de alto risco do nacos-sdk-go é detectada, verifique se você está usando o MSE Gateway com o Nacos como fonte de serviços. Em caso afirmativo, atualize o MSE Gateway para a versão mais recente. Versões anteriores do MSE Gateway incluem uma versão de alto risco do cliente Nacos para Go, e atualizar a versão do engine do gateway limpa o alerta.
Python SDK (nacos-sdk-python)
|
Versões restritas |
Problema |
Ação |
|
2.0.0 - 2.0.6 |
Após uma reconexão, o cliente não se registra novamente nem reassina serviços e configurações automaticamente. Isso leva a interrupções de serviços sem recuperação automática. |
Atualize para a versão 2.0.7 ou superior. |
Dubbo
|
Versões restritas |
Problema |
Ação |
|
2.7.5 e anteriores |
Ao assinar múltiplos serviços, as alterações na lista de endereços de um provedor não são obtidas. O tráfego pode ser roteado para um provedor offline ou inexistente. Detalhes. |
Atualize para a versão 2.7.6 ou superior. |
|
2.7.8 |
Cria uma quantidade excessiva de instâncias do Nacos Client, causando um aumento acentuado nas conexões e threads, o que afeta a estabilidade tanto do cliente quanto do servidor. Detalhes. |
Atualize para a versão 2.7.9 ou superior. |
|
2.7.11 |
Depende do Nacos-Java-Client 1.4.1 por padrão (uma versão restrita). |
Atualize para a versão 2.7.12 ou superior, ou defina explicitamente a versão do Nacos Client para 1.4.2 ou superior. |
|
2.7.19 e anteriores |
Quando o Dubbo assina um serviço, ele assina múltiplos nomes de serviços. Durante a agregação da lista de endereços, o consumidor pode não conseguir encontrar o provedor. Detalhes. |
Atualize para a versão 2.7.20 ou superior. |
|
3.0.0 - 3.1.5 |
Contém problemas conhecidos que afetam a estabilidade. |
Atualize para a versão 3.1.6 ou superior. |
Spring Cloud Alibaba
|
Versões restritas |
Problema |
Ação |
|
Anteriores à 2.2.4 |
Sobrescreve a configuração de logs do Nacos Client. Os logs do Nacos são gravados nos logs de negócio da aplicação, o que complica a solução de problemas. Detalhes. |
Atualize para a versão 2.2.6.RELEASE ou superior. |
|
2.2.4.RELEASE, 2.2.5.RELEASE |
Depende do Nacos-Java-Client 1.4.1 por padrão (uma versão restrita). |
Atualize para a versão 2.2.6.RELEASE ou superior, ou defina explicitamente a versão do Nacos Client para 1.4.2 ou superior. |
|
2.2.X.RELEASE, 2021., 2022. |
Adiciona a sonda de verificação de integridade do Nacos à verificação de integridade do Spring Cloud Actuator por padrão. Quando ocorrem exceções de acesso entre a aplicação e o Nacos, isso pode causar reinícios inesperados da aplicação ou remoção de tráfego. Detalhes. |
Adicione a seguinte configuração ao arquivo de configuração da sua aplicação: |
Atualize o seu Nacos SDK
Identifique o SDK e a versão que sua aplicação usa atualmente (verifique o
pom.xml,go.mod,requirements.txtoupackage.json).Consulte as tabelas acima e confirme a versão de destino.
Atualize a versão da dependência no seu arquivo de configuração de build.
Recompile e teste a aplicação em um ambiente de staging.
Implante a aplicação atualizada.
Nota: O MSE gerencia a versão do Nacos no lado do servidor. As tabelas acima se aplicam ao SDK cliente incluído na sua aplicação.