在美国服务器上线Django 5.2 LTS应用,怎样配置HTTPS与安全设置?
美国服务器上的 Django 5.2 LTS 应用,生产环境通常采用“公网 80/443 端口 → Nginx → Gunicorn → Django → PostgreSQL”的链路。HTTPS 证书由 Nginx 终止,Django 通过可信的反向代理请求头判断原始请求是否使用 HTTPS,再配合安全 Cookie、主机校验、CSRF 来源校验、HSTS、进程隔离、日志和备份,才能形成完整的上线配置。

下面以 Ubuntu 24.04 LTS、Django 5.2、Nginx、Gunicorn、PostgreSQL 和域名 app.example.com 为例。服务器假设拥有公网 IPv4 地址,SSH 用户具备 sudo 权限,应用代码已经准备好,项目包名以 config 为例,生产目录为 /srv/myapp。如果使用托管数据库或其他 Linux 发行版,数据库和系统服务部分需要按实际环境调整。
一、准备条件与部署边界
1. 确认服务器、域名和应用条件
部署前先确认以下事项:
| 项目 | 示例值 | 验证方式 |
|---|---|---|
| 操作系统 | Ubuntu 24.04 LTS | cat /etc/os-release |
| Python | 3.12 | python3 --version |
| 应用框架 | Django 5.2.x | 虚拟环境中执行 python -m django --version |
| Web 入口 | Nginx 监听 80、443 | sudo ss -lntp |
| 应用进程 | Gunicorn Unix Socket | sudo ss -lx |
| 数据库 | PostgreSQL 本机或托管实例 | psql --version |
| 域名 | app.example.com | dig +short app.example.com |
| HTTPS 证书 | ACME 证书 | sudo certbot certificates |
Django 5.2 LTS 仍然需要持续更新 Python 依赖、操作系统和数据库。LTS 主要代表该 Django 版本拥有较长的安全维护周期,并不表示服务器可以停止打补丁。
美国服务器的地域不会改变 Django 的 HTTPS 配置方式,但会影响以下运维事项:
- DNS 的 A 记录或 AAAA 记录必须指向实际服务器。
- 如果域名存在 AAAA 记录,服务器和 Nginx 也必须正确处理 IPv6;否则部分客户端可能优先访问 IPv6 而连接失败。
- 证书续期、日志和备份时间建议统一使用 UTC,减少跨时区排查困难。
- 备份是否存放在美国境内、是否需要跨区域复制,应按照业务的数据合规和灾备要求确认。
- 云平台安全组、A5IDC 控制台防火墙和服务器内部 UFW 可能同时存在,三个层级都要放行 80、443,并只对管理来源开放 SSH。
2. 检查 DNS、时间和网络端口
先在本地或服务器上确认域名解析:
dig +short A app.example.com
dig +short AAAA app.example.com
预期至少能看到服务器的公网 IPv4 地址。如果 AAAA 返回了地址,却没有配置 IPv6,可以先移除错误的 AAAA 记录,或者为 Nginx 增加 IPv6 监听并确认上游网络可达。
在服务器上检查系统时间:
timedatectl
预期 System clock synchronized: yes。如果时间偏差明显,证书校验、日志排序和数据库任务都可能受到影响。
检查端口占用:
sudo ss -lntp
sudo ss -lx
首次部署时,80、443 可能还没有监听;但不应有未知进程占用 80 或 443。若发现其他服务占用端口,先确认它的用途,不要直接杀进程。
3. 安装必要软件
以下命令适用于 Ubuntu 24.04。执行系统升级可能触发服务重启,生产服务器应先确认维护窗口或创建云主机快照。
sudo apt update
sudo apt install -y \
python3 \
python3-venv \
python3-dev \
build-essential \
libpq-dev \
postgresql \
postgresql-contrib \
nginx \
certbot \
curl \
openssl \
rsync
确认关键版本:
python3 --version
nginx -v
psql --version
certbot --version
如果应用使用的是 MySQL、MariaDB 或外部托管 PostgreSQL,不要为了套用示例而额外安装本机数据库。只安装应用实际需要的客户端和编译依赖。
4. 创建应用用户和目录
生产进程不建议以 root 运行。创建专用用户和目录:
sudo adduser --system --group --home /srv/myapp deploy
sudo install -d -o deploy -g deploy -m 0755 /srv/myapp
sudo install -d -o deploy -g deploy -m 0755 /srv/myapp/releases
sudo install -d -o deploy -g www-data -m 0750 /srv/myapp/media
sudo install -d -o deploy -g www-data -m 0750 /srv/myapp/staticfiles
sudo install -d -o root -g deploy -m 0750 /etc/myapp
如果服务器上已经存在 /srv/myapp,不要直接执行递归 chown 覆盖整个目录。应先确认其中是否包含上传文件、备份或其他应用,再分别调整代码、媒体和配置目录的权限。
5. 配置防火墙时避免锁死 SSH
如果 SSH 使用默认端口,并且云平台安全组已经允许当前管理来源,可以先放行:
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw status verbose
确认 SSH 规则正确后再启用 UFW:
sudo ufw enable
sudo ufw status numbered
ufw enable 会修改主机防火墙规则,远程操作时存在中断连接风险。若 SSH 使用非标准端口,应先放行实际端口;如果有带外控制台,建议优先通过控制台完成防火墙变更。
PostgreSQL 的 5432 端口不应向公网开放。检查监听地址:
sudo ss -lntp | grep ':5432'
本机数据库通常应只监听 127.0.0.1 或 Unix Socket。若使用托管数据库,只允许服务器出口 IP 访问数据库端口,并启用数据库服务商提供的 TLS 连接选项。

二、部署 Django 应用和数据库
1. 准备代码发布目录和虚拟环境
推荐用发布目录和 current 软链接管理版本,便于回滚。以下命令假设代码位于服务器上的 /tmp/myapp-src,实际可以替换为 Git、CI/CD 或文件传输工具产生的目录。
export RELEASE="$(date -u +%Y%m%d%H%M%S)"
sudo install -d -o deploy -g deploy -m 0755 "/srv/myapp/releases/$RELEASE"
sudo rsync -a --delete /tmp/myapp-src/ "/srv/myapp/releases/$RELEASE/"
sudo ln -sfnT "/srv/myapp/releases/$RELEASE" /srv/myapp/current
sudo chown -R deploy:deploy "/srv/myapp/releases/$RELEASE"
rsync --delete 会删除目标发布目录中源目录没有的文件,只能用于新建或确认无重要内容的发布目录,不能直接对包含用户上传文件的目录执行。
创建 Python 虚拟环境:
sudo -u deploy python3 -m venv /srv/myapp/venv
sudo -u deploy /srv/myapp/venv/bin/python -m pip install --upgrade pip
sudo -u deploy /srv/myapp/venv/bin/pip install -r /srv/myapp/current/requirements.txt
sudo -u deploy /srv/myapp/venv/bin/pip install gunicorn
生产依赖应在 requirements.txt 中锁定合理版本,例如 Django 5.2 系列、数据库驱动和项目实际需要的包。不要在生产环境无记录地执行大范围 pip install --upgrade,否则可能引入未验证的依赖变化。
验证 Django 版本:
sudo -u deploy /srv/myapp/venv/bin/python \
/srv/myapp/current/manage.py --version
预期输出为 5.2.x。如果输出不是预期版本,先检查虚拟环境和 requirements.txt,不要继续迁移数据库。
2. 创建 PostgreSQL 数据库
如果使用本机 PostgreSQL,可以创建专用数据库用户和数据库:
sudo -u postgres createuser --pwprompt myapp
sudo -u postgres createdb --owner=myapp myapp
createuser --pwprompt 会交互式输入数据库密码,密码不会直接出现在命令行历史中。应用只使用 myapp 数据库用户,不要让 Django 使用 PostgreSQL 的超级用户。
如果数据库已经存在,应先确认:
- 数据库名称、用户名和字符集;
- 应用服务器到数据库的网络路径;
- 数据库用户是否具备迁移所需权限;
- 托管数据库是否要求
sslmode=require或证书校验; - 是否已经有可恢复的备份。
3. 保存生产环境变量
先生成一段随机密钥:
openssl rand -hex 48
复制输出结果,使用 sudoedit 创建环境文件:
sudoedit /etc/myapp/myapp.env
示例内容如下,域名、数据库密码和密钥必须替换为实际值:
DJANGO_SECRET_KEY=请替换为刚才生成的随机字符串
DJANGO_DEBUG=false
DJANGO_ALLOWED_HOSTS=app.example.com
DJANGO_CSRF_TRUSTED_ORIGINS=https://app.example.com
DJANGO_SECURE_SSL_REDIRECT=true
DJANGO_SECURE_HSTS_SECONDS=300
DB_NAME=myapp
DB_USER=myapp
DB_PASSWORD=请替换为数据库密码
DB_HOST=127.0.0.1
DB_PORT=5432
DB_SSLMODE=prefer
设置权限:
sudo chown root:deploy /etc/myapp/myapp.env
sudo chmod 0640 /etc/myapp/myapp.env
环境文件中包含数据库密码和 Django 密钥,不应提交到 Git,也不应放在 /srv/myapp/current 代码目录中。若数据库密码包含特殊字符,建议通过编辑器写入,不要直接拼接进 Shell 命令。
4. 配置 Django 生产安全项
在生产 settings 文件中加入与项目结构相符的配置。下面是一个不依赖额外配置库的示例:
import os
from pathlib import Path
BASE_DIR = Path(__file__).resolve().parent.parent
def env_bool(name, default=False):
return os.getenv(name, str(default)).lower() in {"1", "true", "yes", "on"}
def env_list(name):
value = os.getenv(name, "")
return [item.strip() for item in value.split(",") if item.strip()]
SECRET_KEY = os.environ["DJANGO_SECRET_KEY"]
DEBUG = env_bool("DJANGO_DEBUG", False)
ALLOWED_HOSTS = env_list("DJANGO_ALLOWED_HOSTS")
CSRF_TRUSTED_ORIGINS = env_list("DJANGO_CSRF_TRUSTED_ORIGINS")
INSTALLED_APPS = [
# 项目原有应用
]
MIDDLEWARE = [
"django.middleware.security.SecurityMiddleware",
# 项目原有中间件
]
SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https")
SECURE_SSL_REDIRECT = env_bool("DJANGO_SECURE_SSL_REDIRECT", True)
SESSION_COOKIE_SECURE = True
CSRF_COOKIE_SECURE = True
SESSION_COOKIE_HTTPONLY = True
SESSION_COOKIE_SAMESITE = "Lax"
CSRF_COOKIE_SAMESITE = "Lax"
SECURE_HSTS_SECONDS = int(os.getenv("DJANGO_SECURE_HSTS_SECONDS", "0"))
SECURE_HSTS_INCLUDE_SUBDOMAINS = False
SECURE_HSTS_PRELOAD = False
SECURE_CONTENT_TYPE_NOSNIFF = True
X_FRAME_OPTIONS = "DENY"
SECURE_REFERRER_POLICY = "same-origin"
DATABASES = {
"default": {
"ENGINE": "django.db.backends.postgresql",
"NAME": os.environ["DB_NAME"],
"USER": os.environ["DB_USER"],
"PASSWORD": os.environ["DB_PASSWORD"],
"HOST": os.getenv("DB_HOST", "127.0.0.1"),
"PORT": os.getenv("DB_PORT", "5432"),
"OPTIONS": {
"sslmode": os.getenv("DB_SSLMODE", "prefer"),
},
}
}
STATIC_URL = "/static/"
STATIC_ROOT = "/srv/myapp/staticfiles"
MEDIA_URL = "/media/"
MEDIA_ROOT = "/srv/myapp/media"
这里有几个容易混淆的配置:
ALLOWED_HOSTS用于校验 HTTPHost,填写域名,不要填写https://app.example.com。CSRF_TRUSTED_ORIGINS需要带协议,填写https://app.example.com。SECURE_PROXY_SSL_HEADER只有在 Nginx 是可信代理、并且 Gunicorn 不直接暴露公网时才适用。SECURE_SSL_REDIRECT=True必须和 Nginx 的X-Forwarded-Proto配合,否则可能出现 HTTP/HTTPS 重定向循环。SECURE_HSTS_SECONDS初次上线可以从 300 秒开始,确认所有页面、子域名和静态资源均支持 HTTPS 后,再逐步提高到一年。不要在未检查子域名之前启用includeSubDomains,也不要直接启用 preload。X_FRAME_OPTIONS="DENY"会禁止页面被 iframe 嵌入。如果业务确实需要嵌入,应按实际来源设计,而不是直接删除安全策略。- 不要为了“提高安全性”盲目加入未经测试的 CSP。CSP 需要结合前端脚本、图片、字体和第三方服务逐项验证。
如果项目使用 django.contrib.auth 和 SecurityMiddleware,请确认相关应用、中间件和模板上下文没有被生产配置误删。执行部署检查:
sudo -iu deploy
cd /srv/myapp/current
set -a
. /etc/myapp/myapp.env
set +a
/srv/myapp/venv/bin/python manage.py check --deploy
exit
该命令可能输出具体警告。警告应根据项目实际情况处理,不要简单使用 --fail-level 或忽略输出掩盖问题。
5. 执行数据库迁移和静态文件收集
数据库迁移属于会改变数据结构的操作。正式迁移前,应先完成一次数据库备份,备份方法见后文。
先查看迁移计划:
sudo -iu deploy
cd /srv/myapp/current
set -a
. /etc/myapp/myapp.env
set +a
/srv/myapp/venv/bin/python manage.py migrate --plan
确认计划只包含预期的应用和迁移后,再执行:
/srv/myapp/venv/bin/python manage.py migrate
/srv/myapp/venv/bin/python manage.py collectstatic --noinput
exit
验证是否还有未执行迁移:
sudo -iu deploy
cd /srv/myapp/current
set -a
. /etc/myapp/myapp.env
set +a
/srv/myapp/venv/bin/python manage.py migrate --check
exit
migrate --check 没有输出并返回 0,通常表示没有待执行迁移。若迁移失败,不要直接重复执行可能包含数据变更的 SQL;先查看具体错误、确认事务状态和备份可用性。
三、用 systemd 守护 Gunicorn
1. 创建 Gunicorn 服务
创建 /etc/systemd/system/myapp.service:
[Unit]
Description=Gunicorn service for Django myapp
Wants=network-online.target
After=network-online.target postgresql.service
[Service]
Type=simple
User=deploy
Group=www-data
WorkingDirectory=/srv/myapp/current
EnvironmentFile=/etc/myapp/myapp.env
RuntimeDirectory=myapp
RuntimeDirectoryMode=0750
UMask=0007
ExecStart=/srv/myapp/venv/bin/gunicorn config.wsgi:application \
--bind unix:/run/myapp/gunicorn.sock \
--workers 2 \
--threads 2 \
--timeout 60 \
--graceful-timeout 30 \
--max-requests 1000 \
--max-requests-jitter 100
Restart=on-failure
RestartSec=5
LimitNOFILE=8192
NoNewPrivileges=true
PrivateTmp=true
ProtectHome=true
[Install]
WantedBy=multi-user.target
这里的 config.wsgi:application 必须替换为项目实际的 WSGI 模块。--workers 2 只是适合小型应用的起始值,不是固定标准。进程数过多会消耗内存,尤其是服务器同时运行 PostgreSQL、任务队列和监控组件时。
应用如果需要写入媒体文件,/srv/myapp/media 要保证 deploy 有写权限;如果使用更严格的 ProtectSystem 或其他 systemd 沙箱参数,还需要显式加入可写路径。首次上线不建议一次性加入大量限制项,应逐项启用并验证应用功能。
加载并启动服务:
sudo systemctl daemon-reload
sudo systemctl enable --now myapp.service
sudo systemctl status myapp.service --no-pager
预期状态为 active (running)。进一步查看 Socket:
sudo ss -lx | grep /run/myapp/gunicorn.sock
sudo ls -l /run/myapp/gunicorn.sock
可以通过 Unix Socket 直接测试应用。将 /healthz 替换为项目实际存在的健康检查路径:
sudo -u www-data curl --unix-socket /run/myapp/gunicorn.sock \
-H 'Host: app.example.com' \
http://localhost/healthz
如果项目没有健康检查接口,可使用登录页或一个不会触发写操作的 GET 页面测试。
2. 验证服务失败时的处理顺序
查看服务日志:
sudo journalctl -u myapp.service -n 100 --no-pager
常见结果和处理方向如下:
ModuleNotFoundError:检查WorkingDirectory、WSGI 模块名和虚拟环境依赖。ImproperlyConfigured:检查DJANGO_SECRET_KEY、数据库变量和 settings 模块。permission denied:检查/srv/myapp/current、媒体目录和环境文件的权限。- 数据库连接失败:确认 PostgreSQL 服务、数据库用户名、密码、监听地址和
DB_SSLMODE。 - 服务启动后立即退出:查看完整 traceback,不要仅根据 systemd 的
failed状态猜测原因。
修复配置后执行:
sudo systemctl restart myapp.service
sudo systemctl is-active myapp.service
如果只是修改了环境文件,必须重启服务才能加载新变量;如果只修改了代码,也建议通过受控重启让所有 Gunicorn worker 使用同一版本。
四、配置 Nginx 反向代理和静态文件
1. 先配置 HTTP 入口
创建站点配置:
sudoedit /etc/nginx/sites-available/myapp
证书申请前先使用以下 HTTP 配置:
server {
listen 80;
listen [::]:80;
server_name app.example.com;
location /.well-known/acme-challenge/ {
root /var/www/certbot;
default_type text/plain;
}
location /static/ {
alias /srv/myapp/staticfiles/;
}
location / {
proxy_pass http://unix:/run/myapp/gunicorn.sock;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_connect_timeout 5s;
proxy_read_timeout 60s;
proxy_send_timeout 60s;
client_max_body_size 20m;
}
}
创建 ACME 验证目录并启用站点:
sudo install -d -o root -g www-data -m 0755 /var/www/certbot
sudo ln -s /etc/nginx/sites-available/myapp /etc/nginx/sites-enabled/myapp
sudo nginx -t
sudo systemctl reload nginx
nginx -t 成功后才会进行 reload。配置语法错误不会覆盖正在运行的旧配置,但如果忽略检查直接 reload,排障会变得困难。
创建测试文件并从公网访问:
echo "acme-test" | sudo tee /var/www/certbot/test-file >/dev/null
curl -i http://app.example.com/.well-known/acme-challenge/test-file
预期返回 200,响应正文为 acme-test。如果返回 404,先检查 DNS、Nginx server_name 和 root 路径。
2. 申请证书
确认 80 端口可以从公网访问后,使用 webroot 方式申请证书:

sudo certbot certonly \
--webroot \
-w /var/www/certbot \
-d app.example.com \
--email admin@example.com \
--agree-tos \
--no-eff-email
admin@example.com 只是示例,实际应使用能接收续期提醒的邮箱。证书申请失败时,优先检查:
- 域名是否解析到当前服务器;
- 云防火墙和 UFW 是否放行 80;
- Nginx 是否加载了正确的
server_name; - ACME 验证路径是否被应用重定向或鉴权拦截;
- 是否存在错误的 AAAA 记录。
成功后检查证书:
sudo certbot certificates
3. 切换到 HTTPS 配置
将站点配置调整为以下形式:
server {
listen 80;
listen [::]:80;
server_name app.example.com;
location /.well-known/acme-challenge/ {
root /var/www/certbot;
default_type text/plain;
}
location / {
return 301 https://$host$request_uri;
}
}
server {
listen 443 ssl;
listen [::]:443 ssl;
server_name app.example.com;
ssl_certificate /etc/letsencrypt/live/app.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/app.example.com/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 10m;
ssl_session_tickets off;
server_tokens off;
location /static/ {
alias /srv/myapp/staticfiles/;
access_log off;
expires 7d;
add_header Cache-Control "public";
}
location / {
proxy_pass http://unix:/run/myapp/gunicorn.sock;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_connect_timeout 5s;
proxy_read_timeout 60s;
proxy_send_timeout 60s;
client_max_body_size 20m;
}
}
检查并重新加载:
sudo nginx -t
sudo systemctl reload nginx
client_max_body_size 20m 是资源边界示例,表示 Nginx 单次请求体不超过 20 MB。若 Django、应用业务或对象存储允许更大文件,需要同时检查 Django 上传限制、Gunicorn 超时、磁盘容量和备份带宽,不能只修改 Nginx。
4. 验证反向代理是否正确传递 HTTPS
检查 HTTP 跳转:
curl -I http://app.example.com/
预期看到类似结果:
HTTP/1.1 301 Moved Permanently
Location: https://app.example.com/
检查 HTTPS:
curl -I https://app.example.com/
返回 200、301 或登录页的 302 都可能是正常的,关键是不能继续跳回 HTTP,也不能出现无限重定向。
用 OpenSSL 查看证书和协议:
openssl s_client \
-connect app.example.com:443 \
-servername app.example.com \
-tls1_2 </dev/null 2>/dev/null | \
openssl x509 -noout -subject -issuer -dates
不要使用 curl -k 作为最终验收方式。-k 会跳过证书验证,只适用于临时观察服务响应,不能证明证书链配置正确。
如果访问 HTTPS 时出现重定向循环,通常按以下顺序检查:

- Nginx 是否设置了
X-Forwarded-Proto $scheme。 - Gunicorn 是否只监听 Unix Socket,没有被公网直接访问。
- Django 是否配置了正确的
SECURE_PROXY_SSL_HEADER。 - 外层是否还有 CDN、负载均衡或第二层代理,并且是否覆盖了该请求头。
- 是否错误地把
https://写入ALLOWED_HOSTS,或把不带协议的域名写入CSRF_TRUSTED_ORIGINS。
只有在确认所有业务入口都支持 HTTPS 后,才逐步提高 HSTS:
DJANGO_SECURE_HSTS_SECONDS=31536000
修改环境文件后重启应用:
sudo systemctl restart myapp.service
如果所有子域名也都已经部署 HTTPS,才考虑:
SECURE_HSTS_INCLUDE_SUBDOMAINS = True
SECURE_HSTS_PRELOAD 不应作为初次上线的默认项,因为浏览器一旦长期缓存 HSTS,后续切回 HTTP 或更换证书时会增加恢复难度。
五、证书续期、日志与资源边界
1. 验证证书自动续期
查看 Certbot 定时任务:
systemctl list-timers --all | grep -i certbot
执行模拟续期:
sudo certbot renew --dry-run
预期结果应显示测试续期成功。由于本示例使用 webroot,续期时 Nginx 需要保持运行,并且 80 端口仍要能访问 /.well-known/acme-challenge/。
证书续期后应确保 Nginx 重新加载。可以增加 deploy hook:
sudo install -d -m 0755 /etc/letsencrypt/renewal-hooks/deploy
sudo tee /etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh >/dev/null <<'EOF'
#!/bin/sh
set -eu
/usr/sbin/nginx -t
/bin/systemctl reload nginx
EOF
sudo chmod 0755 /etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh
这个脚本只在证书成功续期后执行;如果 Nginx 配置测试失败,reload 不会继续。
2. 统一查看应用和 Nginx 日志
Gunicorn 日志通过 systemd journal 查看:
sudo journalctl -u myapp.service -f
查看最近 200 行:
sudo journalctl -u myapp.service -n 200 --no-pager
Nginx 日志通常位于:
sudo tail -f /var/log/nginx/access.log /var/log/nginx/error.log
建议按“请求是否到达 Nginx → Nginx 是否成功连接 Gunicorn → Django 是否报错 → 数据库是否报错”的顺序排查。典型判断方式如下:
| 现象 | 优先检查 |
|---|---|
| 连接超时 | 云安全组、UFW、DNS、Nginx 监听地址 |
| 502 Bad Gateway | Gunicorn 状态、Socket 路径和权限 |
| 400 Bad Request | ALLOWED_HOSTS、请求 Host |
| 403 CSRF failure | CSRF_TRUSTED_ORIGINS、代理 HTTPS 头、Cookie |
| 404 静态文件 | collectstatic、STATIC_ROOT、Nginx alias |
| 504 Gateway Timeout | 数据库慢查询、Gunicorn timeout、外部 API |
| HTTPS 页面能开但 Cookie 不安全 | Django 安全配置和代理请求头 |
不要把数据库密码、Django SECRET_KEY 或完整 Authorization 请求头写入自定义日志。若需要增加请求 ID,应在 Nginx 和应用日志中采用同一字段,方便关联排查,但不要记录敏感请求体。
3. 根据资源确定 Gunicorn worker 数量
workers、threads 和 timeout 需要结合 CPU、内存、请求类型和数据库连接数决定。可以从低配置开始观察:
| 服务器资源 | 起始参考 |
|---|---|
| 1 vCPU、1~2 GB 内存 | 1~2 个 worker,谨慎启用线程 |
| 2 vCPU、4 GB 内存 | 2~4 个 worker,逐步压测 |
| 4 vCPU 以上 | 根据单 worker RSS、数据库连接和并发测试调整 |
查看进程内存:
ps -o pid,ppid,%cpu,%mem,rss,cmd -C gunicorn
free -h
不要只按 CPU 核数增加 worker。每个 worker 都会占用 Python 运行时和项目依赖的内存;如果本机还运行 PostgreSQL、定时任务和监控,过多 worker 可能导致系统进入交换分区甚至被 OOM Killer 终止。
--max-requests 和 --max-requests-jitter 可以让 worker 处理一定数量请求后平滑重建,用于降低长期运行中偶发内存增长的影响,但它们不能替代定位内存泄漏。
数据库连接数也要纳入边界。如果 Gunicorn 有 4 个 worker、每个 worker 使用独立数据库连接,PostgreSQL 的 max_connections、连接池和管理工具都需要留出余量。
围绕 Django 生产应用的计算与数据承载需求,A5数据提供美国 Xeon、AMD EPYC 等物理服务器,涵盖大内存与 NVMe 存储配置,可为 Gunicorn 多进程运行、PostgreSQL 数据库及静态文件存储提供资源基础。其美国常规系列另有 CN2 GIA 线路方案,为跨境业务的网站访问、接口调用和远程运维提供网络资源选择,衔接应用上线后的持续运行需求。
4. 备份数据库和媒体文件
数据库备份示例:
sudo install -d -o root -g root -m 0700 /var/backups/myapp
sudo sh -c 'umask 077; runuser -u postgres -- pg_dump -Fc myapp > /var/backups/myapp/myapp-'"$(date -u +%Y%m%dT%H%M%SZ)"'.dump'
sudo ls -lh /var/backups/myapp
在执行迁移、依赖大升级或批量数据操作前,先创建一份带时间标记的备份。备份文件应限制为 root 可读,并复制到与生产服务器不同的存储位置。只保留服务器本地一份备份,无法应对磁盘损坏、误删和整机故障。
可以用 systemd timer 做每日备份:
sudo tee /usr/local/sbin/backup-myapp-db >/dev/null <<'EOF'
#!/bin/sh
set -eu
backup_dir=/var/backups/myapp
timestamp=$(date -u +%Y%m%dT%H%M%SZ)
file="$backup_dir/myapp-$timestamp.dump"
install -d -o root -g root -m 0700 "$backup_dir"
umask 077
runuser -u postgres -- pg_dump -Fc myapp > "$file"
test -s "$file"
sha256sum "$file" > "$file.sha256"
find "$backup_dir" -type f -mtime +14 -delete
EOF
sudo chmod 0700 /usr/local/sbin/backup-myapp-db
创建服务和定时器:
# /etc/systemd/system/myapp-db-backup.service
[Unit]
Description=Backup PostgreSQL database for myapp
[Service]
Type=oneshot
ExecStart=/usr/local/sbin/backup-myapp-db
# /etc/systemd/system/myapp-db-backup.timer
[Unit]
Description=Daily PostgreSQL backup for myapp
[Timer]
OnCalendar=03:30
Persistent=true
[Install]
WantedBy=timers.target
启用并验证:
sudo systemctl daemon-reload
sudo systemctl enable --now myapp-db-backup.timer
sudo systemctl start myapp-db-backup.service
sudo systemctl status myapp-db-backup.service --no-pager
数据库备份不包含媒体文件。若应用允许上传,应另外备份 /srv/myapp/media,并确认对象存储或异地备份的保留周期、加密方式和恢复权限。备份任务成功不等于灾备有效,至少要定期在独立测试数据库中执行一次恢复验证。
测试恢复时不要覆盖生产数据库。示例:
sudo -u postgres createdb myapp_restore_test
sudo -u postgres pg_restore \
--exit-on-error \
--no-owner \
-d myapp_restore_test \
/var/backups/myapp/某个已验证的备份文件.dump
确认恢复数据可读取后,再删除测试数据库。删除数据库属于不可逆操作,应确认数据库名称确实是测试库,并在执行前保留备份:
sudo -u postgres dropdb myapp_restore_test
六、常见异常处理
1. 502 Bad Gateway
先确认服务和 Socket:
sudo systemctl is-active myapp.service
sudo ls -l /run/myapp/gunicorn.sock
sudo journalctl -u myapp.service -n 80 --no-pager
sudo tail -n 80 /var/log/nginx/error.log
如果服务未运行,处理 Gunicorn 日志中的 Python、环境变量或数据库错误。如果 Socket 不存在,检查 RuntimeDirectory 和 ExecStart。如果 Socket 存在但 Nginx 仍然 502,检查目录权限:
namei -l /run/myapp/gunicorn.sock
Nginx 运行用户必须能够穿过 /run/myapp 目录并读取 Socket。
2. DisallowedHost
检查请求 Host 和 Django 设置:
grep -E 'DJANGO_ALLOWED_HOSTS|server_name' \
/etc/myapp/myapp.env /etc/nginx/sites-available/myapp
DJANGO_ALLOWED_HOSTS 应为:
DJANGO_ALLOWED_HOSTS=app.example.com
不要把端口、协议或通配符随意加入生产配置。修改环境文件后需要重启 Gunicorn。
3. CSRF 校验失败
确认:
DJANGO_CSRF_TRUSTED_ORIGINS=https://app.example.com
同时检查:
- 页面是否通过 HTTPS 打开;
- Nginx 是否传递
X-Forwarded-Proto https; - 浏览器是否仍缓存旧的 HTTP 页面;
- 前端是否从另一个未列入信任列表的域名提交表单;
- 应用是否配置了多个域名而只填写了其中一个。
不要为解决 CSRF 问题直接设置 CSRF_TRUSTED_ORIGINS=*,这会扩大信任范围并掩盖真实的域名配置错误。
4. 静态文件 404 或 403
重新收集静态文件:
sudo -iu deploy
cd /srv/myapp/current
set -a
. /etc/myapp/myapp.env
set +a
/srv/myapp/venv/bin/python manage.py collectstatic --noinput
exit
检查文件和 Nginx 配置:
sudo find /srv/myapp/staticfiles -maxdepth 2 -type f | head
sudo nginx -T | grep -A8 -B2 'location /static/'
alias 的路径应指向实际存在的目录,并且 Nginx 用户具有读取权限。动态请求不应由 Nginx 直接执行,Nginx 只负责读取静态文件。
5. HTTPS 证书正常但页面仍有混合内容
证书正确只表示连接层加密,不代表 HTML 中所有资源都使用 HTTPS。检查:
- 模板中的图片、脚本和 CSS 是否写死
http://; - 数据库存储的绝对 URL 是否仍是 HTTP;
- 第三方脚本是否支持 HTTPS;
- 浏览器开发者工具的 Console 和 Security 面板。
不要用 Nginx 强行替换所有响应内容来掩盖应用中的绝对 URL 问题,优先修复 Django 模板、配置和数据库数据。
七、上线验收与回滚检查项
1. 上线验收
正式切换流量前,至少完成以下检查:
dig返回正确的 A/AAAA 记录,错误的 IPv6 记录已经处理。sudo nginx -t返回成功。systemctl is-active nginx和systemctl is-active myapp.service均为 active。- HTTP 访问返回到 HTTPS 的 301。
- HTTPS 访问不会回跳 HTTP,证书域名、有效期和证书链正常。
curl -I https://app.example.com/返回预期状态码。- 登录、退出、Session Cookie 和 CSRF 表单均能正常工作。
python manage.py check --deploy的警告已经逐项确认。/static/文件可以访问,媒体目录不会被错误地暴露为可执行内容。- 应用日志、Nginx 日志和数据库日志能够查询。
certbot renew --dry-run成功。- 数据库备份服务能够生成非空备份文件。
- 备份文件已经复制到独立存储,并完成过测试恢复。
- Gunicorn worker 数量、内存占用、请求超时和上传大小符合当前服务器资源。
- 5432 等数据库端口没有暴露到公网。
- SSH 仍可通过实际管理端口访问,防火墙规则没有误伤运维入口。
2. 应用版本回滚
如果新版本只修改了代码或模板,可以切换回上一发布目录。先确认上一版本目录仍然存在:
ls -ld /srv/myapp/releases/*
readlink -f /srv/myapp/current
切换软链接并重启:
sudo ln -sfnT /srv/myapp/releases/上一版本目录名 /srv/myapp/current
sudo systemctl restart myapp.service
sudo systemctl is-active myapp.service
切换后必须重新检查登录、静态文件和数据库连接。不要在未备份的情况下删除旧发布目录,因为它是应用回滚的直接依据。
3. 配置和 Nginx 回滚
修改 Nginx 前先复制配置:
sudo cp -a /etc/nginx/sites-available/myapp \
"/etc/nginx/sites-available/myapp.$(date -u +%Y%m%d%H%M%S).bak"
如果新配置验证失败,不要 reload;如果已经 reload 后发现业务异常,恢复已验证的配置,执行:
sudo nginx -t
sudo systemctl reload nginx
证书文件不要因为应用回滚而删除。证书由 /etc/letsencrypt/live/ 下的链接管理,回滚应用版本和回滚证书不是同一件事。
4. 数据库迁移回滚
数据库迁移不能简单等同于代码回滚。新代码可能已经写入新字段或新格式,旧代码未必能读取。正确顺序通常是:
- 先停止继续发布和写入。
- 保存当前数据库备份及应用日志。
- 判断是否存在经过验证的向后兼容迁移。
- 如果是可逆迁移,执行项目明确记录的反向迁移。
- 如果数据结构或数据内容已经改变,从备份恢复到独立数据库验证。
- 需要覆盖生产数据库时,安排维护窗口并确认业务方接受数据丢失时间点。
不要直接对生产数据库执行未经验证的 DROP TABLE、批量 DELETE 或手工 SQL“修复”。这类操作影响范围大,且通常无法通过应用软链接回滚。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/3358.html



