Jak opravit chybu časového limitu sítě MongoDB v připojení Mongoose

Nejdůležitější opravou je přestat považovat každý časový limit Mongoose za problém s nastavením časového limitu. Zpráva jako MongoServerSelectionError: connection timed out obvykle znamená, že ovladač MongoDB nemohl vybrat použitelný server před vypršením hodnoty serverSelectionTimeoutMS. Současná dokumentace k řešení problémů MongoDB uvádí jako běžné příčiny problémy s připojením k síti, omezení přístupu IP v Atlasu, selhání DNS SRV a konfigurace TLS. Zvýšení časového limitu může způsobit, že aplikace bude čekat déle, aniž by opravila některou z těchto podmínek.

Místo toho použijte toto pořadí: 1) identifikujte, který časový limit selhal, 2) ověřte, že se hostitel aplikace může připojit k MongoDB, 3) opravte připojovací řetězec nebo adresu specifickou pro prostředí a 4) ladte hodnoty časových limitů až poté, co je známo, že připojení funguje. Níže uvedené příklady používají moderní vzory připojení Mongoose a současné chování ovladače MongoDB zdokumentované v září 2026.

Nejprve zjistěte, na který časový limit se díváte

Mongoose používá pod kapotou ovladač MongoDB pro Node.js, takže v jedné konfiguraci připojení se může objevit několik různých nastavení časového limitu. Neznamenají totéž.

Aktuální dokumentace připojení Mongoose uvádí, že serverSelectionTimeoutMS má výchozí hodnotu 30 sekund a platí jak pro počáteční mongoose.connect(), tak pro pozdější operace, které potřebují vybrat server. Dokumentace možností připojení ovladače MongoDB pro Node.js rozlišuje tuto hodnotu od connectTimeoutMS a socketTimeoutMS.

Časový limit výběru serveru je příznak, který je třeba nejprve klasifikovat; podrobnosti o chybě a základní důvod jsou užitečnější než okamžité zvýšení 30sekundového limitu.

Krok 1: zachyťte přesnou chybu Mongoose a její základní důvod

Začněte s minimálním připojením a zaznamenejte dostatek informací k rozlišení selhání DNS, ověřování, TLS a 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);
}

Výše uvedená hodnota 5 sekund je diagnostická volba, nikoli doporučení pro produkci pro každé nasazení. Mongoose uvádí, že snížení serverSelectionTimeoutMS může poskytnout rychlejší zpětnou vazbu, ale výslovně varuje před jeho náhodným snižováním pro replikové sady, protože výchozí 30sekundové okno může pomoci operacím přežít volby a přepnutí. Mongoose doporučuje kratší hodnoty spíše pro samostatné instance MongoDB nebo serverless běhové prostředí, kde je rychlé selhání užitečné.

Hledejte stopy jako:

• getaddrinfo ENOTFOUND — název hostitele nelze přeložit přes DNS.
• ECONNREFUSED — něco aktivně odmítlo TCP připojení, často proto, že na hostiteli/portu nic neposlouchá.
• ETIMEDOUT — pokus o připojení nebyl dokončen včas, často proto, že je provoz filtrován, špatně směrován nebo cíl není dostupný.
• Text týkající se TLS nebo certifikátu — prošetřujte důvěru v certifikát, shodu názvu hostitele, podporu protokolu nebo konfiguraci TLS.
• Chyby ověřování uvnitř err.reason — opravte přihlašovací údaje nebo authSource místo měření síťových časových limitů.

Podmínka: pokud chyba již hlásí selhání ověřování, přeskočte ladění firewallu, dokud nebudou správné přihlašovací údaje a databáze pro ověřování. Časový limit sítě a zamítnuté přihlášení jsou různé třídy selhání.

Krok 2: ověřte síť, přístup IP Atlasu a DNS ze stejného běhového prostředí

Spusťte testy připojení ze stejného počítače, kontejneru, VM, serverless funkce nebo Kubernetes podu, kde běží proces Node.js. Testování z vašeho laptopu nestačí, pokud produkce běží někde jinde.

Pro Atlas ověřte, že je povolena skutečná odchozí IP aplikace; pro lokální nasazení ověřte, že proces MongoDB skutečně poslouchá na očekávaném rozhraní a portu.

Pokud používáte MongoDB Atlas

Atlas přijímá klientská připojení pouze z adres povolených seznamem přístupových IP projektu. MongoDB to dokumentuje v Spravovat seznam přístupových IP. Ujistěte se, že je uvedena veřejná odchozí IP prostředí aplikace, nikoli pouze IP vašeho osobního pracovního stanice.

Průvodce řešením problémů s časovým limitem výběru serveru od MongoDB také doporučuje kontrolovat odchozí TCP připojení k MongoDB na portu 27017, spolu s firewally, bezpečnostními skupinami, síťovými ACL, VPN a proxy.

Například z Linuxu nebo macOS můžete otestovat konkrétní uzel Atlasu nebo hostitele spravovaný vlastními silami pomocí:

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

V Windows PowerShell je hrubý test dostupnosti TCP:

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

Úspěšný test TCP nedokazuje, že ověřování nebo TLS budou úspěšné, ale neúspěšný test TCP znamená, že ladění časového limitu Mongoose je předčasné.

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

Řetězec připojení SRV závisí na záznamech DNS SRV. Současné kroky řešení problémů od MongoDB doporučují zkontrolovat vyhledávání SRV z klientského prostředí:

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

Pokud dotaz SRV selže, potvrďte název hostitele a konfiguraci DNS. MongoDB dokumentuje připojovací řetězec mongodb:// bez SRV jako možný workaround, když prostředí nedokáže přeložit záznamy SRV, ale tento standardní připojovací řetězec byste měli získat z Atlasu nebo vaší konfigurační souboru nasazení, nikoli vymýšlet názvy uzlů. Viz Řešení problémů s připojením Atlas.

Správná diagnostická sekvence kontroluje adresu a síťovou cestu dříve, než začnete považovat hodnoty časových limitů za příčinu.

Krok 3: opravte URI pro prostředí, kde Node.js skutečně běží

Syntakticky platný URI MongoDB stále může ukazovat na špatné místo. Zkontrolujte schéma, název hostitele, port, název databáze, požadavky replikové sady, zdroj ověřování a zda je název hostitele smysluplný ze síťového jmenného prostoru aplikace.

Lokální Node.js a lokální MongoDB

Mongoose aktuálně doporučuje 127.0.0.1 místo localhost pro lokální MongoDB:

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

Důvodem je Node.js 18 a novější: Mongoose uvádí, že Node.js může přeložit localhost na IPv6 ::1, zatímco lokální instance MongoDB může poslouchat pouze na IPv4. Mongoose také dokumentuje { family: 4 } jako možnost, když překládání upřednostňující IPv6 zpomaluje pokusy o připojení:

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

Použijte family: 4 pouze tehdy, když je cesta překládání IPv4/IPv6 skutečně problémem. Pokud vaše nasazení MongoDB správně podporuje IPv6, vynucování IPv4 je zbytečné.

Node.js uvnitř Dockeru

Pokud je aplikace uvnitř kontejneru, localhost odkazuje na tento kontejner, nikoli automaticky na MongoDB na hostiteli nebo v jiném kontejneru. Použijte název hostitele služby/kontejneru MongoDB na sdílené síti Docker, nebo platformě specifickou adresu hostitele, pokud MongoDB běží na hostiteli.

Například se službou Compose pojmenovanou mongo:

MONGODB_URI=mongodb://mongo:27017/myapp

Podmínka: tento příklad platí pouze pokud si kontejnery sdílejí síť a služba MongoDB je skutečně pojmenována mongo. Nekopírujte název hostitele do nesouvisejícího nasazení.

Atlas

Použijte připojovací řetězec vygenerovaný Atlasem pro váš ovladač, zachovejte přesně hostitele mongodb+srv://, zakódujte vyhrazené znaky v uživatelských jménech nebo heslech pomocí URL, pokud je to vyžadováno, a ověřte, že databázový uživatel existuje v zamýšleném projektu.

Pokud se připojujete k replikové sadě spravované vlastními silami, názvy hostitelů hlášené replikovou sadou musí být také dostupné z klienta. Seed hostitel může být dostupný, zatímco pozdější výběr serveru stále selhává, protože členové replikové sady inzerují názvy hostitelů, které aplikace nemůže přeložit nebo směrovat.

Krok 4: ladte časové limity až po úspěšném připojení

Jakmile se DNS přeloží, síťová cesta funguje, server je dostupný a URI je správné, ladění časových limitů nabývá smyslu.

Mongoose předává možnosti připojení související s časovým limem podkladovému ovladači MongoDB, ale každá možnost řídí jinou fázi; větší hodnoty by neměly být používány ke skrytí rozbité cesty nebo nedostupného serveru.

Konzervativní příklad pro aplikaci, která chce 10sekundový signál o počátečním selhání, může vypadat takto:

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

To, zda je 10 sekund vhodné, závisí na nasazení. Kompromis je přímočarý:

Pro socketTimeoutMS používá aktuální dokumentace ovladače MongoDB pro Node.js výchozí hodnotu 0, což znamená žádný časový limit nečinnosti socketu. MongoDB doporučuje, když se rozhodnete ji nastavit, vybrat hodnotu přibližně dvakrát až třikrát delší než nejpomalejší očekávaná operace. Toto nastavení platí pro sockety, které se již připojily, takže to není hlavní oprava pro počáteční časový limit výběru serveru.

Nekopírujte staré možnosti připojení Mongoose do aktuálního projektu

Mnoho starších příkladů stále obsahuje useNewUrlParser, useUnifiedTopology, keepAlive nebo keepAliveInitialDelay. Aktuální Mongoose nevyžaduje staré volby parseru/topologie a Mongoose dokumentuje keepAlive jako povolené ve výchozím nastavení od Mongoose 5.2 a zastaralé jako možnost připojení od 7.2.

Moderní základ je záměrně malý:

import mongoose from 'mongoose';

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

Přidejte možnosti připojení, protože je vaše prostředí potřebuje, ne proto, že se objevily ve snippetu starém pět let.

Co když připojení funguje, ale dotazy později vyprší?

To je jiný problém. Pokud mongoose.connect() uspěje a aplikace později visí na dotazech, prošetřujte latenci operací, tlak na fond připojení, zatížení serveru, indexy a časové limity socketu nebo operací. Aktuální ovladač MongoDB pro Node.js rozlišuje:

• serverSelectionTimeoutMS — hledání vhodného serveru.
• connectTimeoutMS — navázání jednoho TCP připojení.
• socketTimeoutMS — nečinnost na established socketu.
• maxTimeMS — omezení délky běhu serverové operace, jakmile dosáhne MongoDB.

Pokud selhávají pouze dlouhé dotazy, zvýšení serverSelectionTimeoutMS pravděpodobně nevyřeší skutečný problém.

Rychlá diagnostika podle podmínky chyby

Vzorec připojení vhodný pro produkci

Udržujte tajné údaje mimo zdrojový kód, jasně selhejte při startu, když je databáze nedostupná, a zaznamenávejte dostatek podrobností pro diagnostiku bez tisku přihlašovacích údajů:

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

Tyto 30sekundové hodnoty odpovídají aktuálním zdokumentovaným výchozím hodnotám, takže je můžete vynechat, pokud explicitní politika nepomůže vašim operacím. Důležitá část nejsou čísla; je to vědět, proč by jiné číslo bylo lepší pro vaše nasazení.

Závěrečný kontrolní seznam

• Zachyťte kompletní chybu a prohledejte err.reason.
• Potvrďte, že nasazení MongoDB běží a je dostupné.
• Spusťte testy DNS a TCP ze stejného prostředí jako proces Node.js.
• Pro Atlas ověřte, že odchozí IP aplikace je na seznamu přístupových IP.
• Pro mongodb+srv:// ověřte překládání DNS SRV.
• Pro lokální MongoDB zkuste 127.0.0.1, pokud se localhost překládá na nepoužitelné IPv6.
• Pro Docker nebo Kubernetes použijte název hostitele, který je platný uvnitř tohoto síťového jmenného prostoru.
• Opravte chyby TLS nebo ověřování místo jejich maskování větším časovým limitem.
• Ladte serverSelectionTimeoutMS, connectTimeoutMS nebo socketTimeoutMS pouze pro fázi, kterou skutečně řídí.
• Po opravě ověřte, že se aplikace konzistentně připojuje ze skutečného prostředí nasazení, nikoli pouze z laptopu vývojáře.

Závěr

Pokud Mongoose hlásí časový limit sítě MongoDB, nejprve dokažte, že ovladač může objevit a dosáhnout vhodného serveru MongoDB. Omezení IP Atlasu, firewally, překládání DNS SRV, nesprávné názvy hostitelů kontejnerů, nesoulad IPv4/IPv6, nedostupné procesy MongoDB a konfigurace TLS mohou všechny způsobit, že se 30sekundový časový limit zdá být problémem, i když časovač pouze hlásí selhání.

Používejte nastavení časových limitů k definování toho, jak dlouho má vaše aplikace čekat na známý funkční systém – ne ke kompenzaci rozbité cesty připojení. Jakmile je síťová dostupnost a URI správné, pak vyberte hodnoty časových limitů, které odpovídají vašemu modelu dostupnosti, chování při přepnutí a očekávané latenci operací.