Settings¶

Core Settings
Auth
Messages
Sessions
Sites
Static Files
Core Settings Topical Index

Warning

重写设置时要小心，特别是当默认值是非空列表或字典时，如STATICFILES_FINDERS。确保你保留了你想使用的Django功能所需的组件。

Core Settings ¶

以下是Django核心中可用的设置列表及其默认值。下面列出了由contrib应用程序提供的设置，随后是核心设置的主题索引。有关介绍材料，请参阅设置主题指南。

`ABSOLUTE_URL_OVERRIDES`¶

Default: {} (Empty dictionary)

字典将“app_label.model_name”字符串映射到接受模型对象并返回其URL的函数。这是在每个安装的基础上插入或覆盖get_absolute_url()函数的一种方法。 Example:

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

请注意，无论实际模型类名称的大小写如何，此设置中使用的模型名称应全部为小写。

`ADMINS`¶

Default: [] (Empty list)

所有获取代码错误通知的人的列表。当在LOGGING中配置DEBUG = False和AdminEmailHandler时（默认完成），Django会通过电子邮件向这些人发送请求/响应周期。

列表中的每个项目应该是（全名，电子邮件地址）的元组。 Example:

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

`ALLOWED_HOSTS`¶

Default: [] (Empty list)

表示此Django网站可以提供服务的主机/域名的字符串列表。这是一项安全措施，可以防止HTTP头攻击，即使在许多看似安全的Web服务器配置下也是如此。

这个列表中的值可以是完全限定的名称（例如'www.example.com'），在这种情况下，它们将完全与请求的Host不敏感，不包括端口）。以句号开头的值可以用作子域通配符：'example.com'将匹配example.com，www.example.com以及example.com的任何其他子域。值'*'将匹配任何内容；在这种情况下，您有责任提供您自己对Host标头的验证（可能在中间件中；如果是这样，该中间件必须在MIDDLEWARE中首先列出）。

Django还允许任何条目的fully qualified domain name (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是checked when running tests。

此验证仅适用于get_host()；如果您的代码直接从request.META访问Host头，则您将绕过此安全保护。

Changed in Django 1.11:

在旧版本中，运行测试时未检查ALLOWED_HOSTS。

在旧版本中，如果DEBUG = True，ALLOWED_HOSTS未被选中。 This was also changed in Django 1.10.3, 1.9.11, and 1.8.16 to prevent a DNS rebinding attack.

`APPEND_SLASH`¶

Default: True

当设置为True时，如果请求URL与URLconf中的任何模式都不匹配，并且它不以斜线结尾，则会将HTTP重定向发送到具有斜杠的相同URL。请注意，重定向可能会导致POST请求中提交的任何数据丢失。

APPEND_SLASH设置仅在安装CommonMiddleware时使用（请参阅中间件）。 See also PREPEND_WWW.

`CACHES`¶

Default:

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

包含Django使用的所有缓存设置的字典。它是一个嵌套字典，其内容将缓存别名映射到包含单个缓存选项的字典。

CACHES设置必须配置默认缓存；任何数量的附加缓存也可以被指定。如果您使用本地内存缓存以外的缓存后端，或者您需要定义多个缓存，则需要其他选项。以下缓存选项可用。

`BACKEND`¶

Default: '' (Empty string)

要使用的缓存后端。内置缓存后端是：

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

您可以通过将BACKEND设置为缓存后端类的完全限定路径（即mypackage.backends.whatever.WhateverCache）来使用不支持Django的缓存后端）。

`KEY_FUNCTION`¶

一个字符串，其中包含指向函数（或任何可调用函数）的虚线路径，该函数定义如何将最前面的缓存关键字组成一个前缀，版本和关键字。默认实现等同于该函数：

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

只要具有相同的参数签名，您可以使用任何您想要的键功能。

有关更多信息，请参阅缓存文档。

`KEY_PREFIX`¶

Default: '' (Empty string)

为一个字符串，将被自动包含在Django服务器使用的所有缓存关键字中（默认预置）。

有关更多信息，请参阅缓存文档。

`LOCATION`¶

Default: '' (Empty string)

The location of the cache to use. 这可能是文件系统缓存的目录，Memcache服务器的主机和端口，或简单地说是本地内存缓存的标识名称。 e.g.:

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

`OPTIONS`¶

Default: None

Extra parameters to pass to the cache backend. Available parameters vary depending on your cache backend.

Some information on available parameters can be found in the cache arguments documentation. For more information, consult your backend module’s own documentation.

`TIMEOUT`¶

Default: 300

The number of seconds before a cache entry is considered stale. If the value of this settings is None, cache entries will not expire.

`VERSION`¶

Default: 1

The default version number for cache keys generated by the Django server.

See the cache documentation for more information.

`CACHE_MIDDLEWARE_ALIAS`¶

Default: default

The cache connection to use for the cache middleware.

`CACHE_MIDDLEWARE_KEY_PREFIX`¶

Default: '' (Empty string)

A string which will be prefixed to the cache keys generated by the cache middleware. This prefix is combined with the KEY_PREFIX setting; it does not replace it.

See Django’s cache framework.

`CACHE_MIDDLEWARE_SECONDS`¶

Default: 600

The default number of seconds to cache a page for the cache middleware.

See Django’s cache framework.

`CSRF_USE_SESSIONS`¶

New in Django 1.11.

Default: False

Whether to store the CSRF token in the user’s session instead of in a cookie. It requires the use of django.contrib.sessions.

Storing the CSRF token in a cookie (Django’s default) is safe, but storing it in the session is common practice in other web frameworks and therefore sometimes demanded by security auditors.

`CSRF_FAILURE_VIEW`¶

Default: 'django.views.csrf.csrf_failure'

A dotted path to the view function to be used when an incoming request is rejected by the CSRF protection. The function should have this signature:

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

where reason is a short message (intended for developers or logging, not for end users) indicating the reason the request was rejected. It should return an HttpResponseForbidden.

django.views.csrf.csrf_failure() accepts an additional template_name parameter that defaults to '403_csrf.html'. If a template with that name exists, it will be used to render the page.

`CSRF_HEADER_NAME`¶

Default: 'HTTP_X_CSRFTOKEN'

The name of the request header used for CSRF authentication.

As with other HTTP headers in request.META, the header name received from the server is normalized by converting all characters to uppercase, replacing any hyphens with underscores, and adding an 'HTTP_' prefix to the name. For example, if your client sends a 'X-XSRF-TOKEN' header, the setting should be 'HTTP_X_XSRF_TOKEN'.

`CSRF_TRUSTED_ORIGINS`¶

Default: [] (Empty list)

A list of hosts which are trusted origins for unsafe requests (e.g. POST). For a secure unsafe request, Django’s CSRF protection requires that the request have a Referer header that matches the origin present in the Host header. This prevents, for example, a POST request from subdomain.example.com from succeeding against api.example.com. If you need cross-origin unsafe requests over HTTPS, continuing the example, add "subdomain.example.com" to this list. The setting also supports subdomains, so you could add ".example.com", for example, to allow access from all subdomains of example.com.

`DATABASES`¶

Default: {} (Empty dictionary)

字典包含Django使用的所有数据库设置的。它是一个嵌套字典，其内容将数据库别名映射到包含单个数据库选项的字典。

DATABASES设置必须配置一个默认的数据库；还可以指定任意数量的附加数据库。

最简单的设置文件是使用SQLite进行单一数据库设置的。 This can be configured using the following:

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

当连接到其他数据库后端时，如MySQL，Oracle或PostgreSQL，将需要额外的连接参数。有关如何指定其他数据库类型，请参阅下面的ENGINE设置。 This example is for PostgreSQL:

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

可以使用以下更复杂配置所需的内部选项：

`ATOMIC_REQUESTS`¶

Default: False

将此设置为True以将此数据库中的每个视图包装在事务中。请参阅将交易与HTTP请求绑定。

`AUTOCOMMIT`¶

Default: True

如果您想要禁用Django的事务管理并实现您自己的事务，请将其设置为False。

`ENGINE`¶

Default: '' (Empty string)

要使用的数据库后端。内置的数据库后端是：

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

通过将ENGINE设置为完全限定的路径（即mypackage.backends.whatever），您可以使用不支持Django的数据库后端。

`HOST`¶

Default: '' (Empty string)

连接到数据库时使用哪个主机。一个空字符串表示localhost。不同SQLite一起使用。

如果此值以正斜杠（'/'）开头，并且您正在使用MySQL，则MySQL将通过Unix套接字连接到指定的套接字。 For example:

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

如果你正在使用MySQL并且这个值不以正斜杠开始，那么这个值被认为是主机。

如果您使用PostgreSQL，默认情况下（空HOST），通过UNIX域套接字（pg_hba.conf中的'本地'行）完成与数据库的连接。如果您的UNIX域套接字不在标准位置，请使用postgresql.conf中相同的unix_socket_directory值。如果要通过TCP套接字进行连接，请将HOST设置为'localhost'或'127.0.0.1'（pg_hba.conf中的'主机'行）。在Windows上，您应该始终定义HOST，因为UNIX域套接字不可用。

`NAME`¶

Default: '' (Empty string)

要使用的数据库的名称。对于SQLite，它是数据库文件的完整路径。指定路径时，即使在Windows上也要使用正斜杠（例如，C：/homes/user/mysite/sqlite3.db）。

`CONN_MAX_AGE`¶

Default: 0

数据库连接的生命周期，以秒为单位。设置为0则在每个请求结束时会关闭数据库连接-Django的历史行为-而设置为None将会无限持续连接。

`OPTIONS`¶

Default: {} (Empty dictionary)

连接到数据库时使用的额外参数。可用参数因数据库后端而异。

有关可用参数的一些信息可以在Database Backends文档中找到。有关更多信息，请查阅您的后端模块自己的文档。

`PASSWORD`¶

Default: '' (Empty string)

The password to use when connecting to the database. Not used with SQLite.

`PORT`¶

Default: '' (Empty string)

The port to use when connecting to the database. An empty string means the default port. Not used with SQLite.

`TIME_ZONE`¶

Default: None

表示存储在此数据库中的日期时间的时区的字符串（假定它不支持时区）或无。 DATABASES设置的内部选项接受与一般TIME_ZONE设置相同的值。

这允许与存储日期时间的第三方数据库在本地时间而不是UTC进行交互。为避免出现DST更改的问题，您不应为由Django管理的数据库设置此选项。

当USE_TZ为True且数据库不支持时区时（例如SQLite，MySQL，Oracle），Django根据此选项在本地时间读取和写入日期时间如果不是，则依据UTC。

当USE_TZ为True且数据库支持时区（例如PostgreSQL）时，设置此选项是错误的。

当USE_TZ为False时，设置此选项是错误的。

`DISABLE_SERVER_SIDE_CURSORS`¶

New in Django 1.11.1.

Default: False

Set this to True if you want to disable the use of server-side cursors with QuerySet.iterator(). Transaction pooling and server-side cursors describes the use case.

This is a PostgreSQL-specific setting.

`USER`¶

Default: '' (Empty string)

The username to use when connecting to the database. Not used with SQLite.

`TEST`¶

Default: {} (Empty dictionary)

A dictionary of settings for test databases; for more details about the creation and use of test databases, see The test database.

Here’s an example with a test database configuration:

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

The following keys in the TEST dictionary are available:

`CHARSET`¶

Default: None

The character set encoding used to create the test database. The value of this string is passed directly through to the database, so its format is backend-specific.

Supported by the PostgreSQL (postgresql) and MySQL (mysql) backends.

`COLLATION`¶

Default: None

The collation order to use when creating the test database. This value is passed directly to the backend, so its format is backend-specific.

Only supported for the mysql backend (see the MySQL manual for details).

`DEPENDENCIES`¶

Default: ['default'], for all databases other than default, which has no dependencies.

The creation-order dependencies of the database. See the documentation on controlling the creation order of test databases for details.

`MIRROR`¶

Default: None

The alias of the database that this database should mirror during testing.

This setting exists to allow for testing of primary/replica (referred to as master/slave by some databases) configurations of multiple databases. See the documentation on testing primary/replica configurations for details.

`NAME`¶

Default: None

The name of database to use when running the test suite.

If the default value (None) is used with the SQLite database engine, the tests will use a memory resident database. For all other database engines the test database will use the name 'test_' + DATABASE_NAME.

See The test database.

`SERIALIZE`¶

Boolean value to control whether or not the default test runner serializes the database into an in-memory JSON string before running tests (used to restore the database state between tests if you don’t have transactions). You can set this to False to speed up creation time if you don’t have any test classes with serialized_rollback=True.

`TEMPLATE`¶

New in Django 1.11.

This is a PostgreSQL-specific setting.

The name of a template (e.g. 'template0') from which to create the test database.