Настройки

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

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

Будьте осторожны при перезаписи настроек, особенно когда значение по умолчанию — непустой список или словарь, например 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; если это так, этот middleware должен быть указан первым в MIDDLEWARE).

Django также допускает использование полного доменного имени (FQDN) любых записей. Некоторые браузеры включают конечную точку в заголовке Host , которую 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 (см. Middleware). См. также 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).

`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'

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

`CACHE_MIDDLEWARE_KEY_PREFIX`

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

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

См. фреймворк кэша Django.

`CACHE_MIDDLEWARE_SECONDS`

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

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

См. фреймворк кэша Django.

`CSRF_COOKIE_AGE`

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

Срок действия cookie 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-маркера, а не из кукиса.

Подробности о HttpOnly см. в SESSION_COOKIE_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. Этот флаг предотвращает отправку кукиса в межсайтовых запросах.

Подробности о SameSite см. в SESSION_COOKIE_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.

`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

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

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

`NAME`

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

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

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

См. Тестовую базу данных.

`SERIALIZE`

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

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

`TEMPLATE`

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

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