Πώς να διορθώσετε το σφάλμα "Nginx 502 Bad Gateway" κατά τη μεσολάβηση στο Node.js

Μια κακή πύλη NGINX 502 μπροστά από μια εφαρμογή Node.js συνήθως σημαίνει ένα πράγμα: Η NGINX αποδέχτηκε το αίτημα του πελάτη, αλλά δεν μπόρεσε να λάβει μια χρησιμοποιήσιμη απόκριση από την εφαρμογή upstream με την οποία έπρεπε να επικοινωνήσει. Η ταχύτερη λύση είναι επομένως να μην επανεκκινήσετε τα πάντα ή να αυξήσετε κάθε χρονικό όριο. Πρώτα αποδείξτε εάν η υπηρεσία Node.js είναι προσβάσιμη από την ίδια τοποθεσία δικτύου με την NGINX και, στη συνέχεια, χρησιμοποιήστε το αρχείο καταγραφής σφαλμάτων NGINX για να επιλέξετε την επόμενη κίνηση.

Αυτός ο οδηγός χρησιμοποιεί τέσσερα διαγνωστικά βήματα. Οι εντολές υποθέτουν ότι ένας κεντρικός υπολογιστής Linux και μια εφαρμογή Node.js αναμένονται στη θύρα 3000. Αντικαταστήστε τη θύρα, το όνομα κεντρικού υπολογιστή, τις διαδρομές και τα ονόματα υπηρεσιών με τις τιμές στην ανάπτυξή σας.

Τι πρέπει να ελέγξετε πριν αλλάξετε το NGINX;

Κάντε πρώτα τρεις ερωτήσεις:

• Η διεργασία Node.js ακούει πραγματικά τη διεύθυνση και τη θύρα στην οποία προσπαθεί να φτάσει το NGINX;
• Ποιο ακριβώς σφάλμα upstream καταγράφει το αρχείο καταγραφής σφαλμάτων NGINX για το αποτυχημένο αίτημα;
• Τα NGINX και Node.js εκτελούνται στον ίδιο κεντρικό υπολογιστή, σε ξεχωριστά κοντέινερ ή σε ξεχωριστά μηχανήματα;

Αυτές οι απαντήσεις έχουν σημασία επειδή το ίδιο 502 που είναι ορατό στο πρόγραμμα περιήγησης μπορεί να προέρχεται από πολύ διαφορετικές συνθήκες. Μια διακοπείσα διεργασία Node, η λανθασμένη proxy_passθύρα, ένα κοντέινερ που χρησιμοποιείται 127.0.0.1εσφαλμένα, ένα χρονικό όριο ανόδου και μια μη έγκυρη απόκριση ανόδου δεν έχουν την ίδια λύση.

Το NGINX τεκμηριώνει proxy_passως οδηγία που καθορίζει το πρωτόκολλο και τη διεύθυνση του διακομιστή μεσολάβησης. Η ανοδική του μονάδα εμφανίζει επίσης μεταβλητές όπως $upstream_addr, $upstream_status, $upstream_connect_time, και $upstream_response_time, οι οποίες είναι χρήσιμες όταν χρειάζεστε πιο λεπτομερή καταγραφή παραγωγής. Ανατρέξτε στην επίσημη τεκμηρίωση της μονάδας proxy NGINX και στην τεκμηρίωση της ανοδικής μονάδας NGINX .

Βήμα 1: Μπορεί να επιτευχθεί απευθείας η πρόσβαση στο upstream του NGINX;

Ξεκινήστε παρακάμπτοντας τον αντίστροφο διακομιστή μεσολάβησης. Εάν το NGINX βρίσκεται στον ίδιο κεντρικό υπολογιστή με το Node.js και η διαμόρφωσή σας δείχνει στο 127.0.0.1:3000, δοκιμάστε αυτόν ακριβώς τον προορισμό:

curl -i http://127.0.0.1:3000/health
ss -ltnp | grep ':3000'

Ένα υγιές αποτέλεσμα μπορεί να επιστρέψει HTTP 200 από την εφαρμογή σας και να εμφανίσει έναν ακροατή στη θύρα 3000. Εάν η σύνδεση απορριφθεί, μην επεξεργαστείτε ακόμη τα χρονικά όρια του NGINX. Δεν υπάρχει υπηρεσία ακρόασης στη διεύθυνση που προσπαθεί να χρησιμοποιήσει το NGINX ή η υπηρεσία ακούει κάπου αλλού.

Τι γίνεται αν η διεργασία Node.js εκτελείται αλλά η θύρα λείπει;

Μια εκτελούμενη διεργασία δεν είναι αρκετή. Η εφαρμογή πρέπει να έχει ολοκληρώσει την εκκίνηση του διακομιστή της και να έχει συνδέσει με επιτυχία μια υποδοχή ακρόασης. Το Node.js καταγράφεται server.listen()ως η λειτουργία που ξεκινά έναν διακομιστή TCP ή IPC που ακούει για συνδέσεις. Σημειώνει επίσης ότι αυτό EADDRINUSEσυμβαίνει όταν ένας άλλος διακομιστής κατέχει ήδη την ζητούμενη θύρα. Ανατρέξτε στην επίσημη τεκμηρίωση του διακομιστή δικτύου Node.js και στην τεκμηρίωση HTTP Node.js.

Μια ελάχιστη υπηρεσία δοκιμής HTTP Node.js μπορεί να μοιάζει με αυτό:

import http from 'node:http';

const server = http.createServer((req, res) => {
  if (req.url === '/health') {
    res.writeHead(200, { 'content-type': 'application/json' });
    return res.end(JSON.stringify({ status: 'ok' }));
  }

  res.writeHead(200, { 'content-type': 'text/plain' });
  res.end('Node.js is running');
});

server.listen(3000, '127.0.0.1', () => {
  console.log('Listening on http://127.0.0.1:3000');
});

Η σύνδεση με 127.0.0.1είναι κατάλληλη όταν το NGINX και το Node.js μοιράζονται τον ίδιο κεντρικό υπολογιστή και κανένα άλλο μηχάνημα δεν χρειάζεται άμεση πρόσβαση στη θύρα Node. Εάν βρίσκονται σε ξεχωριστά κοντέινερ, η διεύθυνση αυτή έχει διαφορετική σημασία, η οποία καλύπτεται παρακάτω.

Βήμα 2: Τι λέει στην πραγματικότητα το αρχείο καταγραφής σφαλμάτων NGINX;

Μόλις μάθετε εάν το upstream ανταποκρίνεται άμεσα, ελέγξτε την καταχώρηση καταγραφής που δημιουργήθηκε ταυτόχρονα με το 502. Μια συνηθισμένη τοποθεσία σε πακέτα Linux είναι το /var/log/nginx/error.log, αλλά η πραγματική διαδρομή ελέγχεται από την error_logοδηγία και μπορεί να διαφέρει ανάλογα με την εγκατάσταση.

sudo tail -n 100 /var/log/nginx/error.log

Η βασική τεκμηρίωση του NGINX αναφέρει ότι error_logελέγχει τον προορισμό και τη σοβαρότητα του αρχείου καταγραφής διαγνωστικών. Η τεκμηρίωση γραμμής εντολών παρέχει επίσης nginx -Tτη δυνατότητα δοκιμής και λήψης δεδομένων από την ενεργή διαμόρφωση, η οποία μπορεί να σας βοηθήσει να βρείτε μια μη αναμενόμενη διαδρομή αρχείου καταγραφής ή μπλοκ διακομιστή. Ανατρέξτε στην τεκμηρίωση βασικής καταγραφής του NGINX και στις παραμέτρους γραμμής εντολών του NGINX .

Χρησιμοποιήστε το μήνυμα για να περιορίσετε το πρόβλημα:

Βήμα 3: Υποδεικνύει το proxy_pass τη διεύθυνση που χρησιμοποιεί πραγματικά το Node.js;

Συγκρίνετε τον ζωντανό ακροατή από το Βήμα 1 με την ενεργή διαμόρφωση NGINX. Μια συμβατική ρύθμιση ίδιου κεντρικού υπολογιστή μοιάζει με αυτό:

server {
    listen 80;
    server_name example.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Το NGINX υποστηρίζει επίσημα μια διεύθυνση IP, ένα όνομα κεντρικού υπολογιστή, μια ομάδα upstream ή μια υποδοχή τομέα UNIX σε proxy_pass. Ο κρίσιμος κανόνας είναι απλός: ο προορισμός πρέπει να είναι προσβάσιμος από το περιβάλλον δικτύου του εργαζομένου NGINX.

Βρίσκονται τα NGINX και Node.js σε ξεχωριστά κοντέινερ Docker Compose;

Εάν ναι, 127.0.0.1μέσα στο κοντέινερ NGINX αναφέρεται το ίδιο το κοντέινερ NGINX, όχι το κοντέινερ Node.js. Η τεκμηρίωση του Docker Compose αναφέρει ότι οι υπηρεσίες στο προεπιλεγμένο δίκτυο Compose είναι ανιχνεύσιμες με βάση το όνομα της υπηρεσίας. Συνιστά επίσης τη χρήση της θύρας κοντέινερ για επικοινωνία μεταξύ υπηρεσιών αντί για μια θύρα που δημοσιεύεται από τον κεντρικό υπολογιστή.

Για παράδειγμα, εάν η υπηρεσία Compose έχει όνομα appκαι ο Node εκτελεί ακρόαση στη θύρα κοντέινερ 3000, το NGINX μπορεί να χρησιμοποιήσει:

location / {
    proxy_pass http://app:3000;
}

Και οι δύο υπηρεσίες πρέπει να μοιράζονται ένα δίκτυο. Η υπηρεσία Node πρέπει επίσης να ακούει σε μια διεπαφή προσβάσιμη από αυτό το δίκτυο κοντέινερ. Οι εφαρμογές συνήθως συνδέονται 0.0.0.0μέσα στο κοντέινερ για αυτόν τον σκοπό. Δεν χρειάζεται απαραίτητα να δημοσιεύσετε τη θύρα 3000 στον κεντρικό υπολογιστή μόνο για την κίνηση NGINX-προς-εφαρμογή. Επαληθεύστε την τοπολογία σε σχέση με την επίσημη τεκμηρίωση δικτύωσης Docker Compose .

Να χρησιμοποιήσω localhost ή 127.0.0.1;

Εάν και οι δύο διεργασίες εκτελούνται στον ίδιο κεντρικό υπολογιστή, οποιαδήποτε από τις δύο μπορεί να λειτουργήσει, αλλά δεν είναι πάντα εναλλάξιμες σε κάθε περιβάλλον, επειδή localhostμπορούν να αναλυθούν σε IPv4, IPv6 ή και στα δύο. Η χρήση της ακριβούς διεύθυνσης που εμφανίζεται από τον ακροατή καταργεί μία μεταβλητή. Το Node.js τεκμηριώνει ότι εάν hostπαραλειφθεί το όρισμα, μπορεί να ακούσει την μη καθορισμένη διεύθυνση IPv6 ::όταν είναι διαθέσιμη ή την μη καθορισμένη διεύθυνση IPv4 0.0.0.0διαφορετικά.

Εάν παρατηρήσετε κάποια αναντιστοιχία, όπως η επικοινωνία του NGINX 127.0.0.1:3000ενώ η εφαρμογή είναι διαθέσιμη μόνο μέσω άλλου ονόματος κεντρικού υπολογιστή κοντέινερ, διαφορετικής θύρας ή υποδοχής UNIX, διορθώστε τη διεύθυνση αντί να αντισταθμίσετε με επαναλήψεις.

Είναι όντως η σωστή λύση ένα μεγαλύτερο χρονικό όριο;

Αλλάξτε τα χρονικά όρια μόνο όταν τα αρχεία καταγραφής εμφανίζουν χρονικό όριο και κατανοείτε γιατί η ανοδική ροή χρειάζεται περισσότερο χρόνο. Το NGINX καταγράφει μια προεπιλογή proxy_connect_timeout60 δευτερολέπτων και σημειώνει ότι συνήθως δεν μπορεί να υπερβαίνει τα 75 δευτερόλεπτα. Καταγράφει επίσης μια προεπιλογή proxy_read_timeout60 δευτερολέπτων, η οποία μετράται μεταξύ διαδοχικών αναγνώσεων από την ανοδική ροή και όχι σε ολόκληρη την απόκριση.

location /reports/ {
    proxy_pass http://127.0.0.1:3000;
    proxy_connect_timeout 5s;
    proxy_read_timeout 120s;
}

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

Ελέγξτε την ακριβή σημασιολογία στις επίσημες οδηγίες χρονικού ορίου διακομιστή μεσολάβησης NGINX .

Τι γίνεται αν μόνο οι συνδέσεις WebSocket λάβουν σφάλμα 502 ή αποσυνδεθούν;

Το WebSocket proxying έχει πρόσθετες απαιτήσεις, επειδή οι κεφαλίδες Upgradeκαι Connectionείναι κεφαλίδες hop-by-hop και δεν προωθούνται αυτόματα στη συνηθισμένη διαδρομή reverse-proxy. Η επίσημη τεκμηρίωση WebSocket της NGINX δείχνει ρητά τον ορισμό αυτών των κεφαλίδων.

location /socket/ {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

Το NGINX σημειώνει επίσης ότι μια αδρανής σύνδεση WebSocket με proxy κλείνει εάν η upstream δεν στείλει δεδομένα εντός του διαστήματος χρονικού ορίου ανάγνωσης. Ένα ping σε επίπεδο εφαρμογής μπορεί να διατηρήσει τη σύνδεση ενεργή όπου χρειάζεται. Για την τρέχουσα συμπεριφορά και τις σημειώσεις που αφορούν συγκεκριμένες εκδόσεις, χρησιμοποιήστε την επίσημη τεκμηρίωση proxying του NGINX WebSocket .

Βήμα 4: Πώς επικυρώνετε την επιδιόρθωση χωρίς να δημιουργήσετε νέα διακοπή λειτουργίας;

Ελέγξτε τη διαμόρφωση πριν από την επαναφόρτωση του NGINX:

sudo nginx -t
sudo nginx -s reload

Τα έγγραφα NGINX -tως έλεγχος σύνταξης και αρχείου αναφοράς και -s reloadως σήμα που επαναφορτώνει τη διαμόρφωση ξεκινώντας νέους εργάτες και κλείνοντας ομαλά τους παλιούς.

Στη συνέχεια, επαληθεύστε ξανά και τα δύο επίπεδα:

curl -i http://127.0.0.1:3000/health
curl -I https://example.com/

Μην σταματάτε στις «φορτώσεις της αρχικής σελίδας». Επανεξετάστε τη διαδρομή που απέτυχε αρχικά, συμπεριλαμβανομένης της μεθόδου HTTP και οποιουδήποτε σώματος αιτήματος. Εάν το σφάλμα 502 εμφανίστηκε μόνο σε μεταφορτώσεις, κλήσεις API, μεγάλες αναφορές ή WebSockets, δοκιμάστε το ίδιο μοτίβο επισκεψιμότητας.

Τι γίνεται αν το άμεσο Node.js ζητήσει εργασία, αλλά το NGINX εξακολουθεί να επιστρέφει 502;

Αυτό το αποτέλεσμα περιορίζει σημαντικά το πρόβλημα. Ελέγξτε αυτά τα στοιχεία με τη σειρά:

1. Επιβεβαιώστε το ενεργό μπλοκ διακομιστή. Εκτελέστε sudo nginx -Tκαι βεβαιωθείτε ότι τα αναμενόμενα server_nameκαι locationχειρίζονται το αίτημα.
2. Επιβεβαιώστε τον ακριβή ανοδικό στόχο. Η διεύθυνση στο proxy_passπρέπει να ταιριάζει με αυτό που είναι προσβάσιμο από το NGINX, όχι απλώς με αυτό που λειτουργεί από τον φορητό υπολογιστή σας ή από διαφορετικό κοντέινερ.
3. Ελέγξτε την ασυμφωνία πρωτοκόλλου. Εάν το upstream αναμένει HTTPS αλλά το NGINX χρησιμοποιεί http://ή αντίστροφα, διορθώστε το σχήμα και, στη συνέχεια, ρυθμίστε σκόπιμα το upstream TLS.
4. Αναζητήστε επαναφορές συνδέσεων εφαρμογών. Επιθεωρήστε τα αρχεία καταγραφής διεργασιών Node.js στην ίδια χρονική σήμανση με το σφάλμα NGINX. Μια διακοπή ή διακοπή σύνδεσης απαιτεί μια επιδιόρθωση από την πλευρά της εφαρμογής.
5. Ελέγξτε την εξειδικευμένη επισκεψιμότητα. Τα WebSockets, οι απαντήσεις ροής, τα μεγάλα αιτήματα και οι ασυνήθιστα αργοί χειριστές μπορεί να χρειάζονται διαφορετικές ρυθμίσεις διακομιστή μεσολάβησης από ένα απλό JSON API.

Εάν τα NGINX και Node.js διαχωρίζονται από τείχος προστασίας, υπηρεσία Kubernetes, εξισορροπητή φόρτου, πλέγμα υπηρεσίας ή άλλο διακομιστή μεσολάβησης, το προβληματικό hop ενδέχεται να μην είναι η τοπική σύνδεση NGINX-προς-Node. Ελέγξτε κάθε hop ξεχωριστά αντί να υποθέσετε ότι ο ορατός διακομιστής NGINX είναι η πηγή της αποτυχίας.

Πρέπει πρώτα να επανεκκινήσετε το Node.js ή το NGINX;

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

Εάν η θύρα Node απουσιάζει, ελέγξτε τα αρχεία καταγραφής του διαχειριστή διεργασιών ή του κοντέινερ, διορθώστε το πρόβλημα εκκίνησης της εφαρμογής και, στη συνέχεια, ξεκινήστε την υπηρεσία. Εάν αλλάξατε μόνο τη διαμόρφωση του NGINX, χρησιμοποιήστε το nginx -tπριν από την επαναφόρτωση. Εάν αλλάξατε τον κώδικα ή τις μεταβλητές περιβάλλοντος του Node.js, επανεκκινήστε την υπηρεσία Node χρησιμοποιώντας τον επόπτη που χρησιμοποιεί στην πραγματικότητα η ανάπτυξή σας, όπως το systemd, έναν ενορχηστρωτή κοντέινερ ή έναν άλλο διαχειριστή διεργασιών.

Για το Node.js παραγωγής, επαληθεύστε επίσης ότι βρίσκεστε σε μια υποστηριζόμενη γραμμή έκδοσης. Από τον Σεπτέμβριο του 2026, η επίσημη σελίδα έκδοσης του Node.js παραθέτει τα Node.js 24 και 22 ως γραμμές LTS και συνιστά στις εφαρμογές παραγωγής να χρησιμοποιούν εκδόσεις Active LTS ή Maintenance LTS. Ελέγξτε την τρέχουσα κατάσταση στην επίσημη σελίδα εκδόσεων Node.js αντί να βασίζεστε σε ένα παλιό εκπαιδευτικό βίντεο.

Ένας συμπαγής πίνακας αποφάσεων NGINX 502

Τελικός αυτοέλεγχος

Πιθανότατα έχετε διορθώσει την αιτία, αντί απλώς να καταστείλετε το σύμπτωμα, όταν ισχύουν όλα τα ακόλουθα:

• Το Node.js upstream ανταποκρίνεται απευθείας από το ίδιο περιβάλλον δικτύου που χρησιμοποιεί το NGINX.
• Ο ακροατής κόμβου και proxy_passσυμφωνούν για το πρωτόκολλο, τη διεύθυνση και τη θύρα.
• Το αρχείο καταγραφής σφαλμάτων NGINX δεν καταγράφει πλέον αποτυχίες σύνδεσης upstream για την επηρεαζόμενη διαδρομή.
• nginx -tεπιτυγχάνεται πριν από κάθε επαναφόρτωση διαμόρφωσης.
• Το αρχικό αποτυχημένο αίτημα—όχι μόνο η αρχική σελίδα—τώρα ολοκληρώνεται με επιτυχία μέσω του NGINX.
• Τα χρονικά όρια άλλαζαν μόνο όταν τα αρχεία καταγραφής και η μετρούμενη συμπεριφορά της εφαρμογής δικαιολογούσαν την αλλαγή.
• Οι αναπτύξεις κοντέινερ χρησιμοποιούν δικτύωση από υπηρεσία σε υπηρεσία αντί να υποθέτουν ότι 127.0.0.1διασχίζουν τα όρια των κοντέινερ.

Το πιο αξιόπιστο μοτίβο αντιμετώπισης προβλημάτων είναι επομένως: ελέγξτε απευθείας τον κόμβο, διαβάστε το σφάλμα NGINX, αντιστοιχίστε την ανοδική διεύθυνση με την πραγματική τοπολογία δικτύου και, στη συνέχεια, επικυρώστε και επαναφορτώστε . Ένα σφάλμα 502 είναι σύμπτωμα πύλης. Η χρήσιμη ερώτηση είναι πάντα ποιο hop απέτυχε και τι λέει το αρχείο καταγραφής σχετικά με αυτήν την αποτυχία.