Kako riješiti grešku mrežnog isteka vremena MongoDB u Mongoose vezi

Najvažnija ispravka je prestati tretirati svaki Mongoose istek kao problem s postavkama vremena isteka. Poruka poput MongoServerSelectionError: connection timed out obično znači da MongoDB upravljački program nije mogao odabrati upotrebljiv poslužitelj prije nego što je serverSelectionTimeoutMS istekao. Trenutna MongoDB dokumentacija za rješavanje problema navodi mrežnu povezanost, Atlasova ograničenja pristupa IP adresama, DNS SRV greške i TLS konfiguraciju kao česte uzroke. Povećanje vremena isteka može natjerati aplikaciju da čeka dulje bez popravka bilo kojeg od tih uvjeta.

Umjesto toga, koristite ovaj redoslijed: 1) identificirajte koji je istek zatajio, 2) dokažite da host aplikacije može doseći MongoDB, 3) ispravite niz za povezivanje ili adresu specifičnu za okruženje i 4) podesite vrijednosti vremena isteka tek nakon što je povezanost poznata kao funkcionalna. Primjeri u nastavku koriste moderne obrasce povezivanja Mongoosea i trenutno ponašanje MongoDB upravljačkog programa dokumentirano u rujnu 2026. godine.

Prvo, znajte na koji istek gledate

Mongoose koristi MongoDB Node.js upravljački program u pozadini, pa se nekoliko različitih postavki vremena isteka može pojaviti u istoj konfiguraciji veze. One ne znače isto.

Trenutna dokumentacija o povezivanju Mongoosea navodi da serverSelectionTimeoutMS ima zadanu vrijednost od 30 sekundi i primjenjuje se i na početni mongoose.connect() i na kasnije operacije koje trebaju odabrati poslužitelj. MongoDB dokumentacija opcija povezivanja Node.js upravljačkog programa razlikuje tu vrijednost od connectTimeoutMS i socketTimeoutMS.

Istek odabira poslužitelja je simptom koji treba prvo klasificirati; detalji o grešci i osnovni razlog korisniji su od trenutnog povećanja ograničenja od 30 sekundi.

Korak 1: zabilježite točnu Mongoose grešku i njezin osnovni razlog

Počnite s minimalnom vezom i zabilježite dovoljno informacija kako biste razlikovali DNS, provjeru autentičnosti, TLS i greške dostupnosti:

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);
}

Vrijednost od 5 sekundi gore je dijagnostički izbor, a ne preporuka za proizvodnju za svako uvođenje. Mongoose navodi da smanjenje serverSelectionTimeoutMS može pružiti brže povratne informacije, ali izričito upozorava protiv neopreznog smanjenja za replika setove jer zadani prozor od 30 sekundi može pomoći operacijama da prežive izbore i prebacivanje (failover). Mongoose lakše predlaže kraće vrijednosti za samostalni MongoDB ili serverless okruženja gdje je brzi neuspjeh koristan.

Tražite tragove kao što su:

• getaddrinfo ENOTFOUND — DNS ime se ne može riješiti.
• ECONNREFUSED — nešto je aktivno odbilo TCP vezu, često zato što ništa ne sluša na hostu/portu.
• ETIMEDOUT — pokušaj povezivanja nije dovršen na vrijeme, često zato što je promet filtriran, pogrešno usmjeren ili odredište nedostupno.
• TLS ili tekst certifikata — istražite povjerenje u certifikat, podudaranje imena hosta, podršku za protokol ili TLS konfiguraciju.
• Greške provjere autentičnosti unutar err.reason — ispravite vjerodajnice ili authSource umjesto mijenjanja mrežnih vremena isteka.

Uvjet: ako greška već kaže da je provjera autentičnosti neuspjela, preskočite podešavanje vatrozida dok vjerodajnice i baza za provjeru autentičnosti nisu ispravne. Mrežni istek i odbijena prijava su različite klase neuspjeha.

Korak 2: dokažite mrežu, Atlasov pristup IP adresi i DNS iz istog okruženja

Pokrenite testove povezanosti s istog računala, spremnika, VM-a, serverless funkcije ili Kubernetes poda na kojem se izvodi Node.js proces. Testiranje s vašeg prijenosnog računala nije dovoljno ako se proizvodnja izvodi negdje drugdje.

Za Atlas, provjerite je li stvarna izlazna IP adresa aplikacije dopuštena; za lokalnu implementaciju, provjerite sluša li MongoDB proces zapravo na očekivanom sučelju i portu.

Ako koristite MongoDB Atlas

Atlas prihvaća klijentske veze samo s adresa koje su dopuštene na popisu pristupa IP adresama projekta. MongoDB to dokumentira u Upravljanje popisom pristupa IP adresama. Provjerite je li javna izlazna IP adresa okruženja aplikacije navedena, a ne samo IP adresa vaše osobne radne stanice.

MongoDB vodič za rješavanje problema s istekom odabira poslužitelja također preporučuje provjeru izlazne TCP povezanosti s MongoDBom na portu 27017, zajedno s vatrozidima, sigurnosnim grupama, mrežnim ACL-ovima, VPN-ovima i proxy poslužiteljima.

Na primjer, s Linuxa ili macOS-a možete testirati određeni Atlas čvor ili samoupravljani host s:

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

U Windows PowerShellu, grub test TCP dostupnosti je:

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

Uspješan TCP test ne dokazuje da će provjera autentičnosti ili TLS uspjeti, ali neuspješan TCP test znači da je podešavanje Mongoose vremena isteka prijevremeno.

Ako vaš URI koristi mongodb+srv://

Niz za povezivanje SRV ovisi o DNS SRV zapisima. Trenutni MongoDB koraci za rješavanje problema preporučuju provjeru SRV pretrage iz okruženja klijenta:

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

Ako SRV upit ne uspije, potvrdite ime hosta i DNS konfiguraciju. MongoDB dokumentira ne-SRV mongodb:// niz za povezivanje kao moguće zaobilazno rješenje kada okruženje ne može riješiti SRV zapise, ali taj standardni niz za povezivanje trebate dobiti iz Atlasa ili konfiguracije implementacije, a ne izmišljati imena čvorova. Pogledajte Rješavanje problema s povezivanjem Atlasa.

Točan dijagnostički slijed provjerava adresu i mrežni put prije nego što tretira vrijednosti vremena isteka kao osnovni uzrok.

Korak 3: ispravite URI za okruženje u kojem se Node.js stvarno izvodi

Sintaktički ispravan MongoDB URI i dalje može ukazivati na pogrešno mjesto. Provjerite shemu, ime hosta, port, ime baze podataka, zahtjeve replika seta, izvor provjere autentičnosti i je li ime hosta smisleno iz mrežnog prostora aplikacije.

Lokalni Node.js i lokalni MongoDB

Mongoose trenutno preporučuje 127.0.0.1 umjesto localhost za lokalni MongoDB:

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

Razlog je Node.js 18 i noviji: Mongoose napominje da Node.js može riješiti localhost na IPv6 ::1, dok lokalna instanca MongoDBa možda sluša samo na IPv4. Mongoose također dokumentira { family: 4 } kao opciju kada IPv6-prvo rješavanje usporava pokušaje povezivanja:

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

Koristite family: 4 samo kada je put rješavanja IPv4/IPv6 stvarno problem. Ako vaša MongoDB implementacija ispravno podržava IPv6, prisiljavanje IPv4 nije potrebno.

Node.js unutar Dockera

Ako je aplikacija unutar spremnika, localhost se odnosi na taj spremnik, a ne automatski na MongoDB na hostu ili u drugom spremniku. Koristite ime hosta MongoDB usluge/spremnika na zajedničkoj Docker mreži ili adresu hosta specifičnu za platformu kada MongoDB radi na hostu.

Na primjer, s Compose uslugom nazvanom mongo:

MONGODB_URI=mongodb://mongo:27017/myapp

Uvjet: ovaj primjer se primjenjuje samo ako spremnici dijele mrežu i ako je MongoDB usluga stvarno nazvana mongo. Nemojte kopirati ime hosta u nepovezanu implementaciju.

Atlas

Koristite niz za povezivanje koji generira Atlas za vaš upravljački program, sačuvajte mongodb+srv:// host točno onako kako jest, URL-kodirajte rezervirane znakove u korisničkim imenima ili lozinkama kada je potrebno i provjerite postoji li korisnik baze podataka u namijenjenom projektu.

Ako se povezujete na samoupravljani replika set, imena hosta koja prijavljuje replika set također moraju biti dostupna klijentu. Seed host može biti dostupan, ali kasniji odabir poslužitelja i dalje ne uspijeva jer članovi replika seta oglašavaju imena hosta koja aplikacija ne može riješiti ili usmjeriti.

Korak 4: podesite isteka samo nakon što povezanost uspije

Jednom kada DNS riješi adresu, mrežni put radi, poslužitelj je dostupan i URI je ispravan, podešavanje vremena isteka postaje smisleno.

Mongoose prosljeđuje opcije povezivanja povezane s vremenom isteka osnovnom MongoDB upravljačkom programu, ali svaka opcija kontrolira različitu fazu; veće vrijednosti ne bi trebalo koristiti za skrivanje pokvarenog puta ili nedostupnog poslužitelja.

Konzervativan primjer za aplikaciju koja želi signal početnog neuspjeha nakon 10 sekundi mogao bi izgledati ovako:

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

Je li 10 sekundi prikladno ovisi o implementaciji. Kompromis je jednostavan:

Za socketTimeoutMS, trenutna dokumentacija MongoDB Node.js upravljačkog programa koristi zadanu vrijednost 0, što znači da nema isteka neaktivnosti socket veze. MongoDB preporučuje, kada odlučite postaviti tu vrijednost, odabrati vrijednost otprilike dva do tri puta dužu od najsporije operacije koju očekujete. Ta postavka se primjenjuje na sockete koji su se već povezali, pa nije primarna ispravka za početni istek odabira poslužitelja.

Nemojte kopirati stare Mongoose opcije povezivanja u trenutni projekt

Mnogi stariji primjeri i dalje sadrže useNewUrlParser, useUnifiedTopology, keepAlive ili keepAliveInitialDelay. Trenutni Mongoose ne zahtijeva stare opt-in opcije za parser/topologiju, a Mongoose dokumentira keepAlive kao omogućen po zadanoj vrijednosti od Mongoose 5.2 i zastario kao opcija povezivanja od verzije 7.2.

Moderna osnovna linija je namjerno mala:

import mongoose from 'mongoose';

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

Dodajte opcije povezivanja jer ih vaše okruženje treba, a ne zato što su se pojavile u isječku starom pet godina.

Što ako veza radi, ali upiti kasnije isteknu?

To je drugačiji problem. Ako mongoose.connect() uspije i aplikacija kasnije zastane na upitima, istražite latenciju operacija, pritisak na bazen veza, opterećenje poslužitelja, indekse i isteka socket ili operacija. Trenutni MongoDB Node.js upravljački program razdvaja:

• serverSelectionTimeoutMS — pronalaženje prikladnog poslužitelja.
• connectTimeoutMS — uspostava jedne TCP veze.
• socketTimeoutMS — neaktivnost na uspostavljenoj socket vezi.
• maxTimeMS — ograničavanje koliko dugo serverska operacija može trajati kada stigne do MongoDBa.

Ako samo dugi upiti ne uspijevaju, povećanje serverSelectionTimeoutMS vjerojatno neće riješiti stvarni problem.

Brza dijagnostika prema uvjetu greške

Obrazac povezivanja prilagođen proizvodnji

Držite tajne izvan izvornog koda, jasno neuspješno pokrenite aplikaciju kada je baza podataka nedostupna i zabilježite dovoljno detalja za dijagnostiku bez ispisivanja vjerodajnica:

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;
  }
}

Tih 30 sekundi odgovara trenutnim dokumentiranim zadanim vrijednostima, pa ih možete izostaviti osim ako eksplicitno navođenje politike ne pomaže vašim operacijama. Važan dio nisu brojevi; važno je znati zašto bi drugačiji broj bio bolji za vašu implementaciju.

Konačni popis provjera

• Zabilježite potpunu grešku i pregledajte err.reason.
• Potvrdite radi li MongoDB implementacija i je li dostupna.
• Pokrenite DNS i TCP testove iz istog okruženja kao i Node.js proces.
• Za Atlas, provjerite je li izlazna IP adresa aplikacije na popisu pristupa IP adresama.
• Za mongodb+srv://, provjerite SRV DNS rješavanje.
• Za lokalni MongoDB, pokušajte s 127.0.0.1 ako se localhost rješava na neupotrebljiv IPv6.
• Za Docker ili Kubernetes, koristite ime hosta koje je valjano unutar tog mrežnog prostora.
• Ispravite TLS ili greške provjere autentičnosti umjesto da ih maskirate većim vremenom isteka.
• Podesite serverSelectionTimeoutMS, connectTimeoutMS ili socketTimeoutMS samo za fazu koju stvarno kontroliraju.
• Nakon ispravke, provjerite povezuje li se aplikacija dosljedno iz stvarnog okruženja implementacije, a ne samo s prijenosnog računala programera.

Zaključak

Ako Mongoose prijavi mrežni istek MongoDBa, prvo dokažite da upravljački program može otkriti i doseći prikladan MongoDB poslužitelj. Atlasova ograničenja IP adresa, vatrozidi, DNS SRV rješavanje, netočna imena hostova spremnika, neslaganja IPv4/IPv6, nedostupni MongoDB procesi i TLS konfiguracija mogu sve učiniti da se istek od 30 sekundi čini problemom kada mjerač samo prijavljuje neuspjeh.

Koristite postavke vremena isteka da definirate koliko dugo vaša aplikacija treba čekati na poznato ispravan sustav, a ne da kompenzirate pokvareni put veze. Kada su mrežna dostupnost i URI ispravni, tada odaberite vrijednosti vremena isteka koje odgovaraju vašem modelu dostupnosti, ponašanju pri prebacivanju i očekivanoj latenciji operacija.