Så åtgärdar du MongoDB-nätverksavbrott vid Mongoose-anslutning

Den viktigaste åtgärden är att sluta behandla varje Mongoose-avbrott som ett problem med tidsgränsinställningar. Ett meddelande som MongoServerSelectionError: connection timed out betyder vanligtvis att MongoDB-drivrutinen inte kunde välja en användbar server innan serverSelectionTimeoutMS löpte ut. MongoDBs aktuella felsökningsdokumentation listar nätverksanslutning, Atlas IP-åtkomstbegränsningar, DNS SRV-fel och TLS-konfiguration som vanliga orsaker. Att öka tidsgränsen kan få applikationen att vänta längre utan att reparera någon av dessa förutsättningar.

Använd denna ordning istället: 1) identifiera vilket avbrott som misslyckades, 2) bevisa att applikationsvärden kan nå MongoDB, 3) korrigera anslutningssträngen eller den miljöspecifika adressen, och 4) justera tidsgränsvärden endast efter att anslutningen är känd för att fungera. Exemplen nedan använder moderna Mongoose-anslutningsmönster och aktuellt MongoDB-drivrutinsbeteende som dokumenterats i september 2026.

Först, veta vilket avbrott du tittar på

Mongoose använder MongoDB Node.js-drivrutinen under huven, så flera olika tidsgränsinställningar kan förekomma i samma anslutningskonfiguration. De betyder inte samma sak.

Mongoses aktuella dokumentation för anslutningar anger att serverSelectionTimeoutMS har en standard på 30 sekunder och gäller både för initial mongoose.connect() och för senare operationer som behöver välja en server. MongoDBs dokumentation för anslutningsalternativ för Node.js-drivrutinen skiljer det värdet från connectTimeoutMS och socketTimeoutMS.

Ett servervalstidsavbrott är symtomet som ska klassificeras först; felinformationerna och den underliggande orsaken är mer användbara än att omedelbart öka 30-sekundersgränsen.

Steg 1: fånga det exakta Mongoose-felet och dess underliggande orsak

Börja med en minimal anslutning och logga tillräckligt med information för att skilja på DNS-, autentiserings-, TLS- och tillgänglighetsfel:

import mongoose from 'mongoose';

try {
  await mongoose.connect(process.env.MONGODB_URI, {
    serverSelectionTimeoutMS: 5000
  });

  console.log('MongoDB connected');
} catch (err) {
  console.error(err);
  console.error('Reason:', err.reason);
  process.exit(1);
}

5-sekundersvärdet ovan är ett diagnostiskt val, inte en produktionsrekommendation för varje distribution. Mongoose säger att minskning av serverSelectionTimeoutMS kan ge snabbare återkoppling, men varnar specifikt mot att minska det slarvigt för replikamängder eftersom standardfönstret på 30 sekunder kan hjälpa operationer att överleva val och failovers. Mongoose föreslår kortare värden mer lätt för fristående MongoDB eller serverlösa körningar där snabbt fel är användbart.

Leta efter ledtrådar som:

• getaddrinfo ENOTFOUND — DNS-namnet kan inte lösas upp.
• ECONNREFUSED — något aktivt nekade TCP-anslutningen, ofta för att inget lyssnar på värden/porten.
• ETIMEDOUT — anslutningsförsöket slutfördes inte i tid, ofta för att trafik filtreras, dirigeras felaktigt eller destinationen är otillgänglig.
• TLS- eller certifikattext — undersök certifikattillit, värdnamnsmatchning, protokollstöd eller TLS-konfiguration.
• Autentiseringsfel inuti err.reason — fixa autentiseringsuppgifter eller authSource istället för att ändra nätverkstidsgränser.

Villkor: om felet redan säger att autentisering misslyckades, hoppa över brandväggjusteringar tills autentiseringsuppgifterna och autentiseringsdatabasen är korrekta. Ett nätverksavbrott och ett nekat inloggning är olika felklasser.

Steg 2: bevisa nätverk, Atlas IP-åtkomst och DNS från samma körning

Kör anslutningstester från samma maskin, container, VM, serverlösa funktion eller Kubernetes-pod där Node.js-processen körs. Att testa från din bärbara dator räcker inte om produktionen körs någon annanstans.

För Atlas, verifiera att applikationens verkliga utgående IP är tillåten; för en lokal distribution, verifiera att MongoDB-processen faktiskt lyssnar på det förväntade gränssnittet och porten.

Om du använder MongoDB Atlas

Atlas accepterar klientanslutningar endast från adresser som tillåts av projektets IP-åtkomstlista. MongoDB dokumenterar detta i Hantera IP-åtkomstlistan. Se till att den offentliga utgående IP:n för applikationsmiljön är listad, inte bara din personliga arbetsstations IP.

MongoDBs felsökningsguide för servervalstidsavbrott rekommenderar också att kontrollera utgående TCP-anslutning till MongoDB på port 27017, tillsammans med brandväggar, säkerhetsgrupper, nätverks-ACL, VPN och proxyer.

Till exempel, från Linux eller macOS kan du testa en specifik Atlas-nod eller självhanterad värd med:

nc -vz your-mongodb-host.example.com 27017

På Windows PowerShell är ett ungefärligt TCP-tillgänglighetstest:

Test-NetConnection your-mongodb-host.example.com -Port 27017

Ett framgångsrikt TCP-test bevisar inte att autentisering eller TLS kommer att lyckas, men ett misslyckat TCP-test betyder att Mongoose-tidsgränsjustering är för tidig.

Om din URI använder mongodb+srv://

En SRV-anslutningssträng är beroende av DNS SRV-poster. MongoDBs aktuella felsökningssteg rekommenderar att kontrollera SRV-uppslagningen från klientmiljön:

nslookup -type=SRV _mongodb._tcp.cluster-name.mongodb.net

Om SRV-frågan misslyckas, bekräfta värdnamnet och DNS-konfigurationen. MongoDB dokumenterar en icke-SRV mongodb:// anslutningssträng som en möjlig lösning när miljön inte kan lösa upp SRV-poster, men du bör erhålla den standardanslutningssträngen från Atlas eller din distributionskonfiguration istället för att hitta på nodnamn. Se Atlas anslutningsfelsökning.

Den korrekta diagnostiska sekvensen kontrollerar adressen och nätverksvägen innan tidsgränsvärden behandlas som grundorsaken.

Steg 3: fixa URI:n för miljön där Node.js faktiskt körs

En syntaktiskt giltig MongoDB URI kan fortfarande peka på fel plats. Kontrollera schemat, värdnamnet, porten, databasnamnet, replikamängdskrav, autentiseringskällan och om värdnamnet är meningsfullt från applikationens nätverksnamnrymd.

Lokal Node.js och lokal MongoDB

Mongoose rekommenderar för närvarande 127.0.0.1 istället för localhost för lokal MongoDB:

await mongoose.connect('mongodb://127.0.0.1:27017/myapp');

Anledningen är Node.js 18 och nyare: Mongoose noterar att Node.js kan lösa upp localhost till IPv6 ::1, medan en lokal MongoDB-instans kan lyssna endast på IPv4. Mongoose dokumenterar också { family: 4 } som ett alternativ när IPv6-först-resolution gör anslutningsförsök långsamma:

await mongoose.connect('mongodb://localhost:27017/myapp', {
  family: 4
});

Använd family: 4 endast när IPv4/IPv6-resolutionsvägen faktiskt är problemet. Om din MongoDB-distribution stöder IPv6 korrekt, är det onödigt att tvinga IPv4.

Node.js inuti Docker

Om applikationen är inuti en container, refererar localhost till den containern, inte automatiskt till MongoDB på värden eller i en annan container. Använd MongoDB-tjänsten/container-värdnamnet på ett delat Docker-nätverk, eller den plattformsspecifika värdenadressen när MongoDB körs på värden.

Till exempel, med en Compose-tjänst namnad mongo:

MONGODB_URI=mongodb://mongo:27017/myapp

Villkor: detta exempel gäller endast om containrarna delar ett nätverk och MongoDB-tjänsten faktiskt är namnad mongo. Kopiera inte värdnamnet till en orelaterad distribution.

Atlas

Använd anslutningssträngen som genererats av Atlas för din drivrutin, bevara mongodb+srv://-värden exakt, URL-koda reserverade tecken i användarnamn eller lösenord när det krävs, och verifiera att databasanvändaren finns i det avsedda projektet.

Om du ansluter till en självhanterad replikamängd, måste värdnamnen som rapporteras av replikamängden också vara nåbara från klienten. En seed-värd kan vara nåbar medan senare serverval fortfarande misslyckas eftersom replikamängdsmedlemmar annonserar värdnamn som applikationen inte kan lösa upp eller dirigeras till.

Steg 4: justera tidsgränser endast efter att anslutningen lyckats

När DNS löser upp, nätverksvägen fungerar, servern är tillgänglig och URI:n är korrekt, blir tidsgränsjustering meningsfull.

Mongoose skickar tidsgränsrelaterade anslutningsalternativ till den underliggande MongoDB-drivrutinen, men varje alternativ styr ett annat stadium; större värden bör inte användas för att dölja en trasig väg eller otillgänglig server.

Ett konservativt exempel för en applikation som vill ha en 10-sekunders initial fel signal kan se ut så här:

await mongoose.connect(process.env.MONGODB_URI, {
  serverSelectionTimeoutMS: 10000,
  connectTimeoutMS: 10000
});

Huruvida 10 sekunder är lämpligt beror på distributionen. Avvägningen är enkel:

För socketTimeoutMS, använder den aktuella MongoDB Node.js-drivrutindokumentationen en standard på 0, vilket innebär ingen socket-inaktivitetstidsgräns. MongoDB rekommenderar, när du väljer att ställa in den, att välja ett värde ungefär två till tre gånger längre än den långsammaste operationen du förväntar dig. Den inställningen gäller för sockets som redan har anslutit, så det är inte den primära fixen för ett initialt servervalstidsavbrott.

Kopiera inte gamla Mongoose-anslutningsalternativ till ett aktuellt projekt

Många äldre exempel innehåller fortfarande useNewUrlParser, useUnifiedTopology, keepAlive eller keepAliveInitialDelay. Aktuellt Mongoose kräver inte de gamla parser-/topologi-opt-ins, och Mongoose dokumenterar keepAlive som aktiverat som standard sedan Mongoose 5.2 och föråldrat som ett anslutningsalternativ sedan 7.2.

En modern baslinje är avsiktligt liten:

import mongoose from 'mongoose';

await mongoose.connect(process.env.MONGODB_URI);

Lägg till anslutningsalternativ eftersom din miljö behöver dem, inte eftersom de dök upp i ett fem år gammalt kodutdrag.

Vad händer om anslutningen fungerar, men förfrågningar avbryts senare?

Det är ett annat problem. Om mongoose.connect() lyckas och applikationen senare hänger sig på förfrågningar, undersök operationslatens, anslutningspooltryck, serverbelastning, index och socket- eller operationstidsgränser. MongoDBs aktuella Node.js-drivrutin separerar:

• serverSelectionTimeoutMS — hitta en lämplig server.
• connectTimeoutMS — upprätta en TCP-anslutning.
• socketTimeoutMS — inaktivitet på ett etablerat socket.
• maxTimeMS — begränsa hur länge en serveroperation får köra när den når MongoDB.

Om endast långa förfrågningar misslyckas, är det osannolikt att ökning av serverSelectionTimeoutMS löser det verkliga problemet.

Snabb diagnos efter felvillkor

Ett produktionsvänligt anslutningsmönster

Håll hemligheter utanför källkoden, misslyckas vid start tydligt när databasen är otillgänglig, och logga tillräckligt med detaljer för diagnos utan att skriva ut autentiseringsuppgifter:

import mongoose from 'mongoose';

export async function connectDatabase() {
  const uri = process.env.MONGODB_URI;

  if (!uri) {
    throw new Error('MONGODB_URI is not set');
  }

  try {
    await mongoose.connect(uri, {
      serverSelectionTimeoutMS: 30000,
      connectTimeoutMS: 30000
    });

    console.log('MongoDB connected');
  } catch (err) {
    console.error('MongoDB connection failed:', err.message);
    console.error('Server selection reason:', err.reason);
    throw err;
  }
}

De 30-sekundersvärdena matchar aktuella dokumenterade standarder, så du kan utelämna dem om det inte hjälper dina operationer att göra policyn explicit. Den viktiga delen är inte siffrorna; det är att veta varför ett annat värde skulle vara bättre för din distribution.

Slutlig checklista

• Fånga det kompletta felet och inspektera err.reason.
• Bekräfta att MongoDB-distributionen körs och är tillgänglig.
• Kör DNS- och TCP-tester från samma miljö som Node.js-processen.
• För Atlas, verifiera att applikationens utgående IP finns på IP-åtkomstlistan.
• För mongodb+srv://, verifiera SRV DNS-resolution.
• För lokal MongoDB, prova 127.0.0.1 om localhost löser upp till oanvändbar IPv6.
• För Docker eller Kubernetes, använd ett värdnamn som är giltigt inuti den nätverksnamnrymden.
• Fixa TLS- eller autentiseringsfel istället för att maskera dem med en större tidsgräns.
• Justera serverSelectionTimeoutMS, connectTimeoutMS eller socketTimeoutMS endast för det stadium de faktiskt styr.
• Efter fixen, verifiera att applikationen ansluter konsekvent från den verkliga distributionsmiljön, inte bara från en utvecklarbärbar dator.

Slutsats

Om Mongoose rapporterar ett MongoDB-nätverksavbrott, bevisa först att drivrutinen kan upptäcka och nå en lämplig MongoDB-server. Atlas IP-begränsningar, brandväggar, DNS SRV-resolution, felaktiga container-värdnamn, IPv4/IPv6-mismatch, otillgängliga MongoDB-processer och TLS-konfiguration kan alla få ett 30-sekundersavbrott att se ut som problemet när timern bara rapporterar felet.

Använd tidsgränsinställningar för att definiera hur länge din applikation bör vänta på ett känd-god system – inte för att kompensera för en trasig anslutningsväg. När nätverkstillgänglighet och URI:n är korrekta, välj sedan tidsgränsvärden som matchar din tillgänglighetsmodell, failover-beteende och förväntad operationslatens.