Помещение приложения Django в режим обслуживания важно при обновлениях, решении технических проблем или внесении значительных изменений. Временное ограничение доступа с показом страницы обслуживания позволяет сообщить пользователям о работах, обезопасить данные и избежать конфликтов.

Эта инструкция подходит разработчикам и системным администраторам. Она объясняет, как установить и настроить django-maintenance-mode, как исключать определённые представления или админ‑интерфейс и как минимизировать риски при включении режима.

Что нужно знать в двух предложениях

Режим обслуживания перехватывает запросы и возвращает страницу с кодом 503. Пакет django-maintenance-mode позволяет включать режим глобально через переменную в settings.py либо локально через декораторы на отдельных представлениях.

Краткое содержание статьи

• Установка и базовая настройка django-maintenance-mode
• Создание шаблона 503.html
• Включение режима глобально и для отдельных представлений (функциональных и классовых)
• Исключение админ‑сайта из режима обслуживания
• Полезные дополнения: чек‑листы ролей, критерии приёмки, сценарии тестирования и decision‑tree

Как использовать пакет django-maintenance-mode

Django имеет большое сообщество и множество пакетов, которые ускоряют работу. Один из таких инструментов — django-maintenance-mode. Пакет возвращает страницу с HTTP статусом 503 (Service Unavailable) и позволяет гибко включать и выключать режим.

Шаг 1 — установка в виртуальном окружении

1. Активируйте виртуальное окружение проекта.
2. Установите пакет через pip:

pip install django-maintenance-mode

3. Добавьте приложение в INSTALLED_APPS в файле settings.py:

INSTALLED_APPS = [
    # другие приложения
    'maintenance_mode',
]

4. Добавьте middleware для django-maintenance-mode в MIDDLEWARE:

MIDDLEWARE = [
    # другие middleware
    'maintenance_mode.middleware.MaintenanceModeMiddleware',
]

Важно: порядок middleware может влиять на поведение. Middleware django‑maintenance‑mode должно обрабатываться до middleware, которые формируют окончательный ответ, если вы хотите корректно возвращать 503.

Шаг 2 — создание HTML‑шаблона для страницы обслуживания

Пакет по умолчанию ищет шаблон templates/503.html. Создайте шаблон и укажите директорию в настройках TEMPLATES.

1. В корне проекта создайте папку templates.
2. В settings.py настройте TEMPLATES:

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [BASE_DIR/'templates'],
        'APP_DIRS': True,
        'OPTIONS': {
            'context_processors': [
                # …
            ],
        },
    },
]

3. Создайте файл templates/503.html. Простой пример шаблона:

    
    
    


    

        
503 Service Unavailable
        

            Упс! В настоящий момент проводятся технические работы.
            Приносим извинения за неудобства и благодарим за понимание.
        
        
Пожалуйста, зайдите на сайт позже или свяжитесь с нашей поддержкой.
        Связаться с поддержкой
    

4. Перезапустите сервер разработки (см. шаг 3).

Шаг 3 — включение режима обслуживания и перезапуск сервера

Чтобы включить режим глобально, установите в settings.py:

MAINTENANCE_MODE = True

Перезапустите сервер разработки:

python manage.py runserver

При переходе на сайт вы увидите созданную страницу 503.

Исключение админ‑сайта из режима обслуживания

Если нужно, чтобы Django Admin работал во время обслуживания, добавьте в settings.py:

MAINTENANCE_MODE_IGNORE_ADMIN_SITE = True

По умолчанию значение — False, поэтому без этой настройки админ‑панель будет недоступна.

Исключение отдельных функциональных представлений

Пакет предоставляет декоратор force_maintenance_mode_off, чтобы отключить проверку обслуживания для конкретного view.

В views.py импортируйте декоратор:

from maintenance_mode.decorators import force_maintenance_mode_off

Затем примените его к функциональному представлению:

@force_maintenance_mode_off
def view_name(request):
    # логика представления
    # всегда доступно, не возвращает 503

После этого URL для этого представления будет доступен даже при включённом глобальном MAINTENANCE_MODE.

Исключение отдельных классовых представлений

Для классовых представлений рекомендуется применять декоратор в urls.py:

from maintenance_mode.decorators import force_maintenance_mode_off
from .views import YourView
from django.urls import path

urlpatterns = [
    path('', force_maintenance_mode_off(YourView.as_view()), name='my_view'),
]

Убедитесь, что импортировали path и нужное представление.

Включение режима обслуживания только для одного представления (включение вручную)

Иногда нужно, чтобы остальная часть сайта работала, а отдельное представление возвращало 503. Для этого:

1. Убедитесь, что глобальный режим выключен в settings.py:

MAINTENANCE_MODE = False

2. В views.py импортируйте force_maintenance_mode_on и примените к представлению:

from maintenance_mode.decorators import force_maintenance_mode_on

@force_maintenance_mode_on
def view_name(request):
    # логика представления
    # всегда возвращает 503

Для классового представления применяйте декоратор в urls.py аналогично примеру выше.

Смена имени шаблона 503

По умолчанию пакет ищет MAINTENANCE_MODE_TEMPLATE = “503.html”. При использовании альтернативной структуры можно перенастроить путь:

MAINTENANCE_MODE_TEMPLATE = "errors/503.html"

Тогда пакет будет искать templates/errors/503.html.

Полезные советы и часто встречающиеся проблемы

Important: если вы используете прокси (например, nginx), кеш‑слои или CDN, убедитесь, что они корректно обрабатывают статус 503 и не кешируют страницу обслуживания. Иначе пользователи могут видеть устаревшую страницу после завершения работ.

Note: в production‑окружении чаще управляют режимом обслуживания на уровне load balancer/CI — чтобы минимизировать простои и координировать с миграциями базы данных.

Роли и чек‑листы действий

Чек‑лист для разработчика:

• Подготовить шаблон 503.html и локализованный текст.
• Проверить, что TEMPLATES[‘DIRS’] корректно настроен.
• Убедиться, что middleware добавлен в подходящем порядке.
• Написать тесты на поведение представлений с декораторами force_maintenance_mode_off/on.

Чек‑лист для DevOps / Системного администратора:

• Решить, где включать режим: на уровне приложения или load balancer.
• Проверить, что nginx/HAProxy не кешируют 503 ответ.
• Подготовить план отката (rollback) и время простоя.
• Синхронизировать включение режима с миграциями базы данных и CI/CD.

Чек‑лист для службы поддержки:

• Обновить шаблон поддержки (email, социальные сети) с информацией о работах.
• Подготовить шаблон ответа пользователям.
• Обеспечить канал связи для критических инцидентов.

Мини‑методология: как безопасно включить режим обслуживания

1. Подготовьте шаблон 503 и объявление для пользователей.
2. Установите MAINTENANCE_MODE = True или активируйте режим через CI на воркере/инстансе.
3. Выполните миграции и другие изменения базы данных.
4. Выполните проверку smoke tests и health checks.
5. Отключите MAINTENANCE_MODE = False и снова проверьте работоспособность.

Критерии приёмки:

• Шаблон 503 отображается корректно всем внешним пользователям.
• Админ‑панель доступна при MAINTENANCE_MODE_IGNORE_ADMIN_SITE = True (если это требуется).
• Критические API остаются доступными (если использовали декораторы для исключений).
• CDN/Прокси не кэшируют страницу обслуживания дольше допустимого времени.

Decision‑tree: когда включать режим обслуживания

flowchart TD
  A[Нужны изменения, затрагивающие БД или схемы?] -->|Да| B[Включить режим обслуживания]
  A -->|Нет| C[Попробовать blue-green или rolling‑deploy]
  B --> D{Нужно ли доступ к админке?}
  D -->|Да| E[MAINTENANCE_MODE_IGNORE_ADMIN_SITE = True]
  D -->|Нет| F[Отключить админ-доступ]
  C --> G[Протестировать без режима и откатиться при ошибке]

Тестовые сценарии и критерии приёмки

Тесты, которые следует выполнить перед и после обслуживания:

• Негативный тест: при включённом режиме обычный пользователь получает 503.
• Позитивный тест: администратор (или представление с force_maintenance_mode_off) получает 200.
• Smoke test: ключевые страницы и API возвращают ожидаемые статусы после отключения режима.
• Тест на кэширование: CDN/прокси не отдают старую страницу более допустимого времени.

Edge cases и источники ошибок

• Если middleware добавлен ниже middleware, который формирует ответ, 503 может не отдаваться.
• Неправильно настроенный TEMPLATES[‘DIRS’] приведёт к ошибке TemplateDoesNotExist.
• Кеширующий прокси может продолжать отдавать страницу 503 после выключения режима.

Совместимость и миграции

django-maintenance-mode совместим с типичной конфигурацией Django. Тем не менее обратите внимание на:

• Версию Python и Django в вашем проекте — проверяйте совместимость в документации пакета.
• Наличие кастомных middleware, которые могут влиять на порядок обработки ответов.
• CI/CD pipeline — разумно включать/выключать режим через скрипты развертывания.

Безопасность и GDPR‑заметки

Режим обслуживания обычно не обрабатывает персональные данные. Однако если вы обрабатываете логиинформацию или контактные формы на странице 503, убедитесь, что сбор данных соответствует требованиям конфиденциальности. Не храните лишние журналы с личной информацией во время обслуживания.

Краткая шпаргалка (cheat sheet)

• Установка: pip install django-maintenance-mode
• Добавить в INSTALLED_APPS: ‘maintenance_mode’
• Добавить middleware: ‘maintenance_mode.middleware.MaintenanceModeMiddleware’
• Глобально включить: MAINTENANCE_MODE = True
• Игнорировать админ: MAINTENANCE_MODE_IGNORE_ADMIN_SITE = True
• Декораторы: force_maintenance_mode_off, force_maintenance_mode_on
• Шаблон: templates/503.html или MAINTENANCE_MODE_TEMPLATE = “errors/503.html”

1‑строчная глоссарий

• MAINTENANCE_MODE: булева настройка, включающая глобальный режим обслуживания.
• Middleware: компонент Django, перехватывающий запросы/ответы.
• Decorator: в данном контексте — обёртка для представлений, управляющая поведением обслуживания.
• 503: HTTP‑код «Service Unavailable», используемый для страницы обслуживания.

Заключение и основные выводы

• django-maintenance-mode — простой и надёжный способ показать страницу обслуживания и вернуть 503.
• Используйте декораторы для тонкой настройки доступности отдельных страниц.
• Планируйте работу с учётом прокси и CDN, тестируйте поведение до и после работ.

Подведём итог — следуйте чек‑листам для своей роли, тестируйте все сценарии и координируйте включение режима с командой, чтобы обслуживание прошло гладко.