Hogyan javítsuk meg a MongoDB hálózati időtúllépési hibát a Mongoose kapcsolódásnál

A legfontosabb javítás, hogy ne tekintsünk minden Mongoose időtúllépést időtúllépési beállítási problémának. Egy olyan üzenet, mint a MongoServerSelectionError: connection timed out, általában azt jelenti, hogy a MongoDB illesztőprogram nem tudott használható szervert kiválasztani a serverSelectionTimeoutMS lejárta előtt. A MongoDB jelenlegi hibaelhárítási dokumentációja a hálózati kapcsolódást, az Atlas IP-hozzáférési korlátozásait, a DNS SRV hibákat és a TLS konfigurációt sorolja fel gyakori okként. Az időtúllépés növelése arra kényszerítheti az alkalmazást, hogy tovább várjon anélkül, hogy bármelyik feltételt javítaná.

Használja inkább ezt a sorrendet: 1) azonosítsa, melyik időtúllépés lépett fel, 2) bizonyítsa be, hogy az alkalmazás gazdagépe eléri a MongoDB-t, 3) javítsa meg a kapcsolati karakterláncot vagy a környezetspecifikus címet, és 4) állítsa be az időtúllépési értékeket csak akkor, ha a kapcsolódás működése ismert. Az alábbi példák modern Mongoose kapcsolódási mintákat és a 2026 szeptemberében dokumentált aktuális MongoDB illesztőprogram viselkedést használják.

Először tudja meg, milyen időtúllépésről van szó

A Mongoose a MongoDB Node.js illesztőprogramot használja az alapokon, így több különböző időtúllépési beállítás is megjelenhet ugyanabban a kapcsolati konfigurációban. Ezek nem ugyanazt jelentik.

A Mongoose jelenlegi kapcsolati dokumentációja kimondja, hogy a serverSelectionTimeoutMS alapértelmezett értéke 30 másodperc, és ez vonatkozik mind a kezdeti mongoose.connect() hívásra, mind a későbbi, szervert kiválasztó műveletekre. A MongoDB Node.js illesztőprogram kapcsolati beállításainak dokumentációja megkülönbözteti ezt az értéket a connectTimeoutMS és a socketTimeoutMS értékektől.

A szerverválasztási időtúllépés az első tünet, amelyet osztályozni kell; a hiba részletei és az alapul szolgáló ok hasznosabb, mint azonnal növelni a 30 másodperces korlátot.

1. lépés: rögzítse a pontos Mongoose hibát és annak alapul szolgáló okát

Kezdjen egy minimális kapcsolattal, és naplózzon elegendő információt a DNS, a hitelesítés, a TLS és az elérhetőségi hibák megkülönböztetéséhez:

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

A fenti 5 másodperces érték egy diagnosztikai választás, nem pedig minden telepítésre vonatkozó éles környezeti ajánlás. A Mongoose azt mondja, hogy a serverSelectionTimeoutMS csökkentése gyorsabb visszajelzést adhat, de kifejezetten figyelmeztet, hogy ne csökkentse azt gondatlanul replikakészletek esetén, mert az alapértelmezett 30 másodperces ablak segíthet a műveleteknek túlélni a választásokat és a hibakereséseket. A Mongoose rövidebb értékeket javasol könnyebben önálló MongoDB vagy szerverless futtatókörnyezetek esetén, ahol a gyors hiba sikeres lehet.

Keressen olyan nyomokat, mint:

• getaddrinfo ENOTFOUND — a DNS név nem oldható fel.
• ECONNREFUSED — valami aktívan elutasította a TCP kapcsolatot, gyakran azért, mert semmi sem figyel a gazdagépen/porton.
• ETIMEDOUT — a kapcsolódási kísérlet nem fejeződött be időben, gyakran azért, mert a forgalom szűrt, helytelenül útvonalazott, vagy a cél nem érhető el.
• TLS vagy tanúsítvány szöveg — vizsgálja meg a tanúsítvány megbízhatóságát, a gazdagépnév egyezését, a protokoll támogatását vagy a TLS konfigurációt.
• Hitelesítési hibák az err.reason belsejében — javítsa a hitelesítő adatokat vagy az authSource-t, ahelyett, hogy a hálózati időtúllépéseket változtatná meg.

Feltétel: ha a hiba már azt mondja, hogy a hitelesítés sikertelen, hagyja ki a tűzfal hangolását, amíg a hitelesítő adatok és az hitelesítési adatbázis helyesek nem lesznek. A hálózati időtúllépés és az elutasított bejelentkezés különböző hibaosztályok.

2. lépés: bizonyítsa be a hálózat, az Atlas IP-hozzáférés és a DNS működését ugyanabból a futtatókörnyezetből

Futtasson kapcsolódási teszteket ugyanarról a gépről, konténerből, VM-ről, szerverless függvényből vagy Kubernetes podból, ahol a Node.js folyamat fut. A laptopról végzett tesztelés nem elég, ha az éles környezet máshol fut.

Atlas esetén ellenőrizze, hogy az alkalmazás valódi kimeneti IP-címe engedélyezett-e; helyi telepítés esetén ellenőrizze, hogy a MongoDB folyamat valóban a várt interfészen és porton figyel-e.

Ha MongoDB Atlas-t használ

Az Atlas csak olyan címekről fogad ügyfélkapcsolatokat, amelyeket a projekt IP-hozzáférési listája engedélyez. A MongoDB ezt a IP-hozzáférési lista kezelése című dokumentációban írja le. Győződjön meg róla, hogy az alkalmazási környezet nyilvános kimeneti IP-címe szerepel a listán, nem csupán a személyes munkállomás IP-címe.

A MongoDB szerverválasztási időtúllépés hibaelhárítási útmutatója azt is javasolja, hogy ellenőrizze a kimenő TCP kapcsolódást a MongoDB 27017-es portjára, valamint a tűzfalakat, biztonsági csoportokat, hálózati ACL-eket, VPN-eket és proxykat.

Például Linux vagy macOS rendszeren tesztelhet egy konkrét Atlas csomópontot vagy önállóan kezelt gazdagépet a következő paranccsal:

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

Windows PowerShellben egy durva TCP elérhetőségi teszt a következő:

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

Egy sikeres TCP teszt nem bizonyítja, hogy a hitelesítés vagy a TLS is sikeres lesz, de egy sikertelen TCP teszt azt jelenti, hogy a Mongoose időtúllépés hangolása korai.

Ha az URI mongodb+srv:// formátumot használ

Egy SRV kapcsolati karakterlánc DNS SRV rekordokra támaszkodik. A MongoDB jelenlegi hibaelhárítási lépései azt javasolják, hogy ellenőrizze az SRV lekérdezést az ügyfél környezetéből:

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

Ha az SRV lekérdezés sikertelen, erősítse meg a gazdagépnevet és a DNS konfigurációt. A MongoDB dokumentálja a nem-SRV mongodb:// kapcsolati karakterláncot lehetséges kerülő megoldásként, amikor a környezet nem tudja feloldani az SRV rekordokat, de ezt a szabványos kapcsolati karakterláncot az Atlasból vagy a telepítési konfigurációból kell beszereznie, ahelyett, hogy kitalálná a csomópontneveket. Lásd: Atlas kapcsolódási hibaelhárítás.

A helyes diagnosztikai sorrend ellenőrzi a címet és a hálózati útvonalat, mielőtt az időtúllépési értékeket kezelné gyökéroként.

3. lépés: javítsa meg az URI-t arra a környezetre, ahol a Node.js valóban fut

Egy szintaktikailag érvényes MongoDB URI még mindig rossz helyre mutathat. Ellenőrizze a sémát, a gazdagépnevet, a portot, az adatbázis nevét, a replikakészlet követelményeit, a hitelesítési forrást, és azt, hogy a gazdagépnév értelmes-e az alkalmazás hálózati névtéréből.

Helyi Node.js és helyi MongoDB

A Mongoose jelenleg a 127.0.0.1 használatát ajánlja a localhost helyett helyi MongoDB esetén:

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

Az ok a Node.js 18 és újabb verziók: a Mongoose megjegyzi, hogy a Node.js a localhost-ot IPv6 ::1-re oldhatja fel, míg egy helyi MongoDB példány csak IPv4-en figyelhet. A Mongoose dokumentálja a { family: 4 } opciót is, amikor az IPv6 előnyben részesített feloldás lassú kapcsolódási kísérleteket eredményez:

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

Használja a family: 4 opciót csak akkor, ha az IPv4/IPv6 feloldási útvonal valóban a probléma. Ha a MongoDB telepítése helyesen támogatja az IPv6-ot, az IPv4 kényszerítése felesleges.

Node.js Dockerben

Ha az alkalmazás konténerben fut, a localhost arra a konténerre utal, nem automatikusan a gazdagépen vagy egy másik konténerben lévő MongoDB-re. Használja a MongoDB szolgáltatás/konténer gazdagépnevét egy közös Docker hálózaton, vagy a platformspecifikus gazdagép-címet, amikor a MongoDB a gazdagépen fut.

Például egy mongo nevű Compose szolgáltatással:

MONGODB_URI=mongodb://mongo:27017/myapp

Feltétel: ez a példa csak akkor alkalmazható, ha a konténerek megosztanak egy hálózatot, és a MongoDB szolgáltatás valóban mongo néven fut. Ne másolja a gazdagépnevet egy kapcsolódó nem kapcsolódó telepítésbe.

Atlas

Használja az Atlas által generált kapcsolati karakterláncot az illesztőprogramjához, őrizze meg a mongodb+srv:// gazdagépnevet pontosan, URL-kódolja a foglalt karaktereket a felhasználónevekben vagy jelszavakban, ha szükséges, és ellenőrizze, hogy az adatbázis-felhasználó létezik-e a kívánt projektben.

Ha önállóan kezelt replikakészlethez csatlakozik, a replikakészlet által jelentett gazdagépneveknek is elérhetőnek kell lenniük az ügyfél számára. Egy maggazdagép elérhető lehet, miközben a későbbi szerverválasztás továbbra is sikertelen, mert a replikakészlet tagjai olyan gazdagépneveket hirdetnek, amelyeket az alkalmazás nem tud feloldani vagy útvonalazni.

4. lépés: állítsa be az időtúllépéseket csak a kapcsolódás sikere után

Amint a DNS feloldódik, a hálózati útvonal működik, a szerver elérhető, és az URI helyes, az időtúllépés hangolása értelmes lesz.

A Mongoose az időtúllépéssel kapcsolatos kapcsolati beállításokat továbbítja az alapul szolgáló MongoDB illesztőprogramnak, de minden opció egy másik szakaszt szabályoz; a nagyobb értékeket nem szabad arra használni, hogy elrejtsenek egy törött útvonalat vagy egy hozzáférhetetlen szervert.

Egy konzervatív példa egy olyan alkalmazáshoz, amely 10 másodperces kezdeti hiba jelzést szeretne, így nézhet ki:

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

Hogy a 10 másodperc megfelelő-e, a telepítéstől függ. A kompromisszum egyértelmű:

A socketTimeoutMS esetén a jelenlegi MongoDB Node.js illesztőprogram dokumentációja 0 alapértelmezett értéket használ, ami socket inaktivitási időtúllépés hiányát jelenti. A MongoDB azt javasolja, amikor úgy dönt, hogy beállítja, válasszon egy értéket, amely körülbelül kétszer-háromszor hosszabb, mint a leglassabb várt művelet. Ez a beállítás már csatlakozott socketekre vonatkozik, így nem ez az elsődleges javítás egy kezdeti szerverválasztási időtúllépésre.

Ne másoljon régi Mongoose kapcsolati beállításokat egy aktuális projektbe

Sok régebbi példa még mindig tartalmaz useNewUrlParser, useUnifiedTopology, keepAlive vagy keepAliveInitialDelay beállításokat. A jelenlegi Mongoose nem igényli a régi parser/topológia opt-in beállításokat, és a Mongoose dokumentálja a keepAlive-t, mint alapértelmezetten engedélyezett a Mongoose 5.2 óta, és elavult kapcsolati opcióként a 7.2 óta.

Egy modern alapértelmezett szándékosan kicsi:

import mongoose from 'mongoose';

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

Adjon hozzá kapcsolati beállításokat, mert a környezetének szüksége van rájuk, nem azért, mert megjelentek egy öt éves kódrészletben.

Mi van, ha a kapcsolódás működik, de a lekérdezések később időtúllépést okoznak?

Ez egy másik probléma. Ha a mongoose.connect() sikeres, és az alkalmazás később elakad a lekérdezéseknél, vizsgálja meg a műveleti késleltetést, a kapcsolati készlet nyomását, a szerver terhelését, az indexeket, valamint a socket vagy műveleti időtúllépéseket. A MongoDB jelenlegi Node.js illesztőprogramja szétválasztja:

• serverSelectionTimeoutMS — megfelelő szerver keresése.
• connectTimeoutMS — egy TCP kapcsolódás létrehozása.
• socketTimeoutMS — inaktivitás egy meglévő socketen.
• maxTimeMS — annak korlátozása, meddig futtathat egy szerver műveletet, miután elérte a MongoDB-t.

Ha csak hosszú lekérdezések sikertelenek, a serverSelectionTimeoutMS növelése valószínűleg nem oldja meg a valódi problémát.

Gyors diagnózis hibaállapot szerint

Egy éles környezetbarát kapcsolódási minta

Tartsa a titkokat a forráskódon kívül, hibáztassa egyértelműen az indítást, amikor az adatbázis nem érhető el, és naplózzon elegendő részletet a diagnózishoz anélkül, hogy hitelesítő adatokat nyomtatna ki:

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

Ezek a 30 másodperces értékek megfelelnek a jelenlegi dokumentált alapértelmezett értékeknek, így kihagyhatja őket, hacsak a politika explicit tétele nem segít az üzemeltetésben. A fontos rész nem a számok; hanem az, hogy tudja, miért lenne jobb egy másik szám az Ön telepítéséhez.

Végső ellenőrzőlista

• Rögzítse a teljes hibát és vizsgálja meg az err.reason-t.
• Erősítse meg, hogy a MongoDB telepítés fut és elérhető.
• Futtasson DNS és TCP teszteket ugyanabból a környezetből, mint a Node.js folyamat.
• Atlas esetén ellenőrizze, hogy az alkalmazás kimeneti IP-címe szerepel-e az IP-hozzáférési listán.
• mongodb+srv:// esetén ellenőrizze az SRV DNS feloldást.
• Helyi MongoDB esetén próbálja a 127.0.0.1-et, ha a localhost használhatatlan IPv6-ra oldódik fel.
• Docker vagy Kubernetes esetén használjon egy olyan gazdagépnevet, amely érvényes abban a hálózati névtérben.
• Javítsa a TLS vagy hitelesítési hibákat ahelyett, hogy nagyobb időtúllépéssel maszkolná őket.
• Állítsa be a serverSelectionTimeoutMS, connectTimeoutMS vagy socketTimeoutMS értékeket csak arra a szakaszra, amelyet valóban szabályoznak.
• A javítás után ellenőrizze, hogy az alkalmazás következetesen kapcsolódik-e a valódi telepítési környezetből, nem csak egy fejlesztői laptopról.

Összegzés

Ha a Mongoose MongoDB hálózati időtúllépést jelent, először bizonyítsa be, hogy az illesztőprogram képes felfedezni és elérni egy megfelelő MongoDB szervert. Az Atlas IP-korlátozásai, a tűzfalak, a DNS SRV feloldás, a helytelen konténer gazdagépnevek, az IPv4/IPv6 eltérések, az elérhetetlen MongoDB folyamatok és a TLS konfiguráció mind azt a benyomást kelthetik, hogy a 30 másodperces időtúllépés a probléma, amikor az időzítő csak a hibát jelenti.

Használja az időtúllépési beállításokat annak meghatározására, hogy az alkalmazás meddig várjon egy ismert jó rendszerre – ne arra, hogy kompenzálja a törött kapcsolati útvonalat. Amint a hálózati elérhetőség és az URI helyes, válasszon olyan időtúllépési értékeket, amelyek megfelelnek az elérhetőségi modelljének, a hibakeresési viselkedésének és a várt műveleti késleltetésnek.