Kako odpraviti napako omrežnega časovnega prekoraka MongoDB v povezavi Mongoose

Najpomembnejša rešitev je, da ne obravnavate vsake časovne napake Mongoose kot težavo z nastavitvami časovnega prekoraka. Sporočilo, kot je MongoServerSelectionError: connection timed out, običajno pomeni, da gonilnik MongoDB ni mogel izbrati uporabnega strežnika, preden je potekel serverSelectionTimeoutMS. Trenutna dokumentacija za odpravljanje težav MongoDB navaja omrežno povezljivost, omejitve dostopa do IP naslovov v Atlasu, napake DNS SRV in konfiguracijo TLS kot pogoste vzroke. Povečanje časovnega prekoraka lahko povzroči, da aplikacija dlje čaka, ne da bi popravila katerokoli od teh stanj.

Uporabite naslednji vrstni red: 1) identificirajte, kateri časovni prekorak je odpovedal, 2) dokažite, da gostiteljski računalnik aplikacije lahko doseže MongoDB, 3) popravite niz za povezavo ali naslov, specifičen za okolje, in 4) prilagodite vrednosti časovnega prekoraka šele, ko je znano, da povezljivost deluje. Spodnji primeri uporabljajo sodobne vzorce povezave Mongoose in trenutno vedenje gonilnika MongoDB, dokumentirano septembra 2026.

Najprej vedite, kateri časovni prekorak opazujete

Mongoose v ozadju uporablja gonilnik MongoDB za Node.js, zato se v isti konfiguraciji povezave lahko pojavijo različne nastavitve časovnega prekoraka. Te ne pomenijo istega.

Trenutna dokumentacija o povezavah Mongoose navaja, da je privzeta vrednost za serverSelectionTimeoutMS 30 sekund in da velja tako za začetni mongoose.connect() kot za kasnejše operacije, ki zahtevajo izbiro strežnika. Dokumentacija gonilnika MongoDB za Node.js o možnostih povezave razlikuje to vrednost od connectTimeoutMS in socketTimeoutMS.

Časovni prekorak izbire strežnika je simptom, ki ga je treba najprej klasificirati; podrobnosti napake in osnovni razlog so koristnejši kot takojšnje povečanje 30-sekundne omejitve.

Korak 1: zajemite natančno napako Mongoose in njen osnovni razlog

Začnite z minimalno povezavo in zabeležite dovolj informacij, da razlikujete med napakami DNS, preverjanja pristnosti, TLS in dosegljivosti:

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

Zgornja vrednost 5 sekund je diagnostična izbira, ne priporočilo za proizvodnjo za vsako namestitev. Mongoose navaja, da zmanjšanje serverSelectionTimeoutMS lahko pospeši povratne informacije, vendar posebej opozarja proti neumnemu zmanjševanju za repliške, ker lahko privzeto 30-sekundno okno pomaga operacijam preživeti izbire in preklope. Mongoose lažje predlaga krajše vrednosti za samostojni MongoDB ali strežniške okolice brez strežnika (serverless), kjer je hitra napaka koristna.

Iščite namige, kot so:

• getaddrinfo ENOTFOUND — DNS ime ni mogoče razrešiti.
• ECONNREFUSED — nekaj je aktivno zavrnilo TCP povezavo, pogosto zato, ker na gostitelju/vratih nič ne posluša.
• ETIMEDOUT — poskus povezave ni bil dokončan v roku, pogosto zato, ker je promet filtriran, napačno usmerjen ali cilj nedostopen.
• Besedilo o TLS ali certifikatu — preverite zaupanje v certifikat, ujemanje imena gostitelja, podporo protokolu ali konfiguracijo TLS.
• Napake preverjanja pristnosti znotraj err.reason — popravite poverilnice ali authSource namesto spreminjanja omrežnih časovnih prekorakov.

Pogoj: če napaka že navaja, da je preverjanje pristnosti spodletelo, preskočite prilagajanje požarnega zidu, dokler poverilnice in baza za preverjanje pristnosti niso pravilne. Omrežni časovni prekorak in zavrnjena prijava sta različni vrsti napak.

Korak 2: dokažite omrežno povezljivost, dostop do IP v Atlasu in DNS iz istega okolja za izvajanje

Izvedite teste povezljivosti z istega računalnika, kontejnerja, VM, funkcije brez strežnika ali poda Kubernetes, kjer teče proces Node.js. Testiranje z vašega prenosnika ni dovolj, če proizvodnja teče nekje drugje.

Za Atlas preverite, ali je dejanski izhodni IP aplikacije dovoljen; za lokalno namestitev preverite, ali proces MongoDB dejansko posluša na pričakovanem vmesniku in vratih.

Če uporabljate MongoDB Atlas

Atlas sprejema povezave odjemalcev samo z naslovov, ki so dovoljeni na seznamu dostopa do IP projekta. MongoDB to dokumentira v Upravljanje seznama dostopa do IP. Prepričajte se, da je javni izhodni IP okolja aplikacije na seznamu, ne le IP vašega osebnega delovnega računalnika.

Vodnik za odpravljanje težav s časovnim prekorakom izbire strežnika MongoDB priporoča tudi preverjanje izhodne TCP povezljivosti do MongoDB na vratih 27017, skupaj s požarnimi zidi, varnostnimi skupinami, mrežnimi ACL, VPN in proxyji.

Na primer, iz Linuxa ali macOS lahko testirate določen vozel Atlas ali samoupravljani gostitelj z:

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

V PowerShellu za Windows je grob test TCP dosegljivosti:

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

Uspešen TCP test ne dokazuje, da bosta preverjanje pristnosti ali TLS uspela, vendar neuspešen TCP test pomeni, da je prilagajanje časovnega prekoraka Mongoose prezgodnje.

Če vaš URI uporablja mongodb+srv://

Niz za povezavo SRV je odvisen od zapisov DNS SRV. Trenutni koraki za odpravljanje težav MongoDB priporočajo preverjanje iskanja SRV iz okolja odjemalca:

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

Če poizvedba SRV spodleti, potrdite ime gostitelja in konfiguracijo DNS. MongoDB dokumentira niz za povezavo mongodb:// brez SRV kot možno zaobid, kadar okolje ne more razrešiti zapisov SRV, vendar morate ta standardni niz za povezavo pridobiti iz Atlasa ali konfiguracije namestitve, ne pa izmišljati imen vozlov. Glejte Odpravljanje težav s povezavo v Atlasu.

Pravilno diagnostično zaporedje preveri naslov in omrežno pot, preden vrednosti časovnega prekoraka obravnava kot koren vzroka.

Korak 3: popravite URI za okolje, kjer dejansko teče Node.js

Sintaktično veljaven URI MongoDB je lahko še vedno usmerjen na napačno mesto. Preverite shemo, ime gostitelja, vrata, ime baze, zahteve repliške, vir preverjanja pristnosti in ali je ime gostitelja smiselno iz omrežnega prostora aplikacije.

Lokalni Node.js in lokalni MongoDB

Mongoose trenutno priporoča 127.0.0.1 namesto localhost za lokalni MongoDB:

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

Razlog je Node.js 18 in novejši: Mongoose navaja, da lahko Node.js razreši localhost na IPv6 ::1, medtem ko lokalni primerek MongoDB morda posluša samo na IPv4. Mongoose tudi dokumentira { family: 4 } kot možnost, ko razreševanje, ki daje prednost IPv6, upočasni poskuse povezave:

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

Uporabite family: 4 samo, ko je pot razreševanja IPv4/IPv6 dejansko težava. Če vaša namestitev MongoDB pravilno podpira IPv6, je prisilna uporaba IPv4 nepotrebna.

Node.js znotraj Dockerja

Če je aplikacija znotraj kontejnerja, se localhost nanaša na ta kontejner, ne samodejno na MongoDB na gostitelju ali v drugem kontejnerju. Uporabite ime gostitelja storitve/kontejnerja MongoDB na skupnem omrežju Docker ali naslov gostitelja, specifičen za platformo, kadar MongoDB teče na gostitelju.

Na primer, s storitvijo Compose z imenom mongo:

MONGODB_URI=mongodb://mongo:27017/myapp

Pogoj: ta primer velja samo, če si kontejnerji delijo omrežje in je storitev MongoDB dejansko poimenovana mongo. Ne kopirajte imena gostitelja v nepovezano namestitev.

Atlas

Uporabite niz za povezavo, ki ga je ustvaril Atlas za vaš gonilnik, ohranite gostitelja mongodb+srv:// natančno, kodirajte rezervirane znake v uporabniških imenih ali geslih z URL kodiranjem, kadar je to potrebno, in preverite, ali uporabnik baze obstaja v namenjenem projektu.

Če se povezujete na samoupravljani replišek, morajo biti tudi imena gostiteljev, ki jih poroča replišek, dosegljiva iz odjemalca. Začetni gostitelj je lahko dosegljiv, kasnejša izbira strežnika pa še vedno spodleti, ker člani repliška oglašujejo imena gostiteljev, ki jih aplikacija ne more razrešiti ali usmeriti.

Korak 4: prilagodite časovne prekorake šele, ko povezljivost uspe

Ko DNS razreši, omrežna pot deluje, strežnik je na voljo in URI je pravilen, postane prilagajanje časovnega prekoraka smiselno.

Mongoose posreduje možnosti povezave, povezane s časovnim prekorakom, osnovnemu gonilniku MongoDB, vendar vsaka možnost nadzoruje drugačno stopnjo; večje vrednosti ne smete uporabljati za skrivanje pokvarjene poti ali nedostopnega strežnika.

Konservativen primer za aplikacijo, ki želi 10-sekundni signal za začetno napako, je lahko videti takole:

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

Ali je 10 sekund primerno, je odvisno od namestitve. Kompromis je preprost:

Za socketTimeoutMS trenutna dokumentacija gonilnika MongoDB za Node.js uporablja privzeto vrednost 0, kar pomeni brez časovnega prekoraka neaktivnosti vtičnice. MongoDB priporoča, da kadar se odločite za nastavitev, izberete vrednost, ki je približno dvakrat do trikrat daljša od najpočasnejše operacije, ki jo pričakujete. Ta nastavitev velja za vtičnice, ki so že vzpostavile povezavo, zato ni primarna rešitev za začetni časovni prekorak izbire strežnika.

Ne kopirajte starih možnosti povezave Mongoose v trenutni projekt

Mnogi starejši primeri še vedno vsebujejo useNewUrlParser, useUnifiedTopology, keepAlive ali keepAliveInitialDelay. Trenutni Mongoose ne zahteva starih izbir za parser/topologijo, Mongoose pa dokumentira keepAlive kot privzeto omogočenega od Mongoose 5.2 in opuščenega kot možnosti povezave od 7.2.

Sodobna osnova je namenoma majhna:

import mongoose from 'mongoose';

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

Dodajte možnosti povezave, ker jih vaše okolje potrebuje, ne zato, ker so se pojavile v pred pet let napisanem odseku kode.

Kaj pa, če povezava deluje, a poizvedbe kasneje dosežejo časovni prekorak?

To je drugačen problem. Če mongoose.connect() uspe in aplikacija kasneje zastane pri poizvedbah, preverite zakasnitev operacij, pritisk na bazen povezav, obremenitev strežnika, indekse ter časovne prekorake vtičnic ali operacij. Trenutni gonilnik MongoDB za Node.js loči:

• serverSelectionTimeoutMS — iskanje ustreznega strežnika.
• connectTimeoutMS — vzpostavitev ene TCP povezave.
• socketTimeoutMS — neaktivnost na vzpostavljeni vtičnici.
• maxTimeMS — omejitev, kako dolgo lahko strežniška operacija teče, ko doseže MongoDB.

Če odpovedo samo dolge poizvedbe, povečanje serverSelectionTimeoutMS verjetno ne bo rešilo prave težave.

Hitra diagnoza glede na stanje napake

Vzorec povezave, prijazen do proizvodnje

Tajne hranite zunaj izvorne kode, jasno odpovejte zagon, ko baza ni na voljo, in zabeležite dovolj podrobnosti za diagnozo brez tiskanja poverilnic:

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

Tiste 30-sekundne vrednosti ustrezajo trenutnim dokumentiranim privzetim vrednostim, zato jih lahko izpustite, razen če vam jasna politika pomaga pri operacijah. Pomemben del niso številke; pomembno je vedeti, zakaj bi bilo drugo število boljše za vašo namestitev.

Končni kontrolni seznam

• Zajemite celotno napako in preglejte err.reason.
• Potrdite, da namestitev MongoDB teče in je na voljo.
• Izvedite teste DNS in TCP iz istega okolja kot proces Node.js.
• Za Atlas preverite, ali je izhodni IP aplikacije na seznamu dostopa do IP.
• Za mongodb+srv:// preverite razreševanje DNS SRV.
• Za lokalni MongoDB poskusite 127.0.0.1, če localhost razreši na neuporaben IPv6.
• Za Docker ali Kubernetes uporabite ime gostitelja, ki je veljavno znotraj tega omrežnega prostora.
• Popravite napake TLS ali preverjanja pristnosti namesto da bi jih maskirali z večjim časovnim prekorakom.
• Prilagodite serverSelectionTimeoutMS, connectTimeoutMS ali socketTimeoutMS samo za stopnjo, ki jo dejansko nadzorujejo.
• Po popravilu preverite, ali se aplikacija dosledno povezuje iz dejanskega proizvodnega okolja, ne le z razvijalčevega prenosnika.

Zaključek

Če Mongoose poroča o omrežnem časovnem prekoraku MongoDB, najprej dokažite, da gonilnik lahko odkrije in doseže ustrezen strežnik MongoDB. Omejitve IP v Atlasu, požarni zidi, razreševanje DNS SRV, napačna imena gostiteljev kontejnerjev, neskladja IPv4/IPv6, nedostopni procesi MongoDB in konfiguracija TLS lahko vsi povzročijo, da se 30-sekundni časovni prekorak zdi kot težava, čeprav časovnik samo poroča o napaki.

Nastavitve časovnega prekoraka uporabite za določanje, kako dolgo naj aplikacija čaka na znano delujoč sistem – ne za kompenzacijo pokvarjene poti povezave. Ko sta omrežna dosegljivost in URI pravilna, nato izberite vrednosti časovnega prekoraka, ki ustrezajo vašemu modelu razpoložljivosti, obnašanju ob preklopu in pričakovani zakasnitvi operacij.