Як виправити помилку підключення 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, тому відмова зазвичай вказує на зупинений сервер, інший порт, невідповідність мережі контейнера або віртуальної машини, або проблему з конфігурацією слухача. Помилки автентифікації відрізняються: вони зазвичай виникають після встановлення TCP-з'єднання.

Найшвидший діагностичний метод — це redis-cli -h 127.0.0.1 -p 6379 PING. Якщо повертається PONG, Redis доступний, і вам слід перевірити URL-адресу Redis вашого додатка, облікові дані, налаштування TLS або конфігурацію пулу з'єднань, замість того щоб бездумно перезапускати Redis. Документація Redis спеціально описує PING як спосіб перевірки того, чи є з'єднання активним і чи може сервер надавати дані. Див. офіційну документацію команди Redis PING.

Таблиця швидкої діагностики

1. Відтворіть збій поза вашим додатком

Використовуйте Redis CLI перед зміною коду додатка. Офіційна документація CLI Redis стверджує, що за замовчуванням redis-cli підключається до 127.0.0.1:6379. Ви можете явно вказати ціль:

redis-cli -h 127.0.0.1 -p 6379 PING

Успішний локальний сервер повинен відповісти:

PONG

Якщо ви отримуєте те саме повідомлення про відмову у з'єднанні, ви відтворили проблему на транспортному рівні. Це корисно, оскільки це виключає ваш фреймворк, 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

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

Якщо Redis працює в Docker, а ваш додаток — на хості

Порт контейнера має бути опублікований на хості. Документація Redis щодо Docker показує відображення з хоста на контейнер для порту 6379. Для локальної розробки ви можете прив'язати опублікований порт до адреси зворотного зв'язку хоста:

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

Власна документація Docker щодо публікації портів пояснює, що вказівка 127.0.0.1 робить опублікований порт доступним лише з хоста Docker, що є безпечнішим для локального кешу розробки, ніж публікація його на кожному інтерфейсі. Офіційний швидкий старт Redis для Docker та приклади з'єднань наведені в Запуск Redis Open Source на 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 використовує прив'язку до зворотного зв'язку для локального доступу, вмикає захищений режим за замовчуванням та встановлює звичайний TCP-порт на 6379. Він також документує, що port 0 вимикає TCP-слухач без TLS. Ви можете переглянути поточний шаблон в офіційному репозиторії Redis.

Для налаштування розробки на тому ж хості прив'язка до зворотного зв'язку є доречною. Для легітимного віддаленого або багатохостового розгортання не вирішуйте проблему з'єднання, бездумно змінюючи bind на всі інтерфейси та вимикаючи protected-mode. Redis попереджає проти експонування свого TCP-порту ненадійним мережам. Натомість використовуйте відповідний мережевий інтерфейс, політику брандмауера та автентифікацію Redis або ACL. Перегляньте офіційні рекомендації щодо безпеки Redis перед розширенням мережевого доступу.

Після зміни конфігурації перезапустіть Redis, використовуючи той самий менеджер служб, команду контейнера або процесний супервізор, який володіє запущеним екземпляром. Потім повторіть:

redis-cli -h 127.0.0.1 -p 6379 PING

5. Якщо Redis відповідає, виправте налаштування з'єднання додатка

Якщо Redis CLI повертає PONG з того ж середовища виконання, що й ваш додаток, початкова проблема відмови у з'єднанні більше не є проблемою слухача Redis. Порівняйте налаштування додатка з успішним тестом. Перевірте всі ці значення:

• Ім'я хоста або IP-адреса
• TCP-порт
• Номер бази даних, якщо ваш додаток вибирає базу даних, відмінну від стандартної
• Ім'я користувача та пароль, коли увімкнено автентифікацію ACL
• Чи використовує з'єднання звичайний Redis або TLS
• Чи працює додаток на хості, у WSL, у контейнері чи на іншій машині

Локальна URL-адреса без TLS часто виглядає так:

redis://127.0.0.1:6379/0

Redis CLI також підтримує URI Redis та документує 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, а URI Redis використовують схему 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, означає, що досяг. Різний підхід до цих двох випадків дозволяє уникнути непотрібних змін конфігурації та значно швидше дістатися до справжньої причини.