在 Django 项目中,配置文件是整个应用的核心枢纽,负责管理数据库连接、中间件、应用组件、安全设置等关键参数。以下是对 Django 配置文件的详细解析:
一、配置文件基础
1. 核心配置文件
Django 项目的默认配置文件是settings.py
,通常位于项目根目录下的配置包中(如myproject/settings.py
)。这个文件定义了 Django 应用的所有配置选项。
2. 配置加载顺序
Django 启动时会自动加载settings.py
中的配置,也可以通过DJANGO_SETTINGS_MODULE
环境变量指定其他配置文件:
# 启动时指定配置文件
python manage.py runserver --settings=myproject.settings.production
二、配置文件关键组成部分
1. 基础设置
# 项目根目录
BASE_DIR = Path(__file__).resolve().parent.parent
# 安全密钥(生产环境必须从环境变量获取)
SECRET_KEY = 'your-secret-key-here'
# 调试模式(生产环境必须为False)
DEBUG = True
# 允许访问的域名
ALLOWED_HOSTS = ['localhost', '127.0.0.1']
2. 应用注册
INSTALLED_APPS = [
# Django内置应用
'django.contrib.admin',
'django.contrib.auth',
'django.contrib.contenttypes',
'django.contrib.sessions',
'django.contrib.messages',
'django.contrib.staticfiles',
# 第三方应用
'rest_framework',
'django_celery_beat',
# 自定义应用
'apps.core',
'apps.users',
]
3. 中间件配置
MIDDLEWARE = [
'django.middleware.security.SecurityMiddleware',
'django.contrib.sessions.middleware.SessionMiddleware',
'django.middleware.common.CommonMiddleware',
'django.middleware.csrf.CsrfViewMiddleware',
'django.contrib.auth.middleware.AuthenticationMiddleware',
'django.contrib.messages.middleware.MessageMiddleware',
'django.middleware.clickjacking.XFrameOptionsMiddleware',
]
4. 数据库配置
# SQLite配置(开发环境)
DATABASES = {
'default': {
'ENGINE': 'django.db.backends.sqlite3',
'NAME': BASE_DIR / 'db.sqlite3',
}
}
# PostgreSQL配置(生产环境)
DATABASES = {
'default': {
'ENGINE': 'django.db.backends.postgresql',
'NAME': 'mydatabase',
'USER': 'mydatabaseuser',
'PASSWORD': 'mypassword',
'HOST': '127.0.0.1',
'PORT': '5432',
}
}
5. 静态文件和媒体文件配置
# 静态文件URL和存储位置
STATIC_URL = '/static/'
STATICFILES_DIRS = [BASE_DIR / 'static'] # 开发环境静态文件目录
STATIC_ROOT = BASE_DIR / 'staticfiles' # 生产环境收集静态文件的目录
# 媒体文件URL和存储位置
MEDIA_URL = '/media/'
MEDIA_ROOT = BASE_DIR / 'media'
6. URL 和模板配置
ROOT_URLCONF = 'myproject.urls'
TEMPLATES = [
{
'BACKEND': 'django.template.backends.django.DjangoTemplates',
'DIRS': [BASE_DIR / 'templates'], # 自定义模板目录
'APP_DIRS': True,
'OPTIONS': {
'context_processors': [
'django.template.context_processors.debug',
'django.template.context_processors.request',
'django.contrib.auth.context_processors.auth',
'django.contrib.messages.context_processors.messages',
],
},
},
]
7. 国际化配置
LANGUAGE_CODE = 'zh-hans' # 中文简体
TIME_ZONE = 'Asia/Shanghai' # 中国时区
USE_I18N = True # 启用国际化
USE_L10N = True # 启用本地化
USE_TZ = True # 启用时区支持
8. 安全和会话配置
# 会话配置
SESSION_COOKIE_AGE = 1209600 # 2周(秒)
SESSION_EXPIRE_AT_BROWSER_CLOSE = False
SESSION_SAVE_EVERY_REQUEST = False
# CSRF配置
CSRF_COOKIE_SECURE = True # 仅通过HTTPS传输
CSRF_COOKIE_HTTPONLY = False
# 安全头部配置
SECURE_BROWSER_XSS_FILTER = True
SECURE_CONTENT_TYPE_NOSNIFF = True
X_FRAME_OPTIONS = 'DENY'
三、配置文件最佳实践
1. 环境分离策略
推荐将配置按环境分离(开发、测试、生产):
myproject/
├── settings/
│ ├── __init__.py
│ ├── base.py # 基础配置
│ ├── dev.py # 开发环境配置
│ ├── test.py # 测试环境配置
│ └── prod.py # 生产环境配置
2. 使用环境变量
敏感信息(如密钥、数据库密码)应通过环境变量管理:
# 使用python-decouple库
from decouple import config
SECRET_KEY = config('SECRET_KEY')
DATABASES = {
'default': {
'ENGINE': 'django.db.backends.postgresql',
'NAME': config('DB_NAME'),
'USER': config('DB_USER'),
'PASSWORD': config('DB_PASSWORD'),
}
}
3. 配置文件示例
# settings/base.py (基础配置)
from pathlib import Path
from decouple import config
BASE_DIR = Path(__file__).resolve().parent.parent
SECRET_KEY = config('SECRET_KEY')
DEBUG = config('DEBUG', default=False, cast=bool)
ALLOWED_HOSTS = []
# 其他基础配置...
# settings/dev.py (开发环境配置)
from .base import *
DEBUG = True
SECRET_KEY = 'development-secret-key'
DATABASES = {
'default': {
'ENGINE': 'django.db.backends.sqlite3',
'NAME': BASE_DIR / 'db.sqlite3',
}
}
# settings/prod.py (生产环境配置)
from .base import *
DEBUG = False
DATABASES = {
'default': {
'ENGINE': 'django.db.backends.postgresql',
'NAME': config('DB_NAME'),
'USER': config('DB_USER'),
'PASSWORD': config('DB_PASSWORD'),
'HOST': config('DB_HOST'),
'PORT': config('DB_PORT'),
}
}
# 安全强化配置
SECURE_SSL_REDIRECT = True
SESSION_COOKIE_SECURE = True
CSRF_COOKIE_SECURE = True
四、高级配置选项
1. 缓存配置
# 内存缓存(开发环境)
CACHES = {
'default': {
'BACKEND': 'django.core.cache.backends.locmem.LocMemCache',
'LOCATION': 'unique-snowflake',
}
}
# Redis缓存(生产环境)
CACHES = {
'default': {
'BACKEND': 'django_redis.cache.RedisCache',
'LOCATION': 'redis://127.0.0.1:6379/1',
'OPTIONS': {
'CLIENT_CLASS': 'django_redis.client.DefaultClient',
}
}
}
2. 日志配置
LOGGING = {
'version': 1,
'disable_existing_loggers': False,
'handlers': {
'console': {
'class': 'logging.StreamHandler',
},
'file': {
'class': 'logging.FileHandler',
'filename': BASE_DIR / 'debug.log',
},
},
'root': {
'handlers': ['console', 'file'],
'level': 'INFO',
},
'loggers': {
'django': {
'handlers': ['console', 'file'],
'level': config('DJANGO_LOG_LEVEL', 'INFO'),
'propagate': False,
},
},
}
3. 自定义用户模型
AUTH_USER_MODEL = 'users.User' # 使用自定义用户模型
4. 电子邮件配置
# 控制台邮件后端(开发环境)
EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend'
# SMTP邮件后端(生产环境)
EMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend'
EMAIL_HOST = 'smtp.gmail.com'
EMAIL_PORT = 587
EMAIL_USE_TLS = True
EMAIL_HOST_USER = config('EMAIL_HOST_USER')
EMAIL_HOST_PASSWORD = config('EMAIL_HOST_PASSWORD')
5. 自定义认证后端
AUTHENTICATION_BACKENDS = [
'django.contrib.auth.backends.ModelBackend', # 默认后端
'apps.users.backends.EmailBackend', # 自定义邮箱认证后端
]
五、生产环境安全配置
1. 禁用调试模式
DEBUG = False # 生产环境必须禁用调试模式
2. 安全头部配置
SECURE_HSTS_SECONDS = 31536000 # 1年
SECURE_HSTS_INCLUDE_SUBDOMAINS = True
SECURE_HSTS_PRELOAD = True
SECURE_SSL_REDIRECT = True # 重定向HTTP到HTTPS
3. 密码哈希配置
PASSWORD_HASHERS = [
'django.contrib.auth.hashers.Argon2PasswordHasher',
'django.contrib.auth.hashers.PBKDF2PasswordHasher',
'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher',
'django.contrib.auth.hashers.BCryptSHA256PasswordHasher',
]
4. 敏感信息保护
# 使用环境变量或配置文件外部化敏感信息
# 不要将敏感信息直接写在配置文件中
六、配置文件管理工具
1. python-decouple
pip install python-decouple
# settings.py
from decouple import config
SECRET_KEY = config('SECRET_KEY')
DATABASE_URL = config('DATABASE_URL', default='sqlite:///db.sqlite3')
2. django-environ
pip install django-environ
# settings.py
import environ
env = environ.Env(
DEBUG=(bool, False)
)
environ.Env.read_env()
SECRET_KEY = env('SECRET_KEY')
DEBUG = env('DEBUG')
DATABASES = {
'default': env.db(),
}
总结
Django 配置文件是项目的核心控制中心,合理的配置结构和管理策略对项目的可维护性和安全性至关重要。通过环境分离、敏感信息外部化、合理使用第三方工具等方法,可以构建出既安全又易于维护的配置体系。