Todos os produtos
Search

Este produto

    ApsaraDB for MongoDB:Solução de problemas de conexão e rede

    Central de documentação

    ApsaraDB for MongoDB:Solução de problemas de conexão e rede

    Última atualização: Jul 20, 2026

    Diagnostique e corrija falhas de conexão em instâncias do ApsaraDB for MongoDB. Comece pela seção Erros comuns para obter correções rápidas ou siga as Etapas de solução de problemas para identificar a causa raiz de forma sistemática.

    Etapas de solução de problemas

    Etapa 1: Verificar a conectividade de rede

    Método de solução de problemas

    Teste a conectividade com a instância do ApsaraDB for MongoDB usando os comandos abaixo.

    • Execute o comando ping <domain>. Por exemplo, execute ping dds-xxxx.mongodb.rds.aliyuncs.com.

      ping dds-xxx.mongodb.rds.aliyuncs.com
PING dds-xxx.mongodb.rds.aliyuncs.com (xxx): 56 data bytes
64 bytes from xxx: icmp_seq=0 ttl=90 time=7.698 ms
64 bytes from xxx: icmp_seq=1 ttl=90 time=7.085 ms
64 bytes from xxx: icmp_seq=2 ttl=90 time=11.006 ms
64 bytes from xxx: icmp_seq=3 ttl=90 time=12.154 ms
64 bytes from xxx: icmp_seq=4 ttl=90 time=9.149 ms

      Essa saída confirma que o cliente consegue alcançar a instância do ApsaraDB for MongoDB.

    • Execute o comando telnet <domain> <port>. Por exemplo, execute telnet dds-xxxx.mongodb.rds.aliyuncs.com 3717.

      root@mongotest:~# telnet xxx.mongodb.rds.aliyuncs.com 3717
Trying xxx...
Connected to xxx.mongodb.rds.aliyuncs.com.
Escape character is '^]'.

      Essa saída confirma a resolução de DNS e a acessibilidade da porta 3717.

    Lista de verificação

    Se o teste de rede falhar, verifique os itens a seguir.

    Verifique o status da instância. A instância deve estar no estado Running.

    Verifique as configurações da lista de permissões. O endereço IP do cliente deve estar na lista de permissões da instância do ApsaraDB for MongoDB.

    • Como verificar:

      Adicione temporariamente 0.0.0.0/0 à lista de permissões da instância. Se você conseguir se conectar à instância após essa alteração, as configurações originais da lista de permissões estavam incorretas.

      Importante

      O endereço IP 0.0.0.0/0 permite que qualquer dispositivo acesse a instância do ApsaraDB for MongoDB, o que representa um risco de segurança. Use este endereço IP apenas para fins de teste e remova-o da lista de permissões imediatamente após o teste.

    • Solução:

      Adicione o endereço IP correto do cliente à lista de permissões. Para encontrar o IP público do seu cliente, consulte o FAQ.

    Verifique o tipo de rede e o endpoint. Use o endpoint correto para o seu tipo de rede (privada ou pública).

    Acesse o console do ApsaraDB for MongoDB e visualize os endpoints na página Database Connection.

    Etapa 2: Autorização e autenticação

    Verifique o nome da conta e a senha, e confira se há caracteres especiais na senha.

    • Confirme se o nome da conta e a senha fornecidos estão corretos.

    • Altere a senha. Se precisar alterar a senha, consulte Reset password.

      Se você alterar a senha após se conectar à instância do ApsaraDB for MongoDB usando o Data Management Service (DMS), acesse o DMS console, clique com o botão direito na instância de destino e selecione Edit para fazer login novamente.

    • Caracteres especiais. Ao usar o MongoDB Shell ou código de aplicação para se conectar a uma instância do ApsaraDB for MongoDB, escape quaisquer caracteres especiais, como !@#$%^&*()_+=, no nome da conta ou na senha. Consulte How do I resolve a connection failure that is caused by special characters in a username or password?.

    Verifique o banco de dados de autenticação. Uma conta de banco de dados deve ser autenticada no banco de dados ao qual pertence.

    Consulte How do I specify an authentication database in a connection?.

    Verifique o endpoint da instância. Para uma instância de conjunto de réplicas que exige operações de escrita, recomendamos a conexão via endpoint ConnectionString URI.

    • Sintoma: A instância torna-se inacessível repentinamente, mesmo sem alterações no endpoint.

    • Causa: Apenas o nó primário pode realizar operações de escrita. Se sua aplicação estava conectada anteriormente usando o endpoint do nó primário, um failover pode ter alterado o nó conectado para um secundário, causando falha nas operações de escrita.

    • Solução:

      • Para ambientes de produção, recomendamos que sua aplicação se conecte ao banco de dados usando um ConnectionString URI. Dessa forma, se um nó falhar, as operações de leitura e escrita não serão afetadas pelo failover. Para detalhes sobre endpoints, consulte os tópicos a seguir:

      • Alterne manualmente as funções dos nós conforme descrito em switch node roles. Promova o nó correspondente ao endpoint de nó único para nó primário.

      Implemente lógica de reconexão e tratamento de exceções em sua aplicação para recuperar-se automaticamente de desconexões transitórias.

    Etapa 3: Outras verificações

    Verifique se o desempenho da instância atende aos requisitos do seu negócio.

    Verifique ferramentas de terceiros.

    Se uma ferramenta de terceiros, como Navicat ou Compass, não conseguir se conectar à sua instância do ApsaraDB for MongoDB, o problema pode decorrer de configurações incorretas na instância ou na ferramenta. Siga estas etapas para solucionar o problema:

    1. Teste a conexão usando o MongoDB Shell.

      Recomendamos usar o MongoDB Shell para se conectar à instância por meio de seu ConnectionString URI de alta disponibilidade.

    2. Solucione o problema com base no resultado do teste.

      • Conexão bem-sucedida: A instância está acessível. O problema provavelmente é causado por configurações incorretas na ferramenta de terceiros. Verifique a configuração da ferramenta.

      • Falha na conexão: Se o MongoDB Shell não conseguir se conectar, as configurações da instância podem estar incorretas. Siga as etapas deste tópico para verificar a conectividade de rede, autorização, autenticação e outras configurações.

    Erros comuns

    Mensagem de erro

    Causa e solução

    network error while attempting to run command 'isMaster' on host 'dds-xxxx.mongodb.rds.aliyuncs.com:3717' :exception: connect failed

    • Timed out after 3000ms while waiting for a server that matches ReadPreferenceServerSelector{readPreference=primary}. exception=(com.mongodb.MongoSocketReadException: Prematurely reached end of stream)

    • Socket recv() errno:54 Connection reset by peer x.x.x.x:27017

    A instância pode ter atingido o limite de conexões.

    Solução:

    1. Verifique se as conexões estão esgotadas. Consulte How do I query the number of connections?.

    2. Otimize o uso de conexões. Consulte What do I do if the number of connections to my instance reaches its limit?.

    MongoDB.Driver.MongoWaitQueueFullException: The wait queue for acquiring a connection to server xxx is full.

    A fila de espera do driver do MongoDB está cheia, provavelmente devido a um pool de conexões subdimensionado ou alta concorrência.

    Solução:

    1. Verifique a configuração do pool de conexões na aplicação. Garanta que o pool tenha o tamanho adequado. Consulte How do I limit the number of client connections?.

    2. Se o problema persistir, verifique se as conexões com a instância do ApsaraDB for MongoDB estão esgotadas:

      1. How do I query the number of connections?

      2. What do I do if the number of connections to my instance reaches its limit?

    (TooManyLogicalSessions) Unable to add session into the cache because the number of active sessions is too high.

    Conexões simultâneas excessivas podem esgotar as sessões disponíveis.

    Solução:

    1. Solucione a falha de conexão causada pelo esgotamento de conexões.

      1. How do I query the number of connections?

      2. What do I do if the number of connections to my instance reaches its limit?

    2. Se o número de conexões estiver normal, verifique se outras métricas de desempenho da instância atendem aos requisitos do seu negócio.

      1. Use o node monitoring para monitorar o uso de recursos, como CPU e memória, e determinar se o tipo de instância atende aos requisitos do seu negócio.

      2. Se o tipo de instância for insuficiente para a carga de trabalho, altere a configuração da instância conforme descrito em change the instance configuration durante horários de baixa demanda.

    • getaddrinfo failed.

    • No suitable servers found (serverSelectionTryOnce set).

    Verifique se o endpoint da instância está correto:

    • Failed to connect to 10...8:3717 after 5000 milliseconds, giving up.Error: couldn't connect to server 10...8:3717 (10...8), connection attempt failed

    • pymongo.errors.ServerSelectionTimeoutError: dds-xxxx.mongodb.rds.aliyuncs.com:3717: [Errno 113] No route to host,dds-xxxx.mongodb.rds.aliyuncs.com:3717

    • InvalidInstanceId.NotFound: The instance not in current vpc.

    Uma instância ECS falha ao se conectar a uma instância do ApsaraDB for MongoDB pela rede privada.

    Solução:

    1. Verifique as configurações da lista de permissões. Certifique-se de que o endereço IP privado da instância ECS esteja added to the whitelist da instância do ApsaraDB for MongoDB.

    2. Certifique-se de que a instância ECS e a instância do ApsaraDB for MongoDB possam se comunicar pela rede.

      Instâncias ECS e ApsaraDB for MongoDB na mesma VPC podem se conectar diretamente pela rede privada. Se estiverem em VPCs diferentes, use um dos métodos a seguir:

    org.springframework.data.mongodb.UncategorizedMongoDbException: Timeout while receiving message; nested exception is com.mongodb.MongoSocketReadTimeoutException: Timeout while receiving message

    • "errmsg": "not master", "code": 10107, "codeName": "NotMaster"

    • "errmsg": "not master", "code": 10107, "codeName": "NotWritablePrimary"

    • Time out after 30000ms while waiting for a server that matches writableServerSelector.

    • Command failed with error 10107 (NotWritablePrimary): 'not primary' on server xxx.

    • Explain's child command cannot run on this node. Are you explaining a write command on a secondary?

    • not master and slaveOk=false.

    • MongoNotPrimaryException: Command failed with error 10107 (NotMaster): 'not master' on server xxx.

    • reason: TopologyDescription { type: 'ReplicaSetNoPrimary',...}

    O nó no qual os dados estão sendo gravados não é um nó primário.

    Causa: Operações de escrita só podem ser realizadas no nó primário. Se sua aplicação estava conectada anteriormente usando o endpoint do nó primário, um failover pode ter alterado o nó conectado para um secundário, causando falha nas operações de escrita.

    Solução:

    • Para ambientes de produção, recomendamos que sua aplicação se conecte ao banco de dados usando um ConnectionString URI. Dessa forma, se um nó falhar, as operações de leitura e escrita não serão afetadas pelo failover. Para detalhes sobre endpoints, consulte os tópicos a seguir:

    • Alterne manualmente as funções dos nós conforme descrito em switch node roles. Promova o nó correspondente ao endpoint de nó único para nó primário.

    Implemente lógica de reconexão e tratamento de exceções em sua aplicação para recuperar-se automaticamente de desconexões transitórias.

    [Unauthorized] cloud instance error, disk locked, plz check and upgrade your disk quota,

    O espaço em disco esgotado bloqueou a instância.

    Solução: Resolve instance locking or write failures caused by exhausted disk space.

    (AuthenticationFailed) Authentication failed.

    • !xxx@dds-xxx.mongodb.rds.aliyuncs.com: event not found

    A senha da conta do banco de dados contém caracteres especiais, como !@#$%^&*()_+=.

    Solução: How do I resolve a connection failure that is caused by special characters in a username or password?.

    error getting cluster ID: (CommandNotFound) replSetGetConfig is forbidden by cloud provider for security reason

    O ApsaraDB for MongoDB não oferece suporte a replSetGetConfig. Consulte Limits on commands in ApsaraDB for MongoDB.

    Perguntas frequentes

    Consultando conexões

    O número máximo de conexões varia conforme o instance type.

    Nota

    O limite de conexões se aplica por nó. Por exemplo, uma instância de conjunto de réplicas com três nós, 1 vCPU e 2 GB de memória permite até 500 conexões tanto no nó primário quanto em cada nó secundário. O nó oculto não atende tráfego.

    Console

    1. Acesse a página ApsaraDB for MongoDB Replica Set Instances ou a página ApsaraDB for MongoDB Sharded Cluster Instances. Na barra de navegação superior, selecione uma região. Em seguida, clique no ID da instância de destino.

    2. No painel de navegação à esquerda, clique em Monitoring Information.

    3. Na página Monitoring Information, visualize as informações de Connections da instância.

      Se a instância for um cluster fragmentado, selecione o Mongos que seu service usa atualmente no canto superior direito da página.

    Comando

    1. Connect to the instance by using the MongoDB Shell.

    2. Visualize o número de conexões.

      Execute o comando db.serverStatus().connections.

      mgset-123456:PRIMARY> db.serverStatus().connections
{
        "current" : 1,
        "available" : 999,
        "internal_current" : 10,
        "internal_available" : 990,
        "totalCreated" : 632
}

      Descrição dos parâmetros:

      • "current": o número de conexões estabelecidas.

      • "available": o número de conexões disponíveis.

    3. Consulte as origens das conexões atuais.

      1. Mude para o banco de dados admin.

        use admin

      2. Execute o comando db.runCommand({currentOp: 1, $all: true}).

        mgset-123456:PRIMARY> db.runCommand({currentOp: 1, $all:[{"active" : true}]})

      Analise a saída para identificar o IP de source e a contagem de conexões por cliente. Consulte db.currentOp().

    Limitando conexões de clientes

    Anexe &maxPoolSize=<integer> ao ConnectionString URI para limitar o tamanho do pool. O exemplo a seguir define o pool para 10 conexões (conta: test, banco de dados de autenticação: admin):

    mongosh "mongodb://test:****@dds-bp19f409d7512****-pub.mongodb.rds.aliyuncs.com:3717,dds-bp19f409d7512****-pub.mongodb.rds.aliyuncs.com:3717/admin?replicaSet=mgset-6108****&maxPoolSize=10"
    Nota

    Para limitar o tamanho do pool em outras linguagens, consulte a documentação de MongoDB Drivers.

    Lidando com o limite de conexões

    Você pode restart the instance, its components, or nodes para liberar temporariamente todas as conexões.

    Importante

    Ao reiniciar uma instância, seus nós são reiniciados em sequência. Cada nó sofre uma desconexão transitória de cerca de 30 segundos. Se a instância contiver um grande número de coleções (mais de 10.000), a desconexão pode durar mais. Antes de reiniciar a instância, planeje adequadamente e garanta que sua aplicação possua um mecanismo de reconexão.

    Após a reinicialização, tome as seguintes medidas para evitar reincidência:

    Caracteres especiais nas credenciais

    As conexões falham se o nome da conta ou a senha na string de conexão contiver caracteres especiais não escapados, como !@#$%^&*()_+=.

    Escape os caracteres especiais na string de conexão. A tabela a seguir lista as regras de codificação.

    ! : %21
@ : %40
# : %23
$ : %24
% : %25
^ : %5e
& : %26
* : %2a
( : %28
) : %29
_ : %5f
+ : %2b
= : %3d

    Exemplo: Se a senha for ab@#c, você deve escapar os caracteres especiais na string de conexão. A senha escapada será ab%40%23c.

    Especificando um banco de dados de autenticação

    Uma conta de banco de dados deve ser autenticada no banco de dados onde foi criada.

    Suponha que o nome de usuário e a senha sejam ambos test, e a conta test pertença ao banco de dados testdb.

    Endpoint de alta disponibilidade

    Em um ConnectionString URI ou ConnectionString URI somente leitura, defina authSource como o banco de dados onde a conta foi criada. Se omitido, <database> no URI será usado para autenticação.

    Exemplos:

    • Após a conta test ser autenticada no banco de dados testdb, a instância muda para o banco de dados <database>.

    mongosh "mongodb://test:test@<host1>:<port1>,<host2>:<port2>,...,<hostN>:<portN>/<database>?replicaSet=<replicaSet_value>&authSource=testdb"

    • Após a conta test ser autenticada no banco de dados testdb, a instância muda para o banco de dados testdb.

    mongosh "mongodb://test:test@<host1>:<port1>,<host2>:<port2>,...,<hostN>:<portN>/testdb?replicaSet=<replicaSet_value>"

    Endpoint de nó único

    Você pode executar um dos seguintes comandos para fazer login:

    mongosh --host $myhost --port $myport -u test -p test --authenticationDatabase testdb

    ou

        mongosh --host $myhost --port $myport
    mongo> use testdb
    mongo> db.auth("test", "test")

    Detalhes dos parâmetros de endpoint: Connect to a replica set instance e Connect to a sharded cluster instance.

    Linguagens de cliente compatíveis

    O ApsaraDB for MongoDB é totalmente compatível com o MongoDB e oferece suporte a todos os clientes oficiais do MongoDB.

    As linguagens compatíveis incluem C, C++, C#, Java, Node.js, Python, PHP e Perl (documentação oficial).

    Para exemplos de código, consulte os tópicos a seguir:

    Nota

    Para garantir a autenticação adequada ao se conectar a uma instância do ApsaraDB for MongoDB, use um driver do MongoDB versão 3,0 ou posterior.

    Acesso pela rede pública

    Sim. Consulte Connect to a MongoDB instance from a client on the internet.

    Acesso sem senha

    O ApsaraDB for MongoDB não oferece mais suporte à ativação de acesso sem senha via VPC.

    Se o acesso sem senha já estiver ativado, você pode desativá-lo permanentemente. Consulte Disable password-free access over a private network.

    Mongo Shell no Windows

    Cenários comuns de conexão