Πώς να διορθώσετε το σφάλμα λήξης χρόνου δικτύου του MongoDB στη σύνδεση Mongoose

Η πιο σημαντική διόρθωση είναι να σταματήσετε να αντιμετωπίζετε κάθε λήξη χρόνου του Mongoose ως πρόβλημα ρύθμισης timeout. Ένα μήνυμα όπως MongoServerSelectionError: connection timed out σημαίνει συνήθως ότι ο οδηγός MongoDB δεν μπόρεσε να επιλέξει έναν χρήσιμο διακομιστή πριν λήξει το serverSelectionTimeoutMS. Η τρέχουσα τεκμηρίωση αντιμετώπισης προβλημάτων του MongoDB καταγράφει τη συνδεσιμότητα δικτύου, τους περιορισμούς πρόσβασης IP του Atlas, τις αποτυχίες DNS SRV και τη διαμόρφωση TLS ως κοινές αιτίες. Η αύξηση του timeout μπορεί να κάνει την εφαρμογή να περιμένει περισσότερο χωρίς να επισκευάσει καμία από αυτές τις συνθήκες.

Χρησιμοποιήστε αυτήν τη σειρά αντίθετα: 1) εντοπίστε ποιο timeout απέτυχε, 2) αποδείξτε ότι ο κεντρικός υπολογιστής της εφαρμογής μπορεί να φτάσει το MongoDB, 3) διορθώστε τη συμβολοσειρά σύνδεσης ή τη διεύθυνση συγκεκριμένη για το περιβάλλον, και 4) ρυθμίστε τις τιμές timeout μόνο αφού η συνδεσιμότητα είναι γνωστό ότι λειτουργεί. Τα παρακάτω παραδείγματα χρησιμοποιούν σύγχρονα πρότυπα σύνδεσης Mongoose και τη συμπεριφορά του τρέχοντος οδηγού MongoDB που τεκμηριώθηκε τον Σεπτέμβριο του 2026.

Πρώτα, γνωρίστε ποιο timeout εξετάζετε

Το Mongoose χρησιμοποιεί τον οδηγό Node.js του MongoDB από κάτω, οπότε διάφορες ρυθμίσεις timeout μπορούν να εμφανιστούν στην ίδια διαμόρφωση σύνδεσης. Δεν σημαίνουν το ίδιο πράγμα.

Η τρέχουσα τεκμηρίωση σύνδεσης του Mongoose δηλώνει ότι το serverSelectionTimeoutMS έχει προεπιλογή 30 δευτερόλεπτα και ισχύει τόσο για την αρχική mongoose.connect() όσο και για μεταγενέστερες λειτουργίες που χρειάζεται να επιλέξουν διακομιστή. Η τεκμηρίωση επιλογών σύνδεσης του οδηγού Node.js του MongoDB διαχωρίζει αυτήν την τιμή από το connectTimeoutMS και το socketTimeoutMS.

Η λήξη χρόνου επιλογής διακομιστή είναι το σύμπτωμα που πρέπει να ταξινομήσετε πρώτο. Οι λεπτομέρειες του σφάλματος και ο υποκείμενος λόγος είναι πιο χρήσιμοι από το άμεσο αύξηση του ορίου των 30 δευτερολέπτων.

Βήμα 1: Καταγράψτε το ακριβές σφάλμα Mongoose και τον υποκείμενο λόγο του

Ξεκινήστε με μια ελάχιστη σύνδεση και καταγράψτε αρκετές πληροφορίες για να διαχωρίσετε τις αποτυχίες DNS, ελέγχου ταυτότητας, TLS και προσβασιμότητας:

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

Η τιμή των 5 δευτερολέπτων παραπάνω είναι μια διαγνωστική επιλογή, όχι μια σύσταση παραγωγής για κάθε ανάπτυξη. Το Mongoose λέει ότι η μείωση του serverSelectionTimeoutMS μπορεί να δώσει ταχύτερη ανατροφοδότηση, αλλά προειδοποιεί συγκεκριμένα εναντίον της τυχαίας μείωσής του για σετ αντιγραφής επειδή το προεπιλεγμένο παράθυρο των 30 δευτερολέπτων μπορεί να βοηθήσει τις λειτουργίες να επιβιώσουν εκλογές και failovers. Το Mongoose προτείνει πιο εύκολα μικρότερες τιμές για αυτόνομο MongoDB ή serverless χρόνους εκτέλεσης όπου η γρήγορη αποτυχία είναι χρήσιμη.

Αναζητήστε ενδείξεις όπως:

• getaddrinfo ENOTFOUND — Το όνομα DNS δεν μπορεί να επιλυθεί.
• ECONNREFUSED — Κάτι απέρριψε ενεργά τη σύνδεση TCP, συχνά επειδή τίποτα δεν ακούει στον κεντρικό υπολογιστή/θύρα.
• ETIMEDOUT — Η προσπάθεια σύνδεσης δεν ολοκληρώθηκε εγκαίρως, συχνά επειδή η κίνηση φιλτράρεται, δρομολογείται λανθασμένα ή ο προορισμός δεν είναι διαθέσιμος.
• Κείμενο TLS ή πιστοποιητικού — Ερευνήστε την εμπιστοσύνη πιστοποιητικών, την αντιστοίχιση ονόματος κεντρικού υπολογιστή, την υποστήριξη πρωτοκόλλου ή τη διαμόρφωση TLS.
• Σφάλματα ελέγχου ταυτότητας μέσα στο err.reason — Διορθώστε τα διαπιστευτήρια ή το authSource αντί να αλλάξετε τα timeouts δικτύου.

Προϋπόθεση: Αν το σφάλμα ήδη λέει ότι απέτυχε ο έλεγχος ταυτότητας, παραλείψτε τη ρύθμιση firewall μέχρι τα διαπιστευτήρια και η βάση δεδομένων ελέγχου ταυτότητας να είναι σωστά. Μια λήξη χρόνου δικτύου και μια απόρριψη σύνδεσης είναι διαφορετικές κατηγορίες αποτυχίας.

Βήμα 2: Αποδείξτε το δίκτυο, την πρόσβαση IP Atlas και το DNS από τον ίδιο χρόνο εκτέλεσης

Εκτελέστε δοκιμές συνδεσιμότητας από τον ίδιο μηχανήμα, container, VM, serverless function ή pod Kubernetes όπου εκτελείται η διαδικασία Node.js. Η δοκιμή από τον φορητό υπολογιστή σας δεν είναι αρκετή αν η παραγωγή εκτελείται κάπου αλλού.

Για το Atlas, επαληθεύστε ότι η πραγματική IP εξόδου της εφαρμογής επιτρέπεται. Για μια τοπική ανάπτυξη, επαληθεύστε ότι η διαδικασία MongoDB ακούει πραγματικά στη αναμενόμενη διεπαφή και θύρα.

Αν χρησιμοποιείτε MongoDB Atlas

Το Atlas δέχεται συνδέσεις πελατών μόνο από διευθύνσεις που επιτρέπονται από τη λίστα πρόσβασης IP του έργου. Το MongoDB το τεκμηριώνει στο Διαχείριση της Λίστας Πρόσβασης IP. Βεβαιωθείτε ότι η δημόσια IP εξόδου του περιβάλλοντος εφαρμογής είναι καταχωρημένη, όχι απλώς η IP του προσωπικού σας σταθμού εργασίας.

Ο οδηγός αντιμετώπισης προβλημάτων λήξης χρόνου επιλογής διακομιστή του MongoDB συνιστά επίσης τον έλεγχο της εξερχόμενης συνδεσιμότητας TCP προς το MongoDB στη θύρα 27017, μαζί με firewalls, ομάδες ασφαλείας, ACL δικτύου, VPN και proxies.

Για παράδειγμα, από Linux ή macOS μπορείτε να δοκιμάσετε έναν συγκεκριμένο κόμβο Atlas ή αυτοδιαχειριζόμενο κεντρικό υπολογιστή με:

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

Στο Windows PowerShell, μια χονδρική δοκιμή προσβασιμότητας TCP είναι:

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

Μια επιτυχής δοκιμή TCP δεν αποδεικνύει ότι ο έλεγχος ταυτότητας ή το TLS θα πετύχουν, αλλά μια αποτυχημένη δοκιμή TCP σημαίνει ότι η ρύθμιση timeout του Mongoose είναι πρόωρη.

Αν το URI σας χρησιμοποιεί mongodb+srv://

Μια συμβολοσειρά σύνδεσης SRV εξαρτάται από εγγραφές DNS SRV. Τα τρέχοντα βήματα αντιμετώπισης προβλημάτων του MongoDB συνιστούν τον έλεγχο της αναζήτησης SRV από το περιβάλλον του πελάτη:

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

Αν το ερώτημα SRV αποτύχει, επιβεβαιώστε το όνομα κεντρικού υπολογιστή και τη διαμόρφωση DNS. Το MongoDB τεκμηριώνει μια μη-SRV συμβολοσειρά σύνδεσης mongodb:// ως πιθανή λύση όταν το περιβάλλον δεν μπορεί να επιλύσει εγγραφές SRV, αλλά πρέπει να λάβετε αυτήν την τυπική συμβολοσειρά σύνδεσης από το Atlas ή τη διαμόρφωση ανάπτυξής σας αντί να επινοήσετε ονόματα κόμβων. Δείτε Αντιμετώπιση προβλημάτων σύνδεσης Atlas.

Η σωστή διαγνωστική ακολουθία ελέγχει τη διεύθυνση και τη διαδρομή δικτύου πριν αντιμετωπίσει τις τιμές timeout ως την αιτία ρίζα.

Βήμα 3: Διορθώστε το URI για το περιβάλλον όπου εκτελείται πραγματικά το Node.js

Ένα συντακτικά έγκυρο URI MongoDB μπορεί ακόμα να δείχνει στο λάθος μέρος. Ελέγξτε το σχήμα, το όνομα κεντρικού υπολογιστή, τη θύρα, το όνομα βάσης δεδομένων, τις απαιτήσεις σετ αντιγραφής, την πηγή ελέγχου ταυτότητας και αν το όνομα κεντρικού υπολογιστή είναι σημασιολογικό από τον χώρο ονομάτων δικτύου της εφαρμογής.

Τοπικό Node.js και τοπικό MongoDB

Το Mongoose συνιστά τώρα 127.0.0.1 αντί για localhost για τοπικό MongoDB:

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

Ο λόγος είναι το Node.js 18 και νεότερο: Το Mongoose σημειώνει ότι το Node.js μπορεί να επιλύσει το localhost σε IPv6 ::1, ενώ μια τοπική περίπτωση MongoDB μπορεί να ακούει μόνο σε IPv4. Το Mongoose τεκμηριώνει επίσης το { family: 4 } ως επιλογή όταν η επίλυση IPv6-first κάνει τις προσπάθειες σύνδεσης αργές:

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

Χρησιμοποιήστε το family: 4 μόνο όταν η διαδρομή επίλυσης IPv4/IPv6 είναι πραγματικά το πρόβλημα. Αν η ανάπτυξη MongoDB σας υποστηρίζει σωστά το IPv6, η αναγκαστική χρήση IPv4 είναι περιττή.

Node.js μέσα σε Docker

Αν η εφαρμογή είναι μέσα σε ένα container, το localhost αναφέρεται σε αυτό το container, όχι αυτόματα στο MongoDB στον κεντρικό υπολογιστή ή σε άλλο container. Χρησιμοποιήστε το όνομα κεντρικού υπολογιστή της υπηρεσίας/container MongoDB σε ένα κοινό δίκτυο Docker, ή τη διεύθυνση κεντρικού υπολογιστή συγκεκριμένη για την πλατφόρμα όταν το MongoDB εκτελείται στον κεντρικό υπολογιστή.

Για παράδειγμα, με μια υπηρεσία Compose με όνομα mongo:

MONGODB_URI=mongodb://mongo:27017/myapp

Προϋπόθεση: Αυτό το παράδειγμα ισχύει μόνο αν τα containers μοιράζονται ένα δίκτυο και η υπηρεσία MongoDB ονομάζεται πραγματικά mongo. Μην αντιγράψετε το όνομα κεντρικού υπολογιστή σε μια ασύνδετη ανάπτυξη.

Atlas

Χρησιμοποιήστε τη συμβολοσειρά σύνδεσης που δημιουργήθηκε από το Atlas για τον οδηγό σας, διατηρήστε ακριβώς τον κεντρικό υπολογιστή mongodb+srv://, κωδικοποιήστε με URL τους δεσμευμένους χαρακτήρες στα ονόματα χρηστών ή τους κωδικούς πρόσβασης όταν απαιτείται, και επαληθεύστε ότι ο χρήστης βάσης δεδομένων υπάρχει στο επιθυμητό έργο.

Αν συνδέεστε σε ένα αυτοδιαχειριζόμενο σετ αντιγραφής, τα ονόματα κεντρικών υπολογιστών που αναφέρονται από το σετ αντιγραφής πρέπει επίσης να είναι προσβάσιμα από τον πελάτη. Ένας κόμβος σπόρου μπορεί να είναι προσβάσιμος ενώ η μεταγενέστερη επιλογή διακομιστή αποτυγχάνει ακόμα επειδή τα μέλη του σετ αντιγραφής διαφημίζουν ονόματα κεντρικών υπολογιστών που η εφαρμογή δεν μπορεί να επιλύσει ή να δρομολογήσει.

Βήμα 4: Ρυθμίστε τα timeouts μόνο αφού η συνδεσιμότητα πετύχει

Μόλις το DNS επιλυθεί, η διαδρομή δικτύου λειτουργεί, ο διακομιστής είναι διαθέσιμος και το URI είναι σωστό, η ρύθμιση timeout γίνεται ουσιαστική.

Το Mongoose περνά τις επιλογές σύνδεσης σχετικές με το timeout στον υποκείμενο οδηγό MongoDB, αλλά κάθε επιλογή ελέγχει ένα διαφορετικό στάδιο. Οι μεγαλύτερες τιμές δεν πρέπει να χρησιμοποιούνται για να κρύψουν μια σπασμένη διαδρομή ή έναν μη προσβάσιμο διακομιστή.

Ένα συντηρητικό παράδειγμα για μια εφαρμογή που θέλει ένα σήμα αρχικής αποτυχίας 10 δευτερολέπτων μπορεί να μοιάζει έτσι:

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

Αν τα 10 δευτερόλεπτα είναι κατάλληλα εξαρτάται από την ανάπτυξη. Το αντάλλαγμα είναι απλό:

Για το socketTimeoutMS, η τρέχουσα τεκμηρίωση του οδηγού Node.js του MongoDB χρησιμοποιεί μια προεπιλογή 0, που σημαίνει χωρίς timeout αδράνειας socket. Το MongoDB συνιστά, όταν επιλέξετε να το ορίσετε, να επιλέξετε μια τιμή περίπου δύο έως τρεις φορές μεγαλύτερη από την πιο αργή λειτουργία που περιμένετε. Αυτή η ρύθμιση ισχύει για sockets που έχουν ήδη συνδεθεί, οπότε δεν είναι η κύρια διόρθωση για μια αρχική λήξη χρόνου επιλογής διακομιστή.

Μην αντιγράφετε παλιές επιλογές σύνδεσης Mongoose σε ένα τρέχον έργο

Πολλά παλαιότερα παραδείγματα περιέχουν ακόμα useNewUrlParser, useUnifiedTopology, keepAlive ή keepAliveInitialDelay. Το τρέχον Mongoose δεν απαιτεί τις παλιές επιλογές parser/topology, και το Mongoose τεκμηριώνει το keepAlive ως ενεργοποιημένο από προεπιλογή από το Mongoose 5.2 και καταργημένο ως επιλογή σύνδεσης από το 7.2.

Μια σύγχρονη βάση είναι σκόπιμα μικρή:

import mongoose from 'mongoose';

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

Προσθέστε επιλογές σύνδεσης επειδή το περιβάλλον σας τις χρειάζεται, όχι επειδή εμφανίστηκαν σε ένα απόσπασμα πέντε ετών.

Τι γίνεται αν η σύνδεση λειτουργεί, αλλά τα ερωτήματα λήγουν αργότερα;

Αυτό είναι ένα διαφορετικό πρόβλημα. Αν η mongoose.connect() πετύχει και η εφαρμογή κρεμάσει αργότερα σε ερωτήματα, ερευνήστε τη καθυστέρηση λειτουργίας, την πίεση της δεξαμενής συνδέσεων, το φορτίο διακομιστή, τους δείκτες και τα timeouts socket ή λειτουργίας. Ο τρέχων οδηγός Node.js του MongoDB διαχωρίζει:

• serverSelectionTimeoutMS — Εύρεση κατάλληλου διακομιστή.
• connectTimeoutMS — Δημιουργία μιας σύνδεσης TCP.
• socketTimeoutMS — Αδράνεια σε ένα εγκατεστημένο socket.
• maxTimeMS — Περιορισμός του χρόνου εκτέλεσης μιας λειτουργίας διακομιστή μόλις φτάσει στο MongoDB.

Αν μόνο τα μακρά ερωτήματα αποτυγχάνουν, η αύξηση του serverSelectionTimeoutMS είναι απίθανο να λύσει το πραγματικό πρόβλημα.

Γρήγορη διάγνωση ανά συνθήκη σφάλματος

Ένα πρότυπο σύνδεσης φιλικό προς την παραγωγή

Κρατήστε τα μυστικά εκτός του πηγαίου κώδικα, αποτύχετε καθαρά στην εκκίνηση όταν η βάση δεδομένων δεν είναι διαθέσιμη και καταγράψτε αρκετές λεπτομέρειες για διάγνωση χωρίς να εκτυπώνετε διαπιστευτήρια:

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

Αυτές οι τιμές 30 δευτερολέπτων ταιριάζουν με τις τρέχουσες τεκμηριωμένες προεπιλογές, οπότε μπορείτε να τις παραλείψετε εκτός αν η ρητή πολιτική βοηθά τις λειτουργίες σας. Το σημαντικό μέρος δεν είναι οι αριθμοί. Είναι να γνωρίζετε γιατί ένας διαφορετικός αριθμός θα ήταν καλύτερος για την ανάπτυξή σας.

Τελική λίστα ελέγχου

• Καταγράψτε το πλήρες σφάλμα και επιθεωρήστε το err.reason.
• Επιβεβαιώστε ότι η ανάπτυξη MongoDB εκτελείται και είναι διαθέσιμη.
• Εκτελέστε δοκιμές DNS και TCP από το ίδιο περιβάλλον με τη διαδικασία Node.js.
• Για το Atlas, επαληθεύστε ότι η IP εξόδου της εφαρμογής είναι στη λίστα πρόσβασης IP.
• Για mongodb+srv://, επαληθεύστε την επίλυση DNS SRV.
• Για τοπικό MongoDB, δοκιμάστε 127.0.0.1 αν το localhost επιλύεται σε μη χρησιμοποιήσιμο IPv6.
• Για Docker ή Kubernetes, χρησιμοποιήστε ένα όνομα κεντρικού υπολογιστή που είναι έγκυρο μέσα σε αυτόν τον χώρο ονομάτων δικτύου.
• Διορθώστε τα σφάλματα TLS ή ελέγχου ταυτότητας αντί να τα καλύπτετε με ένα μεγαλύτερο timeout.
• Ρυθμίστε το serverSelectionTimeoutMS, connectTimeoutMS ή socketTimeoutMS μόνο για το στάδιο που ελέγχουν πραγματικά.
• Μετά τη διόρθωση, επαληθεύστε ότι η εφαρμογή συνδέεται συνεπώς από το πραγματικό περιβάλλον ανάπτυξης, όχι μόνο από έναν φορητό υπολογιστή προγραμματιστή.

Τελικό συμπέρασμα

Αν το Mongoose αναφέρει λήξη χρόνου δικτύου MongoDB, πρώτα αποδείξτε ότι ο οδηγός μπορεί να ανακαλύψει και να φτάσει έναν κατάλληλο διακομιστή MongoDB. Οι περιορισμοί IP του Atlas, τα firewalls, η επίλυση DNS SRV, τα λανθασμένα ονόματα κεντρικών υπολογιστών container, οι ασυμφωνίες IPv4/IPv6, οι μη διαθέσιμες διαδικασίες MongoDB και η διαμόρφωση TLS μπορούν όλα να κάνουν μια λήξη χρόνου 30 δευτερολέπτων να φαίνεται ως το πρόβλημα όταν ο χρονομέτρης απλώς αναφέρει την αποτυχία.

Χρησιμοποιήστε τις ρυθμίσεις timeout για να ορίσετε πόσο καιρό η εφαρμογή σας πρέπει να περιμένει για ένα γνωστά καλό σύστημα—όχι για να αντισταθμίσετε μια σπασμένη διαδρομή σύνδεσης. Μόλις η προσβασιμότητα δικτύου και το URI είναι σωστά, τότε επιλέξτε τιμές timeout που ταιριάζουν με το μοντέλο διαθεσιμότητάς σας, τη συμπεριφορά failover και την αναμενόμενη καθυστέρηση λειτουργίας.