Ako opraviť chybu časového limitu siete MongoDB v pripojení Mongoose

Najdôležitejšou opravou je prestať považovať každý časový limit Mongoose za problém s nastavením časového limitu. Správa ako MongoServerSelectionError: connection timed out zvyčajne znamená, že ovládač MongoDB nedokázal vybrať použiteľný server pred vypršaním serverSelectionTimeoutMS. Súčasná dokumentácia riešenia problémov MongoDB uvádza ako bežné príčiny sieťové pripojenie, obmedzenia prístupu IP v Atlase, zlyhania DNS SRV a konfigurácia TLS. Zvýšenie časového limitu môže spôsobiť, že aplikácia bude čakať dlhšie, bez toho aby opravila ktorúkoľvek z týchto podmienok.

Použite namiesto toho tento postup: 1) identifikujte, ktorý časový limit zlyhal, 2) overte, že hostiteľská aplikácia môže dosiahnuť MongoDB, 3) opravte reťazec pripojenia alebo adresu špecifickú pre prostredie a 4) ladiť hodnoty časových limitov až po overení funkčnosti pripojenia. Nasledujúce príklady používajú moderné vzory pripojenia Mongoose a aktuálne správanie ovládača MongoDB zdokumentované v septembri 2026.

Najprv vedzte, na ktorý časový limit sa pozeráte

Mongoose používa pod kapotou ovládač MongoDB pre Node.js, takže v rovnakej konfigurácii pripojenia sa môže objaviť niekoľko rôznych nastavení časového limitu. Neznamenajú to isté.

Aktuálna dokumentácia pripojení Mongoose uvádza, že serverSelectionTimeoutMS má predvolenú hodnotu 30 sekúnd a vzťahuje sa na počiatočné mongoose.connect() aj na neskoršie operácie, ktoré potrebujú vybrať server. Dokumentácia možností pripojenia ovládača MongoDB pre Node.js odlišuje túto hodnotu od connectTimeoutMS a socketTimeoutMS.

Časový limit výberu servera je príznak, ktorý treba najprv klasifikovať; podrobnosti o chybe a jej základná príčina sú užitočnejšie než okamžité zvyšovanie 30-sekundového limitu.

Krok 1: zachyťte presnú chybu Mongoose a jej základnú príčinu

Začnite minimálnym pripojením a zaznamenajte dostatok informácií na rozlíšenie zlyhaní DNS, autentifikácie, TLS a dosiahnuteľnosti:

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

Hodnota 5 sekúnd uvedená vyššie je diagnostická voľba, nie odporúčanie do produkcie pre každé nasadenie. Mongoose uvádza, že zníženie serverSelectionTimeoutMS môže poskytnúť rýchlejšiu spätnú väzbu, ale výslovne varuje pred náhodným znižovaním tejto hodnoty pre replikové sady, pretože predvolené 30-sekundové okno môže pomôcť operáciám prežiť voľby a prepnutia. Mongoose skôr odporúča kratšie hodnoty pre samostatné inštancie MongoDB alebo serverless runtimey, kde je rýchle zlyhanie užitočné.

Hľadajte stopy ako:

• getaddrinfo ENOTFOUND — DNS názov sa nedá vyriešiť.
• ECONNREFUSED — niečo aktívne odmietlo TCP pripojenie, často preto, že na hostiteľovi/porte nič nepočúva.
• ETIMEDOUT — pokus o pripojenie sa nedokončil včas, často preto, že je prevádzka filtrovaná, nesprávne smerovaná alebo cieľ je nedostupný.
• Text týkajúci sa TLS alebo certifikátu — preskúmajte dôveryhodnosť certifikátu, zhodu názvu hostiteľa, podporu protokolu alebo konfiguráciu TLS.
• Chyby autentifikácie v rámci err.reason — opravte prihlasovacie údaje alebo authSource namiesto zmeny sieťových časových limitov.

Podmienka: ak chyba už uvádza, že autentifikácia zlyhala, preskočte ladenie firewallu, kým nebudú správne prihlasovacie údaje a databáza autentifikácie. Sieťový časový limit a zamietnuté prihlásenie sú rôzne triedy zlyhania.

Krok 2: overte sieť, prístup IP Atlasu a DNS z rovnakého runtimeu

Spustite testy pripojenia z rovnakého počítača, kontajnera, VM, serverless funkcie alebo Kubernetes podu, kde beží proces Node.js. Testovanie z vášho laptopu nestačí, ak produkcia beží niekde inde.

Pre Atlas overte, či je skutočná egress IP aplikácie povolená; pre lokálne nasadenie overte, či proces MongoDB skutočne počúva na očakávanom rozhraní a porte.

Ak používate MongoDB Atlas

Atlas prijíma klientske pripojenia iba z adries povolených v zozname prístupu IP projektu. MongoDB to dokumentuje v časti Správa zoznamu prístupu IP. Uistite sa, že je uvedená verejná egress IP prostredia aplikácie, nie iba IP vášho osobného pracovného stanice.

Sprievodca riešením problémov s časovým limitom výberu servera od MongoDB tiež odporúča skontrolovať odchádzajúcu TCP dosiahnuteľnosť na MongoDB na porte 27017, spolu s firewallmi, bezpečnostnými skupinami, sieťovými ACL, VPN a proxy.

Napríklad z Linuxu alebo macOS môžete otestovať konkrétny uzol Atlasu alebo self-managed hostiteľa pomocou:

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

V Windows PowerShell je hrubý test dosiahnuteľnosti TCP:

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

Úspešný test TCP nedokazuje, že autentifikácia alebo TLS budú úspešné, ale neúspešný test TCP znamená, že ladenie časového limitu Mongoose je predčasné.

Ak váš URI používa mongodb+srv://

Reťazec pripojenia SRV závisí od záznamov DNS SRV. Aktuálne kroky riešenia problémov od MongoDB odporúčajú skontrolovať vyhľadávanie SRV z klientskeho prostredia:

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

Ak sa dotaz SRV nepodarí, potvrďte názov hostiteľa a konfiguráciu DNS. MongoDB dokumentuje reťazec pripojenia mongodb:// bez SRV ako možné riešenie, keď prostredie nedokáže vyriešiť záznamy SRV, ale tento štandardný reťazec pripojenia by ste mali získať z Atlasu alebo konfigurácie nasadenia, nie vymýšľať názvy uzlov. Pozri Riešenie problémov s pripojením Atlas.

Správna diagnostická postupnosť kontroluje adresu a sieťovú cestu skôr, než začne považovať hodnoty časového limitu za koreňovú príčinu.

Krok 3: opravte URI pre prostredie, kde sa Node.js skutočne spúšťa

Syntakticky platné URI MongoDB môže stále ukazovať na nesprávne miesto. Skontrolujte schému, názov hostiteľa, port, názov databázy, požiadavky replikovej sady, zdroj autentifikácie a či je názov hostiteľa zmysluplný zo siete aplikácie.

Lokálny Node.js a lokálna MongoDB

Mongoose aktuálne odporúča 127.0.0.1 namiesto localhost pre lokálnu MongoDB:

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

Dôvodom je Node.js 18 a novší: Mongoose uvádza, že Node.js môže vyriešiť localhost na IPv6 ::1, zatiaľ čo lokálna inštancia MongoDB môže počúvať iba na IPv4. Mongoose tiež dokumentuje { family: 4 } ako možnosť, keď IPv6-first resolution spomaľuje pokusy o pripojenie:

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

Použite family: 4 iba vtedy, ak je cesta riešenia IPv4/IPv6 skutočne problémom. Ak vaše nasadenie MongoDB správne podporuje IPv6, vynucovanie IPv4 je zbytočné.

Node.js vnútri Dockeru

Ak je aplikácia vnútri kontajnera, localhost odkazuje na tento kontajner, nie automaticky na MongoDB na hostiteľovi alebo v inom kontajneri. Použite názov hostiteľa služby/kontajnera MongoDB na zdieľanej sieti Docker alebo platformovo špecifickú adresu hostiteľa, keď MongoDB beží na hostiteľovi.

Napríklad so službou Compose pomenovanou mongo:

MONGODB_URI=mongodb://mongo:27017/myapp

Podmienka: tento príklad platí iba vtedy, ak kontajnery zdieľajú sieť a služba MongoDB je skutočne pomenovaná mongo. Nekopírujte názov hostiteľa do nesúvisiaceho nasadenia.

Atlas

Použite reťazec pripojenia generovaný Atlasom pre váš ovládač, zachovajte hostiteľa mongodb+srv:// presne, zakódujte vyhradené znaky v používateľských menách alebo heslách pomocou URL, ak je to potrebné, a overte, či databázový používateľ existuje v zamýšľanom projekte.

Ak sa pripájate k self-managed replikovej sade, názvy hostiteľov hlásené replikovou sadou musia byť tiež dosiahnuteľné z klienta. Seed hostiteľ môže byť dosiahnuteľný, zatiaľ čo neskorší výber servera stále zlyháva, pretože členovia replikovej sady inzerujú názvy hostiteľov, ktoré aplikácia nedokáže vyriešiť alebo smerovať.

Krok 4: ladiť časové limity až po úspešnom pripojení

Akonáhle sa DNS vyrieši, sieťová cesta funguje, server je dostupný a URI je správne, ladenie časových limitov nadobúda zmysel.

Mongoose odovzdáva možnosti pripojenia súvisiace s časovým limitom podkladovému ovládaču MongoDB, ale každá možnosť ovláda inú fázu; väčšie hodnoty by sa nemali používať na zakrytie pokazeného smerovania alebo nedostupného servera.

Konzervatívny príklad pre aplikáciu, ktorá chce 10-sekundový počiatočný signál zlyhania, môže vyzerať takto:

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

To, či je 10 sekúnd vhodné, závisí od nasadenia. Kompromis je priamočiary:

Pre socketTimeoutMS používa aktuálna dokumentácia ovládača MongoDB pre Node.js predvolenú hodnotu 0, čo znamená žiadny časový limit nečinnosti socketu. MongoDB odporúča, keď sa rozhodnete nastaviť túto hodnotu, vybrať hodnotu približne dva až trikrát dlhšiu, ako je najpomalšia očakávaná operácia. Toto nastavenie sa vzťahuje na sockety, ktoré sa už pripojili, takže nie je primárnou opravou pre počiatočný časový limit výberu servera.

Nekopírujte staré možnosti pripojenia Mongoose do aktuálneho projektu

Mnohé staršie príklady stále obsahujú useNewUrlParser, useUnifiedTopology, keepAlive alebo keepAliveInitialDelay. Aktuálny Mongoose nevyžaduje staré opt-in pre parser/topológiu a Mongoose dokumentuje keepAlive ako povolené predvolene od Mongoose 5.2 a zastarané ako možnosť pripojenia od verzie 7.2.

Moderný základ je zámerne malý:

import mongoose from 'mongoose';

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

Pridávajte možnosti pripojenia, pretože ich vaše prostredie potrebuje, nie preto, že sa objavili v päť rokov starom úryvku kódu.

Čo ak pripojenie funguje, ale dotazy neskôr vypršia?

To je iný problém. Ak mongoose.connect() uspeje a aplikácia sa neskôr zasekne na dotazoch, preskúmajte latenciu operácií, tlak na pool pripojení, zaťaženie servera, indexy a časové limity socketov alebo operácií. Aktuálny ovládač MongoDB pre Node.js rozlišuje:

• serverSelectionTimeoutMS — nájdenie vhodného servera.
• connectTimeoutMS — nadviazanie jedného TCP pripojenia.
• socketTimeoutMS — nečinnosť na established sockete.
• maxTimeMS — obmedzenie dĺžky, počas ktorej môže serverová operácia bežať, keď dosiahne MongoDB.

Ak zlyhávajú iba dlhé dotazy, zvýšenie serverSelectionTimeoutMS pravdepodobne nevyrieši skutočný problém.

Rýchla diagnostika podľa podmienky chyby

Vzorec pripojenia priateľský k produkcii

Uchovávajte tajné údaje mimo zdrojového kódu, jasne zlyhajte pri štarte, keď je databáza nedostupná, a logujte dostatok detailov na diagnostiku bez vypisovania prihlasovacích údajov:

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

Tieto 30-sekundové hodnoty zodpovedajú aktuálnym zdokumentovaným predvoleným hodnotám, takže ich môžete vynechať, pokiaľ explicitné zadanie politiky nepomáha vašim operáciám. Dôležitá nie sú čísla; dôležité je vedieť, prečo by iné číslo bolo lepšie pre vaše nasadenie.

Záverečný kontrolný zoznam

• Zachyťte úplnú chybu a preskúmajte err.reason.
• Potvrďte, že nasadenie MongoDB beží a je dostupné.
• Spustite testy DNS a TCP z rovnakého prostredia ako proces Node.js.
• Pre Atlas overte, či je egress IP aplikácie na zozname prístupu IP.
• Pre mongodb+srv:// overte riešenie DNS SRV.
• Pre lokálnu MongoDB skúste 127.0.0.1, ak sa localhost rieši na nepoužiteľné IPv6.
• Pre Docker alebo Kubernetes použite názov hostiteľa, ktorý je platný v rámci tohto sieťového priestoru.
• Opravte chyby TLS alebo autentifikácie namiesto ich maskovania väčším časovým limitom.
• Ladiť serverSelectionTimeoutMS, connectTimeoutMS alebo socketTimeoutMS iba pre fázu, ktorú skutočne ovládajú.
• Po oprave overte, či sa aplikácia konzistentne pripája zo skutočného prostredia nasadenia, nie iba z laptopu vývojára.

Záver

Ak Mongoose hlási sieťový časový limit MongoDB, najprv dokážte, že ovládač môže objaviť a dosiahnuť vhodný server MongoDB. Obmedzenia IP Atlasu, firewally, riešenie DNS SRV, nesprávne názvy hostiteľov kontajnerov, nezhody IPv4/IPv6, nedostupné procesy MongoDB a konfigurácia TLS môžu všetko spôsobiť, že 30-sekundový časový limit sa zdá byť problémom, hoci časovač iba hlási zlyhanie.

Používajte nastavenia časového limitu na definovanie toho, ako dlho by mala vaša aplikácia čakať na známy funkčný systém – nie na kompenzáciu pokazeného spojenia. Keď je sieťová dosiahnuteľnosť a URI správne, potom vyberte hodnoty časových limitov, ktoré zodpovedajú vášmu modelu dostupnosti, správaniu pri prepnutí a očakávanej latencii operácií.