Ako opraviť chybu pripojenia Redis k 127.0.0.1:6379

Rýchla odpoveď: Ak vaša aplikácia hlási Could not connect to Redis at 127.0.0.1:6379: Connection refused, začnite kontrolou, či Redis server skutočne počúva na tejto adrese a porte. Redis CLI používa predvolene 127.0.0.1 a port 6379, takže odmietnutie zvyčajne ukazuje na zastavený server, iný port, nesúlad v sieti kontajnera alebo virtuálneho stroja, alebo problém s konfiguráciou listenera. Chyby autentifikácie sú iné: zvyčajne sa vyskytujú až po nadviazaní TCP pripojenia.

Najrýchlejšia diagnostika je redis-cli -h 127.0.0.1 -p 6379 PING. Ak vráti PONG, Redis je dostupný a namiesto slepého reštartovania Redisu by ste mali skontrolovať Redis URL vašej aplikácie, prihlasovacie údaje, nastavenia TLS alebo konfiguráciu fondu pripojení. Redis dokumentuje príkaz PING špecificky ako spôsob testovania, či je pripojenie aktívne a či server môže obsluhovať dáta. Pozrite si oficiálnu dokumentáciu príkazu Redis PING.

Rýchla diagnostická tabuľka

1. Reprodukovanie zlyhania mimo vašej aplikácie

Pred zmenou kódu aplikácie použite Redis CLI. Oficiálna dokumentácia CLI Redisu uvádza, že predvolene sa redis-cli pripája na 127.0.0.1:6379. Cieľ môžete explicitne špecifikovať:

redis-cli -h 127.0.0.1 -p 6379 PING

Úspešný lokálny server by mal odpovedať:

PONG

Ak dostanete rovnakú správu o odmietnutí pripojenia, reprodukovali ste problém na transportnej úrovni. To je užitočné, pretože to vylučuje váš framework, ORM, knižnicu cache a kód aplikácie z bezprostredného vyšetrovania. Redis CLI tiež prijíma -h pre hostiteľa a -p pre port, ako je zdokumentované v referencii Redis CLI.

Ak PING už vracia PONG, preskočte na krok 5. Neobnovujte zdravú inštanciu Redisu; zamerajte sa na reťazec pripojenia aplikácie a behové prostredie.

2. Uistite sa, že Redis server beží

V systéme Linux nainštalovanom cez správcu balíčkov možno Redis často ovládať ako systémovú službu. Dokumentácia inštalácie Redisu pre Linux ukazuje príkazy systemctl start a systemctl stop a uvádza, že názov služby môže byť redis alebo redis-server v závislosti od platformy. Typická kontrola na Ubuntu/Debian je:

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

Ak vaša distribúcia používa ako názov služby redis, nahraďte tento názov. Ak systemd nespravuje váš proces Redis, použite spôsob spustenia, ktorý zodpovedá spôsobu inštalácie Redisu, a nepredpokladajte, že služba existuje. Aktuálne pokyny pre Redis na Linuxe sú dostupné v oficiálnej dokumentácii inštalácie pre Linux.

Poznámka pre Windows a WSL

Nepredpokladajte, že existuje natívna služba Redis pre Windows len preto, že vaša aplikácia beží na Windowse. Aktuálny prehľad inštalácie Redisu uvádza Windows pod cestou Docker, pričom Redis tiež udržiava pokyny pre Windows pre WSL a jeho partnera kompatibility pre Windows. Ak Redis beží vo vnútri WSL, otestujte ho najprv z rovnakého prostredia WSL. Ak Redis beží v Docker Desktop, použite kontroly Docker v nasledujúcej časti. Pozrite si aktuálny prehľad inštalácie Redis Open Source a dokumentáciu inštalácie Redis pre Windows/WSL.

3. Skontrolujte port 6379 a opravte sieť Docker

Redis zvyčajne používa TCP port 6379. Ak Redis beží, ale nič nepočúva na tomto porte, skontrolujte, či bol server spustený s inou konfiguráciou. Na Linuxe môže rýchla kontrola operačného systému, ako je ss -ltnp, zobraziť počúvajúce TCP sokety; na Windowse môže pomôcť príkaz PowerShellu Test-NetConnection 127.0.0.1 -Port 6379 rozlíšiť počúvajúci port od odmietnutého. Rozhodujúcim testom však zostáva funkčný príkaz Redis, ako je PING.

Ak Redis beží v Docker a vaša aplikácia beží na hostiteľovi

Port kontajnera musí byť publikovaný na hostiteľa. Dokumentácia Docker pre Redis ukazuje mapovanie z hostiteľa do kontajnera pre port 6379. Pre lokálny vývoj môžete publikovaný port viazať na spätnú slučku hostiteľa:

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

Dokumentácia publikovania portov Dockeru vysvetľuje, že špecifikácia 127.0.0.1 robí publikovaný port dostupným iba z hostiteľa Docker, čo je bezpečnejšie pre lokálnu cache vo vývoji ako publikovanie na všetkých rozhraniach. Oficiálny rýchly štart Docker pre Redis a príklady pripojenia sú v Spustenie Redis Open Source na Docker a správanie adresy hostiteľa je opísané v dokumentácii publikovania portov Docker.

Ak vaša aplikácia tiež beží v Docker

Toto je bežný zdroj zmätku. Vo vnútri kontajnera sa 127.0.0.1 vzťahuje na samotný kontajner. Ak je Redis samostatná služba Compose, pripojte sa k názvu služby Redis, napríklad redis:6379, v zdieľanej sieti Compose, a nie na 127.0.0.1:6379. Docker dokumentuje, že služby Compose v predvolenej sieti sú objaviteľné podľa názvu služby vo svojej príručke siete Compose.

Ak je aplikácia v kontajneri Docker Desktop, ale Redis beží priamo na hostiteľovi, Docker odporúča špeciálny názov hostiteľa host.docker.internal na prístup k službám hostiteľa. Toto správanie je zdokumentované v FAQ siete Docker Desktop.

4. Overte redis.conf: bind, chránený režim a port

Ak proces beží, ale počúva na nesprávnom rozhraní alebo porte, preskúmajte konfiguračný súbor, ktorý aktívny proces Redis skutočne používa. Pre túto chybu sú najdôležitejšie tri nastavenia:

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

Oficiálna šablóna konfigurácie Redisu používia viazanie na spätnú slučku pre lokálny prístup, predvolene povoľuje chránený režim a nastavuje normálny TCP port na 6379. Tiež dokumentuje, že port 0 zakazuje non-TLS TCP listener. Aktuálnu šablónu si môžete prezrieť v oficiálnom repozitári Redis.

Pre nastavenie vývoja na rovnakom hostiteľovi je viazanie na spätnú slučku vhodné. Pre legitímne vzdialené alebo viac-hostiteľské nasadenie neriešte konektivitu ľahostajnou zmenou bind na všetky rozhrania a vypnutím protected-mode. Redis varuje pred vystavením svojho TCP portu nedôveryhodným sieťam. Namiesto toho použite vhodné sieťové rozhranie, politiku firewallu a autentifikáciu Redis alebo ACL. Pred rozšírením sieťového prístupu si prečítajte oficiálne bezpečnostné pokyny Redis.

Po zmene konfigurácie reštartujte Redis pomocou rovnakého správcu služieb, príkazu kontajnera alebo správcu procesov, ktorý vlastní bežiacu inštanciu. Potom zopakujte:

redis-cli -h 127.0.0.1 -p 6379 PING

5. Ak Redis odpovedá, opravte nastavenia pripojenia aplikácie

Akonáhle Redis CLI vráti PONG z rovnakého behového prostredia ako vaša aplikácia, pôvodný problém s odmietnutím pripojenia už nie je problémom listenera Redis. Porovnajte nastavenia aplikácie s úspešným testom. Skontrolujte všetky tieto hodnoty:

• Názov hostiteľa alebo IP adresa
• TCP port
• Číslo databázy, ak vaša aplikácia vyberá databázu inú ako predvolenú
• Používateľské meno a heslo, keď je povolená autentifikácia ACL
• Či pripojenie používa čistý Redis alebo TLS
• Či aplikácia beží na hostiteľovi, vo WSL, v kontajneri alebo na inom stroji

Lokálna URL bez TLS často vyzerá takto:

redis://127.0.0.1:6379/0

Redis CLI tiež podporuje Redis URI a dokumentuje rediss:// pre TLS. Ak server vyžaduje autentifikáciu, použite príslušné používateľské meno a heslo. Pre testovanie CLI Redis odporúča premennú prostredia REDISCLI_AUTH namiesto vkladania hesla priamo do príkazového riadku. Pozrite si možnosti pripojenia Redis CLI.

Nezamieňajte zlyhania autentifikácie a TLS s odmietnutím pripojenia

Ak sa správa zmení z Connection refused na NOAUTH, WRONGPASS alebo chybu ACL, je to pokrok: klient dosiahol server Redis a teraz potrebuje platné prihlasovacie údaje. Redis odporúča autentifikáciu založenú na ACL pre moderné nasadenia; oficiálna dokumentácia ACL Redis vysvetľuje tento model.

Rovnako, ak koncový bod vyžaduje TLS, čistý TCP klient Redis môže zlyhať počas nastavenia protokolu, aj keď je port dostupný. Redis CLI podporuje --tls a Redis URI používajú schému rediss pre TLS pripojenia. Podrobnosti o TLS na strane servera nájdete v dokumentácii TLS Redis.

Ciele pripojenia špecifické pre prostredie

Rýchly kontrolný zoznam

• Spustite redis-cli -h 127.0.0.1 -p 6379 PING.
• Ak je odmietnuté, potvrďte, že proces alebo služba Redis beží.
• Potvrďte, že Redis skutočne počúva na porte 6379, alebo aktualizujte klienta na konfigurovaný port.
• Ak používate Docker, overte mapovanie portov a či je klient na hostiteľovi alebo v inom kontajneri.
• Ak sú obe služby v Compose, použite názov služby Redis namiesto 127.0.0.1.
• Skontrolujte aktívny redis.conf pre bind, protected-mode a port.
• Udržujte Redis mimo verejného internetu; nevypínajte bezpečnostné nastavenia len preto, aby chyba zmizla.
• Kedy PING funguje, prejdite na prihlasovacie údaje aplikácie, TLS, URL, číslo databázy a sieťovanie špecifické pre behové prostredie.

Čo zvyčajne opraví túto chybu?

Pre vývojársky stroj je najbežnejšia úspešná cesta jednoduchá: spustite Redis, uistite sa, že počúva na koncovom bode, ktorý vaša aplikácia skutočne používa, a potom overte pomocou PING. Docker mení význam „localhost“, takže kontajnerizované aplikácie často potrebujú názov služby alebo host.docker.internal namiesto 127.0.0.1. Zmeny konfigurácie by mali byť poslednou možnosťou, nie prvou.

Kľúčovou diagnostickou hranicou je, či sa dá nadviazať TCP pripojenie. Odmietnutie znamená, že klient nedosiahol použiteľný listener Redis na požadovanom koncovom bode. Chyba Redis, ako je NOAUTH, znamená, že áno. Rozlišovanie týchto dvoch prípadov sa vyhne zbytočným zmenám konfigurácie a dostane vás k skutočnej príčine oveľa rýchlejšie.