在云服务器上运行Django 4.2应用,如何配置反向代理与应用进程的衔接?
生产环境中,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/ 后,典型请求链路如下:

- 域名解析到云服务器或前置负载均衡。
- Nginx 接收请求,完成 TLS 加密连接处理,并根据路径选择静态文件或应用请求。
- 静态资源由 Nginx 直接读取;动态请求经 Unix 套接字转发给 Gunicorn。
- Gunicorn 将请求交给 Django WSGI 应用。
- Django 执行业务逻辑,按需访问数据库、缓存等后端,再将响应返回给 Gunicorn。
- 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 只监听本机地址,防火墙不对公网开放该端口 |
| 内网 TCP | Nginx 和应用进程位于不同机器 | 网络访问控制、链路安全、应用端只接受可信入口 |
单机部署常选 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 返回 502 | Gunicorn 是否运行;套接字路径是否一致;套接字目录和文件权限是否允许 Nginx 访问 |
Django 返回 DisallowedHost | ALLOWED_HOSTS 是否包含请求域名;Nginx 转发的 Host 是否正确 |
| HTTPS 页面反复重定向 | Nginx 是否发送正确的 X-Forwarded-Proto;Django 是否仅信任真实的代理 |
| 静态文件返回 404 | 是否运行 collectstatic;STATIC_ROOT、Nginx alias 和文件读取权限是否对应 |
| 上传请求返回 413 | Nginx 请求体大小限制是否低于业务所需;调整前确认应用本身也能安全处理相应大小的文件 |
| 应用启动后很快退出 | 查看 journalctl 中的 Python 异常、环境变量缺失、工作目录和 WSGI 模块路径 |
发布和回退时注意进程状态
单实例应用重启时,可能出现短暂不可用。Gunicorn 收到 HUP 信号时通常会重新加载工作进程,示例 unit 文件因此提供了 systemctl reload myapp。实际采用热重载还是重启,应结合发布过程验证:代码文件、依赖和配置变更可能需要不同的处理方式,不能只依赖某一种信号就认为部署已经完成。
发布前保留上一个可运行版本;新版本启动后,检查服务状态、应用日志、HTTPS 页面和关键静态文件。如果应用无法正常提供服务,按预先验证的步骤恢复代码或配置,并重新加载相应服务。不要在故障时临时删除目录、放宽整棵项目目录权限或关闭安全校验来掩盖问题。
回到请求链路判断配置是否完成
配置完成的标志不是 Nginx 和 Gunicorn 都显示“运行中”,而是请求确实能从 HTTPS 入口进入 Django,应用能识别正确的域名与外部协议,静态资源由预期目录提供,服务重启后套接字仍可用,并且错误能够在对应组件的日志中定位。
部署后的下一步,应分别验证套接字权限、Nginx 到 Django 的请求头、静态目录映射和服务重启行为。若其中任何一项依赖手工修复才能工作,就应先把该依赖固化到服务配置或发布流程中,再判断这套反向代理与应用进程衔接方式是否适合持续运行。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/9731.html


