Mongon verkkoaikakatkaisuvirheen korjaaminen Mongoose-yhteydessä

Tärkein korjaus on lopettaa jokaisen Mongoose-aikakatkaisun käsittely aikakatkaisuasetusongelmana. Viesti kuten MongoServerSelectionError: connection timed out tarkoittaa yleensä, että MongoDB-ajuri ei pystynyt valitsemaan käyttökelpoista palvelinta ennen kuin serverSelectionTimeoutMS umpeutui. Mongon nykyinen vianmääritysdokumentointi listaa verkkoyhteyden, Atlas IP-pääsyrajoitukset, DNS SRV -virheet ja TLS-määritykset yleisiksi syiksi. Aikakatkaisun kasvattaminen voi saada sovelluksen odottamaan kauemmin korjaamatta mitään näistä ehdoista.

Käytä tämän sijaan seuraavaa järjestystä: 1) tunnistetaan, mikä aikakatkaisu epäonnistui, 2) osoitetaan, että sovellusisäntä voi tavoittaa Mongon, 3) korjataan yhteysmerkkijono tai ympäristökohtainen osoite, ja 4) säädetään aikakatkaisuarvoja vasta, kun yhteys toimii. Alla olevat esimerkit käyttävät nykyaikaisia Mongoose-yhteysmalleja ja MongoDB-ajurin nykyistä käyttäytymistä, joka on dokumentoitu syyskuussa 2026.

Tunnista ensin, mihin aikakatkaisuun törmäät

Mongoose käyttää taustalla MongoDB Node.js -ajuria, joten useita eri aikakatkaisuasetuksia voi esiintyä samassa yhteysmäärityksessä. Ne eivät tarkoita samaa asiaa.

Mongosen nykyinen yhteysdokumentaatio ilmoittaa, että serverSelectionTimeoutMS -oletusarvo on 30 sekuntia ja se koskee sekä alkuperäistä mongoose.connect() -kutsua että myöhempiä operaatioita, jotka vaativat palvelimen valintaa. Mongon Node.js-ajurin yhteysvaihtoehtojen dokumentaatio erottaa tämän arvon connectTimeoutMS:stä ja socketTimeoutMS:stä.

Palvelimen valinta-aikakatkaisu on oire, joka luokitellaan ensin; virheen tiedot ja taustalla oleva syy ovat hyödyllisempiä kuin 30 sekunnin rajan välitön kasvattaminen.

Vaihe 1: Tallenna tarkka Mongoose-virhe ja sen taustalla oleva syy

Aloita minimaalisella yhteydellä ja kirjaudu riittävästi tietoa erottamaan DNS-, todennus-, TLS- ja tavoitettavuusvirheet:

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

Yllä oleva 5 sekunnin arvo on diagnostinen valinta, ei tuotantosuositus jokaiselle käyttöönotolle. Mongoose sanoo, että serverSelectionTimeoutMS -arvon pienentäminen voi antaa nopeampaa palautetta, mutta se varoittaa erityisesti sitä vastaan, että arvoa pienennetään kevyesti replikasettien kohdalla, koska oletusarvoinen 30 sekunnin ikkuna voi auttaa operaatioita selviytymään vaaleista ja vikasietoisista siirtymistä. Mongoose suosittelee lyhyempiä arvoja helpommin itsenäiselle MongoDB:lle tai palveluttomille suoritusajoille, joissa nopea epäonnistuminen on hyödyllistä.

Etsi vihjeitä kuten:

• getaddrinfo ENOTFOUND — DNS-nimeä ei voida ratkaista.
• ECONNREFUSED — jokin hylkäsi TCP-yhteyden aktiivisesti, usein koska isännällä/portilla ei kuunnella mitään.
• ETIMEDOUT — yhteysyritys ei valmistunut ajoissa, usein koska liikenne on suodatettu, reititetty väärin tai kohde ei ole käytettävissä.
• TLS- tai varmenneviesti — tutki varmenteen luottamusta, isäntänimen vastaavuutta, protokollatukea tai TLS-määrityksiä.
• Todennusvirheet err.reason:n sisällä — korjaa tunnukset tai authSource sen sijaan, että muuttaisit verkkoaikakatkaisuja.

Ehto: Jos virhe sanoo jo, että todennus epäonnistui, ohita palomuurin säätäminen, kunnes tunnukset ja todennustietokanta ovat oikein. Verkkoaikakatkaisu ja hylätty kirjautuminen ovat eri virhetyyppejä.

Vaihe 2: Osoita verkko-, Atlas IP-pääsy ja DNS samasta suoritusajosta

Suorita yhteystestit samalta koneelta, kontilta, VM:ltä, palveluttomalta funktiolta tai Kubernetes-podilta, jossa Node.js-prosessi suorittaa. Testaaminen omalta kannettavalta ei riitä, jos tuotanto pyörii muualla.

Atlasta varten varmista, että sovelluksen todellinen ulostulon IP on sallittu; paikalliselle käyttöönotolle varmista, että MongoDB-prosessi todella kuuntelee odotettua liitäntää ja porttia.

Jos käytät MongoDB Atlas -palvelua

Atlas hyväksyy asiakasyhteydet vain osoitteista, jotka on sallittu projektin IP-pääsyluettelossa. MongoDB dokumentoi tämän IP-pääsyluettelon hallinnassa. Varmista, että sovellusympäristön julkinen ulostulon IP on listattu, ei vain henkilökohtaisen työasemasi IP.

Mongon palvelimen valinta-aikakatkaisun vianmääritysopas suosittelee myös ulostulevan TCP-yhteyden tarkistamista MongoDB:hen portissa 27017 sekä palomuureja, tietoturvaryhmiä, verkko-ACL:itä, VPN:iä ja välityspalvelimia.

Esimerkiksi Linuxista tai macOS:sta voit testata tiettyä Atlas-solmua tai itse hallinnoitua isäntää komennolla:

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

Windows PowerShellissa karkea TCP-tavoitettavuustesti on:

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

Onnistunut TCP-testi ei todista, että todennus tai TLS onnistuu, mutta epäonnistunut TCP-testi tarkoittaa, että Mongoose-aikakatkaisujen säätäminen on ennenaikaista.

Jos URI käyttää mongodb+srv://

SRV-yhteysmerkkijono riippuu DNS SRV -tietueista. Mongon nykyiset vianmääritysvaiheet suosittelevat SRV-haun tarkistamista asiakasympäristöstä:

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

Jos SRV-kysely epäonnistuu, varmista isäntänimi ja DNS-määritykset. MongoDB dokumentoi ei-SRV mongodb:// -yhteysmerkkijonon mahdolliseksi kiertotieksi, kun ympäristö ei voi ratkaista SRV-tietueita, mutta sinun tulisi hankkia tämä standardi yhteysmerkkijono Atlasista tai käyttöönottoasetuksistasi sen sijaan, että keksisit solmunimiä. Katso Atlas-yhteyden vianmääritys.

Oikea diagnostinen järjestys tarkistaa osoitteen ja verkkoreitin ennen kuin aikakatkaisuarvoja pidetään juurisyyinä.

Vaihe 3: Korjaa URI ympäristölle, jossa Node.js todella suorittaa

Syntaktisesti kelvollinen MongoDB-URI voi silti osoittaa väärään paikkaan. Tarkista skeema, isäntänimi, portti, tietokannan nimi, replikasettivaatimukset, todennuslähde ja onko isäntänimi merkityksellinen sovelluksen verkkoavaruudessa.

Paikallinen Node.js ja paikallinen MongoDB

Mongoose suosittelee tällä hetkellä 127.0.0.1 -osoitetta localhost:n sijaan paikalliselle MongoDB:lle:

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

Syy on Node.js 18 ja uudemmat: Mongoose huomauttaa, että Node.js voi ratkaista localhost:n IPv6-osoitteeksi ::1, kun taas paikallinen MongoDB-instanssi voi kuunnella vain IPv4:ää. Mongoose dokumentoi myös { family: 4 } -vaihtoehdon, kun IPv6-ensisijainen ratkaisu hidastaa yhteysyrityksiä:

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

Käytä family: 4 -vaihtoehtoa vain, kun IPv4/IPv6-ratkaisupolku on todellinen ongelma. Jos MongoDB-käyttöönotto tukee IPv6:ta oikein, IPv4:n pakottaminen on tarpeetonta.

Node.js Dockerin sisällä

Jos sovellus on kontin sisällä, localhost viittaa kyseiseen konttiin, ei automaattisesti isännällä tai toisessa kontissa olevaan MongoDB:hen. Käytä MongoDB-palvelun/kontin isäntänimeä jaetussa Docker-verkossa tai alustakohtaista isäntäosoitetta, kun MongoDB suorittaa isännällä.

Esimerkiksi Compose-palvelulla, jonka nimi on mongo:

MONGODB_URI=mongodb://mongo:27017/myapp

Ehto: Tämä esimerkki pätee vain, jos kontit jakavat verkon ja MongoDB-palvelun nimi on todella mongo. Älä kopioi isäntänimeä epäolennaiseen käyttöönottoon.

Atlas

Käytä Atlasin ajurillesi luomaa yhteysmerkkijonoa, säilytä mongodb+srv:// -isäntä täsmälleen, URL-koodaa varatut merkit käyttäjänimissä tai salasanoissa tarvittaessa ja varmista, että tietokantakäyttäjä on olemassa tarkoitetussa projektissa.

Jos muodostat yhteyden itse hallinnoituun replikasettiin, replikasettien ilmoittamien isäntänimien on myös oltava tavoitettavissa asiakkaalta. Siemenisäntä voi olla tavoitettavissa, mutta myöhempi palvelimen valinta voi silti epäonnistua, koska replikasettien jäsenet ilmoittavat isäntänimiä, joita sovellus ei voi ratkaista tai reitittää.

Vaihe 4: Säädä aikakatkaisuja vasta, kun yhteys onnistuu

Kun DNS ratkeaa, verkkopolku toimii, palvelin on käytettävissä ja URI on oikein, aikakatkaisujen säätäminen tulee merkitykselliseksi.

Mongoose välittää aikakatkaisuun liittyvät yhteysvaihtoehdot taustalla olevalle MongoDB-ajurille, mutta jokainen vaihtoehto ohjaa eri vaihetta; suurempia arvoja ei tulisi käyttää rikkoutuneen reitin tai tavoittamattoman palvelimen piilottamiseen.

Konservatiivinen esimerkki sovellukselle, joka haluaa 10 sekunnin alkuperäisen epäonnistumissignaalin, voisi näyttää tältä:

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

Onko 10 sekuntia sopiva, riippuu käyttöönotosta. Kompromissi on suoraviivainen:

socketTimeoutMS:n osalta nykyinen MongoDB Node.js -ajurin dokumentaatio käyttää oletusarvoa 0, mikä tarkoittaa, ettei pistorasian passiivisuusaikakatkaisua ole. MongoDB suosittelee, kun valitset asettaa sen, valitsemaan arvon, joka on noin kaksi tai kolme kertaa pidempi kuin hitain odotettu operaatio. Tämä asetus koskee pistorasioita, jotka ovat jo muodostaneet yhteyden, joten se ei ole ensisijainen korjaus alkuperäiseen palvelimen valinta-aikakatkaisuun.

Älä kopioi vanhoja Mongoose-yhteysvaihtoehtoja nykyiseen projektiin

Monet vanhemmat esimerkit sisältävät edelleen useNewUrlParser, useUnifiedTopology, keepAlive tai keepAliveInitialDelay. Nykyinen Mongoose ei vaadi vanhoja parseri/topologia-opt-in -vaihtoehtoja, ja Mongoose dokumentoi keepAlive:n oletuksena käytössä olevaksi Mongoose 5.2:sta lähtien ja vanhentuneeksi yhteysvaihtoehdoksi 7.2:sta lähtien.

Nykyaikainen perustaso on tarkoituksellisen pieni:

import mongoose from 'mongoose';

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

Lisää yhteysvaihtoehtoja, koska ympäristösi tarvitsee niitä, ei siksi, että ne esiintyivät viiden vuoden takaisessa koodinpätkässä.

Mitä jos yhteys toimii, mutta kyselyt aikakatkaisevat myöhemmin?

Se on eri ongelma. Jos mongoose.connect() onnistuu ja sovellus myöhemmin jumittuu kyselyihin, tutki operaation viivettä, yhteyspoolin painetta, palvelinkuormaa, indeksejä sekä pistorasian tai operaation aikakatkaisuja. Mongon nykyinen Node.js-ajuri erottaa:

• serverSelectionTimeoutMS — sopivan palvelimen löytäminen.
• connectTimeoutMS — yhden TCP-yhteyden muodostaminen.
• socketTimeoutMS — passiivisuus muodostetussa pistorasiassa.
• maxTimeMS — rajoittaa, kuinka kauan palvelinoperaatio voi suorittaa, kun se saavuttaa Mongon.

Jos vain pitkät kyselyt epäonnistuvat, serverSelectionTimeoutMS:n kasvattaminen ei todennäköisesti ratkaise todellista ongelmaa.

Nopea diagnoosi virheen ehdon mukaan

Tuotantoystävällinen yhteysmalli

Pidä salaisuudet pois lähdekoodista, epäonnistu käynnistyksessä selkeästi, kun tietokanta ei ole käytettävissä, ja kirjaudu riittävästi yksityiskohtia diagnosointia varten tulostamatta tunnuksia:

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

Nämä 30 sekunnin arvot vastaavat nykyisiä dokumentoituja oletusarvoja, joten voit jättää ne pois, ellei käytännön tekeminen eksplisiittiseksi autta operaatioitasi. Tärkeä osa ei ole numerot; se on tietää, miksi eri numero olisi parempi käyttöönotollesi.

Lopullinen tarkistuslista

• Tallenna täydellinen virhe ja tutki err.reason.
• Varmista, että MongoDB-käyttöönotto on käynnissä ja käytettävissä.
• Suorita DNS- ja TCP-testit samasta ympäristöstä kuin Node.js-prosessi.
• Atlasta varten varmista, että sovelluksen ulostulon IP on IP-pääsyluettelossa.
• mongodb+srv://:n kohdalla varmista SRV DNS-ratkaisu.
• Paikallisen MongoDB:n kohdalla kokeile 127.0.0.1, jos localhost ratkeaa käyttökelvottomaan IPv6:een.
• Dockerin tai Kubernetesin kohdalla käytä isäntänimeä, joka on kelvollinen kyseisessä verkkoavaruudessa.
• Korjaa TLS- tai todennusvirheet sen sijaan, että peittäisit ne suuremmalla aikakatkaisulla.
• Säädä serverSelectionTimeoutMS, connectTimeoutMS tai socketTimeoutMS vain vaiheelle, jota ne todella ohjaavat.
• Korjauksen jälkeen varmista, että sovellus muodostaa yhteyden johdonmukaisesti todellisesta käyttöönottoympäristöstä, ei vain kehittäjän kannettavalta.

Yhteenveto

Jos Mongoose ilmoittaa MongoDB-verkkoaikakatkaisusta, osoita ensin, että ajuri voi löytää ja tavoittaa sopivan MongoDB-palvelimen. Atlas IP-rajoitukset, palomuurit, DNS SRV -ratkaisu, virheelliset konttien isäntänimet, IPv4/IPv6-epäsuhta, ei-käytettävissä olevat MongoDB-prosessit ja TLS-määritykset voivat kaikki saada 30 sekunnin aikakatkaisun näyttämään ongelmalta, kun ajastin vain ilmoittaa epäonnistumisesta.

Käytä aikakatkaisuasetuksia määrittelemään, kuinka kauan sovelluksesi tulisi odottaa tunnettua hyvää järjestelmää – ei kompensoimaan rikkoutunutta yhteyspolkua. Kun verkkotavoitettavuus ja URI ovat oikein, valitse sitten aikakatkaisuarvot, jotka vastaavat saatavuusmalliasi, vikasietoisuuskäyttäytymistäsi ja odotettua operaatioviivettä.