Django-生产环境要注意哪些事项
这篇讲什么
- 把一个 Django 项目放上生产环境,要改的东西不多,但每一条都能决定线上会不会出事:配置层的
DEBUG/ALLOWED_HOSTS/SECRET_KEY,发布动作里的迁移与静态资源,运行层的进程守护与反向代理,最后还有「改完敢不敢上线」的单元测试。 - 这篇不抄清单,每一条都在本机跑一遍再写结论,包括实测到的报错原文、耗时数字和几个反直觉的地方(比如 gunicorn 默认就相信
X-Forwarded-Proto,TestCase到底清不清表)。
- 实测环境:WSL2 Ubuntu 26.04.1 LTS + Python 3.14.4 + Django 5.2.19 LTS + MySQL 9.7.4(驱动 mysqlclient 2.3.0)+ Gunicorn 26.2.0 + Uvicorn 0.54.0 + Nginx 1.28.3 + systemd 258。
发布前必须动的三个配置
1.1 DEBUG:生产必须是 False
DEBUG=True 时,任何未捕获异常都会渲染成一张「技术调试页面」,里面是完整栈帧、局部变量、请求 POST/GET/COOKIES、以及 settings 表。实测一个故意抛 ValueError 的视图:
1 | DEBUG=True status=500 页面长度=53501 字节 含 "ValueError"=True |
差 369 倍。这张页面对外网就是「把源码和上下文摊开给你看」,所以第一条铁律是 DEBUG=False。
顺带纠正一个常见误解:DEBUG 页并不是什么都漏,敏感项它自己会脱敏。实测把 DJANGO_SECRET_KEY 设成一个可识别的值再打开 DEBUG 页:
1 | 含真实值 super-secret-value = False |
也就是说 Django 早就把带 KEY / PASSWORD 字样的项打了星号,真正漏的是代码、栈帧、请求数据,不是口令。别因为「反正会脱敏」就把 DEBUG 打开。
关掉 DEBUG 之后异常并不会消失,它落到日志里(logs/deploy.log):
1 | ERROR 2026-11-05 05:51:22,696 django.request Internal Server Error: /boom/ |
配置写法(DEBUG 由环境变量决定,避免手改文件):
1 | import os |
1.2 ALLOWED_HOSTS:它校验的是 Host 请求头
DEBUG=False 时 Django 会检查请求的 Host 头在不在名单里,不在就直接 400。实测(名单里只放 probe.local):
1 | Host=probe.local -> 200 |
被拒时抛的是 DisallowedHost,异常消息写得很明白:
1 | django.core.exceptions.DisallowedHost: Invalid HTTP_HOST header: '127.0.0.1'. |
这条最容易踩的坑不是「忘了配」,而是配了域名却忘了本机测试用的 127.0.0.1,结果一切健康检查、curl localhost 全 400。规则:
- 值必须是全小写域名列表,可以带端口(
"example.com:8000")。 - 以点开头的
".example.com"匹配example.com和它的所有子域。 "*"会匹配任意Host,只在DEBUG=True时才是默认行为,生产别写。DEBUG=True且ALLOWED_HOSTS为空时,Django 会退化成允许localhost/127.0.0.1/[::1],这是为了方便开发,不是安全设置。
用环境变量给列表,省得为不同环境改代码:
1 | def env_list(name, default=None): |
1 | export DJANGO_ALLOWED_HOSTS=127.0.0.1,localhost,probe.local,recruit.example.com |
SECRET_KEY
生成一条命令就够,实测长度是 50:
1 | $ python -c 'from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())' |
startproject 生成的 settings.py 里那个 key 是 django-insecure- 开头的,check --deploy 会专门盯它(下面 1.4 会看到 W009 原文)。
换 key 的连带影响比想象大:session cookie、CSRF cookie、签名 URL、密码重置令牌、Signer 产物全都用它签名。实测换 key 前后:
1 | 同一 key 解签名对象 = {'user_id': 7, 'action': 'reset'} |
注意 BadSignature 不区分「被人篡改」和「你换了 key」,所以轮换 key 之后所有未过期令牌都会失效,得挑低峰做,并提前告诉用户重新登录。
存放位置按优先级:环境变量 → systemd 的 EnvironmentFile → 云的 KMS / 密钥管理产品。代码里绝不写死,也别留「读不到就用一个弱默认」的后门——这条我实测过风险:
1 | SECRET_KEY = env("DJANGO_SECRET_KEY", "dev-only-insecure-key") |
1 | 有环境变量时 SECRET_KEY 长度 = 50 |
生产更稳的写法是读不到就抛异常,让发布失败而不是悄悄降级:
1 | SECRET_KEY = os.environ["DJANGO_SECRET_KEY"] # 没配就直接 KeyError,别给默认值 |
一(续)、check --deploy 到底会报什么
这是发布前的体检命令,别只看别人转述的条目,本机跑出来的原文是这样:
1 | $ python manage.py check --settings=proj.settings.prod --deploy |
1 | System check identified some issues: |
三条分别对应:HSTS 没开(全站只走 HTTPS 时才建议开,开错很难撤回,官方文档特意提醒)、没强制 HTTPS 跳转、SECRET_KEY 太短或还是 startproject 那个。
如果站点是纯内网 HTTP(比如只在 VPC 里跑),W004 / W008 可以留着不消,但要清楚自己在干什么;W009 无论如何都要消。

配置分层
三份 settings 的目录写法
startproject 只给一个 settings.py,上线前建议拆成包:
1 | proj/settings/ |
1 | from proj.settings.base import * # noqa: F403 |
1 | from proj.settings.base import * # noqa: F403 |
from ... import * 之后还要显式覆盖的项,必须再 from base import env_bool 把函数单独拿进来——import * 不会带下划线开头的名字,也不会带你没写 __all__ 时的辅助函数以外的东西,这点很容易写成 NameError。
选哪一份:优先级实测
三个地方都能指定 settings,优先级从高到低:
1 | 1. 命令行 --settings=proj.settings.dev (单次最高) |
实测用第 1 种跑测试(第 3 种是 manage.py 里的 setdefault,所以前两种都能盖掉它):
1 | $ python manage.py test --settings=proj.settings.dev -v 2 |
wsgi.py / asgi.py 里写的是 setdefault,所以 gunicorn 只要不显式给环境变量就会用生产那份:
1 | import os |
数据库配置里跟发布有关的几项
3.1 DATABASES 全部走环境变量,账号只用最小权限
1 | DATABASES = { |
建库和授权也建议在文章里就写清楚(实测在 MySQL 9.7.4 上可用):
1 | CREATE DATABASE django_note_deploy |
connect_timeout 别省:连不上时默认会一直挂着,加上之后 5 秒就抛 OperationalError,容器里排错快很多(PostgreSQL 同理,psycopg 用 OPTIONS: {"connect_timeout": 8})。
3.2 CONN_MAX_AGE:持久连接省了多少
实测 30 次会打两条 SQL 的请求:
1 | CONN_MAX_AGE=0 30 次请求墙钟 0.049s |
同机 socket 情况下只差 10ms,看着不值一提;但生产库通常在另一个可用区,一次握手 3~10ms 时,这 20% 会变成肉眼可见的尾延迟。代价是连接会占着 MySQL 的 max_connections(实测本机默认 151),所以要按 worker 数算账:
1 | 占用连接数 ≈ worker 数 × 每 worker 线程数(sync worker 就是 1) |
另外实测到一个细节:connection.close() 之前 SHOW PROCESSLIST 里那条连接还在,close() 之后才归零——CONN_MAX_AGE 的「过期」是 Django 在请求结束时判断的,不是数据库那边踢掉。
3.3 时区:Django 存 UTC,MySQL 的 NOW() 存本地时间
1 | timezone.now() = 2026-11-04 21:51:45.654201+00:00 |
USE_TZ=True 时 Django 写库一律 UTC,读出来再按 TIME_ZONE 转本地。但如果你在 SQL 里用 Now()、CURRENT_TIMESTAMP、DEFAULT NOW(),那是 MySQL 自己的会话时区(本机是 SYSTEM,即 +08),两套时间会差 8 小时。
这个坑在《Django-Celery》里已经实测过一次(django_celery_results.date_started 用数据库 Now() 写,比 Python 写的 date_created 早 8 小时),部署时同样会撞上。结论:
- 时间列一律交给 Django 写(
auto_now_add、timezone.now()),别用数据库默认值。 - 真要混用,就把
DATABASES["default"]["TIME_ZONE"]显式设成和会话一致,并在代码评审里禁止裸Now()。
数据库层还有约束兜底
sqlmigrate 能直接看到建表语句,实测 MySQL 9.7.4 生成的 DDL 里带 UNSIGNED 和 CHECK:
1 | $ python manage.py sqlmigrate core 0001 |
1 | CREATE TABLE `core_deployitem` ( |
绕过 ORM 直接写负数会被数据库拦下(实测):
1 | INSERT ... VALUES ('negative', -1, NOW(6)) |
也就是说 PositiveIntegerField 的校验其实有三层:表单 full_clean()、ORM 字段、数据库列。生产上第三层最可靠,别关掉。
迁移的执行顺序
发布时先迁移还是先发代码,取决于改动类型。实测这几条命令的行为:
1 | $ python manage.py migrate --settings=proj.settings.prod |
安全顺序(零停机):
-
加列先用「可空」或「有默认值」,别在同一次发布里
NOT NULL直接加。 -
先发代码(旧代码不读新列),再
migrate。 -
删列拆成两次发布:第一次代码不再用它,第二次
RemoveField。 -
数据迁移写进
RunPython,配atomic=True,并在--plan里确认它排在结构迁移之后。 -
出问题要回退时优先「往前修」,别在生产
migrate app 000X往回滚,除非确认过django_migrations表状态。
四、静态资源:collectstatic 与托管
三个 STATIC 键各管什么
| 键 | 管谁 | 生产写法 | 常见误解 |
|---|---|---|---|
STATIC_URL |
浏览器访问静态资源的 URL 前缀 | /static/ |
以为它是磁盘路径 |
STATIC_ROOT |
collectstatic 收集到哪个目录 |
/srv/django/static(绝对路径) |
写成 "static" 会和源目录撞车 |
STATICFILES_DIRS |
除应用 static/ 之外还要扫哪些目录 |
[BASE_DIR / "static"] |
忘了它,第三方应用的静态资源找不到 |
老笔记里那句 STATIC_ROOT = 'static' 是错的示范:相对路径会随当前工作目录变化,而且如果它和 STATICFILES_DIRS 里的目录重名,collectstatic 会直接报「冲突」并拒绝执行。
实测收集结果
1 | $ python manage.py collectstatic --noinput --settings=proj.settings.prod |
prod 用的是 ManifestStaticFilesStorage,所以除了原文件还会生成带哈希的副本和一张清单:
1 | staticfiles/ |
哈希名由内容算出,内容不变文件名不变,所以可以放心给静态资源设很长的缓存头。两个注意点:
- 改了 CSS/JS 必须重新
collectstatic,否则模板引用的哈希名和清单对不上。 ManifestStaticFilesStorage会在收集时校验模板里引用的每个资源是否存在,引用不到就报错中断——这是好事,但第一次上生产时容易把构建卡住。
4.3 由 Nginx 直接服务,别让 Django 管
STATIC_URL 对应的路径交给 Nginx,Django 只处理动态请求:
1 | location /static/ { |
实测经 Nginx 取静态文件(后端是两个 gunicorn 实例):
1 | /static/site.css -> 200 165B 0.0024s |
更能说明问题的是这一条:把两个后端全 kill 掉之后,/static/site.css 仍然 200,而 / 返回 502。
1 | 两个 upstream 都停 -> / 502 |
也就是说静态资源的可用性不该依赖应用进程,这正是把它交给 Web 服务器(或 CDN)的理由。
日志:写到哪、怎么转、谁来收
一份能直接抄的 LOGGING
1 | LOG_DIR = env("DJANGO_LOG_DIR", str(BASE_DIR / "logs")) |
django.request 这个 logger 是专门记 4xx/5xx 的,级别设 WARNING 就够(404 也会记),生产上想少刷屏可以调 ERROR。
轮转实测
往 core 这个 logger 灌 15000 条约 170 字节的日志,看 RotatingFileHandler 的行为:
1 | deploy.log 1022944 字节 |
maxBytes=2MB 生效:写满 2MB 就整份改名成 .log.1,新日志从 .log 重新开始,backupCount=3 决定最多留几份。
生产上更推荐只写 stdout/stderr,让 systemd 收(原因:文件轮转和权限在多进程下容易踩坑, journald 已经帮你做了轮转和查询)。gunicorn 侧只要这样:
1 | accesslog = "-" # "-" 表示 stdout |
实测 journald 里能直接看到访问行:
1 | $ journalctl -u djdeploy --no-pager -n 6 |
出错时日志在哪看
- 500:
django.request记Internal Server Error: /boom/+ traceback(实测在logs/deploy.log,684 字节那份就是它)。 - 数据库连不上:
OperationalError在django.db.backends下,默认不单独配也行。 ADMINS邮件报警:实测默认ADMINS = [],且没有自定义handler500,所以「关掉 DEBUG 就看不到错误」是错觉,错误全在日志里;要靠邮件收 500 报警得显式配ADMINS和可用的邮件后端。
应用容器
runserver 是单线程的开发服务器(--threaded 也只是加线程),没有进程管理、没有优雅关闭、没有 worker 回收,绝不能当生产用。生产要选一个 WSGI/ASGI 容器。
选型对照
| 容器 | 协议 | 实现 | 什么时候用 |
|---|---|---|---|
| Gunicorn | WSGI | 纯 Python | 默认选择,配置简单,官方文档点名推荐 |
| uWSGI | WSGI | C | 已有 uwsgi 生态(宝塔/旧运维脚本)时沿用 |
| Uvicorn | ASGI | Python + uvloop | 用到异步视图、WebSocket、async ORM 时 |
| Daphne | ASGI | twisted | Channels 项目的历史选择 |
| Hypercorn | ASGI | sans-io | HTTP/2 需求明确时 |
同步项目用 Gunicorn,异步用 Uvicorn(或 Gunicorn + UvicornWorker)。Django 自身的异步支持路线是:3.0 上 ASGI、3.1 上异步视图、4.1 上异步 ORM 模板层,5.2 里 ORM 仍是同步的,别在 async def 视图里直接调 ORM。
Gunicorn 实测
启动 3 个 sync worker:
1 | $ gunicorn proj.wsgi:application --bind 127.0.0.1:8001 --workers 3 |
并发能力直接测:/slow/ 每次固定 sleep(0.2),串行 10 次要 2.0s。
1 | 3 个 sync worker 10 个并发请求墙钟 0.86s(另一轮 systemd 起的 3 worker 是 0.95s) |
worker 分布可以用 access log 的 pid 字段看(--access-logformat '%(p)s %(t)s "%(r)s" %(s)s'),实测 10 个请求落在三个 worker 上是 3/5/3,不是严格轮转——sync worker 是「谁空谁拿」,别指望均匀。
优雅重载(改代码后不中断服务):
1 | $ kill -HUP 4206 # 只杀主进程 |
主进程 4206 一直活着(kill -0 验证),监听不断,只换 worker。ExecReload=/bin/kill -s HUP $MAINPID 就是给 systemctl reload 用的。
内存回收靠 max_requests(防内存泄漏兜底):
1 | max_requests = 1000 |
systemd 托管实测
unit 文件(Type=notify 是 gunicorn 支持的,systemd 会等它真正就绪才算启动成功):
1 | [Unit] |
实测行为:
1 | systemctl start djdeploy -> active,Main PID: 4618 (gunicorn) |
EnvironmentFile 里放密钥(文件权限 600),别把 SECRET_KEY 写进 unit 文件——unit 是会被 systemctl show 全文打印出来的。
Uvicorn 实测
1 | $ uvicorn proj.asgi:application --host 127.0.0.1 --port 8100 --workers 2 |
同样打 10 个并发 /slow/:
1 | uvicorn 2 worker 墙钟 0.25s |
单 worker 的 uvicorn 为什么能并发?因为 Django 的同步视图在 ASGI 下会被 asgiref 丢进线程池执行,实测那个 worker 进程里有 5 个线程。结论有两面:
- 好处:ASGI 部署下,同步视图不会像 sync worker 那样一个个排队。
- 代价:并发上限不再是 worker 数,而是线程池大小;
threading.local、连接数、CONN_MAX_AGE的账要按「worker × 线程」重算,MySQL 的max_connections更容易被打满。
另外两个实测细节:uvicorn 0.54.0 没有 --pid-file 和 --daemon 选项(写了会直接 Error: No such option '--pid-file'),要后台运行请用 systemd 或 nohup ... &。
6.5 反向代理与 X-Forwarded-Proto
Nginx 配置里 upstream 挂两个 gunicorn 实例,实测 12 次请求的分布:
1 | 8001 收到: 6 次 |
关键的一条:gunicorn 默认就相信 X-Forwarded-Proto。实测在没配 Django 的 SECURE_PROXY_SSL_HEADER 的实例上,直接伪造这个头:
1 | 直连后端,不带伪头 -> X-Request-Secure: False |
SECURE_SSL_REDIRECT=1 时还能看到跳转:
1 | HTTP/1.1 301 Moved Permanently |
这条的实际含义是:信任边界在 WSGI 服务器,不在 Django。所以两件事必须做对:
- gunicorn/uvicorn 只监听
127.0.0.1(或 unix socket),不能让外网直连,否则任何人都能伪造X-Forwarded-Proto绕过 HTTPS 跳转、污染 cookie 的Secure判定。 - Nginx 要覆盖而不是透传客户端的伪头:
proxy_set_header X-Forwarded-Proto $scheme;(写成$http_x_forwarded_proto就是把伪造权交给客户端)。
uvicorn 侧对应的是 --proxy-headers(默认开)与 --forwarded-allow-ips,同样要把可信来源收紧到 127.0.0.1。
单元测试:上线前的最后一道门
四个基类的分工
| 基类 | 数据库 | 隔离方式 | 什么时候用 |
|---|---|---|---|
SimpleTestCase |
禁止访问 | 无 | 纯函数、表单、模板渲染、URL 解析 |
TestCase |
允许 | 类级原子事务 + 每个用例回滚 | 绝大多数用例,默认选它 |
TransactionTestCase |
允许 | 每个用例结束后 TRUNCATE 全部表 | 要真的 commit()、测 ON DELETE CASCADE、多数据库 |
LiveServerTestCase |
允许 | 同 TestCase,外加起一个真 HTTP server |
Selenium 等外部工具访问 |
老笔记里两处要改:SimplTestCase 拼错了,正确是 SimpleTestCase;「TestCase 执行完不清理表数据」这句反了——TestCase 是靠事务回滚隔离的,真正会清表的是 TransactionTestCase。

目录与发现规则
Django 沿用 unittest 的发现机制,默认在工作目录下找 test*.py。两种组织方式都合法:
1 | core/tests.py # 小项目 |

跑法与实测耗时
1 | $ python manage.py test # 全部 |
实测数字(4 个用例,MySQL):
1 | manage.py test -v 2 -> Ran 4 tests in 0.036s |
也就是说用例本身 36 毫秒,其余全是建测试库和迁移。所以 CI 上要么 --keepdb,要么把测试库换成 SQLite(前提是你的用例不依赖 MySQL 特性)。
test --help 里能看到的常用开关(实测存在):--failfast、--keepdb、--parallel [N]、--tag / --exclude-tag、-r/--reverse、--pdb、-t TOP_LEVEL、-p PATTERN。
一个坑:最小权限账号跑不了测试
用 3.1 那个只授权单库的 djdeploy 账号跑测试,第一步就挂:
1 | Got an error creating the test database: |
原因是 unittest 会另建一个 test_<NAME> 库,而 GRANT ... ON django_note_deploy.* 不包含它(_ 在 MySQL 授权里是单字符通配,必须转义)。解法是显式加一条:
1 | GRANT ALL PRIVILEGES ON `test\_django\_note\_deploy`.* TO 'djdeploy'@'localhost'; |
实测加上之后 4 个用例全绿,跑完 Django 会自己 Destroying test database。CI 里更省事的做法是给流水线单独一个能建库的账号,和生产账号分开。
一份能抄的用例文件
1 | from django.test import SimpleTestCase, TestCase, override_settings |
三个容易写错的地方:
setUpTestData是@classmethod,它建的数据在类内所有用例间共享,且只回滚不重建。assertRaises(IntegrityError)不加transaction.atomic()时,MySQL 的事务已被标记为无效,后面任何查询都会报错。SimpleTestCase里一旦访问数据库会直接抛异常,这是设计如此,不是 bug。
发布清单
- 冻结依赖并核对版本:
pip freeze > requirements.txt,装之前先看新包会不会把 Django 降级(实测django-prometheus在未装 Django 的环境里会顺手拉Django 6.0.10)。 - 跑测试:
python manage.py test --settings=proj.settings.dev。 - 生产配置体检:
python manage.py check --settings=proj.settings.prod --deploy,把 W009 这类必须消的消掉。 - 备份数据库(
mysqldump --single-transaction),这一步别省。 - 收集静态资源:
python manage.py collectstatic --noinput --settings=proj.settings.prod。 - 发布代码(软链切换或蓝绿),保留上一版本目录便于回滚。
- 执行迁移:
python manage.py migrate --settings=proj.settings.prod。 - 重载应用进程:
systemctl restart djdeploy,或kill -HUP主进程做优雅重启。 - 冒烟验证:
curl -i http://127.0.0.1:8090/、/static/site.css、一个会写库的接口,再看journalctl -u djdeploy有没有 500。 - 观察 5~10 分钟错误率与响应时间再离开。

这一批实测里最容易踩的坑
DEBUG=False却忘了把127.0.0.1加进ALLOWED_HOSTS,健康检查全 400。SECRET_KEY留了弱默认值,读不到环境变量时不报错——实测会静默用 21 字符的默认 key。- 时间列用数据库
Now()写,和 Django 的 UTC 混在一起差 8 小时。 STATIC_ROOT写成相对路径"static",和源码目录撞车。- 给生产库建了最小权限账号,结果 CI 跑测试时建不了
test_库(1044)。 - 以为 gunicorn 需要
SECURE_PROXY_SSL_HEADER才认X-Forwarded-Proto,实测它默认就认——于是忘了收紧监听地址和 Nginx 的头覆盖。 - uvicorn 没有
--daemon/--pid-file,脚本里照抄旧文章会启动失败。 - 断言
IntegrityError时没包transaction.atomic(),导致同一个测试类里后续用例连锁失败。
参考
- Django 官方:部署清单(How to deploy Django):
check --deploy各条检查项的含义。 - Django 官方:部署检查清单(Deployment checklist):
DEBUG、ALLOWED_HOSTS、SECRET_KEY、安全中间件各开关。 - Django 官方:静态文件处理:
STATIC_ROOT与collectstatic的行为、ManifestStaticFilesStorage。 - Django 官方:测试工具:四个测试基类的隔离方式与事务行为。
- Django 官方:日志配置:
django.request等内置 logger。 - Gunicorn 官方文档:worker 模型、
max_requests、优雅重启信号。 - Uvicorn 官方文档:
--workers、--proxy-headers、--forwarded-allow-ips。 - systemd 服务单元文档:
Type=notify、ExecReload、EnvironmentFile。