Настройки

Основные настройки
Авторизация
Сообщения
Сессии
Сайты
Статические файлы
Тематический указатель основных настроек

Предупреждение

Будьте осторожны при перезаписи настроек, особенно если значение по умолчанию — непустой список или словарь, например STATICFILES_FINDERS. Убедитесь, что вы сохранили компоненты, необходимые для работы функций Django, которые вы хотите использовать.

Основные настройки

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

`ABSOLUTE_URL_OVERRIDES`

Значение по умолчанию: {} (Пустой словарь)

Словарь, сопоставляющий строки "app_label.model_name" с функциями, которые принимают объект модели и возвращают его URL. Это способ вставки или перезаписи get_absolute_url() методов на основе конкретной установки. Пример:

ABSOLUTE_URL_OVERRIDES = {
    'blogs.blog': lambda o: "/blogs/%s/" % o.slug,
    'news.story': lambda o: "/stories/%s/%s/" % (o.pub_year, o.slug),
}

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

`ADMINS`

Значение по умолчанию: [] (Пустой список)

Список всех людей, которые получают уведомления об ошибках кода. Когда DEBUG=False и AdminEmailHandler настроены в LOGGING (выполняется по умолчанию), Django отправляет этим людям подробности исключений, возникающих в цикле запроса/ответа.

Каждый элемент списка должен быть кортежем (Полное имя, адрес электронной почты). Пример:

[('John', 'john@example.com'), ('Mary', 'mary@example.com')]

`ALLOWED_HOSTS`

Значение по умолчанию: [] (Пустой список)

Список строк, представляющих имена хостов/доменов, которые может обслуживать этот сайт Django. Это мера безопасности, предотвращающая атаки с использованием заголовка HTTP Host, которые возможны даже при многих, на первый взгляд, безопасных конфигурациях веб-сервера.

Значения в этом списке могут быть полными именами (например, 'www.example.com'), в этом случае они будут точно сопоставляться с заголовком запроса Host (регистронезависимо, без порта). Значение, начинающееся с точки, может использоваться в качестве поддоменного шаблона: '.example.com' будет соответствовать example.com, www.example.com, и любому другому поддомену example.com. Значение '*' будет соответствовать всему; в этом случае вы несете ответственность за предоставление собственной валидации заголовка Host (возможно, в миддлваре; если это так, этот миддлвар должен быть указан в MIDDLEWARE).

Django также допускает полное доменное имя (FQDN) любых записей. Некоторые браузеры включают конечную точку в заголовке Host header, которую Django удаляет при проверке хоста.

Если заголовок Host (или X-Forwarded-Host если USE_X_FORWARDED_HOST включен) не соответствует ни одному значению в этом списке, метод django.http.HttpRequest.get_host() вызовет SuspiciousOperation.

Когда DEBUG равно True и ALLOWED_HOSTS пусто, хост проверяется на соответствие ['.localhost', '127.0.0.1', '[::1]'].

ALLOWED_HOSTS также проверяется при запуске тестов.

Эта проверка применяется только через get_host(); если ваш код напрямую обращается к заголовку Host из request.META, вы обходите эту защиту безопасности.

`APPEND_SLASH`

Значение по умолчанию: True

Если установлено значение True, если URL-адрес запроса не соответствует ни одному из шаблонов в URLconf и не заканчивается на слеш, отправляется перенаправление HTTP на тот же URL-адрес со добавленным слешем. Обратите внимание, что перенаправление может привести к потере любых данных, отправленных в запросе POST.

Настройка APPEND_SLASH используется только в том случае, если установлен CommonMiddleware (см. Миддлвары). См. также PREPEND_WWW.

`CACHES`

Значение по умолчанию:

{
    'default': {
        'BACKEND': 'django.core.cache.backends.locmem.LocMemCache',
    }
}

Словарь, содержащий настройки всех кэшей, которые будут использоваться с Django. Это вложенный словарь, содержимое которого сопоставляет псевдонимы кэшей со словарем, содержащим параметры для отдельного кэша.

Настройка CACHES должна настроить default кэш; также может быть указано любое количество дополнительных кэшей. Если вы используете кэш-бекенд, отличный от кэша локальной памяти, или вам нужно определить несколько кэшей, потребуются другие параметры. Доступны следующие параметры кэша.

`BACKEND`

Значение по умолчанию: '' (Пустая строка)

Кэш-бекенд для использования. Встроенные кэш-бекенды:

'django.core.cache.backends.db.DatabaseCache'
'django.core.cache.backends.dummy.DummyCache'
'django.core.cache.backends.filebased.FileBasedCache'
'django.core.cache.backends.locmem.LocMemCache'
'django.core.cache.backends.memcached.PyMemcacheCache'
'django.core.cache.backends.memcached.PyLibMCCache'
'django.core.cache.backends.redis.RedisCache'

Вы можете использовать кэш-бекенд, не поставляемый с Django, установив BACKEND на полное квалифицированное имя класса кэш-бекенда (например, mypackage.backends.whatever.WhateverCache).

Изменено в Django 4.0:

Добавлен бекенд RedisCache.

`KEY_FUNCTION`

Строка, содержащая путь с точкой к функции (или любому вызываемому объекту), определяющей, как составить префикс, версию и ключ в конечный ключ кэша. Реализация по умолчанию эквивалентна функции:

def make_key(key, key_prefix, version):
    return ':'.join([key_prefix, str(version), key])

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

См. документацию по кэшу для получения дополнительной информации.

`KEY_PREFIX`

Значение по умолчанию: '' (Пустая строка)

Строка, которая автоматически будет включена (по умолчанию добавлена в начало) ко всем ключам кэша, используемым сервером Django.

См. документацию по кэшу для получения дополнительной информации.

`LOCATION`

Значение по умолчанию: '' (Пустая строка)

Расположение кэша для использования. Это может быть каталог для кэша на файловой системе, хост и порт для сервера memcache или идентификационное имя для кэша локальной памяти. Например:

CACHES = {
    'default': {
        'BACKEND': 'django.core.cache.backends.filebased.FileBasedCache',
        'LOCATION': '/var/tmp/django_cache',
    }
}

`OPTIONS`

Значение по умолчанию: None

Дополнительные параметры для передачи кэш-бекенду. Доступные параметры зависят от вашего кэш-бекенда.

Некоторую информацию о доступных параметрах можно найти в документации по параметрам кэша. Более подробную информацию см. в документации модуля вашего бекенда.

`TIMEOUT`

Значение по умолчанию: 300

Количество секунд, по истечении которых запись кэша считается устаревшей. Если значение этой настройки равно None, записи кэша не будут истекать. Значение 0 вызывает немедленное истечение ключей (по сути, «не кэшировать»).

`VERSION`

Значение по умолчанию: 1

Номер версии по умолчанию для ключей кэша, сгенерированных сервером Django.

См. документацию по кэшу для получения дополнительной информации.

`CACHE_MIDDLEWARE_ALIAS`

Значение по умолчанию: 'default'

Подключение к кэшу, используемое для миддлвара кэша.

`CACHE_MIDDLEWARE_KEY_PREFIX`

Значение по умолчанию: '' (Пустая строка)

Строка, которая будет добавлен в качестве префикса к ключам кэша, сгенерированным миддлваром кэша. Этот префикс объединяется с настройкой KEY_PREFIX; он не заменяет его.

См. систему кэширования Django.

`CACHE_MIDDLEWARE_SECONDS`

Значение по умолчанию: 600

Значение по умолчанию для количества секунд кэширования страницы для средства кэширования.

См. рамку кэширования Django.

`CSRF_COOKIE_AGE`

Значение по умолчанию: 31449600 (примерно 1 год, в секундах)

Возраст куки CSRF в секундах.

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

Некоторые браузеры (в частности, Internet Explorer) могут запретить использование постоянных куки или могут повредить индексы в файле куки на диске, что может привести к (иногда периодическим) ошибкам проверки защиты CSRF. Измените это значение на None для использования куки CSRF на основе сеанса, которые хранят куки в памяти вместо постоянного хранилища.

`CSRF_COOKIE_DOMAIN`

Значение по умолчанию: None

Домен, который будет использоваться при установке куки CSRF. Это может быть полезно для простого исключения запросов между поддоменами из стандартной защиты от поддельных запросов с другого сайта. Его следует установить на строку, например, ".example.com", чтобы разрешить запрос POST из формы на одном поддомене, принимаемый представлением, обслуживаемым с другого поддомена.

Обратите внимание, что наличие этой настройки не подразумевает, что защита Django от поддельных запросов с другого сайта по умолчанию безопасна от атак между поддоменами — см. раздел ограничения CSRF.

`CSRF_COOKIE_HTTPONLY`

Значение по умолчанию: False

Использовать флаг HttpOnly для куки CSRF. Если это значение установлено в True, клиентский JavaScript не сможет получить доступ к куки CSRF.

Присвоение куки CSRF флага HttpOnly не обеспечивает никакой практической защиты, так как CSRF предназначена только для защиты от атак между доменными зонами. Если злоумышленник может прочитать куки через JavaScript, он уже находится на том же домене, насколько это известно браузеру, поэтому он может делать всё, что захочет. (XSS — это гораздо большая проблема, чем CSRF).

Хотя настройка мало что дает на практике, её иногда требуют аудиторы безопасности.

Если вы включили это и вам нужно отправить значение маркера CSRF с запросом AJAX, ваш JavaScript должен извлечь значение из скрытого поля ввода маркера CSRF вместо из куки.

См. SESSION_COOKIE_HTTPONLY для получения подробной информации о HttpOnly.

`CSRF_COOKIE_MASKED`

Значение по умолчанию: False

Маскировать куки CSRF. См. примечания к выпуску для получения подробной информации об использовании.

Устаревшее начиная с версии 4.1: Эта переходная настройка устарела и будет удалена в Django 5.0.

`CSRF_COOKIE_NAME`

Значение по умолчанию: 'csrftoken'

Имя куки, используемой для маркера аутентификации CSRF. Вы можете задать любое имя (только если оно отличается от других имён куки в вашем приложении). См. Защита от поддельных запросов с другого сайта.

`CSRF_COOKIE_PATH`

Значение по умолчанию: '/'

Путь, установленный в куки CSRF. Он должен соответствовать пути URL вашего приложения Django или быть его предком.

Это полезно, если у вас несколько экземпляров Django, работающих под одним именем хоста. Они могут использовать разные пути куки, и каждый экземпляр будет видеть только свои собственные куки CSRF.

`CSRF_COOKIE_SAMESITE`

Значение по умолчанию: 'Lax'

Значение флага SameSite в куки CSRF. Этот флаг предотвращает отправку куки в межсайтовых запросах.

См. SESSION_COOKIE_SAMESITE для получения подробной информации о SameSite.

`CSRF_COOKIE_SECURE`

Значение по умолчанию: False

Использовать защищённую куки для куки CSRF. Если это значение установлено в True, куки будет помечена как «защищённая», что означает, что браузеры могут убедиться, что куки отправляется только с подключением HTTPS.

`CSRF_USE_SESSIONS`

Значение по умолчанию: False

Хранить маркер CSRF в сессии пользователя вместо куки. Требует использования django.contrib.sessions.

Хранение маркера CSRF в куки (по умолчанию в Django) безопасно, но хранение в сессии — обычная практика в других веб-фреймворках и поэтому иногда требуется аудиторами безопасности.

Поскольку представления по умолчанию для ошибок требуют маркера CSRF, SessionMiddleware должен появляться в MIDDLEWARE до любого средства промежуточного программного обеспечения, которое может вызывать исключение для запуска представления ошибки (например, PermissionDenied), если вы используете CSRF_USE_SESSIONS. См. Порядок расположения средств промежуточного программного обеспечения.

`CSRF_FAILURE_VIEW`

Значение по умолчанию: 'django.views.csrf.csrf_failure'

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

def csrf_failure(request, reason=""):
    ...

где reason — короткое сообщение (предназначенное для разработчиков или логирования, а не для конечных пользователей), указывающее причину отклонения запроса. Оно должно возвращать HttpResponseForbidden.

django.views.csrf.csrf_failure() принимает дополнительный параметр template_name, который по умолчанию '403_csrf.html'. Если шаблон с таким именем существует, он будет использован для отрисовки страницы.

`CSRF_HEADER_NAME`

Значение по умолчанию: 'HTTP_X_CSRFTOKEN'

Имя заголовка запроса, используемого для аутентификации CSRF.

Как и другие HTTP-заголовки в request.META, имя заголовка, полученное от сервера, нормализуется путём преобразования всех символов в верхний регистр, замены всех тире на нижние подчеркивания и добавления префикса 'HTTP_' к имени. Например, если ваш клиент отправляет заголовок 'X-XSRF-TOKEN', настройка должна быть 'HTTP_X_XSRF_TOKEN'.

`CSRF_TRUSTED_ORIGINS`

Значение по умолчанию: [] (Пустой список)

Список доверенных источников для небезопасных запросов (например, POST).

Для запросов, содержащих заголовок Origin, защита Django от поддельных запросов с другого сайта требует, чтобы этот заголовок соответствовал источнику, присутствующему в заголовке Host.

Для небезопасного запроса secure, который не содержит заголовок Origin, запрос должен содержать заголовок Referer, соответствующий источнику, указанному в заголовке Host.

Эти проверки предотвращают, например, запрос POST из subdomain.example.com от успешного выполнения против api.example.com. Если вам нужны междоменные небезопасные запросы, продолжая пример, добавьте 'https://subdomain.example.com' в этот список (и/или http://... если запросы исходят с небезопасной страницы).

Настройка также поддерживает поддомены, поэтому можно добавить 'https://*.example.com', например, для разрешения доступа со всех поддоменов example.com.

Изменено в Django 4.0:

Значения в более ранних версиях должны были содержать только имя хоста (возможно, с ведущей точкой) и не содержать схемы или звёздочки.

Также, проверка заголовка Origin в более ранних версиях не выполнялась.

`DATABASES`

Значение по умолчанию: {} (Пустой словарь)

Словарь, содержащий настройки всех баз данных, которые будут использоваться с Django. Это вложенный словарь, содержимое которого сопоставляет псевдоним базы данных со словарем, содержащим параметры для отдельной базы данных.

Настройка DATABASES должна настроить базу данных default; также можно указать любое количество дополнительных баз данных.

Простейший возможный файл настроек для конфигурации с одной базой данных с использованием SQLite. Это можно настроить следующим образом:

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.sqlite3',
        'NAME': 'mydatabase',
    }
}

При подключении к другим базам данных, таким как MariaDB, MySQL, Oracle или PostgreSQL, потребуются дополнительные параметры подключения. См. настройку ENGINE ниже, чтобы указать другие типы баз данных. Этот пример для PostgreSQL:

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'mydatabase',
        'USER': 'mydatabaseuser',
        'PASSWORD': 'mypassword',
        'HOST': '127.0.0.1',
        'PORT': '5432',
    }
}

Для более сложных конфигураций доступны следующие внутренние параметры:

`ATOMIC_REQUESTS`

Значение по умолчанию: False

Установите это значение в True, чтобы обернуть каждый просмотр транзакцией в этой базе данных. См. Связывание транзакций с запросами HTTP.

`AUTOCOMMIT`

По умолчанию: True

Установите это значение в False, если вы хотите отключить управление транзакциями Django и реализовать собственное.

`ENGINE`

По умолчанию: '' (пустая строка)

Бэкенд базы данных для использования. Встроенные бэкенды баз данных:

'django.db.backends.postgresql'
'django.db.backends.mysql'
'django.db.backends.sqlite3'
'django.db.backends.oracle'

Вы можете использовать бэкенд базы данных, который не поставляется с Django, установив ENGINE в полном квалифицированном пути (например, mypackage.backends.whatever).

`HOST`

По умолчанию: '' (пустая строка)

Хост для подключения к базе данных. Пустая строка означает localhost. Не используется с SQLite.

Если это значение начинается с косой черты ('/') и вы используете MySQL, MySQL подключится по сокету Unix к указанному сокету. Например:

"HOST": '/var/run/mysql'

Если вы используете MySQL, и это значение не начинается с косой черты, тогда это значение предполагается как хост.

Если вы используете PostgreSQL, по умолчанию (пустая HOST) подключение к базе данных выполняется через сокеты области имен UNIX («локальные» строки в pg_hba.conf). Если ваш сокет области имен UNIX не находится в стандартном месте, используйте то же значение unix_socket_directory из postgresql.conf. Если вы хотите подключиться через TCP-сокеты, установите HOST в «localhost» или «127.0.0.1» («хост» строки в pg_hba.conf). В Windows вы всегда должны определить HOST, так как сокеты области имен UNIX недоступны.

`NAME`

По умолчанию: '' (пустая строка)

Имя базы данных для использования. Для SQLite это полный путь к файлу базы данных. При указании пути всегда используйте косые черты, даже в Windows (например, C:/homes/user/mysite/sqlite3.db).

`CONN_MAX_AGE`

По умолчанию: 0

Срок службы подключения к базе данных в секундах. Используйте 0, чтобы закрывать подключения к базе данных в конце каждого запроса — историческое поведение Django — и None, для неограниченных постоянных подключений к базе данных.

`CONN_HEALTH_CHECKS`

Новое в Django 4.1.

По умолчанию: False

Если установлено в True, существующие постоянные подключения к базе данных будут проверяться на работоспособность перед повторным использованием в каждом запросе, выполняющем доступ к базе данных. Если проверка работоспособности завершится неудачей, подключение будет переустановлено без сбоя запроса, когда подключение больше непригодно, но сервер базы данных готов принять и обслуживать новые подключения (например, после перезагрузки сервера базы данных, закрывающего существующие подключения).

`OPTIONS`

По умолчанию: {} (пустой словарь)

Дополнительные параметры для подключения к базе данных. Доступные параметры зависят от бэкенда вашей базы данных.

Некоторая информация о доступных параметрах содержится в документации по Бэкендам баз данных. Для получения дополнительной информации обратитесь к документации модуля вашего бэкенда.

`PASSWORD`

По умолчанию: '' (пустая строка)

Пароль для подключения к базе данных. Не используется с SQLite.

`PORT`

По умолчанию: '' (пустая строка)

Порт для подключения к базе данных. Пустая строка означает порт по умолчанию. Не используется с SQLite.

`TIME_ZONE`

По умолчанию: None

Строка, представляющая часовой пояс для этого подключения к базе данных, или None. Этот внутренний параметр параметра DATABASES принимает те же значения, что и общий параметр TIME_ZONE.

Когда USE_TZ равно True, а этот параметр установлен, чтение дат и времени из базы данных возвращает значащие даты и время в этом часовом поясе вместо UTC. Когда USE_TZ равно False, установка этого параметра является ошибкой.

Если бэкенд базы данных не поддерживает часовые пояса (например, SQLite, MySQL, Oracle), Django читает и записывает даты и время в местном времени в соответствии с этим параметром, если он установлен, и в UTC, если нет.

Изменение часового пояса подключения изменяет способ чтения и записи дат и времени в базу данных.
- Если Django управляет базой данных и у вас нет веской причины поступить иначе, оставьте этот параметр без значения. Лучше всего сохранять даты и время в UTC, так как это предотвращает неоднозначные или несуществующие даты и время во время перехода на летнее время. Кроме того, получение дат и времени в UTC упрощает арифметику дат и времени — нет необходимости учитывать возможные изменения смещения при переходе на летнее время.
- Если вы подключаетесь к базе данных стороннего разработчика, которая сохраняет даты и время в местном времени, а не в UTC, вам необходимо установить этот параметр в соответствующий часовой пояс. Аналогично, если Django управляет базой данных, но системы сторонних разработчиков подключаются к той же базе данных и ожидают найти даты и время в местном времени, вам необходимо установить этот параметр.
Если бэкенд базы данных поддерживает часовые пояса (например, PostgreSQL), параметр TIME_ZONE очень редко нужен. Его можно изменить в любое время; база данных позаботится о преобразовании дат и времени в желаемый часовой пояс.

Настройка часового пояса подключения к базе данных может быть полезна для запуска необработанных SQL-запросов, включающих функции дат/времени, предоставляемые базой данных, такие как date_trunc, потому что их результаты зависят от часового пояса.

Однако это имеет недостаток: получение всех дат и времени в местном времени усложняет арифметику дат и времени — вам необходимо учесть возможные изменения смещения при переходе на летнее время.

Вместо установки параметра TIME_ZONE, рассмотрите явное преобразование в местное время с помощью AT TIME ZONE в необработанных SQL-запросах.

`DISABLE_SERVER_SIDE_CURSORS`

По умолчанию: False

Установите это значение в True, если вы хотите отключить использование курсоров на стороне сервера с QuerySet.iterator(). Пулы транзакций и курсоры на стороне сервера описывает случай использования.

Это PostgreSQL-специфическая настройка.

`USER`

По умолчанию: '' (пустая строка)

Имя пользователя для подключения к базе данных. Не используется с SQLite.

`TEST`

По умолчанию: {} (пустой словарь)

Словарь настроек для тестовых баз данных; для получения более подробной информации о создании и использовании тестовых баз данных см. Тестовая база данных.

Вот пример с настройкой тестовой базы данных:

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'USER': 'mydatabaseuser',
        'NAME': 'mydatabase',
        'TEST': {
            'NAME': 'mytestdatabase',
        },
    },
}

Следующие ключи в словаре TEST доступны:

`CHARSET`

По умолчанию: None

Кодировка набора символов, используемая для создания тестовой базы данных. Значение этой строки передается непосредственно в базу данных, поэтому ее формат зависит от бэкенда.

Поддерживается бэкендами PostgreSQL (postgresql) и MySQL (mysql).

`COLLATION`

По умолчанию: None

Порядок сортировки, используемый при создании тестовой базы данных. Это значение передается непосредственно бэкенду, поэтому его формат зависит от бэкенда.

Поддерживается только для бэкенда mysql (см. справочник MySQL для получения подробной информации).

`DEPENDENCIES`

По умолчанию: ['default'], для всех баз данных, кроме default, у которой нет зависимостей.

Зависимости создания базы данных. Подробнее см. документацию по управлению порядком создания тестовых баз данных.

`MIGRATE`

По умолчанию: True

При установке в False миграции не будут выполняться при создании тестовой базы данных. Это аналогично установке None в качестве значения в MIGRATION_MODULES, но для всех приложений.

`MIRROR`

По умолчанию: None

Псевдоним базы данных, который эта база данных должна дублировать во время тестирования.

Этот параметр существует, чтобы позволить тестирование конфигураций мастер/реплики (в некоторых базах данных называемых мастер/раб) нескольких баз данных. Подробнее см. документацию по тестированию конфигураций мастер/реплики.

END_OF_DOCUMENT_MARKER

`NAME`

По умолчанию: None

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

Если используется значение по умолчанию (None) с движком базы данных SQLite, тесты будут использовать базу данных в оперативной памяти. Для всех остальных движков баз данных база данных тестов будет использовать имя 'test_' + DATABASE_NAME.

См. Базу данных тестов.

`SERIALIZE`

Булево значение, определяющее, сериализует ли стандартный запуск тестов базу данных в строку JSON в оперативной памяти перед запуском тестов (используется для восстановления состояния базы данных между тестами, если у вас нет транзакций). Можно установить это значение в False для ускорения времени создания, если у вас нет классов тестов с serialized_rollback=True.

Устарело начиная с версии 4.0: Это значение устарело, поскольку его можно вывести из databases с включённым параметром serialized_rollback.

`TEMPLATE`

Это параметр, специфичный для PostgreSQL.

Имя шаблона (например, 'template0'), по которому будет создаваться база данных тестов.