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

Ниже — подробное руководство по использованию пакета django-maintenance-mode, расширенные рекомендации, шаблоны и операционные процедуры (SOP).

Короткое описание пакета django-maintenance-mode

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

Термин: maintenance mode — режим обслуживания, при котором пользователям показывается временная страница недоступности.

Как установить и настроить django-maintenance-mode

Следуйте шагам ниже, чтобы быстро подготовить приложение.

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

1. В активированном виртуальном окружении установите пакет через pip:

pip install django-maintenance-mode

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

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

3. Подключите middleware пакета в MIDDLEWARE:

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

Шаг 2: Создание шаблона 503.html

Пакет по умолчанию ищет шаблон templates/503.html. Пример настройки и простого HTML-шаблона ниже.

1. Создайте папку templates в корне проекта.
2. Убедитесь, что в настройки TEMPLATES в settings.py указано:

'DIRS': [BASE_DIR/'templates'],

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

    
    
    


    

        
503 Service Unavailable
        

            Oops! We are currently working on some updates.
            We apologize for the inconvenience and appreciate your patience.
        
        
Please visit the website later or contact our support team
        
            Contact support
        
    

Сохраните файл и убедитесь, что шаблон рендерится корректно.

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

В settings.py временно установите:

MAINTENANCE_MODE = True

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

python manage.py runserver

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

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

Чтобы админка Django оставалась доступной во время обслуживания, установите в settings.py:

MAINTENANCE_MODE_IGNORE_ADMIN_SITE = True

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

Исключение конкретного function-based view

Чтобы разрешить доступ к отдельному представлению, импортируйте и примените декоратор:

from maintenance_mode.decorators import force_maintenance_mode_off

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

После этого URL для этого представления останется доступным.

Исключение конкретного class-based view

Обычно удобнее обернуть представление в urls.py:

from maintenance_mode.decorators import force_maintenance_mode_off
from .views import YourView

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

Не забудьте импортировать path и другие обязательные элементы.

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

Иногда нужно, наоборот, оставлять сайт открытым, но перевести в обслуживание одно конкретное представление.

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

MAINTENANCE_MODE = False

2. Используйте декоратор force_maintenance_mode_on:

from maintenance_mode.decorators import force_maintenance_mode_on

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

Для class-based view применяют схожий подход в urls.py:

from maintenance_mode.decorators import force_maintenance_mode_on
from .views import YourView

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

Изменение имени шаблона для режима обслуживания

По умолчанию используется “503.html”. Чтобы задать пользовательский путь, например templates/errors/503.html, в settings.py укажите:

MAINTENANCE_MODE_TEMPLATE = "errors/503.html"

После этого пакет будет искать шаблон по указанному пути.

Часто используемые дополнительные настройки (краткая сводка)

• MAINTENANCE_MODE — глобальное включение/выключение.
• MAINTENANCE_MODE_IGNORE_ADMIN_SITE — исключение админки.
• MAINTENANCE_MODE_TEMPLATE — путь к шаблону 503.
• Декораторы force_maintenance_mode_off и force_maintenance_mode_on — локальная гибкость.

Подробные опции смотрите в документации пакета.

Когда режим обслуживания не решит проблему (контрпримеры)

• Миграции базы данных с несовместимыми изменениями схемы, требующие поэтапного деплоя — простой 503 не решит проблему; нужен план миграций.
• Проблемы с балансировщиком или внешними сервисами — если ошибка на уровне сети или поставщика, показ страницы обслуживания не поможет пользователям, которые ожидают восстановление сервиса.
• Для API‑клиентов, которым критично получать структурированный JSON-ответ: показывать HTML 503 может привести к ошибочной обработке на стороне клиента. В таких случаях нужно отдавать корректный JSON с кодом 503.

Альтернативные подходы

• Использовать прокси/балансировщик (NGINX, HAProxy) для выдачи страницы обслуживания на уровне инфраструктуры.
• Feature flags (флаги фич) для выборочной деактивации функционала вместо полного отключения сайта.
• Canary‑деплой и blue/green‑развертывание для бесшовных обновлений без режима обслуживания.

Когда выбирать: для простых операций и быстрого уведомления пользователей — django-maintenance-mode; для сложных миграций и нулевого простоя — blue/green или canary.

Ментальные модели (как думать о режиме обслуживания)

• «Когорта пользователей»: кто должен видеть страницу обслуживания — все, только неадмины, или только часть интерфейсов?
• «Область воздействия»: глобальный режим против локального выключения одного view.
• «Согласованность данных»: если операция меняет данные, временная блокировка клиентов снижает риск гонок и частичных обновлений.

Операционная инструкция (SOP) для включения режима обслуживания — краткий план

1. Оцените влияние: какие URL, API и пользователи пострадают.
2. Подготовьте шаблон 503 с контактами и ожидаемым временем простоя.
3. Включите MAINTENANCE_MODE = True в settings.py (или через переменную окружения).
4. Перезапустите приложение/процесс (gunicorn, systemd, контейнер).
5. Выполните необходимые обновления/миграции/тесты.
6. Проверки: smoke-тесты основных путей, проверка админки (если доступна).
7. Откат: если ошибка — отмените изменения; если успешна — выключите режим обслуживания и уведомите пользователей.

Чек‑лист ролей при операциях обслуживания

Разделите ответственности:

• Разработчик: подготовка шаблона 503, тесты представлений, подготовка миграций.
• Операции/DevOps: переключение конфигураций, перезапуск процессов, мониторинг.
• Техническая поддержка: обновление статусов в каналах поддержки, ответы пользователям.
• QA: выполнение smoke и регрессионных тестов после обслуживания.

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

• Шаблон 503 отображается для обычных пользователей.
• Админ-панель доступна при включённом MAINTENANCE_MODE_IGNORE_ADMIN_SITE=True (если это требуется).
• Критические API возвращают ожидаемый код ошибки (например, 503 + корректный JSON для API).
• Все миграции прошли без ошибок, тесты упали не более допустимого порога.

Риск‑матрица и способы смягчения

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

Безопасность и конфиденциальность

• Не размещайте чувствительные данные в шаблонах 503 и сопроводительных сообщениях.
• Если в процессе обслуживания задействованы журналы и дампы, храните их в защищённых местах и удаляйте по политике хранения.
• Для пользователей в ЕС учитывайте требования GDPR — уведомления о корректировке данных и минимизация хранения персональных данных во время обслуживания.

Шаблон 503.html — компактный шаблон и варианты (шаблон для API)

Простой HTML уже приведён выше. Для API можно вернуть JSON, например в middleware или view, если запрос ожидает JSON:

from django.http import JsonResponse

def service_unavailable(request):
    return JsonResponse({'detail': 'Service temporarily unavailable'}, status=503)

Или на уровне NGINX отдавать JSON при звонках к API.

Советы по тестированию

• Smoke тест: проверьте главную страницу, страницу логина и ключевые API.
• Тесты интеграции: прогоните тесты миграций в изолированной среде.
• Acceptance: убедитесь, что пользователь видит страницу 503, а админ доступен (если настроено).

Миграция с версии на версию и совместимость

• Проверяйте совместимость пакета django-maintenance-mode с вашей версией Django.
• Перед обновлением пакета тестируйте на staging окружении.

Локальные альтернативы и подводные камни

• На shared‑hosting режим приложения может игнорироваться; используйте прокси‑уровень.
• Не забывайте о кэше CDN — если у вас CDN, обновите правила, иначе пользователи могут получать устаревший контент.

Короткое резюме

Использование django-maintenance-mode — быстрый и прозрачный способ организовать окно обслуживания. Он удобен для большинства рутинных операций, но для сложных сценариев обновления лучше сочетать его с практиками blue/green или canary. Подготовьте шаблоны, определите исключения и следуйте чек‑листу — это минимизирует простои и недоразумения.

Важные моменты:

• Подготовьте понятный шаблон 503 с контактной информацией.
• Тестируйте поведение для обычных пользователей и для API-клиентов.
• Используйте декораторы для точечной гибкости.

Спасибо за внимание. Если нужно, могу подготовить готовый playbook в формате checklist.md или mermaid-диаграмму для принятия решения о включении режима обслуживания.