Как да поправите грешката „Redis Connection to 127.0.0.1:6379 Failed“

Бърз отговор: ако вашето приложение докладва Could not connect to Redis at 127.0.0.1:6379: Connection refused, започнете, като проверите дали Redis сървърът наистина слуша на този адрес и порт. Redis CLI използва 127.0.0.1 и порт 6379 по подразбиране, така че отказът обикновено сочи към спрян сървър, различен порт, несъответствие в мрежата на контейнер или виртуална машина, или проблем с конфигурацията на слушателя. Грешките при удостоверяване са различни: те обикновено възникват след като TCP връзката вече е установена.

Най-бързата диагностика е redis-cli -h 127.0.0.1 -p 6379 PING. Ако върне PONG, Redis е достъпен и трябва да проверите URL адреса на Redis във вашето приложение, данните за удостоверяване, настройките за TLS или конфигурацията на пула за връзки, вместо да рестартирате Redis на сляпо. Redis документира PING конкретно като начин за тестване дали връзката е жива и дали сървърът може да обслужва данни. Вижте официалната документация за командата Redis PING.

Таблица за бърза диагностика

1. Възпроизведете грешката извън вашето приложение

Използвайте Redis CLI, преди да променяте кода на приложението. Официалната документация на Redis за CLI посочва, че по подразбиране redis-cli се свързва с 127.0.0.1:6379. Можете да направите целта явна:

redis-cli -h 127.0.0.1 -p 6379 PING

Успешният локален сървър трябва да отговори:

PONG

Ако получите същото съобщение за отказ на връзка, сте възпроизвели проблема на транспортно ниво. Това е полезно, защото премахва вашия framework, ORM, библиотека за кеш и кода на приложението от непосредственото разследване. Redis CLI също приема -h за хоста и -p за порта, както е документирано в референцията на Redis CLI.

Ако PING вече връща PONG, преминете към стъпка 5. Не продължавайте да рестартирате здравословен инстанс на 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

Не приемайте, че съществува native Windows Redis услуга, само защото вашето приложение работи на 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, Test-NetConnection 127.0.0.1 -Port 6379 на PowerShell може да помогне да се разграничи слушащ порт от отказан. Решаващият тест обаче остава работеща Redis команда като PING.

Ако Redis работи в Docker, а вашето приложение работи на хоста

Портът на контейнера трябва да бъде публикуван към хоста. Документацията на Redis за Docker показва картографиране от хост към контейнер за порт 6379. За локално само разработка, можете да обвържете публикувания порт с адреса на loopback на хоста:

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

Собствената документация на Docker за публикуване на портове обяснява, че посочването на 127.0.0.1 прави публикувания порт достъпен само от Docker хоста, което е по-безопасно за локален кеш за разработка, отколкото публикуването му на всеки интерфейс. Официалният бърз старт на Redis за Docker и примерите за връзка са в Run Redis Open Source on Docker, а поведението на адреса на хоста е описано в документацията на Docker за публикуване на портове.

Ако вашето приложение също работи в Docker

Това е честа причина за объркване. Вътре в контейнер, 127.0.0.1 се отнася за самия контейнер. Ако Redis е отделна Compose услуга, свържете се с името на Redis услугата, като redis:6379, в споделената Compose мрежа, вместо с 127.0.0.1:6379. Docker документира, че Compose услугите в мрежата по подразбиране са откриваеми по име на услугата в неговото ръководство за мрежи на Compose.

Ако приложението е в Docker Desktop контейнер, но Redis работи директно на хоста, Docker препоръчва специалното име на хост host.docker.internal за достигане до услуги на хоста. Това поведение е документирано в FAQ за мрежи на Docker Desktop.

4. Проверете redis.conf: bind, защитен режим и порт

Ако процесът работи, но слуша на грешния интерфейс или порт, проверете конфигурационния файл, който активният Redis процес всъщност използва. Три настройки са най-важни за тази грешка:

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

Официалният шаблон за конфигурация на Redis използва loopback обвързване за локален достъп, активира защитен режим по подразбиране и задава нормалния TCP порт на 6379. Той също така документира, че port 0 деактивира не-TLS TCP слушателя. Можете да проверите текущия шаблон в официалното хранилище на Redis.

За конфигурация за разработка на един и същ хост, loopback обвързването е подходящо. За легитимно отдалечено или многохостово внедряване, не решавайте свързаността, като небрежно промените bind на всеки интерфейс и изключите protected-mode. Redis предупреждава срещу излагането на неговия TCP порт на ненадеждни мрежи. Използвайте подходящ мрежов интерфейс, политика на firewall и удостоверяване или ACL на Redis вместо това. Прегледайте официалните указания за сигурност на Redis, преди да разширите мрежовия достъп.

След промяна на конфигурацията, рестартирайте Redis, използвайки същия мениджър на услуги, команда за контейнер или процесен супервизор, който притежава работещия инстанс. След това повторете:

redis-cli -h 127.0.0.1 -p 6379 PING

5. Ако Redis отговаря, поправете настройките за връзка на приложението

След като Redis CLI върне PONG от същата среда за изпълнение като вашето приложение, оригиналният проблем с отказ на връзка вече не е проблем с Redis слушателя. Сравнете настройките на приложението с успешния тест. Проверете всички тези стойности:

• Име на хост или IP адрес
• TCP порт
• Номер на база данни, ако вашето приложение избира не-по-подразбиране база данни
• Потребителско име и парола, когато е активирано ACL удостоверяване
• Дали връзката използва обикновен Redis или TLS
• Дали приложението работи на хоста, в WSL, в контейнер или на друга машина

Локален, не-TLS URL често изглежда така:

redis://127.0.0.1:6379/0

Redis CLI също поддържа Redis URI и документира rediss:// за TLS. Ако сървърът изисква удостоверяване, използвайте подходящото потребителско име и парола. За CLI тестване, Redis препоръчва променливата на средата REDISCLI_AUTH вместо поставяне на парола директно в командния ред. Вижте опциите за връзка на Redis CLI.

Не бъркайте грешки при удостоверяване и TLS с отказ на връзка

Ако съобщението се промени от Connection refused на NOAUTH, WRONGPASS или ACL грешка, това е прогрес: клиентът е достигнал Redis сървъра и сега се нуждае от валидни данни за удостоверяване. Redis препоръчва удостоверяване, базирано на ACL, за модерни внедрявания; официалната документация за Redis ACL обяснява модела.

По същия начин, ако крайната точка изисква TLS, обикновен TCP Redis клиент може да се провали по време на настройка на протокола, въпреки че портът е достъпен. Redis CLI поддържа --tls, а Redis URI използват схемата rediss за TLS връзки. За детайли за TLS от страна на сървъра, вижте документацията на Redis за TLS.

Цели за връзка, специфични за средата

Бърз чеклист

• Изпълнете redis-cli -h 127.0.0.1 -p 6379 PING.
• Ако е отказано, потвърдете, че Redis процесът или услугата работи.
• Потвърдете, че Redis наистина слуша на порт 6379, или актуализирайте клиента до конфигурирания порт.
• Ако използвате Docker, проверете картографирането на портовете и дали клиентът е на хоста или в друг контейнер.
• Ако и двете услуги са в Compose, използвайте името на Redis услугата, вместо 127.0.0.1.
• Проверете активния redis.conf за bind, protected-mode и port.
• Дръжте Redis извън публичния интернет; не деактивирайте настройките за сигурност само за да изчезне грешката.
• Когато PING работи, преминете към данните за удостоверяване на приложението, TLS, URL, номера на базата данни и мрежата, специфична за средата за изпълнение.

Как обикновено поправя тази грешка?

За машина на разработчик, най-честият успешен път е прост: стартирайте Redis, уверете се, че той слуша на крайната точка, която вашето приложение всъщност използва, и след това проверете с PING. Docker променя значението на „localhost“, така че контейнеризираните приложения често се нуждаят от име на услуга или host.docker.internal, вместо 127.0.0.1. Промените в конфигурацията трябва да бъдат последната мярка, а не първата.

Ключовата диагностична граница е дали TCP връзка може да бъде установена. Отказът означава, че клиентът не е достигнал използваем Redis слушател на поисканата крайна точка. Redis грешка като NOAUTH означава, че е. Третирането на тези два случая по различен начин избягва ненужни промени в конфигурацията и ви води до истинската причина много по-бързо.