在美国服务器上线Django 5.2 LTS应用,怎样配置HTTPS与安全设置?

发布人:A5数据发布时间:2026-10-12 10:35阅读量:129

美国服务器上的 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 LTScat /etc/os-release
Python3.12python3 --version
应用框架Django 5.2.x虚拟环境中执行 python -m django --version
Web 入口Nginx 监听 80、443sudo ss -lntp
应用进程Gunicorn Unix Socketsudo ss -lx
数据库PostgreSQL 本机或托管实例psql --version
域名app.example.comdig +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 用于校验 HTTP Host,填写域名,不要填写 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 方式申请证书:

配置 Nginx 反向代理和静态文件配图

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 反向代理和静态文件配图

  1. Nginx 是否设置了 X-Forwarded-Proto $scheme。
  2. Gunicorn 是否只监听 Unix Socket,没有被公网直接访问。
  3. Django 是否配置了正确的 SECURE_PROXY_SSL_HEADER。
  4. 外层是否还有 CDN、负载均衡或第二层代理,并且是否覆盖了该请求头。
  5. 是否错误地把 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 GatewayGunicorn 状态、Socket 路径和权限
400 Bad RequestALLOWED_HOSTS、请求 Host
403 CSRF failureCSRF_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. 数据库迁移回滚

数据库迁移不能简单等同于代码回滚。新代码可能已经写入新字段或新格式,旧代码未必能读取。正确顺序通常是:

  1. 先停止继续发布和写入。
  2. 保存当前数据库备份及应用日志。
  3. 判断是否存在经过验证的向后兼容迁移。
  4. 如果是可逆迁移,执行项目明确记录的反向迁移。
  5. 如果数据结构或数据内容已经改变,从备份恢复到独立数据库验证。
  6. 需要覆盖生产数据库时,安排维护窗口并确认业务方接受数据丢失时间点。

不要直接对生产数据库执行未经验证的 DROP TABLE、批量 DELETE 或手工 SQL“修复”。这类操作影响范围大,且通常无法通过应用软链接回滚。

本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/3358.html

相关推荐