Laravel и Redis на сервере: кеш, сессии и очереди
В новом проекте Laravel хранит кеш, сессии и очереди в базе данных. Их можно перенести в Redis — хранилище в оперативной памяти: страницы с кешем отвечают быстрее, а база данных разгружается. Для этого на сервере нужны сам Redis и расширение PHP, а в .env — несколько строк. Ниже — какие строки, где Laravel хранит данные в Redis и что проверить после переключения.
Содержание 13
Что сделать прямо сейчас
- Поставьте Redis, если его ещё нет на сервере, — Установка Redis.
- Поставьте расширение PHP:
sudo apt install php-redisи перезапустите PHP-FPM:sudo systemctl restart php8.3-fpm. - Откройте .env проекта:
nano /var/www/example.com/.env— и впишите строки ниже. - Соберите кеш настроек и перезапустите воркеры:
sudo -u www-data php artisan config:cacheиsudo -u www-data php artisan queue:restart.
Команды вводятся на сервере: подключитесь к нему по SSH (как подключиться). Проект в примерах лежит в /var/www/example.com, Redis работает на этом же сервере.
Что можно хранить в Redis
| Что | Строка в .env | В новом проекте |
|---|---|---|
| кеш | CACHE_STORE=redis | database |
| сессии посетителей | SESSION_DRIVER=redis | database |
| очереди задач | QUEUE_CONNECTION=redis | database |
Переключать можно по одному: например, только кеш, а сессии и очереди оставить в базе данных.
Расширение PHP
Laravel подключается к Redis через расширение PHP redis — в настройках оно называется phpredis. Поставьте его и перезапустите PHP-FPM:
sudo apt install php-redis
sudo systemctl restart php8.3-fpmПроверка: php -m | grep redis — в ответе должна быть строка redis. Команда для Ubuntu 24.04, где стоит PHP 8.3; как узнать свою версию — Установка PHP.
Если поставить расширение нельзя, документация Laravel предлагает пакет Predis — он написан на PHP и расширения не требует:
cd /var/www/example.com
composer require predis/predisТогда в .env укажите REDIS_CLIENT=predis.
Строки в .env
REDIS_CLIENT=phpredis
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379
CACHE_STORE=redis
SESSION_DRIVER=redis
QUEUE_CONNECTION=redis| Строка | Что значит |
|---|---|
REDIS_CLIENT=phpredis | подключаться через расширение PHP redis |
REDIS_HOST=127.0.0.1 | Redis на этом же сервере |
REDIS_PASSWORD=null | пароля нет; если пароль задан — впишите его вместо null |
REDIS_PORT=6379 | порт Redis |
CACHE_STORE=redis | кеш в Redis |
SESSION_DRIVER=redis | сессии в Redis |
QUEUE_CONNECTION=redis | очереди в Redis |
Строки REDIS_… уже есть в .env нового проекта — поправьте их, а не добавляйте вторые. Если Redis закрыт паролем, а для сайта заведён отдельный пользователь, добавьте строку REDIS_USERNAME=имя. Как задать пароль — Пароль и пользователи Redis. Как устроен файл .env — .env на сервере.
Где Laravel хранит данные в Redis
Внутри Redis 16 отдельных баз с номерами от 0 до 15. Laravel берёт две:
| Соединение | Строка в .env | По умолчанию | Что там лежит |
|---|---|---|---|
| default | REDIS_DB | 0 | очереди и сессии |
| cache | REDIS_CACHE_DB | 1 | кеш |
Посмотреть, сколько ключей в базе кеша: redis-cli -n 1 DBSIZE. Если на Redis стоит пароль, войдите с ним — redis-cli. Подробнее о базах — Базы и ключи Redis.
Что стирает cache:clear
sudo -u www-data php artisan cache:clearОтвет: Application cache cleared successfully. С кешем в Redis команда очищает всю базу кеша — номер из REDIS_CACHE_DB, а не только ключи вашего сайта. Документация Laravel предупреждает: очистка кеша не учитывает префикс.
Пока в базе 1 лежит только кеш этого сайта, это не страшно: кеш соберётся заново. Если в ту же базу пишет другой сайт или программа, их данные тоже пропадут — дайте каждому сайту свои базы, как в примере ниже.
Два сайта на одном Redis
Laravel добавляет к каждому ключу префикс из имени приложения — строки APP_NAME. Если два сайта на одном Redis называются одинаково, например рабочий и тестовый, они читают данные друг друга: воркер одного сайта может взять задачу другого.
Дайте каждому сайту свои базы и свой префикс. В .env второго сайта:
REDIS_DB=2
REDIS_CACHE_DB=3
REDIS_PREFIX=example-staging-database-| Сайт | REDIS_DB | REDIS_CACHE_DB |
|---|---|---|
| первый | 0 | 1 |
| второй | 2 | 3 |
| третий | 4 | 5 |
После переключения
| Что переключили | Что произойдёт | Что сделать |
|---|---|---|
| сессии | посетители выйдут из аккаунтов: старые сессии остались в базе данных | ничего — войдут заново |
| очереди | задачи, которые уже лежали в таблице jobs, воркер больше не видит | доделайте их: sudo -u www-data php artisan queue:work database --stop-when-empty |
| кеш | кеш начнёт собираться заново | ничего |
После любой правки .env соберите кеш настроек: sudo -u www-data php artisan config:cache. Воркеры очереди держат старые настройки в памяти — перезапустите их: sudo -u www-data php artisan queue:restart. Подробнее — Очереди и Supervisor.
Память Redis
Если для Redis задан предел памяти maxmemory с политикой allkeys-lru, при нехватке памяти он удаляет любые ключи — не только кеш, но и сессии и задачи очереди. Когда в одном Redis лежат кеш и очереди, выберите другую политику — какую.
Как проверить
cd /var/www/example.com
php artisan about --only=driversВ строках Cache, Queue и Session должно стоять redis. Если там database, Laravel читает старые настройки — выполните sudo -u www-data php artisan config:cache. Подробнее — php artisan about.
Откройте пару страниц сайта и выполните redis-cli -n 1 DBSIZE — число ключей в базе кеша должно вырасти.
Ошибки и как их исправить
| Что видите | Причина | Что делать |
|---|---|---|
Please make sure the PHP Redis extension is installed and enabled. | нет расширения PHP redis | sudo apt install php-redis и sudo systemctl restart php8.3-fpm |
NOAUTH Authentication required. | на Redis пароль, а в .env его нет | Разбор |
WRONGPASS invalid username-password pair or user is disabled. | неверный пароль или имя в .env | Разбор |
в laravel.log RedisException и отказ в соединении | Redis не запущен или неверный REDIS_HOST | Разбор |
OOM command not allowed when used memory > 'maxmemory'. | Redis упёрся в предел памяти | Разбор |
поправили .env, а в about по-прежнему database | собран кеш настроек | sudo -u www-data php artisan config:cache |
| задачи перестали выполняться после переключения | воркеры не перезапущены | sudo -u www-data php artisan queue:restart |
| сайт показывает данные другого сайта | одинаковые APP_NAME и базы Redis | разведите базы |
Тексты сообщений Laravel сверены по исходному коду Laravel 13.42.0.
Источники
- Документация Laravel: Redis — на английском: phpredis и Predis, REDIS_DB, REDIS_CACHE_DB и REDIS_PREFIX.
- Документация Laravel: Cache — на английском: кеш в Redis и очистка без учёта префикса.
- Документация Laravel: Session — на английском: сессии в Redis.
- Шаблон config/database.php — на английском: соединения default и cache, базы 0 и 1.
- Исходный код PhpRedisConnector в Laravel 13.42.0 — на английском: сообщение о расширении PHP redis.
- Исходный код RedisStore в Laravel 13.42.0 — на английском: очистка кеша командой FLUSHDB.
Сверено 13 ноября 2026 года.
Что почитать дальше
- Laravel на серверевсе статьи о работе проекта на VPS.
- Установка Redisкак поставить Redis и закрыть его паролем.
- Очереди и Supervisorворкеры, которые разбирают очередь.