Jak opravit chybu připojení Redis k 127.0.0.1:6379

Rychlá odpověď: Pokud vaše aplikace hlásí Could not connect to Redis at 127.0.0.1:6379: Connection refused, začněte kontrolou, zda na dané adrese a portu skutečně naslouchá server Redis. Redis CLI používá ve výchozím nastavení 127.0.0.1 a port 6379, takže odmítnutí obvykle ukazuje na zastavený server, jiný port, nesoulad v síťovém nastavení kontejneru nebo virtuálního stroje, nebo problém s konfigurací naslouchání. Chyby ověřování jsou odlišné: obvykle se vyskytují až poté, co bylo TCP spojení již navázáno.

Nejrychlejší diagnostikou je příkaz redis-cli -h 127.0.0.1 -p 6379 PING. Pokud vrátí PONG, je Redis dostupný a místo slepého restartování Redisu byste měli zkontrolovat URL Redisu ve vaší aplikaci, přihlašovací údaje, nastavení TLS nebo konfiguraci fondu připojení. Dokumentace Redisu uvádí příkaz PING specificky jako způsob, jak otestovat, zda je spojení aktivní a zda server může poskytovat data. Podívejte se na oficiální dokumentaci příkazu Redis PING.

Rychlá diagnostická tabulka

1. Reprodukovat selhání mimo vaši aplikaci

Před změnou kódu aplikace použijte Redis CLI. Oficiální dokumentace CLI pro Redis uvádí, že ve výchozím nastavení se redis-cli připojuje k 127.0.0.1:6379. Cíl můžete zadat explicitně:

redis-cli -h 127.0.0.1 -p 6379 PING

Úspěšný lokální server by měl odpovědět:

PONG

Pokud obdržíte stejnou zprávu o odmítnutí připojení, reprodukovali jste problém na transportní úrovni. To je užitečné, protože to z okamžitého šetření vylučuje váš framework, ORM, knihovnu pro cache a kód aplikace. Redis CLI také přijímá -h pro hostitele a -p pro port, jak je zdokumentováno v referenci Redis CLI.

Pokud PING již vrací PONG, přejděte rovnou ke kroku 5. Neustále nerestartujte zdravou instanci Redisu; zaměřte se na řetězec připojení aplikace a běhové prostředí.

2. Ujistěte se, že server Redis běží

Na systému Linux nainstalovaném přes správce balíčků lze Redis obvykle ovládat jako systémovou službu. Dokumentace instalace Redisu pro Linux ukazuje příkazy systemctl start a systemctl stop a uvádí, že název služby může být redis nebo redis-server v závislosti na platformě. Typická kontrola na Ubuntu/Debian je:

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

Pokud vaše distribuce používá jako název služby redis, nahraďte tento název. Pokud systemd nespravuje váš proces Redis, použijte metodu spuštění, která odpovídá způsobu instalace Redisu, a nepředpokládejte, že služba existuje. Aktuální pokyny pro Redis na Linuxu jsou dostupné v oficiální dokumentaci instalace pro Linux.

Poznámka pro Windows a WSL

Nepředpokládejte, že existuje nativní služba Redis pro Windows jen proto, že vaše aplikace běží na Windows. Aktuální přehled instalace Redisu řadí Windows pod cestu Docker, zatímco Redis také udržuje pokyny pro Windows pro WSL a jeho partnera kompatibility pro Windows. Pokud Redis běží uvnitř WSL, otestujte jej nejprve ze stejného prostředí WSL. Pokud Redis běží v Docker Desktop, použijte kontroly Dockeru v další sekci. Podívejte se na aktuální přehled instalace Redis Open Source a dokumentaci instalace Redis pro Windows/WSL.

3. Zkontrolujte port 6379 a opravte síťové nastavení Dockeru

Redis obvykle používá TCP port 6379. Pokud Redis běží, ale na tomto portu nic naslouchá, zkontrolujte, zda byl server spuštěn s jinou konfigurací. Na Linuxu může rychlá kontrola operačního systému, jako je ss -ltnp, zobrazit naslouchající TCP sokety; na Windows může PowerShell Test-NetConnection 127.0.0.1 -Port 6379 pomoci rozlišit mezi naslouchajícím a odmítnutým portem. Rozhodujícím testem však zůstává funkční příkaz Redisu, jako je PING.

Pokud Redis běží v Dockeru a vaše aplikace běží na hostiteli

Port kontejneru musí být publikován na hostitele. Dokumentace Dockeru pro Redis ukazuje mapování z hostitele do kontejneru pro port 6379. Pro lokální vývoj můžete publikovaný port svázat s adresou loopback hostitele:

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

Vlastní dokumentace Dockeru o publikování portů vysvětluje, že zadání 127.0.0.1 činí publikovaný port dostupným pouze z hostitele Dockeru, což je pro lokální vývojovou cache bezpečnější než jeho publikování na všech rozhraních. Oficiální rychlý start Dockeru pro Redis a příklady připojení jsou v Spusťte Redis Open Source na Dockeru a chování adresy hostitele je popsáno v dokumentaci Dockeru o publikování portů.

Pokud vaše aplikace také běží v Dockeru

Toto je běžný zdroj zmatku. Uvnitř kontejneru odkazuje 127.0.0.1 na samotný tento kontejner. Pokud je Redis samostatnou službou v Compose, připojujte se k názvu služby Redis, například redis:6379, ve sdílené síti Compose, nikoli k 127.0.0.1:6379. Docker dokumentuje, že služby Compose ve výchozí síti jsou objevitelné podle názvu služby ve své příručce síťování Compose.

Pokud je aplikace v kontejneru Docker Desktop, ale Redis běží přímo na hostiteli, Docker doporučuje speciální název hostitele host.docker.internal pro přístup ke službám hostitele. Toto chování je zdokumentováno v FAQ síťování Docker Desktop.

4. Ověřte redis.conf: bind, chráněný režim a port

Pokud proces běží, ale naslouchá na špatném rozhraní nebo portu, prozkoumejte konfigurační soubor, který aktivní proces Redisu skutečně používá. Pro tuto chybu jsou nejdůležitější tři nastavení:

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

Oficiální šablona konfigurace Redisu používá vazbu na loopback pro lokální přístup, ve výchozím nastavení povoluje chráněný režim a nastavuje běžný TCP port na 6379. Také dokumentuje, že port 0 zakazuje naslouchání na TCP bez TLS. Aktuální šablonu si můžete prohlédnout v oficiálním repozitáři Redisu.

Pro nastavení vývoje na stejném hostiteli je vazba na loopback vhodná. Pro legitimní vzdálené nebo vícestrojové nasazení neřešte konektivitu tím, že lehkomyslně změníte bind na všechna rozhraní a vypnete protected-mode. Redis varuje před vystavením svého TCP portu nedůvěryhodným sítím. Místo toho použijte vhodné síťové rozhraní, firewall a ověřování Redisu nebo ACL. Před rozšířením síťového přístupu si prostudujte oficiální bezpečnostní pokyny Redisu.

Po změně konfigurace restartujte Redis pomocí stejného správce služeb, příkazu kontejneru nebo dohledového procesu, který vlastní běžící instanci. Poté opakujte:

redis-cli -h 127.0.0.1 -p 6379 PING

5. Pokud Redis odpovídá, opravte nastavení připojení aplikace

Jakmile Redis CLI vrátí PONG ze stejného běhového prostředí jako vaše aplikace, původní problém s odmítnutím připojení již není problémem naslouchání Redisu. Porovnejte nastavení aplikace s úspěšným testem. Zkontrolujte všechny tyto hodnoty:

• Název hostitele nebo IP adresa
• TCP port
• Číslo databáze, pokud vaše aplikace vybírá jinou než výchozí databázi
• Uživatelské jméno a heslo, pokud je povoleno ověřování ACL
• Zda připojení používá běžný Redis nebo TLS
• Zda aplikace běží na hostiteli, ve WSL, v kontejneru nebo na jiném stroji

Lokální URL bez TLS často vypadá takto:

redis://127.0.0.1:6379/0

Redis CLI také podporuje URI Redisu a dokumentuje rediss:// pro TLS. Pokud server vyžaduje ověřování, použijte příslušné uživatelské jméno a heslo. Pro testování přes CLI Redis doporučuje proměnnou prostředí REDISCLI_AUTH místo vkládání hesla přímo do příkazového řádku. Podívejte se na možnosti připojení Redis CLI.

Nezaměňujte selhání ověřování a TLS s odmítnutím připojení

Pokud se zpráva změní z Connection refused na NOAUTH, WRONGPASS nebo chybu ACL, je to pokrok: klient dosáhl serveru Redis a nyní potřebuje platné přihlašovací údaje. Redis doporučuje ověřování založené na ACL pro moderní nasazení; oficiální dokumentace ACL Redisu vysvětluje tento model.

Stejně tak, pokud koncový bod vyžaduje TLS, běžný TCP klient Redisu může selhat během nastavování protokolu, i když je port dostupný. Redis CLI podporuje --tls a URI Redisu používají schéma rediss pro připojení TLS. Podrobnosti o TLS na straně serveru najdete v dokumentaci TLS Redisu.

Cíle připojení specifické pro prostředí

Rychlý kontrolní seznam

• Spusťte redis-cli -h 127.0.0.1 -p 6379 PING.
• Pokud je připojení odmítnuto, potvrďte, že proces nebo služba Redis běží.
• Potvrďte, že Redis skutečně naslouchá na portu 6379, nebo aktualizujte klienta na nakonfigurovaný port.
• Pokud používáte Docker, ověřte mapování portů a zda je klient na hostiteli nebo v jiném kontejneru.
• Pokud jsou obě služby v Compose, použijte název služby Redis místo 127.0.0.1.
• Zkontrolujte aktivní redis.conf pro bind, protected-mode a port.
• Udržujte Redis mimo veřejný internet; nevypínejte bezpečnostní nastavení pouze proto, aby chyba zmizela.
• Když PING funguje, přejděte k přihlašovacím údajům aplikace, TLS, URL, číslu databáze a síťovému nastavení specifickému pro běhové prostředí.

Co obvykle tuto chybu opraví?

Pro vývojářský stroj je nejčastější úspěšná cesta jednoduchá: spusťte Redis, ujistěte se, že naslouchá na koncovém bodu, který vaše aplikace skutečně používá, a poté ověřte pomocí PING. Docker mění význam „localhostu“, takže kontejnerizované aplikace často potřebují název služby nebo host.docker.internal místo 127.0.0.1. Změny konfigurace by měly být posledním, ne prvním krokem.

Klíčovou diagnostickou hranicí je, zda lze navázat TCP spojení. Odmítnutí znamená, že klient nedosáhl použitelného naslouchání Redisu na požadovaném koncovém bodu. Chyba Redisu, jako je NOAUTH, znamená, že dosáhl. Rozlišování těchto dvou případů se vyhýbá zbytečným změnám konfigurace a rychleji vás dostane ke skutečné příčině.