django-unfold 生产环境部署指南：静态文件、请求链路与慢查询的逐项排查

django-unfold 生产环境部署指南：静态文件、请求链路与慢查询的逐项排查

【免费下载链接】QuickRecorderA lightweight screen recorder based on ScreenCapture Kit for macOS / 基于 ScreenCapture Kit 的轻量化多功能 macOS 录屏工具项目地址: https://gitcode.com/GitHub_Trending/qu/QuickRecorder

django-unfold 是面向 Django 的现代管理框架，用 Tailwind CSS 构建的界面替代默认后台，适合需要快速交付且便于维护的内部管理系统。本文不堆配置模板，而是按真实请求链路组织：先验证是否有问题，再决定改什么，最后用什么证据确认。目标是把上线首周常见的三类问题一次解决：静态资源缺失、管理列表页变慢、安全项被漏掉。

一、30 秒结论：先做哪三件事

适用对象：已有 Django 项目、已引入 django-unfold、需要迁到生产服务器的人。

优先做三件事：

1. 用 collectstatic 生成静态文件，交给 Nginx 直接返回；
2. 应用用 Gunicorn 启动并放在 Nginx 之后，不要使用 runserver；
3. 列表页跑通后，给常用过滤字段补数据库索引。

能避免：CSS 缺失导致的白屏或 404、查询未优化造成列表页不可用、DEBUG 未关导致暴露面扩大。

二、上线前诊断：逐项判断有没有问题

诊断不需要新工具，有浏览器和命令行即可。

1. 静态资源

• 检查：打开管理页看网络请求，.css 或 .js 出现 404 就是有问题。
• 标准：静态文件应在服务器生成，由 Nginx 直接返回，Django 只处理动态请求。
• 动作：确认 STATIC_ROOT 目录，执行python manage.py collectstatic --noinput，核对输出列表包含 unfold 相关资源。

2. 应用服务

• 检查：看进程列表，runserver 还在跑或 Gunicorn 只有 1 个 worker 都有问题。
• 标准：worker 数约等于 CPU 核数，每 worker 配 2 到 4 个线程；进程要在登出后存活（systemd 或进程管理器托管）。

3. 数据库

• 检查：用 Django Debug Toolbar 看列表页 SQL，逐行查一次（N+1）时数据一多必然变慢。
• 标准：列表、过滤、搜索都是高频查询，确认对应字段建了数据库索引。

4. 安全

• 检查：跑python manage.py check --deploy，它会逐条提示常见的生产风险。
• 标准：不必全绿，但 DEBUG 与 HTTPS 跳转相关项必须处理。

三、请求链路优化：静态、代理与应用服务器如何分工

以一次访问管理列表页的请求为例，分工是：

1. 浏览器到 Nginx：/static/ 请求直接命中 staticfiles 目录，不进入 Python 进程；这里设置一年缓存是安全的，因为 collectstatic 的 Manifest 存储会生成带内容哈希的文件名。
2. Nginx 到 Gunicorn：其余请求代理到 127.0.0.1:8000。Host 与转发协议头必须传，否则 HTTPS 判断和 CSRF 会出错。
3. Gunicorn 到 Django：worker 数按 CPU 核数，gthread 模式加少量线程即可。请求慢时先查数据库。

Nginx 关键只有两个 location：

location /static/ { alias /path/to/staticfiles/; expires 1y; add_header Cache-Control "public, immutable"; } location / { proxy_pass http://127.0.0.1:8000; proxy_set_header Host $host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; }

Django 侧在收集静态文件前配置 Manifest 存储（配置名以你的 Django 版本为准）：

STATIC_ROOT = BASE_DIR / "staticfiles" STATICFILES_STORAGE = "django.contrib.staticfiles.storage.ManifestStaticFilesStorage"

验证：重启后访问首页，确认 CSS 请求出现 304 或命中缓存，/static/ 响应头带有长缓存指令。

四、数据访问优化：从列表、过滤与搜索开始

管理后台是 Django 项目里查询最集中的地方，这一步是 Django Admin 性能优化的主战场，顺序跟着用户动作走：

• 列表页：列表里展示的关联字段默认逐行查询。在 ModelAdmin 的 get_queryset 中对相关字段加select_related()，多对多或一对多用 prefetch。
• 过滤：条件落在 WHERE 子句里，常用字段有单列索引即可；若总是两个字段组合过滤，考虑复合索引。
• 搜索：走的是 LIKE，大表上全表扫描慢，优先收窄搜索列。
• Django 缓存是补充：把访问频繁、变更少的数据（如站点配置）缓存起来，不能替代查询优化。

确认方法：同一页面在小数据集下跑一遍，记录 SQL 条数与耗时，再对照生产数据规模判断。单请求超过 1 秒就先处理。不要给每个字段都加索引，索引有写入成本，加给你能证明慢的字段。

五、安全与回滚：最小配置集与判断标准

最小安全项

不要一次加满，先保证这几项落地：

DEBUG = False ALLOWED_HOSTS = ["yourdomain.com"] SECURE_SSL_REDIRECT = True SESSION_COOKIE_SECURE = True CSRF_COOKIE_SECURE = True SECURE_HSTS_SECONDS = 31536000

验证：用 http 访问站点，确认 301 到 https；查看响应头里是否有 HSTS 字段。

日志与会话

LOGGING 配一个文件 handler，把项目和 django 的日志器输出到同一目录（如 /var/log/django/）。目标是慢请求或报错发生时，5 分钟内能定位到时间窗口。多实例部署时把会话切到缓存后端，保证登录状态一致。

回滚判断

满足任一条，先回滚再查原因：

• 上线后静态资源 404 成批出现（通常是漏跑 collectstatic）；
• 列表页耗时明显变差，且能从 SQL 里认出新增代码；
• 报错日志量上涨，或健康检查接口不再返回 200。

回滚动作本身应该是一条命令（切版本号或重启旧进程），而不是现场排查。

六、验收清单：检查项、预期结果与异常处理

最后强调一句：清单是一次性验收，不替代长期监控。上线后定期看两个数：慢请求数量与列表页耗时，用真实数据调优。

【免费下载链接】QuickRecorderA lightweight screen recorder based on ScreenCapture Kit for macOS / 基于 ScreenCapture Kit 的轻量化多功能 macOS 录屏工具项目地址: https://gitcode.com/GitHub_Trending/qu/QuickRecorder