在云服务器上运行Django 4.2应用,如何配置反向代理与应用进程的衔接?

发布人:A5数据发布时间:2026-11-16 10:53阅读量:18

生产环境中,Nginx 与 Django 4.2 应用进程之间通常通过 Unix 套接字或本机 TCP 端口衔接:Nginx 接收 HTTPS 请求、处理证书并转发动态请求,Gunicorn 等 WSGI 服务器管理 Django 进程,Django 再按业务需要访问数据库、缓存等服务。关键不是单独配通某一个组件,而是让请求头、套接字权限、服务生命周期和日志在整条链路上保持一致。

下面以 Ubuntu 或 Debian、Nginx、Gunicorn、systemd,以及域名 app.example.com 为例说明。示例假定应用代码位于 /srv/myapp,Django 项目包名为 config,运行用户为 myapp,Nginx 用户组为 www-data。实际部署时应先核对系统中的 Nginx 用户、项目模块名和证书路径,再调整示例配置。

当前问题与业务链路

用户访问 https://app.example.com/ 后,典型请求链路如下:

当前问题与业务链路配图

  1. 域名解析到云服务器或前置负载均衡。
  2. Nginx 接收请求,完成 TLS 加密连接处理,并根据路径选择静态文件或应用请求。
  3. 静态资源由 Nginx 直接读取;动态请求经 Unix 套接字转发给 Gunicorn。
  4. Gunicorn 将请求交给 Django WSGI 应用。
  5. Django 执行业务逻辑,按需访问数据库、缓存等后端,再将响应返回给 Gunicorn。
  6. Gunicorn 将响应交还 Nginx,Nginx 最后发送给客户端。

这里的“反向代理与应用进程衔接”,主要涉及三个容易混淆的问题:

  • 连接方式:Nginx 应该把请求转发到哪个地址,应用进程是否正在监听该地址。
  • 请求语义:Django 能否识别原始域名、客户端地址和外部 HTTPS 状态。
  • 运行边界:Nginx 是否有权限访问套接字,应用异常时能否从服务日志定位问题。

如果 Nginx 返回 502,通常要先检查应用进程、监听地址和套接字权限;如果请求能到达 Django,但出现域名校验错误或 HTTPS 重定向循环,则应检查 Host、转发协议头和 Django 安全设置。将这几类问题分开处理,比单纯反复重启服务更有效。

相关组件的职责

Nginx:入口、TLS 与请求转发

Nginx 面向公网接收连接,负责 TLS 证书、虚拟主机匹配、请求转发和静态文件服务。它不执行 Django 的业务代码,也不应承担数据库访问等应用职责。

静态文件通常由 Django 的 collectstatic 命令集中生成,再由 Nginx 直接读取。这样可以避免每个静态资源请求都占用 Django 工作进程。上传文件则属于另一类数据:应用可能需要写入它们,Nginx 只在文件允许公开访问时提供读取。私有附件不应仅因存在服务器目录,就直接配置为公开 URL。

Gunicorn:管理 Django 的 WSGI 进程

Django 4.2 可以通过 WSGI 接口运行。Gunicorn 负责启动多个应用工作进程、接收 Nginx 转来的请求,并把结果返回给 Nginx。它与 Nginx 的分工是“应用进程管理与请求执行”对“公网入口与转发”,二者不能互相替代。

一个工作进程通常同一时刻处理有限数量的同步请求。进程数量过少,慢请求可能排队;数量过多,则可能挤占内存或增加数据库连接数。应结合 CPU、可用内存、单个工作进程的常驻内存、请求耗时和数据库连接上限调整,而不是把某个经验公式直接当成固定答案。

systemd:应用进程的生命周期管理

systemd 负责按指定用户启动 Gunicorn,在进程异常退出时按策略重启,并将标准输出和错误输出收集到系统日志中。生产部署不宜通过 SSH 会话手动运行 Gunicorn,否则终端断开、机器重启或进程异常时,应用的运行状态难以管理。

Django:处理应用逻辑并识别可信请求信息

Django 应明确设置 DEBUG=False、ALLOWED_HOSTS 和生产环境密钥。由于 HTTPS 在 Nginx 终止,Django 与 Gunicorn 之间收到的可能是本地套接字请求;Django 需要通过受信任代理传递的协议头,才能正确判断外部请求是否为 HTTPS。

只有当应用能保证请求确实经过可信的 Nginx,并且 Nginx 会覆盖相应请求头时,才应配置 SECURE_PROXY_SSL_HEADER。如果该值可以被不可信客户端直接控制,应用可能错误地把普通 HTTP 请求当成 HTTPS。

组件交互:用 Unix 套接字连接 Nginx 与 Gunicorn

在 Nginx 和 Gunicorn 位于同一台云服务器时,Unix 套接字是常见的连接方式。它不占用对外 TCP 端口,也能通过文件系统权限控制访问。需要留意的是,套接字所在目录和套接字本身都必须允许 Nginx 进程访问。

准备应用运行目录和环境变量

以下路径仅为示例。部署前确认应用代码和虚拟环境已放在相应位置,并确认 Django 项目具有 config.wsgi:application 入口。

生产密钥、数据库连接信息等敏感值可放在权限受限的环境文件中,不应提交到代码仓库。创建和编辑配置前,先备份服务器上已有的同名配置文件;不要直接覆盖仍在运行的生产配置而不保留回退副本。

例如,/etc/myapp/myapp.env 可包含:

DJANGO_SECRET_KEY=替换为随机且保密的密钥
DJANGO_ALLOWED_HOSTS=app.example.com

限制文件读取权限,使其仅由管理员和应用运行账户按实际需求访问。Django 设置可从环境变量读取:

import os

SECRET_KEY = os.environ["DJANGO_SECRET_KEY"]
DEBUG = False

ALLOWED_HOSTS = [
    host.strip()
    for host in os.environ.get("DJANGO_ALLOWED_HOSTS", "").split(",")
    if host.strip()
]

CSRF_TRUSTED_ORIGINS = ["https://app.example.com"]

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

CSRF_TRUSTED_ORIGINS 中应填写带协议的来源。若应用使用多个正式域名,应逐个列出;不要为了消除域名错误而将 ALLOWED_HOSTS 设为任意主机。

使用 systemd 管理 Gunicorn

创建 /etc/systemd/system/myapp.service:

[Unit]
Description=Gunicorn for myapp
After=network.target

[Service]
Type=notify
User=myapp
Group=www-data
WorkingDirectory=/srv/myapp
EnvironmentFile=/etc/myapp/myapp.env
Environment=PYTHONUNBUFFERED=1
RuntimeDirectory=myapp
RuntimeDirectoryMode=0750
UMask=0007
ExecStart=/srv/myapp/venv/bin/gunicorn \
    --workers 3 \
    --bind unix:/run/myapp/gunicorn.sock \
    --umask 007 \
    --access-logfile - \
    --error-logfile - \
    config.wsgi:application
ExecReload=/bin/kill -s HUP $MAINPID
Restart=on-failure
RestartSec=3
TimeoutStopSec=30

[Install]
WantedBy=multi-user.target

这里由 systemd 在 /run/myapp 下创建运行目录,目录在服务停止后可能被清理;服务启动时会重新创建。目录属于 myapp:www-data,权限模式允许所属组访问。Gunicorn 的 umask 用于限制新建套接字的权限。实际运行后仍要检查套接字权限,因为不同环境中的账户、目录权限或服务配置可能与示例不同。

--workers 3 只是用于说明配置形式的起点,不是对所有云服务器都适用的固定值。小内存实例如果工作进程过多,可能导致内存压力;若请求较慢或并发较高,也要结合应用耗时、数据库连接数和监控结果调整。若应用包含较长时间运行的请求,不宜只靠无限增加工作进程解决,应先判断请求是否适合异步处理或拆分。

配置 Nginx 转发与静态资源

下面的示例将 /static/ 指向 Django 收集后的静态目录,并将其余请求转发到 Gunicorn 套接字。示例证书路径采用常见的证书目录形式,部署前确认文件确实存在且 Nginx 有权限读取。

server {
    listen 80;
    server_name app.example.com;

    location ^~ /.well-known/acme-challenge/ {
        root /var/www/acme;
    }

    location / {
        return 301 https://$host$request_uri;
    }
}

server {
    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;

    access_log /var/log/nginx/myapp_access.log;
    error_log  /var/log/nginx/myapp_error.log;

    location /static/ {
        alias /srv/myapp/shared/static/;
    }

    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;
    }
}

alias 末尾的斜杠应与 location /static/ 配合,避免静态文件路径拼接错误。对应的 Django 设置示例为:

STATIC_URL = "/static/"
STATIC_ROOT = "/srv/myapp/shared/static"

每次静态资源发生变化后,应在正确的虚拟环境和应用设置下运行:

cd /srv/myapp
/srv/myapp/venv/bin/python manage.py collectstatic --noinput

执行前确认 STATIC_ROOT 指向的是专用静态目录,而不是应用源码或其他需要保留的文件目录。Nginx 只需要读取静态文件;如果应用需要写入上传目录,应单独设置上传目录及其权限,不要为了省事让 Nginx 和应用都获得整个项目目录的写权限。

示例中的 X-Forwarded-For 用于传递转发链中的地址。若服务器前面还存在负载均衡或其他可信代理,应明确哪些代理可以提供真实客户端地址;如果应用或第三方组件会解析转发链,不要把客户端自行提交的转发头当成可信来源。若 Nginx 直接面向公网,应确认其接收和转发头部的方式符合应用的信任边界。

部署取舍:套接字、TCP 与进程数量

Unix 套接字还是本机 TCP

方式适用场景需要重点确认
Unix 套接字Nginx 与 Gunicorn 在同一台机器目录和套接字权限、路径一致、服务重启后重新创建
本机 TCP需要用端口工具检查,或组件部署方式更适合端口连接Gunicorn 只监听本机地址,防火墙不对公网开放该端口
内网 TCPNginx 和应用进程位于不同机器网络访问控制、链路安全、应用端只接受可信入口

单机部署常选 Unix 套接字,减少端口暴露面;若排查工具或部署平台对 TCP 支持更直接,也可以让 Gunicorn 监听 127.0.0.1:8000,并将 Nginx 的 proxy_pass 改为 http://127.0.0.1:8000。不要让应用监听 0.0.0.0 后忘记配置访问控制,否则 Gunicorn 可能绕过 Nginx 暴露在公网。

如果代理和应用在不同服务器上,Unix 套接字不能跨机器使用,应采用受限的内网 TCP 或由基础设施提供的服务发现方式,并检查云防火墙和主机防火墙的允许范围。不要因“只是内部端口”就默认该端口对任意来源开放。

面向 Django 应用从单机运行到多节点部署的不同资源需求,A5idc数据提供中国香港、美国、日本等地区的物理服务器租用,涵盖 Xeon Gold 与 AMD EPYC 等平台,并提供 SSD、NVMe 存储及不同线路方案,可为应用进程、数据库和接口服务提供相应的计算、存储与网络资源基础。

单实例与多实例的取舍

单台服务器上的一个 Gunicorn 服务容易部署和排查,但进程重启、服务器维护或资源耗尽时,都会影响该实例承载的请求。多实例部署可以让入口在多个应用节点间分配请求,但会增加健康检查、版本一致性、共享上传文件、会话和数据库连接管理等要求。只有在可用性或容量确实需要时,才应引入多实例架构。

工作进程数量也要与数据库连接预算一起考虑。例如,若 Gunicorn 配置了多个进程,而每个请求都可能占用数据库连接,应用进程增加后,数据库连接数也可能上升。调整前应查看数据库允许的连接数、应用连接池设置和实际并发需求,而不是只观察 CPU 使用率。

HTTPS 与安全头的配置边界

生产环境中,Nginx 通常负责对外 HTTPS,Gunicorn 只接受本机或受限网络内的请求。Django 的 SECURE_PROXY_SSL_HEADER 应与 Nginx 实际发送的 X-Forwarded-Proto 对应。配置错误时,常见现象包括 Django 持续把请求重定向到 HTTPS,或在 HTTPS 页面中仍把请求识别为 HTTP。

SECURE_HSTS_SECONDS 等 HSTS 设置不宜在证书、域名和 HTTPS 路径尚未验证时贸然启用。尤其是包含子域名的策略,可能影响同一域名下尚未完成 HTTPS 配置的服务。应先确认目标域名均可稳定通过 HTTPS 访问,再依据维护范围逐步启用。

运行要点:启动、验证与维护

变更前准备

正式替换 Nginx 配置或 systemd 服务文件前,先备份当前版本并记录相关文件路径。确认以下条件:

  • Nginx 用户组与服务中的 Group 设置一致,或已通过其他方式授予套接字访问权限。
  • 虚拟环境中的 Gunicorn 已安装,项目的 WSGI 模块路径正确。
  • 环境变量文件存在且权限受限。
  • 证书与私钥路径正确,静态目录和应用目录权限符合读写需求。
  • 若要执行数据库迁移,已评估迁移对现有数据和旧版本应用的影响,并准备经过验证的备份和回退方案。

数据库迁移并非代理配置的一部分。迁移涉及数据变更时,应先确认备份可恢复、影响范围清楚,并根据迁移内容安排执行顺序;不要把“重启应用”当成数据库操作的回滚方法。

启动服务并检查配置

确认 Django 设置后,可先运行部署检查:

cd /srv/myapp
/srv/myapp/venv/bin/python manage.py check --deploy

检查输出中的安全项和配置项,并结合实际部署判断是否需要调整。随后加载 systemd 配置,启动应用,并在检查 Nginx 配置通过后重新加载 Nginx:

sudo systemctl daemon-reload
sudo systemctl enable --now myapp
sudo systemctl status myapp --no-pager

sudo nginx -t
sudo systemctl reload nginx

nginx -t 未通过时不要执行 reload;应先根据错误提示修复配置。重新加载失败或站点异常时,可以恢复之前备份的配置,重新执行语法检查,再加载旧配置。应用服务的变更也应保留旧版服务文件和代码版本,避免出现无法恢复的状态。

从入口到应用逐层验证

先检查应用服务是否运行,再检查套接字是否存在,以及 Nginx 用户是否有权访问套接字:

sudo systemctl status myapp --no-pager
sudo ls -l /run/myapp/gunicorn.sock
sudo namei -l /run/myapp/gunicorn.sock

接着可以绕过 Nginx,直接通过套接字请求应用。将域名改为真实的 ALLOWED_HOSTS 条目:

curl --unix-socket /run/myapp/gunicorn.sock \
  -H 'Host: app.example.com' \
  -H 'X-Forwarded-Proto: https' \
  -sS -o /dev/null -w '%{http_code}\n' \
  http://localhost/

如果这里能返回应用预期的 HTTP 状态码,说明套接字到 Django 的路径基本可用。返回 404 可能代表请求已到达应用,但该路径不存在;这与 502 的含义不同。然后从公网域名检查完整链路:

curl -I https://app.example.com/

检查证书是否匹配域名、响应状态是否符合应用预期,以及 HTTP 请求是否按预期跳转到 HTTPS。静态资源也应使用浏览器或 curl 单独访问一个实际存在的文件,确认 Nginx 的 alias 与 STATIC_ROOT 对应。

日志与常见故障含义

Gunicorn 的访问和错误输出在示例中写入标准输出、标准错误,可用 systemd 日志查看:

sudo journalctl -u myapp -n 100 --no-pager

Nginx 的访问日志和错误日志分别位于示例配置指定的文件。生产环境应按主机的日志保留策略轮转和限制日志体积,避免长期运行后日志占满磁盘;同时避免在日志中记录密码、密钥、完整会话令牌等敏感内容。

现象优先检查方向
Nginx 返回 502Gunicorn 是否运行;套接字路径是否一致;套接字目录和文件权限是否允许 Nginx 访问
Django 返回 DisallowedHostALLOWED_HOSTS 是否包含请求域名;Nginx 转发的 Host 是否正确
HTTPS 页面反复重定向Nginx 是否发送正确的 X-Forwarded-Proto;Django 是否仅信任真实的代理
静态文件返回 404是否运行 collectstatic;STATIC_ROOT、Nginx alias 和文件读取权限是否对应
上传请求返回 413Nginx 请求体大小限制是否低于业务所需;调整前确认应用本身也能安全处理相应大小的文件
应用启动后很快退出查看 journalctl 中的 Python 异常、环境变量缺失、工作目录和 WSGI 模块路径

发布和回退时注意进程状态

单实例应用重启时,可能出现短暂不可用。Gunicorn 收到 HUP 信号时通常会重新加载工作进程,示例 unit 文件因此提供了 systemctl reload myapp。实际采用热重载还是重启,应结合发布过程验证:代码文件、依赖和配置变更可能需要不同的处理方式,不能只依赖某一种信号就认为部署已经完成。

发布前保留上一个可运行版本;新版本启动后,检查服务状态、应用日志、HTTPS 页面和关键静态文件。如果应用无法正常提供服务,按预先验证的步骤恢复代码或配置,并重新加载相应服务。不要在故障时临时删除目录、放宽整棵项目目录权限或关闭安全校验来掩盖问题。

回到请求链路判断配置是否完成

配置完成的标志不是 Nginx 和 Gunicorn 都显示“运行中”,而是请求确实能从 HTTPS 入口进入 Django,应用能识别正确的域名与外部协议,静态资源由预期目录提供,服务重启后套接字仍可用,并且错误能够在对应组件的日志中定位。

部署后的下一步,应分别验证套接字权限、Nginx 到 Django 的请求头、静态目录映射和服务重启行为。若其中任何一项依赖手工修复才能工作,就应先把该依赖固化到服务配置或发布流程中,再判断这套反向代理与应用进程衔接方式是否适合持续运行。

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

相关推荐