Ecom house logo

Tryb utrzymania w Magento 2 (Maintenance Mode)

Opublikowano: 17 lipca 2026

Tryb utrzymania (maintenance mode) to mechanizm Magento, który pokazuje klientom stronę informacyjną zamiast sklepu, gdy musisz wykonać operację wymagającą chwilowej niedostępności - wdrożenie nowej wersji, restore bazy, krytyczna aktualizacja.

Kiedy używać maintenance mode

Sytuacja Maintenance?
Deploy nowej wersji kodu / nowego modułu Tak
setup:upgrade po dodaniu modułu Tak
Migracja / restore bazy Tak
Aktualizacja PHP / MySQL Tak
Zmiany w konfiguracji w panelu admina Nie (klienci nie zauważają)
Import produktów / qty / klientów Nie (import jest async)
Reindex w trybie schedule Nie
Zmiana ceny pojedynczego produktu Nie
Awarie SSL / DNS Nie (maintenance i tak niedostępny)

Generalna zasada: maintenance mode tylko, gdy klient mógłby zobaczyć błędy serwera (500) lub niespójne dane podczas wdrożenia.

Krok 1. Włącz / wyłącz przez CLI

# Włącz
bin/magento maintenance:enable

# Wyłącz
bin/magento maintenance:disable

# Sprawdź status
bin/magento maintenance:status

Po włączeniu Magento tworzy plik flag:

var/.maintenance.flag

Obecność tego pliku sprawia, że wszyscy klienci widzą stronę "Service Temporarily Unavailable".

Krok 2. IP whitelist - wpuszczanie devów i adminów

Podczas wdrożenia chcesz testować sklep z biurowego IP, ale klienci nie powinni mieć dostępu. Dlatego maintenance mode wspiera whitelist IP:

# Włącz maintenance + dodaj IP do whitelist
bin/magento maintenance:enable --ip=203.0.113.10 --ip=198.51.100.20

# Tylko dodaj IP (bez włączania)
bin/magento maintenance:allow-ips 203.0.113.10

# Wyczyść whitelist
bin/magento maintenance:allow-ips --none

IP w whitelist trafiają do pliku var/.maintenance.ip:

203.0.113.10
198.51.100.20

Klienci z tych IP widzą normalny sklep, reszta - stronę maintenance.

Cały zespół wdrożeniowy: Przed dużym deployem zbierz IP całego zespołu (devs, QA, PM) i wpisz je hurtem:

bin/magento maintenance:allow-ips 203.0.113.10 203.0.113.11 203.0.113.12

Lub: użyj VPN firmowy i dodaj tylko IP serwera VPN - wszyscy zdalni zobaczą sklep przez VPN.

Krok 3. Custom maintenance page

Domyślna strona Magento jest brzydka i techniczna. Możesz nadpisać:

pub/errors/default/503.phtml

albo, dla custom maintenance:

pub/errors/default/503.phtml.original (stwórz kopię i edytuj 503.phtml)

Wskazówki dla custom maintenance page

  • Logo sklepu - żeby klient nie myślał że trafił na phishing.
  • Komunikat po polsku - "Trwa konserwacja sklepu. Wracamy o 14:00." (z konkretną godziną).
  • Email / kontakt - gdyby ktoś pilnie potrzebował kontaktu.
  • Status page - link do statusu (np. status.sklep.pl).
  • Social media links - informacja na FB / Twitter, gdzie aktualnie wisi info "wracamy o ...".

Przykład minimalnej custom page

<!DOCTYPE html>
<html lang="pl">
<head>
    <meta charset="UTF-8">
    <title>Sklep XYZ - Konserwacja</title>
    <style>
        body { font-family: sans-serif; text-align: center; padding: 100px 20px; }
        h1 { color: #f26322; }
    </style>
</head>
<body>
    <img src="/media/logo.png" alt="Sklep XYZ">
    <h1>Trwa konserwacja sklepu</h1>
    <p>Wracamy o <strong>14:00</strong>. Przepraszamy za niedogodności.</p>
    <p>W razie pilnych spraw: <a href="mailto:[email protected]">[email protected]</a></p>
    <p><a href="https://facebook.com/sklep">Facebook</a> | <a href="https://twitter.com/sklep">Twitter</a></p>
</body>
</html>

503 HTTP status code: Strona maintenance zwraca HTTP 503 Service Unavailable - to dobrze:

  • Google wie, że to chwilowa niedostępność, nie wyrzuca strony z indeksu.
  • Po wyłączeniu maintenance crawler szybko wraca.

Jeśli zwróciłbyś 200 OK z treścią "we'll be back" - Google zindeksuje stronę maintenance zamiast właściwej treści. Strata SEO.

Krok 4. Skript wdrożeniowy z maintenance

Typowy flow deploya z maintenance:

#!/bin/bash
# deploy.sh
set -e

cd /var/www/magento

# 1. Włącz maintenance (whitelist office IP)
bin/magento maintenance:enable --ip=203.0.113.10

# 2. Update kodu
git pull origin main

# 3. Update composer
composer install --no-dev --optimize-autoloader

# 4. Setup
bin/magento setup:upgrade --keep-generated
bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f pl_PL en_US

# 5. Cache
bin/magento cache:flush

# 6. Permissions
sudo chown -R www-data:www-data var generated pub/static pub/media

# 7. Wyłącz maintenance
bin/magento maintenance:disable

# 8. Powiadomienie
echo "Deploy successful at $(date)" | mail -s "Magento Deploy" [email protected]

Maintenance mode + Varnish

Jeśli używasz Varnish jako Full Page Cache, klient może widzieć wycached'owaną stronę nawet w trybie maintenance. Aby tego uniknąć:

Wariant 1: Wyczyść Varnish przed maintenance

bin/magento cache:flush
sudo varnishadm "ban req.url ~ ."

Wariant 2: Konfiguracja Varnish, by respektował HTTP 503

W VCL Varnisha:

sub vcl_backend_response {
    if (beresp.status == 503) {
        set beresp.uncacheable = true;
        return (deliver);
    }
}

Najczęstsze problemy

Włączyłem maintenance i nie mogę się dostać do panelu

Twoje IP nie jest w whitelist:

# Sprawdź swoje publiczne IP (z poziomu serwera)
curl ifconfig.me

# Dodaj IP do whitelist
bin/magento maintenance:allow-ips $(curl -s ifconfig.me)

Lub: usuń var/.maintenance.flag ręcznie (bez maintenance całkowicie):

rm var/.maintenance.flag

Maintenance page się nie pokazuje, klient widzi błąd 500

Plik pub/errors/default/503.phtml ma błąd PHP lub brakuje pliku. Sprawdź:

ls -la pub/errors/default/

Jeśli brak - przywróć z pub/errors/default.sample:

cp pub/errors/default.sample pub/errors/default

Po wyłączeniu maintenance klienci nadal widzą starą wersję

To cache (Varnish, Cloudflare, browser):

bin/magento cache:flush
# Varnish:
sudo varnishadm "ban req.url ~ ."
# Cloudflare: cleanup z poziomu dashboardu Cloudflare.

Nie da się włączyć maintenance - "command not found"

Najczęściej brak uprawnień:

sudo -u www-data php bin/magento maintenance:enable

Maintenance włączony, ale strona nadal działa dla wszystkich

Sprawdź konfigurację serwera:

  • Nginx - czy pub/errors/ jest properly mapowany.
  • Apache - czy RewriteRule honoruje .maintenance.flag.

Skontaktuj się z developerem / devops, jeśli sklep ma nietypową konfigurację serwera.

Powiązane