Режим обслуживания Laravel: php artisan down и up
Пока вы обновляете код или базу, посетитель может попасть на полуобновлённый сайт и увидеть ошибку. Команда php artisan down закрывает сайт: на любой адрес Laravel отвечает страницей 503 Service Unavailable. Команда php artisan up открывает его снова. Ниже — как закрыть сайт, самому зайти на него во время работ и что ещё останавливается, пока сайт закрыт.
Содержание 12
Что сделать прямо сейчас
- Перейдите в папку проекта:
cd /var/www/example.com. - Закройте сайт и получите секретный адрес для себя:
sudo -u www-data php artisan down --with-secret --render="errors::503". - Откройте в браузере адрес из ответа — вы увидите сайт, посетители увидят страницу 503.
- Закончите работы и откройте сайт:
sudo -u www-data php artisan up.
Команды вводятся на сервере: подключитесь к нему по SSH (как подключиться). Проект в примерах лежит в /var/www/example.com. Команды down и up запускайте от пользователя сайта www-data — так файлы режима обслуживания в storage/framework достанутся ему.
Как закрыть и открыть сайт
cd /var/www/example.com
sudo -u www-data php artisan downОтвет: Application is now in maintenance mode. С этой минуты на любой адрес сайта Laravel отвечает кодом 503 и страницей со словами Service Unavailable.
Открыть сайт:
sudo -u www-data php artisan up| Ответ | Что значит |
|---|---|
Application is now in maintenance mode. | сайт закрыт |
Maintenance mode options updated. | сайт уже был закрыт, применены новые ключи |
Application is now live. | сайт открыт |
Application is already up. | сайт и не был закрыт |
Команда down создаёт файл storage/framework/down, команда up удаляет его. Пока файл на месте, сайт закрыт — даже после перезагрузки сервера. Открывает сайт только sudo -u www-data php artisan up.
Как зайти на закрытый сайт самому
sudo -u www-data php artisan down --with-secretLaravel придумает секрет и покажет адрес в строке You may bypass maintenance mode via [https://example.com/секрет]. Откройте этот адрес в браузере: Laravel поставит в браузер cookie и перенаправит вас на главную. Дальше сайт открывается вам как до закрытия, а посетители без cookie видят страницу 503.
Можно задать секрет самому:
sudo -u www-data php artisan down --secret="moj-sekret-2026"Тогда адрес для входа — https://example.com/moj-sekret-2026.
- В секрете — латинские буквы, цифры и дефисы. Знаки
?и&не ставьте: в адресах у них особый смысл. - Адрес в ответе Laravel строит из строки
APP_URLв .env. Если тамhttp://localhost, замените начало адреса на свой домен и поправьте APP_URL. - Cookie хранится в одном браузере. Чтобы зайти с телефона, откройте секретный адрес и на нём.
Ключи php artisan down
| Ключ | Что делает |
|---|---|
--with-secret | придумать секрет для входа и показать адрес |
--secret="…" | задать свой секрет |
--render="errors::503" | заранее собрать страницу 503 и отдавать её до загрузки остального кода |
--refresh=15 | браузер посетителя сам обновит страницу через 15 секунд |
--retry=60 | добавить заголовок Retry-After: 60; по словам документации Laravel, браузеры его не учитывают |
--redirect=/ | перенаправлять все адреса на одну страницу |
--status=503 | код ответа; по умолчанию 503 |
Ключи можно сочетать:
sudo -u www-data php artisan down --with-secret --render="errors::503" --refresh=15Если сайт уже закрыт, повторный sudo -u www-data php artisan down с другими ключами заменит настройки — ответ Maintenance mode options updated.
Страница 503 во время composer install
Пока идёт composer install, файлы в папке vendor меняются, и Laravel может не загрузиться — посетитель увидит ошибку вместо страницы 503. Ключ --render это исправляет: Laravel заранее собирает страницу, а файл public/index.php отдаёт её в самом начале запроса, до загрузки папки vendor.
sudo -u www-data php artisan down --render="errors::503"errors::503 — стандартная страница Laravel. Ставьте этот ключ при каждой выкладке — весь порядок команд в статье Выкладка обновлений.
Своя страница вместо стандартной
Создайте в проекте файл resources/views/errors/503.blade.php — Laravel покажет его вместо своей страницы, в том числе с ключом --render="errors::503". Пример простой страницы:
<!DOCTYPE html>
<html lang="ru">
<head>
<meta charset="utf-8">
<title>Сайт обновляется</title>
</head>
<body>
<h1>Сайт обновляется</h1>
<p>Загляните через несколько минут.</p>
</body>
</html>Файл кладут в репозиторий проекта вместе с остальным кодом. Если шаблоны собраны в кеш, после добавления файла выполните sudo -u www-data php artisan view:cache — подробнее.
Очереди и планировщик
| Что | Пока сайт закрыт |
|---|---|
| воркеры очереди | задачи не берут; задачи ждут в очереди и выполнятся после up |
воркер с ключом --force | работает как прежде |
| задачи по расписанию | не запускаются |
задача с ->evenInMaintenanceMode() | запускается по расписанию |
Если очередь отправляет письма о заказах, на время работ они задержатся. Чтобы воркер работал и при закрытом сайте, допишите --force в строку command= файла Supervisor — Очереди и Supervisor. Про задачи по расписанию — Планировщик Laravel.
Если серверов несколько
Файл storage/framework/down лежит на диске одного сервера, поэтому sudo -u www-data php artisan down пришлось бы запускать на каждом. Чтобы закрывать все серверы одной командой, храните отметку в общем кеше — строки в .env:
APP_MAINTENANCE_DRIVER=cache
APP_MAINTENANCE_STORE=databaseХранилище должно быть общим для всех серверов: одна база данных или один Redis. После правки .env соберите кеш настроек: sudo -u www-data php artisan config:cache.
Как проверить
curl -I https://example.com/В первой строке ответа при закрытом сайте будет 503, при открытом — 200.
php artisan about --only=environmentВ строке Maintenance Mode при закрытом сайте стоит ENABLED, при открытом — OFF. Подробнее — php artisan about.
Ошибки и как их исправить
| Что видите | Причина | Что делать |
|---|---|---|
| сайт отвечает 503 после выкладки | не выполнили up | sudo -u www-data php artisan up |
503 без страницы Laravel, а php artisan about пишет OFF | ответ дал nginx или PHP-FPM | Разбор |
| секретный адрес тоже отвечает 503 | в адресе другой секрет или сайт закрыт без секрета | закройте сайт заново: sudo -u www-data php artisan down --with-secret |
в адресе из ответа localhost | в APP_URL адрес из образца | замените домен в адресе и поправьте APP_URL |
| письма не ушли во время работ | воркеры не берут задачи при закрытом сайте | откройте сайт или добавьте воркеру --force |
| задача по расписанию не выполнилась | планировщик не запускает задачи при закрытом сайте | добавьте задаче ->evenInMaintenanceMode() |
| ошибка вместо страницы 503 во время composer install | сайт закрыт без --render | sudo -u www-data php artisan down --render="errors::503" |
Failed to enter maintenance mode: … | нет прав на запись в storage/framework | верните права |
Failed to disable maintenance mode: … | нет прав на storage/framework | верните права |
Тексты сообщений сверены по исходному коду Laravel 13.42.0.
Источники
- Документация Laravel: Maintenance Mode — на английском: down, up, секрет, --render, --refresh, --retry, --redirect и несколько серверов.
- Документация Laravel: Queues — на английском: очереди в режиме обслуживания и ключ --force.
- Документация Laravel: Task Scheduling — на английском: evenInMaintenanceMode.
- Исходный код команды down в Laravel 13.42.0 — на английском: ключи и тексты ответов.
- Исходный код команды up в Laravel 13.42.0 — на английском: тексты ответов.
- Исходный код FileBasedMaintenanceMode в Laravel 13.42.0 — на английском: файл storage/framework/down.
Сверено 13 ноября 2026 года.
Что почитать дальше
- Laravel на серверевсе статьи о работе проекта на VPS.
- Выкладка обновленийпорядок команд при обновлении сайта.
- 503 Service Unavailableкогда 503 отдаёт не Laravel.