Πώς να διορθώσετε το σφάλμα αποτυχίας σύνδεσης Redis στο 127.0.0.1:6379

Γρήγορη απάντηση: Εάν η εφαρμογή σας αναφέρει Could not connect to Redis at 127.0.0.1:6379: Connection refused, ξεκινήστε ελέγχοντας αν ένας διακομιστής Redis ακούει πραγματικά σε αυτήν τη διεύθυνση και θύρα. Το Redis CLI χρησιμοποιεί από προεπιλογή το 127.0.0.1 και τη θύρα 6379, οπότε μια απόρριψη συνήθως υποδηλώνει έναν διακομιστή που έχει σταματήσει, μια διαφορετική θύρα, ασυμφωνία δικτύωσης σε container ή εικονική μηχανή, ή πρόβλημα στη διαμόρφωση του ακροατή (listener). Τα σφάλματα πιστοποίησης είναι διαφορετικά: εμφανίζονται συνήθως αφού η σύνδεση TCP έχει ήδη εγκατασταθεί.

Η ταχύτερη διάγνωση είναι η εντολή redis-cli -h 127.0.0.1 -p 6379 PING. Εάν επιστρέψει PONG, το Redis είναι προσβάσιμο και πρέπει να ελέγξετε το URL του Redis στην εφαρμογή σας, τα διαπιστευτήρια, τις ρυθμίσεις TLS ή τη διαμόρφωση της δεξαμενής συνδέσεων (connection pool) αντί να κάνετε επανεκκίνηση του Redis τυφλά. Το Redis τεκμηριώνει συγκεκριμένα την εντολή PING ως τρόπο ελέγχου αν μια σύνδεση είναι ενεργή και αν ο διακομιστής μπορεί να εξυπηρετήσει δεδομένα. Δείτε την επίσημη τεκμηρίωση της εντολής PING του Redis.

Πίνακας γρήγορης διάγνωσης

1. Αναπαραγωγή της αποτυχίας εκτός της εφαρμογής σας

Χρησιμοποιήστε το Redis CLI πριν αλλάξετε τον κώδικα της εφαρμογής. Η επίσημη τεκμηρίωση του CLI του Redis αναφέρει ότι, από προεπιλογή, το redis-cli συνδέεται στο 127.0.0.1:6379. Μπορείτε να κάνετε τον στόχο ρητό:

redis-cli -h 127.0.0.1 -p 6379 PING

Ένας επιτυχής τοπικός διακομιστής θα απαντήσει:

PONG

Εάν λάβετε το ίδιο μήνυμα απόρριψης σύνδεσης, έχετε αναπαράγει το πρόβλημα στο επίπεδο μεταφοράς. Αυτό είναι χρήσιμο επειδή αφαιρεί το framework, το ORM, τη βιβλιοθήκη cache και τον κώδικα της εφαρμογής από την άμεση έρευνα. Το Redis CLI δέχεται επίσης το -h για τον host και το -p για τη θύρα, όπως τεκμηριώνεται στην αναφορά του Redis CLI.

Εάν το PING επιστρέφει ήδη PONG, μεταβείτε στο βήμα 5. Μην συνεχίζετε να κάνετε επανεκκίνηση ενός υγιούς instance Redis· εστιάστε στη συμβολοσειρά σύνδεσης της εφαρμογής και στο περιβάλλον εκτέλεσης.

2. Βεβαιωθείτε ότι ο διακομιστής Redis εκτελείται

Σε ένα σύστημα Linux εγκατεστημένο μέσω διαχειριστή πακέτων, το Redis μπορεί συνήθως να ελέγχεται ως υπηρεσία συστήματος. Η τεκμηρίωση εγκατάστασης του Redis για Linux δείχνει τις εντολές systemctl start και systemctl stop, σημειώνοντας ότι το όνομα της υπηρεσίας μπορεί να είναι redis ή redis-server ανάλογα με την πλατφόρμα. Ένας τυπικός έλεγχος σε Ubuntu/Debian είναι:

sudo systemctl status redis-server
sudo systemctl start redis-server
sudo systemctl status redis-server

Εάν η διανομή σας χρησιμοποιεί το redis ως όνομα υπηρεσίας, αντικαταστήστε με αυτό το όνομα. Εάν το systemd δεν διαχειρίζεται τη διαδικασία Redis σας, χρησιμοποιήστε τη μέθοδο εκκίνησης που ταιριάζει με τον τρόπο εγκατάστασης του Redis αντί να υποθέσετε ότι υπάρχει υπηρεσία. Η τρέχουσα καθοδήγηση του Redis για Linux είναι διαθέσιμη στην επίσημη τεκμηρίωση εγκατάστασης για Linux.

Σημείωση για Windows και WSL

Μην υποθέσετε ότι υπάρχει μια εγγενής υπηρεσία Redis για Windows μόνο επειδή η εφαρμογή σας εκτελείται σε Windows. Η τρέχουσα επισκόπηση εγκατάστασης του Redis κατατάσσει τα Windows στη διαδρομή Docker, ενώ το Redis διατηρεί επίσης τεκμηρίωση για Windows για το WSL και τον συνεργάτη συμβατότητας για Windows. Εάν το Redis εκτελείται μέσα στο WSL, δοκιμάστε το πρώτα από το ίδιο περιβάλλον WSL. Εάν το Redis εκτελείται στο Docker Desktop, χρησιμοποιήστε τους ελέγχους Docker στην επόμενη ενότητα. Δείτε την τρέχουσα επισκόπηση εγκατάστασης του Redis Open Source και την τεκμηρίωση εγκατάστασης Redis για Windows/WSL.

3. Ελέγξτε τη θύρα 6379 και διορθώστε τη δικτύωση Docker

Το Redis χρησιμοποιεί συνήθως τη θύρα TCP 6379. Εάν το Redis εκτελείται αλλά τίποτα δεν ακούει σε αυτήν τη θύρα, ελέγξτε αν ο διακομιστής ξεκίνησε με διαφορετική διαμόρφωση. Σε Linux, ένας γρήγορος έλεγχος λειτουργικού συστήματος όπως το ss -ltnp μπορεί να δείξει τα ακροατήρια TCP· στα Windows, η εντολή PowerShell Test-NetConnection 127.0.0.1 -Port 6379 μπορεί να βοηθήσει στη διάκριση μιας θύρας που ακούει από μια που απορρίπτει. Η καθοριστική δοκιμή, ωστόσο, παραμένει μια λειτουργική εντολή Redis όπως το PING.

Εάν το Redis εκτελείται σε Docker και η εφαρμογή σας στον host

Η θύρα του container πρέπει να δημοσιευτεί στον host. Η τεκμηρίωση Docker του Redis δείχνει αντιστοίχιση host-to-container για τη θύρα 6379. Για τοπική ανάπτυξη μόνο, μπορείτε να δεσμεύσετε τη δημοσιευμένη θύρα στη διεύθυνση loopback του host:

docker run -d --name redis -p 127.0.0.1:6379:6379 redis
docker ps

Η ίδια η τεκμηρίωση δημοσίευσης θυρών του Docker εξηγεί ότι η καθορισμός του 127.0.0.1 καθιστά τη δημοσιευμένη θύρα προσβάσιμη μόνο από τον host του Docker, κάτι που είναι ασφαλέστερο για μια τοπική cache ανάπτυξης από το να τη δημοσιεύσετε σε κάθε διεπαφή. Η επίσημη γρήγορη εκκίνηση Docker του Redis και τα παραδείγματα σύνδεσης βρίσκονται στο Εκτέλεση Redis Open Source σε Docker, και η συμπεριφορά της διεύθυνσης host περιγράφεται στην τεκμηρίωση δημοσίευσης θυρών του Docker.

Εάν η εφαρμογή σας εκτελείται επίσης σε Docker

Αυτή είναι μια κοινή πηγή σύγχυσης. Μέσα σε ένα container, το 127.0.0.1 αναφέρεται στο ίδιο το container. Εάν το Redis είναι μια ξεχωριστή υπηρεσία Compose, συνδεθείτε στο όνομα της υπηρεσίας Redis, όπως redis:6379, στο κοινό δίκτυο Compose αντί για 127.0.0.1:6379. Το Docker τεκμηριώνει ότι οι υπηρεσίες Compose στο προεπιλεγμένο δίκτυο είναι ανακαλύψιμες με όνομα υπηρεσίας στον οδηγό δικτύωσης Compose.

Εάν η εφαρμογή βρίσκεται σε container Docker Desktop αλλά το Redis εκτελείται απευθείας στον host, το Docker συνιστά το ειδικό hostname host.docker.internal για την πρόσβαση σε υπηρεσίες host. Αυτή η συμπεριφορά τεκμηριώνεται στο FAQ δικτύωσης του Docker Desktop.

4. Επαληθεύστε το redis.conf: bind, protected mode και port

Εάν η διαδικασία εκτελείται αλλά ακούει στη λάθος διεπαφή ή θύρα, επιθεωρήστε το αρχείο διαμόρφωσης που χρησιμοποιεί πραγματικά η ενεργή διαδικασία Redis. Τρεις ρυθμίσεις έχουν τη μεγαλύτερη σημασία για αυτό το σφάλμα:

bind 127.0.0.1 -::1
protected-mode yes
port 6379

Το επίσημο πρότυπο διαμόρφωσης του Redis χρησιμοποιεί δέσμευση loopback για τοπική πρόσβαση, ενεργοποιεί την προστατευμένη λειτουργία από προεπιλογή και ορίζει την κανονική θύρα TCP στο 6379. Τεκμηριώνει επίσης ότι το port 0 απενεργοποιεί τον ακροατή TCP χωρίς TLS. Μπορείτε να επιθεωρήσετε το τρέχον πρότυπο στο επίσημο αποθετήριο του Redis.

Για μια ρύθμιση ανάπτυξης στον ίδιο host, η δέσμευση loopback είναι κατάλληλη. Για μια νόμιμη απομακρυσμένη ή πολυ-υπολογιστική ανάπτυξη, μην λύσετε τη συνδεσιμότητα αλλάζοντας τυχαία το bind σε κάθε διεπαφή και απενεργοποιώντας το protected-mode. Το Redis προειδοποιεί κατά της έκθεσης της θύρας TCP σε μη έμπιστα δίκτυα. Χρησιμοποιήστε μια κατάλληλη διεπαφή δικτύου, πολιτική firewall και πιστοποίηση ή ACLs του Redis αντίθετα. Αναθεωρήστε την επίσημη καθοδήγηση ασφαλείας του Redis πριν διευρύνετε την πρόσβαση δικτύου.

Μετά την αλλαγή της διαμόρφωσης, κάντε επανεκκίνηση του Redis χρησιμοποιώντας τον ίδιο διαχειριστή υπηρεσιών, εντολή container ή επόπτη διαδικασιών που κατέχει το τρέχον instance. Στη συνέχεια, επαναλάβετε:

redis-cli -h 127.0.0.1 -p 6379 PING

5. Εάν το Redis απαντά, διορθώστε τις ρυθμίσεις σύνδεσης της εφαρμογής

Μόλις το Redis CLI επιστρέψει PONG από το ίδιο περιβάλλον εκτέλεσης με την εφαρμογή σας, το αρχικό πρόβλημα απόρριψης σύνδεσης δεν είναι πλέον πρόβλημα ακροατή Redis. Συγκρίνετε τις ρυθμίσεις της εφαρμογής με την επιτυχή δοκιμή. Ελέγξτε όλες αυτές τις τιμές:

• Όνομα host ή διεύθυνση IP
• Θύρα TCP
• Αριθμός βάσης δεδομένων, εάν η εφαρμογή σας επιλέγει μια μη προεπιλεγμένη βάση δεδομένων
• Όνομα χρήστη και κωδικός πρόσβασης όταν η πιστοποίηση ACL είναι ενεργοποιημένη
• Εάν η σύνδεση χρησιμοποιεί απλό Redis ή TLS
• Εάν η εφαρμογή εκτελείται στον host, στο WSL, σε container ή σε άλλο μηχάνημα

Ένα τοπικό URL χωρίς TLS συχνά μοιάζει με:

redis://127.0.0.1:6379/0

Το Redis CLI υποστηρίζει επίσης URIs Redis και τεκμηριώνει το rediss:// για TLS. Εάν ο διακομιστής απαιτεί πιστοποίηση, χρησιμοποιήστε το κατάλληλο όνομα χρήστη και κωδικό πρόσβασης. Για δοκιμές CLI, το Redis συνιστά τη μεταβλητή περιβάλλοντος REDISCLI_AUTH αντί να τοποθετείτε έναν κωδικό πρόσβασης απευθείας στη γραμμή εντολών. Δείτε τις επιλογές σύνδεσης του Redis CLI.

Μην συγχέετε τις αποτυχίες πιστοποίησης και TLS με την απόρριψη σύνδεσης

Εάν το μήνυμα αλλάξει από Connection refused σε NOAUTH, WRONGPASS ή σφάλμα ACL, αυτό είναι πρόοδος: ο πελάτης έφτασε στον διακομιστή Redis και τώρα χρειάζεται έγκυρα διαπιστευτήρια. Το Redis συνιστά την πιστοποίηση βάσει ACL για σύγχρονες αναπτύξεις· η επίσημη τεκμηρίωση ACL του Redis εξηγεί το μοντέλο.

Ομοίως, εάν το endpoint απαιτεί TLS, ένας απλός πελάτης TCP Redis μπορεί να αποτύχει κατά τη ρύθμιση πρωτοκόλλου παρόλο που η θύρα είναι προσβάσιμη. Το Redis CLI υποστηρίζει το --tls, και τα URIs Redis χρησιμοποιούν το σχήμα rediss για συνδέσεις TLS. Για λεπτομέρειες TLS πλευράς διακομιστή, δείτε την τεκμηρίωση TLS του Redis.

Στόχοι σύνδεσης ανά περιβάλλον

Γρήγορη λίστα ελέγχου

• Εκτελέστε redis-cli -h 127.0.0.1 -p 6379 PING.
• Εάν απορριφθεί, επιβεβαιώστε ότι η διαδικασία ή η υπηρεσία Redis εκτελείται.
• Επιβεβαιώστε ότι το Redis ακούει πραγματικά στη θύρα 6379, ή ενημερώστε τον πελάτη στη διαμορφωμένη θύρα.
• Εάν χρησιμοποιείτε Docker, επαληθεύστε την αντιστοίχιση θυρών και εάν ο πελάτης βρίσκεται στον host ή σε άλλο container.
• Εάν και οι δύο υπηρεσίες είναι σε Compose, χρησιμοποιήστε το όνομα της υπηρεσίας Redis αντί για 127.0.0.1.
• Ελέγξτε το ενεργό redis.conf για bind, protected-mode και port.
• Κρατήστε το Redis μακριά από το δημόσιο διαδίκτυο· μην απενεργοποιείτε ρυθμίσεις ασφαλείας απλώς για να εξαφανιστεί το σφάλμα.
• Όταν το PING λειτουργεί, προχωρήστε στα διαπιστευτήρια της εφαρμογής, TLS, URL, αριθμό βάσης δεδομένων και δικτύωση ειδική για το περιβάλλον εκτέλεσης.

Τι συνήθως διορθώνει αυτό το σφάλμα;

Για μια μηχανή προγραμματιστή, η πιο κοινή επιτυχής διαδρομή είναι απλή: ξεκινήστε το Redis, βεβαιωθείτε ότι ακούει στο endpoint που χρησιμοποιεί πραγματικά η εφαρμογή σας και στη συνέχεια επαληθεύστε με PING. Το Docker αλλάζει το νόημα του "localhost", οπότε οι εφαρμογές σε container συχνά χρειάζονται ένα όνομα υπηρεσίας ή host.docker.internal αντί για 127.0.0.1. Οι αλλαγές διαμόρφωσης πρέπει να είναι η τελευταία λύση, όχι η πρώτη.

Το βασικό όριο διάγνωσης είναι αν μπορεί να εγκατασταθεί μια σύνδεση TCP. Μια απόρριψη σημαίνει ότι ο πελάτης δεν έχει φτάσει σε έναν χρήσιμο ακροατή Redis στο ζητούμενο endpoint. Ένα σφάλμα Redis όπως το NOAUTH σημαίνει ότι έχει. Η διαφορετική αντιμετώπιση αυτών των δύο περιπτώσεων αποφεύγει περιττές αλλαγές διαμόρφωσης και σας οδηγεί στην πραγματική αιτία πολύ πιο γρήγορα.