Режим maintenance в Laravel: чек-лист перед продакшеном

Классический сценарий: вы выкатываете миграцию, запускаете php artisan down, идёте править базу — а через минуту сами не можете открыть сайт, чтобы проверить результат. Или хуже: балансировщик пингует /, получает 503 и выкидывает воркер из пула прямо во время деплоя. Режим обслуживания в Laravel решает не только задачу «повесить заглушку», и большинство проблем с ним возникает из-за того, что параметры down настраивают в момент инцидента, а не заранее.

Ниже — чек-лист для Laravel 10.x и 11.x: какие флаги передавать в down, как не заблокировать себя и мониторинг, чем artisan-режим отличается от pre-render и когда его вообще не хватает. Формат — практика: у каждого приёма есть цена.

Что делает php artisan down на самом деле

Команда создаёт файл storage/framework/maintenance.php (в Laravel 8+ и далее — именно PHP-файл, а не флаг storage/framework/down из старых версий). Middleware PreventRequestsDuringMaintenance проверяет его наличие на каждом запросе и, если файл есть, отдаёт 503 с заголовком Retry-After.

Ключевой нюанс — файл читается на раннем этапе через public/index.php, ещё до полной загрузки фреймворка. Поэтому, если ошибка деплоя ломает автозагрузку или конфиг, заглушка всё равно покажется. Это плюс, но и ограничение: логика в PHP-файле минимальна, никакого доступа к вашим сервисам там нет.

Режим обслуживания в Laravel — не «страница-заглушка», а способ отсечь трафик до того, как приложение успеет упасть на полпути деплоя. Настраивать его флаги в момент паники — гарантированный способ заблокировать себя вместе с пользователями.

Флаги down, ради которых всё и затевается

Три опции команды down закрывают три отдельные проблемы. Их и надо продумать до продакшена.

--secret: как самому пройти сквозь заглушку

Без секрета вы кладёте сайт целиком, включая себя. Флаг --secret задаёт токен: перейдя по https://ваш-домен/ТОКЕН, вы получаете cookie и дальше видите сайт как обычно, пока остальные видят 503.

# Laravel 10.x / 11.x
php artisan down --secret="YOUR_MAINTENANCE_SECRET"

# затем открыть в браузере один раз:
# https://example.com/YOUR_MAINTENANCE_SECRET
# редиректнет на корень, дальше сайт работает для вас

Проверка, что получилось: обычный запрос без cookie возвращает 503, а после перехода по секретному URL — 200. Секрет должен быть непредсказуемым; не используйте secret, deploy и подобное. В Laravel 11 появился вариант сгенерировать секрет автоматически флагом --with-secret — токен выведется в консоль.

--render: заглушка, а не голый 503

По умолчанию пользователь увидит стандартную страницу 503. Флаг --render заранее рендерит указанный Blade-шаблон и сохраняет результат прямо в maintenance.php. Это важно: HTML отдаётся, даже если приложение в процессе деплоя не поднимается.

php artisan down --render="errors::503"

# или свой шаблон resources/views/maintenance.blade.php:
php artisan down --render="maintenance"

Раз шаблон рендерится в момент запуска команды, переменные и локализация фиксируются на этот момент — динамику сюда закладывать бессмысленно.

--retry и --refresh: что сказать клиенту и поисковику

Флаг --retry=N ставит заголовок Retry-After: N (в секундах). Это сигнал поисковым ботам и клиентам, когда возвращаться, — важно, чтобы Google не воспринял долгий 503 как исчезновение страниц. Флаг --refresh=N добавляет в HTML мета-тег автообновления страницы через N секунд.

php artisan down --retry=60 --refresh=15 --secret="YOUR_MAINTENANCE_SECRET"

Собранная вместе рабочая команда для короткого деплоя: секрет для себя, retry для ботов, refresh для живых пользователей на странице.

Сравнение флагов и типовых сценариев

Как не сломать деплой и мониторинг

Здесь собраны грабли, на которые наступают именно в продакшене.

• Балансировщик и health-check. Если ваш LB или Kubernetes-проба дёргает обычный URL, во время обслуживания он получит 503 и выведет инстанс из ротации. Настройте отдельный health-endpoint, который не проходит через PreventRequestsDuringMaintenance, либо учитывайте 503 как «живой» на время деплоя.
• Очереди. Воркеры queue:work продолжают работать в режиме обслуживания — они не ходят через HTTP-middleware. Если во время миграции джоба лезет в изменённую таблицу, получите ошибки. Останавливайте воркеры (php artisan queue:restart плюс остановка супервизора) до down и поднимайте после up.
• Планировщик. Cron-задачи через schedule:run тоже не знают о maintenance. Обёртывайте деплой так, чтобы планировщик был приостановлен, или добавляйте в задачи проверку.
• Атомарность деплоя. При zero-downtime деплое с симлинками (Envoyer, Deployer) новая версия кода лежит в новом каталоге, а maintenance.php — в storage, который обычно шарится между релизами. Проверьте, что down/up вызываются на правильном пути, иначе заглушка «залипнет» или не появится.

Кастомная страница обслуживания

Файл resources/views/errors/503.blade.php Laravel подхватит автоматически как страницу 503. Для отдельного шаблона обслуживания создайте свой Blade и передавайте его в --render.

<!-- resources/views/maintenance.blade.php -->
<!doctype html>
<html lang="ru">
<head>
    <meta charset="utf-8">
    <title>Идёт обслуживание</title>
</head>
<body>
    <h1>Скоро вернёмся</h1>
    <p>Проводим обновление. Обычно это занимает несколько минут.</p>
</body>
</html>

Проверка: после php artisan down --render="maintenance" откройте сайт в приватном окне (без секрет-cookie) — должен показаться ваш HTML с кодом ответа 503, а не стандартная страница фреймворка. Код ответа удобно смотреть через curl -I https://example.com.

Возврат в строй

Команда php artisan up удаляет maintenance.php. Проверка: обычный запрос снова отдаёт 200. Если после up сайт всё ещё показывает заглушку — почти всегда виноват кеш: OPcache держит старый maintenance.php, реверс-прокси кеширует 503, либо файл лежит в другом релизе. Сбросьте кеш и убедитесь, что команда выполнялась в текущем каталоге деплоя.

Где artisan-режима не хватает

Файловый механизм рассчитан на один сервер или общий сетевой storage. При нескольких инстансах без общего хранилища down на одной ноде не отключит остальные. В таких схемах обслуживание обычно переносят на уровень выше — балансировщик или reverse-proxy отдаёт статичную заглушку сам, а Laravel вообще не трогают. Настройка LB — отдельная тема, здесь мы её не разворачиваем.

Что сделать перед первым деплоем

1. Заведите в скрипте деплоя фиксированную команду down с --secret и --retry — не набирайте её руками в момент релиза.
2. Создайте кастомный 503-шаблон и проверьте его в приватном окне.
3. Отделите health-endpoint от middleware обслуживания или научите LB терпеть 503 на время деплоя.
4. Пропишите остановку очередей и планировщика до down и запуск после up.
5. Прогоните полный цикл down → миграция → up на стейджинге и убедитесь по curl -I, что коды ответа корректны на каждом шаге.