Настройки

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

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

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

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

Изменено в 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.

END_OF_DOCUMENT_MARKER ```

`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_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 для неограниченных постоянных подключений.

`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

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

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

`NAME`

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

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

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

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

`SERIALIZE`

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

END_OF_DOCUMENT_MARKER

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

`TEMPLATE`

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

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