AxVi

Можливості

Білий список IP-адрес з опціональним терміном дії
Кілька іменованих токенів обходу (cookie для веб, заголовок для API, URL-обхід)
Заплановані вікна обслуговування з автоматичним відключенням
Красива, настроювана сторінка 503 з таймером зворотного відліку
На основі бази даних — працює бездоганно на кількох серверах
Вбудований шар кешування — уникає запитів до БД при кожному запиті
Виключення шляхів з обслуговування (health checks, webhooks тощо)
Налаштовуване з'єднання з базою даних та назви таблиць
Artisan команди для повного управління через CLI
Події: MaintenanceModeEnabled, MaintenanceModeDisabled, MaintenanceBypassGranted
Автоматично замінює вбудований middleware Laravel для обслуговування

Встановлення

composer require axvi/laravel-maintenance

Запустіть міграції:

php artisan migrate

Міграції завантажуються автоматично. Якщо потрібно їх налаштувати:

php artisan vendor:publish --tag=maintenance-migrations

За бажанням опублікуйте конфігурацію та шаблон 503:

php artisan vendor:publish --tag=maintenance-config
php artisan vendor:publish --tag=maintenance-views

Як це працює

Цей пакет замінює вбудований middleware Laravel PreventRequestsDuringMaintenance на власний CheckMaintenanceMode. Порядок перевірки обходу:

Виключені шляхи — URL, що відповідають патернам except, завжди дозволені
Білий список IP — якщо IP запиту є в таблиці maintenance_ips (кешовано)
Cookie — якщо запит має дійсний cookie обходу
Заголовок — якщо запит має дійсний токен у заголовку X-Maintenance-Token
Відповідь 503 — HTML-сторінка з таймером (або JSON для API-запитів)

Весь стан зберігається в базі даних, тому режим обслуговування працює однаково на кількох серверах. Запити кешуються для мінімізації впливу на продуктивність.

Використання

Увімкнути режим обслуговування

# Базове
php artisan maintenance:down

# З повідомленням, білим списком IP та секретним токеном
php artisan maintenance:down \
  --message="Ми повернемося через 30 хвилин" \
  --allow=192.168.1.1 \
  --secret=my-secret-token \
  --ends-at="2025-01-01 03:00:00"

Вимкнути режим обслуговування

php artisan maintenance:up

Управління IP-адресами

php artisan maintenance:ip add 192.168.1.50 --label="Dev machine"
php artisan maintenance:ip add 10.0.0.1 --expires-at="2025-06-01 00:00:00"
php artisan maintenance:ip remove 192.168.1.50
php artisan maintenance:ip list

Управління токенами

# Додати з автоматично згенерованим UUID токеном
php artisan maintenance:token add dev-token

# Додати з явним значенням токена
php artisan maintenance:token add dev-token abc123

# Додати з терміном дії
php artisan maintenance:token add temp-token --expires-at="2025-06-01 00:00:00"

php artisan maintenance:token revoke dev-token
php artisan maintenance:token list

Методи обходу

URL-обхід (веб)

Перейдіть за https://yourapp.com/maintenance/{secret-token} — встановлює cookie обходу дійсний 12 годин. Префікс маршруту налаштовується через bypass_route.prefix у конфігурації.

Обхід через заголовок (API)

X-Maintenance-Token: my-secret-token

Назва заголовка налаштовується через middleware.header_name у конфігурації.

Кешування

За замовчуванням пакет кешує стан обслуговування та білий список IP, щоб уникнути запитів до бази даних при кожному HTTP-запиті. Кеш автоматично інвалідується при увімкненні/вимкненні обслуговування або зміні білого списку IP.

Для використання конкретного сховища кешу (наприклад, Redis):

'cache' => [
    'enabled' => true,
    'store'   => 'redis',
    'ttl'     => 30,
],

Знайшли баг або маєте пропозицію? Створіть issue на GitHub. Підписуйтесь на LinkedIn або X.

Laravel Maintenance