Настройки

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

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

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

Срок действия куки CSRF в секундах.

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

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

`CSRF_COOKIE_DOMAIN`

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

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

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

`CSRF_COOKIE_HTTPONLY`

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

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

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

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

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

Подробности о HttpOnly см. в разделе SESSION_COOKIE_HTTPONLY.

`CSRF_COOKIE_NAME`

По умолчанию: 'csrftoken'

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

`CSRF_COOKIE_PATH`

По умолчанию: '/'

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

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

`CSRF_COOKIE_SAMESITE`

По умолчанию: 'Lax'

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

Подробности о SameSite см. в разделе SESSION_COOKIE_SAMESITE.

`CSRF_COOKIE_SECURE`

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

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

`CSRF_USE_SESSIONS`

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

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

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

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

`CSRF_FAILURE_VIEW`

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

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

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 от CSRF требует, чтобы этот заголовок соответствовал источнику, указанному в заголовке 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`

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

База данных backend. Встроенные бэкэнды баз данных:

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

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

`HOST`

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

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

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

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

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

END_OF_DOCUMENT_MARKER

Если вы используете PostgreSQL, по умолчанию (пустая HOST), подключение к базе данных осуществляется через сокеты доменной области UNIX («локальные» строки в pg_hba.conf). Если ваш сокет доменной области UNIX находится не в стандартном месте, используйте то же значение unix_socket_directory из postgresql.conf. Если вы хотите подключиться через сокеты TCP, установите HOST на ‘localhost’ или ‘127.0.0.1’ («строки host» в 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`

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

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

`OPTIONS`

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

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

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

`PASSWORD`

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

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

`PORT`

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

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

`TIME_ZONE`

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

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

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

Когда USE_TZ — False, установка этого параметра является ошибкой.

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

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

Хотя установка параметра TIME_ZONE очень редко необходима, существуют ситуации, когда это становится необходимым. В частности, рекомендуется согласовать значение с общим параметром TIME_ZONE при работе с сырыми запросами, включающими функции даты/времени, такие как функция PostgreSQL date_trunc() или generate_series(), особенно при генерировании временных рядов, которые переходят летнее время.

Это значение может быть изменено в любое время, база данных обработает преобразование дат и времени в настроенный часовой пояс.

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

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

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

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

`TEMPLATE`

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

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

`CREATE_DB`

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

Это Oracle-специфический параметр.

Если установлено на False, тестовые табличные пространства не будут автоматически создаваться в начале тестов или удаляться в конце.

`CREATE_USER`

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

Это Oracle-специфический параметр.

Если установлено на False, тестовый пользователь не будет автоматически создаваться в начале тестов и удаляться в конце.