异常教程

Django Nginx+uwsgi 安装配置（保姆级教程）

更新时间:

💡一则或许对你有用的小广告

欢迎加入小哈的星球 ，你将获得：专属的项目实战 / 1v1 提问 / Java 学习路线 / 学习打卡 / 每月赠书 / 社群讨论

截止目前， 星球 内专栏累计输出 90w+ 字，讲解图 3441+ 张，还在持续爆肝中.. 后续还会上新更多项目，目标是将 Java 领域典型的项目都整一波，如秒杀系统, 在线商城, IM 即时通讯，权限管理，Spring Cloud Alibaba 微服务等等，已有 3100+ 小伙伴加入学习 ，欢迎点击围观

前言

在 Web 开发领域，Django 以其高效性和易用性成为 Python 后端开发的热门框架。然而，当需要将 Django 应用部署到生产环境时，仅依赖 Django 自带的开发服务器显然不够。此时，Nginx 和 uwsgi 的组合便成为了一个高性能、高可靠性的解决方案。本文将从零开始，逐步讲解如何安装、配置 Django、uwsgi 和 Nginx，帮助开发者构建一个完整的生产级 Web 环境。

Django 安装与项目创建

安装 Python 环境

Django 是基于 Python 的 Web 框架，因此需要先安装 Python。建议使用 Python 3.8 或更高版本。对于 Windows 用户，可通过 Python 官网 下载安装包；对于 Linux 或 macOS 用户，可通过终端命令安装：

sudo apt update && sudo apt install python3 python3-pip  

brew install python

创建虚拟环境

为避免全局 Python 环境污染，建议使用虚拟环境工具（如 venv 或 conda）。以下以 venv 为例：

python3 -m venv myenv  
source myenv/bin/activate  # 激活虚拟环境

安装 Django

通过 pip 安装 Django：

pip install Django

创建 Django 项目

运行以下命令生成基础项目结构：

django-admin startproject myproject  
cd myproject

此时，项目目录中会包含 manage.py 和 myproject 包，其中 settings.py 存储了核心配置。

uwsgi 安装与配置

什么是 uwsgi？

uwsgi 是一个兼容 WSGI 标准的 Web 服务器网关接口，它充当 Django 应用与 Nginx 之间的“桥梁”。与 Django 开发服务器不同，uwsgi 能够高效处理高并发请求，并支持多线程、多进程模式。

安装 uwsgi

通过 pip 安装：

pip install uwsgi

配置 uwsgi

在项目根目录下创建 uwsgi.ini 文件，内容如下：

[uwsgi]  
module = myproject.wsgi:application  # Django 的 WSGI 应用入口  
master = true                        # 启用主进程管理  
processes = 4                        # 进程数量（根据 CPU 核心数调整）  
threads = 2                          # 每个进程的线程数  
socket = myproject.sock              # 与 Nginx 通信的 socket 文件  
chmod-socket = 660                  # 设置 socket 文件权限（允许 Nginx 访问）  
vacuum = true                       # 退出时自动清理 socket 文件

关键参数解释

参数作用说明
moduleDjango 项目的 WSGI 入口，格式为 <project>.wsgi:application
socketuwsgi 与 Nginx 通信的路径，通常使用 Unix socket 提升性能
chmod-socket设置 socket 文件权限，确保 Nginx 用户（如 www-data）可读写

Nginx 安装与配置

什么是 Nginx？

Nginx 是一个高性能的 HTTP 服务器和反向代理服务器。它擅长处理静态文件请求、负载均衡和 SSL/TLS 加密，常与 uwsgi 结合使用，形成“前端静态处理 + 后端动态处理”的架构。

安装 Nginx

根据系统类型执行以下命令：

sudo apt install nginx  

sudo yum install epel-release  
sudo yum install nginx

配置 Nginx 反向代理

在 /etc/nginx/sites-available/ 目录下创建配置文件 myproject，内容如下：

server {  
    listen 80;  
    server_name example.com;  # 替换为你的域名或 IP 地址  

    location / {  
        include uwsgi_params;  
        uwsgi_pass unix:/path/to/myproject.sock;  # uwsgi 的 socket 路径  
    }  

    # 静态文件配置  
    location /static/ {  
        alias /path/to/myproject/static/;  # Django 静态文件路径  
    }  
}

关键配置说明

配置项作用说明
listen 80监听 80 端口，处理 HTTP 请求
uwsgi_pass指定 uwsgi 的 socket 连接路径
location /static/配置静态文件路径，需与 Django 的 STATIC_ROOT 对应

启用配置并重启 Nginx

创建符号链接并重启服务：

sudo ln -s /etc/nginx/sites-available/myproject /etc/nginx/sites-enabled/  
sudo systemctl restart nginx

配置 Django 项目

设置静态文件路径

在 Django 的 settings.py 中配置静态文件路径：

STATIC_URL = '/static/'  
STATIC_ROOT = '/path/to/myproject/static/'  # 需与 Nginx 配置中的 alias 一致

运行 python manage.py collectstatic 将静态文件收集到指定目录。

数据库配置

默认情况下，Django 使用 SQLite 数据库。若需切换到 MySQL 或 PostgreSQL，需在 settings.py 中修改 DATABASES 配置，并安装对应驱动：

pip install mysqlclient  # MySQL  
pip install psycopg2     # PostgreSQL

启动与测试

启动 uwsgi

在项目根目录下执行：

uwsgi --ini uwsgi.ini

此时，uwsgi 会监听 myproject.sock，并等待 Nginx 的请求。

访问测试

通过浏览器访问服务器的 IP 或域名，若看到 Django 的默认欢迎页面（或你的自定义页面），则说明配置成功。

常见问题与解决

1. Nginx 访问 502 错误

原因：uwsgi 未启动或 socket 权限不足。
解决：

  • 确保 uwsgi 进程已运行：ps aux | grep uwsgi
  • 检查 socket 文件权限：chmod 660 myproject.sock
  • 验证 Nginx 配置：nginx -t

2. 静态文件无法加载

原因：Django 的 STATIC_ROOT 路径未正确配置，或 Nginx 无权限访问静态目录。
解决：

  • 运行 collectstatic 后，检查静态文件是否存在指定路径。
  • 设置目录权限：sudo chown -R www-data:www-data /path/to/static

总结

通过本文的步骤，读者可以掌握 Django、uwsgi 和 Nginx 的安装与配置方法。这一组合的优势在于：

  • 高性能：uwsgi 的多进程模式可处理高并发请求，Nginx 优化静态文件传输效率。
  • 高可靠性：通过反向代理和负载均衡，提升服务的容错能力。
  • 灵活性：支持 SSL 加密、动态扩展等企业级需求。

建议读者在实际部署时，进一步优化配置（如 HTTPS 配置、日志管理），并结合监控工具（如 Prometheus）实时跟踪服务状态。希望本文能为你的 Django 项目部署提供清晰的路径！

最新发布

查看更多文章