Django 5.2部署与HTTPS配置

准备一个已验证的项目

本文按Ubuntu 24.04、Python 3.12和Django 5.2系列部署已有WSGI项目。requirements.txt应锁定已验证的Django维护版、Gunicorn及数据库驱动。示例模块名config,实际项目若是mysite,应把config.wsgi替换成mysite.wsgi。需要ASGI、WebSocket的项目不能照抄WSGI启动方式。

先准备独立数据库及账号、一个普通运行用户webapp,以及归它管理的/srv/django-app目录。代码、管理命令和pip都用webapp操作,不能用root运行网站。域名的Nginx HTTPS虚拟主机应已可用,部署期间先限制为管理员可访问,完成数据库迁移和权限验收后再开放。证书可参考Certbot配置教程。

一、使用独立虚拟环境

sudo apt update
sudo apt install python3.12-venv

管理员完成软件包安装后,以webapp进入自己的项目目录,再执行:

cd /srv/django-app
python3.12 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python -m pip check

缺少系统开发库时按具体驱动报错补齐,不向系统Python强行pip安装。确认manage.py与config/wsgi.py实际存在。保留依赖文件和源码版本,后续更新可以定位差异。

二、让正式配置读取独立秘密

编辑本项目settings中的对应项,不要整份覆盖其他配置。示例要求Nginx是唯一入口,并覆盖传给应用的协议头:

import os

SECRET_KEY = os.environ["DJANGO_SECRET_KEY"]
DEBUG = False
ALLOWED_HOSTS = ["app.example.com"]
CSRF_TRUSTED_ORIGINS = ["https://app.example.com"]

STATIC_URL = "/static/"
STATIC_ROOT = BASE_DIR / "staticfiles"
MEDIA_ROOT = BASE_DIR / "media"

SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https")
SESSION_COOKIE_SECURE = True
CSRF_COOKIE_SECURE = True

数据库按项目实际驱动配置,从环境读取独立账号密码。将DJANGO_SECRET_KEY和项目所需变量写入app.env,使用普通KEY='值'格式,由webapp拥有并设为600,禁止提交代码仓库。首次生成随机密钥;搬迁已有站点保留原密钥。不要把ALLOWED_HOSTS设成*解决错误。

在webapp的Shell中加载自己维护的环境文件,检查生产配置,再初始化新库并收集静态文件:

set -a
. ./app.env
set +a
.venv/bin/python manage.py check --deploy
.venv/bin/python manage.py migrate --plan
.venv/bin/python manage.py migrate
.venv/bin/python manage.py collectstatic --noinput

已有数据库先备份并审核迁移。staticfiles只放可公开静态资源,media是用户上传数据,不能混用;私密附件必须由应用鉴权,不能直接用静态目录公开。逐项处理check --deploy结果,不能一概忽略。

三、建立独立systemd服务

管理员创建/etc/systemd/system/django-app.service:

[Unit]
Description=Django App
After=network.target

[Service]
User=webapp
Group=webapp
WorkingDirectory=/srv/django-app
EnvironmentFile=/srv/django-app/app.env
ExecStart=/srv/django-app/.venv/bin/gunicorn --bind 127.0.0.1:8001 config.wsgi:application
Restart=on-failure
RestartSec=5
UMask=0027

[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable --now django-app
sudo systemctl status django-app --no-pager
sudo journalctl -u django-app -n 50 --no-pager

先核对8001未被占用。应用仅监听回环地址,不向公网开放此端口。Nginx所在用户需要读取staticfiles并穿过父目录,但不能读取app.env。

四、配置代理并验收真实功能

在该站点HTTPS的server块合并:

location /static/ {
    alias /srv/django-app/staticfiles/;
}
location / {
    proxy_pass http://127.0.0.1:8001;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $remote_addr;
}

nginx -t通过后重载,HTTP入口应跳转HTTPS。代理头信任只适用于这里的单一可信入口,后端不能被其他网络直接访问。验证首页、后台静态样式、登录和一个受控写入;上传功能还要检查读取权限及持久保存。

发生502先查Gunicorn服务与端口,样式丢失先查collectstatic输出及Nginx读取权限。不要用runserver长期提供公网服务,也不要把DEBUG重新打开来向访客展示错误。更新失败时回退本项目代码与环境,数据库回退另按数据变化处理。

没有webapp用户时,可由管理员先创建这个专用普通账号,再只把本项目目录交给它;已有同名用户先核对用途。不要迁入开发电脑的虚拟环境,服务器上重新安装锁定依赖,避免本机与Linux二进制不兼容。

收集完成的公开静态文件通常可设为文件644、目录755供Nginx读取。不要把这套权限递归套到整个项目,环境文件仍保持600。若需要创建后台管理员,使用manage.py createsuperuser交互输入,随后验证普通账号不能进入管理后台。