从零到一：在Ubuntu 20.04上部署Django项目的避坑指南与实战

1. 环境准备从零搭建Ubuntu 20.04服务器第一次部署Django项目时我踩过的第一个坑就是服务器环境配置。Ubuntu 20.04虽然预装了Python 3.8但直接使用系统自带的Python可能会导致后续依赖冲突。这里推荐用pyenv管理多版本Python环境实测能避开90%的依赖问题。先更新系统基础包sudo apt update sudo apt upgrade -y sudo apt install -y make build-essential libssl-dev zlib1g-dev \ libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm \ libncurses5-dev libncursesw5-dev xz-utils tk-dev libffi-dev liblzma-dev安装pyenv不要用root用户操作curl https://pyenv.run | bash echo export PYENV_ROOT$HOME/.pyenv ~/.bashrc echo command -v pyenv /dev/null || export PATH$PYENV_ROOT/bin:$PATH ~/.bashrc echo eval $(pyenv init -) ~/.bashrc exec $SHELL安装特定Python版本以3.8.12为例pyenv install 3.8.12 pyenv global 3.8.12验证安装python -V # 应显示Python 3.8.12 pip -V # 应显示对应pip版本提示如果遇到SSL相关错误可能是系统OpenSSL版本不兼容可尝试PYTHON_CONFIGURE_OPTS--with-openssl/usr/include/openssl pyenv install 3.8.122. 项目依赖与虚拟环境配置很多教程会推荐直接全局安装依赖但实际项目中这会导致严重的环境污染。我的血泪教训是必须为每个项目创建独立虚拟环境创建项目目录并初始化虚拟环境mkdir ~/myproject cd ~/myproject python -m venv venv source venv/bin/activate安装基础依赖注意版本号pip install django4.2 uwsgi2.0.21这里有个隐藏大坑uWSGI必须用pip安装如果用apt安装会出现Python插件缺失。我曾因此浪费三小时排查502错误。验证uWSGI是否正常uwsgi --version # 应显示2.0.21项目依赖建议保存到requirements.txtpip freeze requirements.txt3. Nginx配置的七个关键细节Nginx配置不当会导致静态文件404、API请求超时等问题。这是我的生产级配置模板server { listen 80; server_name yourdomain.com; # 静态文件配置必须放在location / 前面 location /static/ { alias /home/user/myproject/static/; expires 30d; access_log off; } # 媒体文件配置 location /media/ { alias /home/user/myproject/media/; expires 7d; } # 主应用配置 location / { include uwsgi_params; uwsgi_pass unix:///tmp/myproject.sock; uwsgi_read_timeout 300s; # 解决413 Request Entity Too Large client_max_body_size 100M; # 重要头信息传递 uwsgi_param Host $host; uwsgi_param X-Real-IP $remote_addr; uwsgi_param X-Forwarded-For $proxy_add_x_forwarded_for; } # 禁止访问.git等隐藏文件 location ~ /\. { deny all; } }关键注意事项静态文件alias路径必须以/结尾uWSGI socket文件权限要设为www-data用户可读写超时时间根据业务需求调整API接口建议300秒以上生产环境务必配置SSL证书4. uWSGI的魔鬼细节配置uWSGI的配置直接影响服务稳定性。这是我的优化配置uwsgi.ini[uwsgi] chdir /home/user/myproject module myproject.wsgi:application # 使用unix socket比TCP性能更好 socket /tmp/myproject.sock chmod-socket 666 vacuum true # 进程数 CPU核心数*21 processes 5 threads 2 # 优雅的重启配置 max-requests 1000 harakiri 30 reload-on-as 512 reload-on-rss 256 # 日志记录 daemonize /var/log/uwsgi/myproject.log disable-logging true常见问题解决方案socket权限问题执行sudo chown www-data:www-data /tmp/myproject.sock内存泄漏设置max-requests定期重启workerDjango静态文件收集先执行python manage.py collectstatic5. 部署后的必备调优部署完成后还有几个关键检查点防火墙配置sudo ufw allow 80 sudo ufw allow 443 sudo ufw enable服务自启动使用systemd 创建/etc/systemd/system/myproject.service[Unit] DescriptionMyProject uWSGI Service Afternetwork.target [Service] Useruser Groupwww-data WorkingDirectory/home/user/myproject EnvironmentPATH/home/user/myproject/venv/bin ExecStart/home/user/myproject/venv/bin/uwsgi --ini uwsgi.ini [Install] WantedBymulti-user.target启用服务sudo systemctl daemon-reload sudo systemctl start myproject sudo systemctl enable myproject性能监控 安装uwsgitop实时监控pip install uwsgitop uwsgitop /tmp/myproject.sock6. 故障排查指南当出现502错误时按这个顺序排查检查uWSGI日志tail -f /var/log/uwsgi/myproject.log检查Nginx错误日志tail -f /var/log/nginx/error.log手动启动uWSGI测试uwsgi --ini uwsgi.ini --http :8000检查socket文件权限ls -l /tmp/myproject.sock数据库连接问题特别常见在settings.py中增加DATABASES { default: { CONN_MAX_AGE: 600, # 连接池保持时间 OPTIONS: { connect_timeout: 5, # 连接超时设置 } } }7. 安全加固措施生产环境必须做的安全配置关闭DEBUG模式DEBUG False ALLOWED_HOSTS [yourdomain.com, IP地址]配置CSRF_TRUSTED_ORIGINSCSRF_TRUSTED_ORIGINS [https://yourdomain.com]自动备份方案每日凌晨执行# 备份数据库 pg_dump -U username dbname db_backup.sql # 备份代码和媒体文件 tar -czvf project_backup_$(date %F).tar.gz /home/user/myproject这套配置经过多个百万PV项目验证最久稳定运行超过400天。记得定期更新依赖包版本我习惯每月第一个周一执行pip list --outdated检查更新。