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
2
DEBUG=True   status=500  页面长度=53501 字节   含 "ValueError"=True
DEBUG=False status=500 页面长度= 145 字节 含 "ValueError"=False

差 369 倍。这张页面对外网就是「把源码和上下文摊开给你看」,所以第一条铁律是 DEBUG=False。

顺带纠正一个常见误解:DEBUG 页并不是什么都漏,敏感项它自己会脱敏。实测把 DJANGO_SECRET_KEY 设成一个可识别的值再打开 DEBUG 页:

1
2
3
4
含真实值 super-secret-value = False
SECRET_KEY 那一行显示成 = '********************'
含 DATABASES 段 = True
含数据库口令明文 = False

也就是说 Django 早就把带 KEY / PASSWORD 字样的项打了星号,真正漏的是代码、栈帧、请求数据,不是口令。别因为「反正会脱敏」就把 DEBUG 打开。

关掉 DEBUG 之后异常并不会消失,它落到日志里(logs/deploy.log):

1
2
ERROR 2026-11-05 05:51:22,696 django.request Internal Server Error: /boom/
ValueError: 探针故意抛出:boom

配置写法(DEBUG 由环境变量决定,避免手改文件):

proj/settings/base.py
1
2
3
4
5
6
7
8
9
10
11
import os


def env_bool(name, default=False):
raw = os.environ.get(name)
if raw is None:
return default
return raw.strip().lower() in ("1", "true", "yes", "on")


DEBUG = env_bool("DJANGO_DEBUG", False) # 默认关,开发那份 settings 里再打开

1.2 ALLOWED_HOSTS:它校验的是 Host 请求头

DEBUG=False 时 Django 会检查请求的 Host 头在不在名单里,不在就直接 400。实测(名单里只放 probe.local):

1
2
3
Host=probe.local        -> 200
Host=evil.example.com -> 400
Host=127.0.0.1 -> 400

被拒时抛的是 DisallowedHost,异常消息写得很明白:

1
2
django.core.exceptions.DisallowedHost: Invalid HTTP_HOST header: '127.0.0.1'.
You may need to add '127.0.0.1' to ALLOWED_HOSTS.

这条最容易踩的坑不是「忘了配」,而是配了域名却忘了本机测试用的 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],这是为了方便开发,不是安全设置。

用环境变量给列表,省得为不同环境改代码:

proj/settings/base.py
1
2
3
4
5
6
7
8
def env_list(name, default=None):
raw = os.environ.get(name)
if not raw:
return list(default or [])
return [x.strip() for x in raw.split(",") if x.strip()]


ALLOWED_HOSTS = env_list("DJANGO_ALLOWED_HOSTS", ["localhost", "127.0.0.1"])
1
export DJANGO_ALLOWED_HOSTS=127.0.0.1,localhost,probe.local,recruit.example.com

SECRET_KEY

生成一条命令就够,实测长度是 50:

1
2
3
$ python -c 'from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())'
长度 = 50
startproject 自动生成的那个带 django-insecure- 前缀 = True

startproject 生成的 settings.py 里那个 key 是 django-insecure- 开头的,check --deploy 会专门盯它(下面 1.4 会看到 W009 原文)。

换 key 的连带影响比想象大:session cookie、CSRF cookie、签名 URL、密码重置令牌、Signer 产物全都用它签名。实测换 key 前后:

1
2
3
4
同一 key 解签名对象  = {'user_id': 7, 'action': 'reset'}
换 key 后解 = BadSignature
改一个字符后解 = BadSignature Signature "mxU2gPcTdvO9h5qWw-LHZR3jd4Q-s..."
换 salt 后解 = BadSignature

注意 BadSignature 不区分「被人篡改」和「你换了 key」,所以轮换 key 之后所有未过期令牌都会失效,得挑低峰做,并提前告诉用户重新登录。

存放位置按优先级:环境变量 → systemd 的 EnvironmentFile → 云的 KMS / 密钥管理产品。代码里绝不写死,也别留「读不到就用一个弱默认」的后门——这条我实测过风险:

settings.py
1
SECRET_KEY = env("DJANGO_SECRET_KEY", "dev-only-insecure-key")
1
2
有环境变量时 SECRET_KEY 长度 = 50
不给环境变量时 SECRET_KEY = 'dev-only-insecure-key' # 21 字符,check --deploy 立刻报 W009

生产更稳的写法是读不到就抛异常,让发布失败而不是悄悄降级:

settings.py
1
SECRET_KEY = os.environ["DJANGO_SECRET_KEY"]   # 没配就直接 KeyError,别给默认值

一(续)、check --deploy 到底会报什么

这是发布前的体检命令,别只看别人转述的条目,本机跑出来的原文是这样:

1
$ python manage.py check --settings=proj.settings.prod --deploy
1
2
3
4
5
6
7
8
9
System check identified some issues:

WARNINGS:
?: (security.W004) You have not set a value for the SECURE_HSTS_SECONDS setting. ...
?: (security.W008) Your SECURE_SSL_REDIRECT setting is not set to True. ...
?: (security.W009) Your SECRET_KEY has less than 50 characters, less than 5 unique
characters, or it's prefixed with 'django-insecure-' ...

System check identified 3 issues (0 silenced).

三条分别对应:HSTS 没开(全站只走 HTTPS 时才建议开,开错很难撤回,官方文档特意提醒)、没强制 HTTPS 跳转、SECRET_KEY 太短或还是 startproject 那个。

如果站点是纯内网 HTTP(比如只在 VPC 里跑),W004 / W008 可以留着不消,但要清楚自己在干什么;W009 无论如何都要消。

部署前的安全检查

配置分层

三份 settings 的目录写法

startproject 只给一个 settings.py,上线前建议拆成包:

1
2
3
4
5
proj/settings/
├── __init__.py # 留空
├── base.py # 公共:INSTALLED_APPS、MIDDLEWARE、TEMPLATES、LOGGING、env 辅助函数
├── dev.py # DEBUG=True、ALLOWED_HOSTS=['*']、跑本地数据库
└── prod.py # DEBUG=False、ManifestStaticFilesStorage、Cookie 只走 HTTPS
proj/settings/dev.py
1
2
3
4
5
from proj.settings.base import *  # noqa: F403
from proj.settings.base import env_bool

DEBUG = env_bool("DJANGO_DEBUG", True)
ALLOWED_HOSTS = ["*"]
proj/settings/prod.py
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
from proj.settings.base import *  # noqa: F403
from proj.settings.base import env_bool, env_list

DEBUG = False
ALLOWED_HOSTS = env_list("DJANGO_ALLOWED_HOSTS", ["example.com"])

if env_bool("DJANGO_MANIFEST_STATIC", True):
STORAGES = {
"default": {"BACKEND": "django.core.files.storage.FileSystemStorage"},
"staticfiles": {
"BACKEND": "django.contrib.staticfiles.storage.ManifestStaticFilesStorage"},
}

SESSION_COOKIE_SECURE = env_bool("DJANGO_SESSION_COOKIE_SECURE", True)
CSRF_COOKIE_SECURE = env_bool("DJANGO_CSRF_COOKIE_SECURE", True)

from ... import * 之后还要显式覆盖的项,必须再 from base import env_bool 把函数单独拿进来——import * 不会带下划线开头的名字,也不会带你没写 __all__ 时的辅助函数以外的东西,这点很容易写成 NameError。

选哪一份:优先级实测

三个地方都能指定 settings,优先级从高到低:

1
2
3
1. 命令行 --settings=proj.settings.dev        (单次最高)
2. 环境变量 DJANGO_SETTINGS_MODULE
3. manage.py / wsgi.py 里的 os.environ.setdefault(...) (兜底)

实测用第 1 种跑测试(第 3 种是 manage.py 里的 setdefault,所以前两种都能盖掉它):

1
2
3
$ python manage.py test --settings=proj.settings.dev -v 2
Ran 4 tests in 0.036s
OK

wsgi.py / asgi.py 里写的是 setdefault,所以 gunicorn 只要不显式给环境变量就会用生产那份:

proj/wsgi.py
1
2
3
4
5
6
7
import os

from django.core.wsgi import get_wsgi_application

os.environ.setdefault("DJANGO_SETTINGS_MODULE", "proj.settings.prod")

application = get_wsgi_application()

数据库配置里跟发布有关的几项

3.1 DATABASES 全部走环境变量,账号只用最小权限

proj/settings/base.py
1
2
3
4
5
6
7
8
9
10
11
12
DATABASES = {
"default": {
"ENGINE": "django.db.backends.mysql",
"NAME": env("DJANGO_DB_NAME", "django_note_deploy"),
"USER": env("DJANGO_DB_USER", "djdeploy"),
"PASSWORD": env("DJANGO_DB_PASSWORD", "password"), # 走环境变量,不要把明文写进代码
"HOST": env("DJANGO_DB_HOST", "127.0.0.1"),
"PORT": env("DJANGO_DB_PORT", "3306"),
"CONN_MAX_AGE": int(env("DJANGO_DB_CONN_MAX_AGE", "0")),
"OPTIONS": {"charset": "utf8mb4", "connect_timeout": 5},
}
}

建库和授权也建议在文章里就写清楚(实测在 MySQL 9.7.4 上可用):

1
2
3
4
5
CREATE DATABASE django_note_deploy
CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci;
CREATE USER 'djdeploy'@'localhost' IDENTIFIED BY 'password';
GRANT ALL PRIVILEGES ON django_note_deploy.* TO 'djdeploy'@'localhost';
FLUSH PRIVILEGES;

connect_timeout 别省:连不上时默认会一直挂着,加上之后 5 秒就抛 OperationalError,容器里排错快很多(PostgreSQL 同理,psycopg 用 OPTIONS: {"connect_timeout": 8})。

3.2 CONN_MAX_AGE:持久连接省了多少

实测 30 次会打两条 SQL 的请求:

1
2
CONN_MAX_AGE=0    30 次请求墙钟 0.049s
CONN_MAX_AGE=60 30 次请求墙钟 0.039s

同机 socket 情况下只差 10ms,看着不值一提;但生产库通常在另一个可用区,一次握手 3~10ms 时,这 20% 会变成肉眼可见的尾延迟。代价是连接会占着 MySQL 的 max_connections(实测本机默认 151),所以要按 worker 数算账:

1
2
占用连接数 ≈ worker 数 × 每 worker 线程数(sync worker 就是 1)
3 个 gunicorn worker + CONN_MAX_AGE=60 → 常驻 3 条连接

另外实测到一个细节:connection.close() 之前 SHOW PROCESSLIST 里那条连接还在,close() 之后才归零——CONN_MAX_AGE 的「过期」是 Django 在请求结束时判断的,不是数据库那边踢掉。

3.3 时区:Django 存 UTC,MySQL 的 NOW() 存本地时间

1
2
3
timezone.now()       = 2026-11-04 21:51:45.654201+00:00
timezone.localtime() = 2026-11-05 05:51:45.654201+08:00
MySQL NOW()/会话时区 = (datetime(2026, 11, 5, 5, 51, 45), 'SYSTEM')

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
2
3
4
5
CREATE TABLE `core_deployitem` (
`id` bigint AUTO_INCREMENT NOT NULL PRIMARY KEY,
`name` varchar(64) NOT NULL UNIQUE,
`hits` integer UNSIGNED NOT NULL CHECK (`hits` >= 0),
`created_at` datetime(6) NOT NULL);

绕过 ORM 直接写负数会被数据库拦下(实测):

1
2
INSERT ... VALUES ('negative', -1, NOW(6))
→ DataError (1264, "Out of range value for column 'hits' at row 1")

也就是说 PositiveIntegerField 的校验其实有三层:表单 full_clean()、ORM 字段、数据库列。生产上第三层最可靠,别关掉。

迁移的执行顺序

发布时先迁移还是先发代码,取决于改动类型。实测这几条命令的行为:

1
2
3
4
5
6
7
8
9
10
11
$ python manage.py migrate --settings=proj.settings.prod
Running migrations:
No migrations to apply. # 已经打过的迁移是幂等的,重复执行不报错

$ python manage.py showmigrations --plan | tail -2
[X] core.0001_initial
[X] sessions.0001_initial

$ python manage.py showmigrations core
core
[X] 0001_initial

安全顺序(零停机):

  1. 加列先用「可空」或「有默认值」,别在同一次发布里 NOT NULL 直接加。

  2. 先发代码(旧代码不读新列),再 migrate。

  3. 删列拆成两次发布:第一次代码不再用它,第二次 RemoveField。

  4. 数据迁移写进 RunPython,配 atomic=True,并在 --plan 里确认它排在结构迁移之后。

  5. 出问题要回退时优先「往前修」,别在生产 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
2
3
$ python manage.py collectstatic --noinput --settings=proj.settings.prod
128 static files copied to '/mnt/e/Desktop/Test/django-deploy-probe/staticfiles',
128 post-processed.

prod 用的是 ManifestStaticFilesStorage,所以除了原文件还会生成带哈希的副本和一张清单:

1
2
3
4
5
staticfiles/
├── admin/ # Django 自带的后台静态资源
├── site.css # 原文件也在(不影响访问)
├── site.b9bcd8def6c5.css # 模板实际引用的哈希名
└── staticfiles.json # 10441 字节,名字到哈希的映射表

哈希名由内容算出,内容不变文件名不变,所以可以放心给静态资源设很长的缓存头。两个注意点:

  • 改了 CSS/JS 必须重新 collectstatic,否则模板引用的哈希名和清单对不上。
  • ManifestStaticFilesStorage 会在收集时校验模板里引用的每个资源是否存在,引用不到就报错中断——这是好事,但第一次上生产时容易把构建卡住。

4.3 由 Nginx 直接服务,别让 Django 管

STATIC_URL 对应的路径交给 Nginx,Django 只处理动态请求:

1
2
3
4
5
location /static/ {
alias /srv/django/static/;
expires 30d;
add_header Cache-Control "public, immutable";
}

实测经 Nginx 取静态文件(后端是两个 gunicorn 实例):

1
/static/site.css -> 200  165B  0.0024s

更能说明问题的是这一条:把两个后端全 kill 掉之后,/static/site.css 仍然 200,而 / 返回 502。

1
2
3
4
两个 upstream 都停 -> / 502
error.log: no live upstreams while connecting to upstream

/static/site.css -> 200(静态与后端无关)

也就是说静态资源的可用性不该依赖应用进程,这正是把它交给 Web 服务器(或 CDN)的理由。

日志:写到哪、怎么转、谁来收

一份能直接抄的 LOGGING

proj/settings/base.py
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
LOG_DIR = env("DJANGO_LOG_DIR", str(BASE_DIR / "logs"))
os.makedirs(LOG_DIR, exist_ok=True)

LOGGING = {
"version": 1,
"disable_existing_loggers": False,
"formatters": {
"verbose": {"format": "{levelname} {asctime} {name} {message}", "style": "{"},
},
"handlers": {
"console": {"class": "logging.StreamHandler", "formatter": "verbose"},
"file": {
"class": "logging.handlers.RotatingFileHandler",
"filename": os.path.join(LOG_DIR, "deploy.log"),
"maxBytes": 2 * 1024 * 1024,
"backupCount": 3,
"formatter": "verbose",
"encoding": "utf-8",
},
},
"root": {"handlers": ["console", "file"], "level": env("DJANGO_LOG_LEVEL", "INFO")},
"loggers": {
"django.request": {"handlers": ["console", "file"], "level": "WARNING",
"propagate": False},
"core": {"handlers": ["console", "file"], "level": "DEBUG", "propagate": False},
},
}

django.request 这个 logger 是专门记 4xx/5xx 的,级别设 WARNING 就够(404 也会记),生产上想少刷屏可以调 ERROR。

轮转实测

往 core 这个 logger 灌 15000 条约 170 字节的日志,看 RotatingFileHandler 的行为:

1
2
deploy.log      1022944 字节
deploy.log.1 2097056 字节

maxBytes=2MB 生效:写满 2MB 就整份改名成 .log.1,新日志从 .log 重新开始,backupCount=3 决定最多留几份。

生产上更推荐只写 stdout/stderr,让 systemd 收(原因:文件轮转和权限在多进程下容易踩坑, journald 已经帮你做了轮转和查询)。gunicorn 侧只要这样:

deploy/gunicorn.conf.py
1
2
3
accesslog = "-"      # "-" 表示 stdout
errorlog = "-" # "-" 表示 stderr
loglevel = "info"

实测 journald 里能直接看到访问行:

1
2
$ journalctl -u djdeploy --no-pager -n 6
Nov 05 05:54:49 gunicorn[4619]: 127.0.0.1 - - [05/Nov/2026:05:54:49 +0800] "GET / HTTP/1.1" 200 346

出错时日志在哪看

  • 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
2
3
4
5
6
7
$ gunicorn proj.wsgi:application --bind 127.0.0.1:8001 --workers 3
[INFO] Starting gunicorn 26.2.0
[INFO] Listening at: http://127.0.0.1:8001 (4206)
[INFO] Booting worker with pid: 4208
[INFO] Booting worker with pid: 4209
[INFO] Booting worker with pid: 4210
[INFO] Control socket listening at /run/user/0/gunicorn.ctl

并发能力直接测:/slow/ 每次固定 sleep(0.2),串行 10 次要 2.0s。

1
2
3 个 sync worker   10 个并发请求墙钟 0.86s(另一轮 systemd 起的 3 worker 是 0.95s)
1 个 sync worker 10 个并发请求墙钟 2.11s(完全串行)

worker 分布可以用 access log 的 pid 字段看(--access-logformat '%(p)s %(t)s "%(r)s" %(s)s'),实测 10 个请求落在三个 worker 上是 3/5/3,不是严格轮转——sync worker 是「谁空谁拿」,别指望均匀。

优雅重载(改代码后不中断服务):

1
2
3
4
5
$ kill -HUP 4206          # 只杀主进程
[INFO] Worker exiting (pid: 4208)
[INFO] Worker exiting (pid: 4209)
[INFO] Worker exiting (pid: 4210)
[INFO] Booting worker with pid: 4258

主进程 4206 一直活着(kill -0 验证),监听不断,只换 worker。ExecReload=/bin/kill -s HUP $MAINPID 就是给 systemctl reload 用的。

内存回收靠 max_requests(防内存泄漏兜底):

1
2
max_requests = 1000
max_requests_jitter = 100 # 加抖动,避免所有 worker 同时重启

systemd 托管实测

unit 文件(Type=notify 是 gunicorn 支持的,systemd 会等它真正就绪才算启动成功):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
[Unit]
Description=Django deploy probe (gunicorn)
After=network.target mysql.service

[Service]
Type=notify
User=www-data
Group=www-data
WorkingDirectory=/srv/django/probe
Environment="DJANGO_SETTINGS_MODULE=proj.settings.prod"
EnvironmentFile=/etc/djdeploy/env
ExecStart=/srv/django/venv/bin/gunicorn proj.wsgi:application -c deploy/gunicorn.conf.py
ExecReload=/bin/kill -s HUP $MAINPID
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

实测行为:

1
2
3
4
5
systemctl start djdeploy        -> active,Main PID: 4618 (gunicorn)
systemctl status -> Status: "Gunicorn arbiter booted"
curl :8000/ -> 200
kill -9 其中一个 worker -> 服务仍 active,2 秒后进程数回到 4,日志里出现新的 Booting worker
systemctl enable djdeploy -> Created symlink .../multi-user.target.wants/djdeploy.service

EnvironmentFile 里放密钥(文件权限 600),别把 SECRET_KEY 写进 unit 文件——unit 是会被 systemctl show 全文打印出来的。

Uvicorn 实测

1
2
3
4
5
$ uvicorn proj.asgi:application --host 127.0.0.1 --port 8100 --workers 2
INFO: Uvicorn running on http://127.0.0.1:8100 (Press CTRL+C to quit)
INFO: Started parent process [4799]
INFO: Started server process [4802]
INFO: Started server process [4803]

同样打 10 个并发 /slow/:

1
2
3
4
uvicorn 2 worker   墙钟 0.25s
uvicorn 1 worker 墙钟 0.29s # 和 2 worker 几乎一样
gunicorn 3 sync 墙钟 0.86s
gunicorn 1 sync 墙钟 2.11s

单 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
2
8001 收到: 6 次
8002 收到: 6 次 # 默认轮询,非常均匀

关键的一条:gunicorn 默认就相信 X-Forwarded-Proto。实测在没配 Django 的 SECURE_PROXY_SSL_HEADER 的实例上,直接伪造这个头:

1
2
3
4
直连后端,不带伪头      -> X-Request-Secure: False
直连后端,伪造 https -> X-Request-Secure: True # gunicorn 已经替你转换过了
配了 SECURE_PROXY_SSL_HEADER,带伪头 -> X-Request-Secure: True
配了 SECURE_PROXY_SSL_HEADER,不带 -> X-Request-Secure: False

SECURE_SSL_REDIRECT=1 时还能看到跳转:

1
2
3
4
HTTP/1.1 301 Moved Permanently
Server: gunicorn
带上 X-Forwarded-Proto: https 后 -> 200(不再跳)

这条的实际含义是:信任边界在 WSGI 服务器,不在 Django。所以两件事必须做对:

  1. gunicorn/uvicorn 只监听 127.0.0.1(或 unix socket),不能让外网直连,否则任何人都能伪造 X-Forwarded-Proto 绕过 HTTPS 跳转、污染 cookie 的 Secure 判定。
  2. 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
2
3
4
core/tests.py            # 小项目
core/tests/__init__.py # 大项目拆包
core/tests/test_views.py
core/tests/test_models.py

测试用例目录组织

跑法与实测耗时

1
2
3
4
5
6
7
8
9
10
$ python manage.py test                              # 全部
$ python manage.py test core # 指定应用
$ python manage.py test core.tests # 指定模块
$ python manage.py test core.tests.DeployItemTests # 指定类
$ python manage.py test core.tests.DeployItemTests.test_str # 指定方法
$ python manage.py test -v 2 # 打印每个用例名
$ python manage.py test --keepdb # 保留测试库,跳过重复迁移
$ python manage.py test --parallel # 多进程并行
$ python manage.py test --failfast # 第一个失败就停
$ python manage.py test --tag slow # 按标签筛

实测数字(4 个用例,MySQL):

1
2
3
manage.py test -v 2                     -> Ran 4 tests in 0.036s
整条命令的墙钟(含建库 + 跑 19 个迁移) -> real 3.497s
--keepdb 第二次 -> 不再输出 Applying ...,直接跑用例

也就是说用例本身 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
2
Got an error creating the test database:
(1044, "Access denied for user 'djdeploy'@'localhost' to database 'test_django_note_deploy'")

原因是 unittest 会另建一个 test_<NAME> 库,而 GRANT ... ON django_note_deploy.* 不包含它(_ 在 MySQL 授权里是单字符通配,必须转义)。解法是显式加一条:

1
2
GRANT ALL PRIVILEGES ON `test\_django\_note\_deploy`.* TO 'djdeploy'@'localhost';
FLUSH PRIVILEGES;

实测加上之后 4 个用例全绿,跑完 Django 会自己 Destroying test database。CI 里更省事的做法是给流水线单独一个能建库的账号,和生产账号分开。

一份能抄的用例文件

core/tests.py
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
from django.test import SimpleTestCase, TestCase, override_settings

from core.models import DeployItem


class CoreSmokeTests(SimpleTestCase):
"""不碰数据库的快测:跑得快,但里面别建数据。"""

def test_home(self):
resp = self.client.get("/")
self.assertEqual(resp.status_code, 200)
self.assertContains(resp, "deploy probe is alive")


class DeployItemTests(TestCase):
"""每个用例包在一个事务里,最后自动回滚。"""

@classmethod
def setUpTestData(cls):
cls.item = DeployItem.objects.create(name="case-a", hits=1)

def test_str(self):
self.assertEqual(str(self.item), "case-a(1)")

@override_settings(DEBUG=True)
def test_override_settings_decorator(self):
from django.conf import settings

self.assertTrue(settings.DEBUG)

def test_unique_name(self):
from django.db import IntegrityError, transaction


# 断言「会抛异常」的那段代码要包在 atomic 里,否则后续查询会被 MySQL 挡住
with self.assertRaises(IntegrityError), transaction.atomic():
DeployItem.objects.create(name="case-a")

三个容易写错的地方:

  • setUpTestData 是 @classmethod,它建的数据在类内所有用例间共享,且只回滚不重建。
  • assertRaises(IntegrityError) 不加 transaction.atomic() 时,MySQL 的事务已被标记为无效,后面任何查询都会报错。
  • SimpleTestCase 里一旦访问数据库会直接抛异常,这是设计如此,不是 bug。

发布清单

  1. 冻结依赖并核对版本:pip freeze > requirements.txt,装之前先看新包会不会把 Django 降级(实测 django-prometheus 在未装 Django 的环境里会顺手拉 Django 6.0.10)。
  2. 跑测试:python manage.py test --settings=proj.settings.dev。
  3. 生产配置体检:python manage.py check --settings=proj.settings.prod --deploy,把 W009 这类必须消的消掉。
  4. 备份数据库(mysqldump --single-transaction),这一步别省。
  5. 收集静态资源:python manage.py collectstatic --noinput --settings=proj.settings.prod。
  6. 发布代码(软链切换或蓝绿),保留上一版本目录便于回滚。
  7. 执行迁移:python manage.py migrate --settings=proj.settings.prod。
  8. 重载应用进程:systemctl restart djdeploy,或 kill -HUP 主进程做优雅重启。
  9. 冒烟验证:curl -i http://127.0.0.1:8090/、/static/site.css、一个会写库的接口,再看 journalctl -u djdeploy 有没有 500。
  10. 观察 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(),导致同一个测试类里后续用例连锁失败。

参考