Настройки

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

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

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

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

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

`ABSOLUTE_URL_OVERRIDES`

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

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

ABSOLUTE_URL_OVERRIDES = {
    'blogs.weblog': 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, вы обходите эту меру безопасности.

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

Если ALLOWED_HOSTS пусто и DEBUG=True, поддомены localhost были разрешены.

`APPEND_SLASH`

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

Если установлено значение True, если адрес запроса не соответствует ни одному шаблону в 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.MemcachedCache'
'django.core.cache.backends.memcached.PyLibMCCache'

Вы можете использовать кэш-бекенд, не поставляемый с 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, записи в кэше не будут истекать.

`VERSION`

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

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

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

`CACHE_MIDDLEWARE_ALIAS`

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

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

`CACHE_MIDDLEWARE_KEY_PREFIX`

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

Строка, которая будет добавленa в качестве префикса к ключам кэша, сгенерированным middleware кэша. Этот префикс комбинируется с настройкой 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.

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

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

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

`CSRF_COOKIE_PATH`

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

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

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

`CSRF_COOKIE_SAMESITE`

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

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

Подробности о SameSite см. в SESSION_COOKIE_SAMESITE.

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

Разрешено было устанавливать CSRF_COOKIE_SAMESITE = 'None'.

`CSRF_COOKIE_SECURE`

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

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

`CSRF_USE_SESSIONS`

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

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

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

Поскольку стандартные контроллеры ошибок требуют токена CSRF, SessionMiddleware должен появляться в MIDDLEWARE перед любым 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). Для secure небезопасного запроса защита Django от CSRF требует, чтобы запрос имел заголовок Referer, соответствующий источнику, указанному в заголовке Host. Это предотвращает, например, запрос POST с subdomain.example.com от успешного выполнения против api.example.com. Если вам нужны междоменные небезопасные запросы по HTTPS, продолжая пример, добавьте "subdomain.example.com" в этот список. Этот параметр также поддерживает поддомены, поэтому вы можете добавить ".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» («host» в pg_hba.conf). В Windows всегда необходимо определять HOST, так как сокеты UNIX-домена недоступны.

`NAME`

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

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

`CONN_MAX_AGE`

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

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

`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 упрощает арифметику с датами и временем — нет необходимости использовать метод normalize() из pytz.
- Если вы подключаетесь к базе данных стороннего разработчика, которая хранит даты и время в местном времени, а не в UTC, то необходимо установить этот параметр в соответствующий часовой пояс. Аналогично, если Django управляет базой данных, но системы сторонних разработчиков подключаются к той же базе данных и ожидают найти даты и время в местном времени, то необходимо установить этот параметр.
Если бэкенд базы данных поддерживает часовые пояса (например, PostgreSQL), параметр TIME_ZONE используется очень редко. Его можно изменить в любое время; база данных позаботится о преобразовании дат и времени в желаемый часовой пояс.

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

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

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

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

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

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

Новое в Django 3.1.

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

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

`MIRROR`

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

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

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

`NAME`

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

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

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

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

`SERIALIZE`

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

`TEMPLATE`

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

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

`CREATE_DB`

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

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

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