“路飞学城”这个名字最早是我参与的一个模拟在线教育平台项目的代号。表面上它就是一个典型的网课系统学员能注册登录、选课下单、看视频、记录学习进度管理员能维护课程分类、处理订单、看用户数据。开发阶段大家写代码写得很嗨但真正让整个团队头皮发麻的是最后一步——项目上线。我前后在服务器上折腾了快三周从架构选型、环境初始化到半夜处理 502 和数据库断连几乎把初学者能踩的坑都踩了一遍。这篇我把整个“项目上线”阶段的方案细节、执行步骤、真实故障排查过程整理出来希望能给准备独立部署 Web 项目的人一些参考。1. 先摸清项目的家底再谈上线1.1 路飞学城的技术架构上线之前最忌讳的就是拿着开发代码直接往服务器上扔。你得先搞清楚项目是由哪些部分组成的、每个部分在生产环境里各自扮演什么角色。路飞学城的开发环境跑得很简单浏览器里一个 Vue 前端本地一个 Django 后端外加一个 MySQL 存业务数据Redis 做缓存Celery 处理异步任务。但这套组合在本地跑得顺离生产可用还差着十万八千里。开发环境里Django 自带 runserver 进程把动态请求和静态文件一股脑都扛了看着方便。可这个开发服务器是单线程同步模型稍微来几个并发的课程列表查询响应时间就会直线上升。生产环境里常见的部署组合是四层结构Nginx 在最前面接收用户请求静态资源直接由 Nginx 走文件系统返回带 .php 或特定 URL 的动态请求再转给后端的 WSGI 进程比如 uWSGI 或 Gunicorn数据库和缓存则独立部署。路飞学城的具体分层是这个样子前端Vue 项目构建后的 dist 目录交给 Nginx 托管。后端Django 应用由 Gunicorn或 uWSGI以多进程方式运行。Web 服务器Nginx 监听 80/443做反向代理和静态资源服务。数据层MySQL 存放订单、课程、用户等核心数据。缓存与异步Redis 负责缓存会话、接口热点数据Celery worker 消费耗时任务比如发送邮件、生成学习报表。1.2 上线前必须明确的几个目标很多人一上来就配 Nginx结果项目上线后三天两头出问题本质上是因为没有想清楚上线的核心目标。我们在部署路飞学城的“正式环境”前先定了几条硬性标准服务要稳进程崩溃了必须自动拉起不能依赖人工 ssh 上去重启。数据不能丢MySQL 要定时备份Redis 重要数据要做持久化策略评估。能发现问题要有日志系统至少要能看到 Nginx access/error 日志、Django 日志出问题能定位。可回滚新版本上线后如果发现致命 Bug能在几分钟内切回上一个版本而不是现场改代码。这四条是后来所有配置决策的基本原则。每次碰到两难选择我都会拿这四个标准去卡一下基本不会跑偏。2. 上线方案选型别一上来就调配置2.1 进程模型怎么选Python Web 项目最常见的生产选择是 Gunicorn 和 uWSGI。路飞学城用的是 uWSGI理由是当时团队成员对配置文件更熟而且 uWSGI 自带强大的 worker 管理能力。但这不代表 Gunicorn 不行我更建议初学者用 Gunicorn它的默认配置更接近常规思维坑比 uWSGI 少一些。最关键的是要理解 WSGI 进程的关系。Django 开发服务器是单进程的而 Gunicorn 会 fork 出多个 worker 进程每个 worker 独立处理请求。worker 数量不是越大越好太小会排队太大会抢占 CPU 和内存。路飞学城的服务器配置是 4 核 8G我一开始拍脑袋配了 8 个 worker结果还没撑过 5 分钟内存就报警了。后来老老实实按公式worker 数 CPU 核心数 × 2 1也就是 9 个配合合适的超时时间才稳定下来。uWSGI 或 Gunicorn 本身都不适合直接暴露给公网因为它们对慢连接、大并发静态请求的应对能力很弱必须用 Nginx 做前置网关。Nginx 是事件驱动的一个 master 进程可以轻松管理成千上万个连接把静态文件和访问日志这些“脏活”接过去后端的 Python 进程就能专心算业务逻辑。2.2 为什么一定要加一层 Nginx直接让 uWSGI 监听公网端口不是不能跑但会有几个特别务实的问题。第一HTTP 报文解析和处理静态文件不是 uWSGI 的强项专业的事情要交给专业工具。第二Django 的 runserver 能自己处理静态文件但切换到生产模式后静态文件收集和权限处理细节特别容易出错。Nginx 只需要一行 alias 或 root 配置就能把静态目录映射出去效率极高。第三Nginx 是天然的负载均衡器。如果以后路飞学城要横向扩容加一台应用服务器Nginx 不用改动上层逻辑只需要在 upstream 里加一条记录。所以我没有选择“去掉 Nginx直接用 uWSGI 扛”的省事方案而是规规矩矩地搭了 Nginx 反代层。这也是生产环境里的标准姿势。2.3 数据层和缓存的考虑MySQL 部署的时候要改几个关键项。字符集必须用 utf8mb4不然用户昵称里加个 emoji 表情数据写入直接报错连接数上限要调大一点binlog 最好开着后续做数据恢复会方便很多。路飞学城初期只有一台 MySQL 实例所以我没有上主从复制但对 binlog 和全量备份做了固定策略。如果你一开始就想做高可用主从是推荐的但单实例部署时先把备份做好优先级更高。Redis 在路飞学城里主要做两件事Django 的缓存后端和 Celery 的消息队列。最容易忽视的是 Redis 的持久化配置。默认环境下 Redis 只存在内存里一旦机器重启所有缓存和队列里的任务全部不见。我上线第一天就吃过这个亏后来用 RDB AOF 的组合策略保住了队列里尚未处理的任务。记住Redis 定位是缓存但现在被我们当成队列用了那持久化就不能按纯缓存的标准去评估。3. 生产环境部署关键步骤3.1 服务器与环境初始化正式部署路飞学城那天我从服务器初始化开始记录每一步操作。买的这台 Linux 服务器第一步是创建专用的系统用户不要用 root 直接跑应用。原因很简单万一应用被攻击攻击者拿到的权限就越小越好。# 创建用户并设置主目录 sudo useradd -m -s /bin/bash luffy sudo passwd luffy然后把项目代码 push 到发布目录sudo mkdir -p /data/www/luffy sudo chown -R luffy:luffy /data/www/luffy接着安装系统依赖。Django 项目通常会需要一些编译类的库比如 Pillow 处理图片它依赖 libjpeg、zlib 等。这一步我用 apt 直接装掉免得后面编译源码的时候四处报错。sudo apt-get update sudo apt-get install -y python3-dev default-libmysqlclient-dev build-essential vim nginxPython 的部分我不直接装到系统环境而是用虚拟环境隔离。路飞学城的依赖锁定在 requirements.txt 里装包前先升级 pip装完后顺手导出一份 freeze给团队留个最真实的依赖快照。cd /data/www/luffy python3 -m venv venv source venv/bin/activate pip install --upgrade pip pip install -r requirements.txt3.2 数据库创建与项目配置调整MySQL 装好后第一步建立业务库和专用账号。注意账号权限不要直接给 all privileges按需授权即可。CREATE DATABASE luffy DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; CREATE USER luffy_applocalhost IDENTIFIED BY 请改成强密码; GRANT ALL PRIVILEGES ON luffy.* TO luffy_applocalhost; FLUSH PRIVILEGES;Django 的 settings.py 有几处必须改。第一个是 DEBUG必须设为 False不然出错时会直接把整个堆栈和配置信息渲染在浏览器里严重的信息泄露风险。第二个是 ALLOWED_HOSTS改成域名或服务器 IP。第三个是数据库引擎配置确认连接池和超时参数合理。静态文件路径需要规划清楚方便 Nginx 后面映射。然后依次执行数据库迁移和数据初始化python manage.py makemigrations python manage.py migrate python manage.py collectstatic --noinput这里有一个特别容易踩的坑collectstatic 一定要在 Nginx 配置好静态目录之前做否则你明明看到 Nginx 配了路径但页面就是样式全丢怀疑配置半天结果发现是静态文件还没收集到指定目录。建议把顺序固定下来先收集、再配 Nginx。3.3 前端构建与静态资源处理路飞学城的前端是 Vue 项目上线前要在本地或 CI 环境执行构建生成 dist 目录。dist 里都是压缩混淆过后的 HTML、CSS、JS 文件。构建命令一般是npm run build构建完成后把 dist 目录里的文件整体上传到服务器的指定目录我放在 /data/www/luffy_frontend/dist。这外表看起来很简单但有几个细节影响后续联调体验。第一个是前端接口地址。开发时前端发请求一般指向 localhost:8000构建进生产包后这个地址必须改成后端 API 的完整路径比如 https://api.你的域名.com否则上线后前端调接口全部 404。第二个是 Vue Router 如果是 history 模式Nginx 需要做 try_files 重写把所有非文件请求都转到 index.html否则你刷新一下页面Nginx 就会返回 404。3.4 Nginx 配置要点Nginx 配置是整个上线过程中最值得反复斟酌的部分。我在路飞学城上用的是两个 server 块一个 server 专门负责后端 API另一个负责前端静态页面。后端 API 的反代配置大致是这样server { listen 80; server_name api.luffy.example.com; client_max_body_size 20m; location / { proxy_pass http://127.0.0.1:8000; 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 60s; proxy_read_timeout 60s; proxy_send_timeout 60s; } }前端页面用另一个 server 托管核心是根目录指向 dist并在 location / 里配置 try_filesserver { listen 80; server_name luffy.example.com; root /data/www/luffy_frontend/dist; index index.html; location / { try_files $uri $uri/ /index.html; } location /assets/ { expires 7d; add_header Cache-Control public; } }静态资源加 7 天缓存是很实用的操作因为构建后的文件名带 hash内容变了文件名也会变不会出现缓存旧文件的问题。3.5 用 systemd 托管后端进程路飞学城的后端进程我用 systemd 来管理没有直接 nohup 扔后台。nohup 的缺点是进程挂了没人管也不方便查看状态和开机自启。systemd 可以用一段 unit 文件把进程生命周期管起来崩溃了自动重启服务器重启也能自动拉起。[Unit] DescriptionLuffy Learning Platform Backend Afternetwork.target mysql.service redis-server.service [Service] Userluffy Groupluffy WorkingDirectory/data/www/luffy ExecStart/data/www/luffy/venv/bin/gunicorn config.wsgi:application -w 9 -b 127.0.0.1:8000 --timeout 60 Restartalways RestartSec3 [Install] WantedBymulti-user.target保存到 /etc/systemd/system/luffy-backend.service 后执行 daemon-reload 再启动服务。启动后的状态检查、重启命令也要一并记下来方便后面排查sudo systemctl daemon-reload sudo systemctl enable luffy-backend sudo systemctl start luffy-backend sudo systemctl status luffy-backendCelery worker 也可以用 systemd 单独托管不然异步任务和主服务是割裂的哪天 worker 挂了你还在傻等邮件发送成功。4. 上线时遇到的真实坑和排查过程4.1 登录页样式全丢静态文件 404路飞学城正式对外开放的第一个晚上我打开浏览器输入域名页面确实出来了HTML 结构都有但 CSS 和 JS 全部加载失败。F12 一看network 面板里全是 404。刚开始我怀疑是 Nginx 的 root 配错了。检查了一遍 root 路径dist 目录存在文件也在权限也正常但仍然 404。最后发现问题出在 collectstatic 的顺序上。Django 项目的静态文件不仅包括前端构建产物还包括 admin 后台的静态资源。我只顾着管理前端 dist没注意 Django 后台的静态文件压根没有收集到指定目录。执行 collectstatic 时又因为某个权限问题跳过了一半文件admin 的样式全部缺失。处理方式很机械但有效把整个 dist 清空重新执行 collectstatic再重启 Nginx。这个问题的教训是上线检查清单里必须有一条“访问页面并查看网络面板确认所有静态资源返回 200”。肉眼看到页面有内容不代表资源加载正常。4.2 页面偶发 502Gunicorn 进程集体卡死上线第三天开始有用户反馈部分页面要么转圈很久要么直接出现 502。我打开 Nginx 日志错误日志里刷屏的是connect() to 127.0.0.1:8000 failed (111: Connection refused) while connecting to upstream这通常代表后端进程没在监听端口或者进程挂了。systemctl status luffy-backend 一查Gunicorn 确实在运行但响应极慢。再翻 Django 日志发现大量请求堆积在数据库查询上。问题原因是某个课程列表接口没有正确使用 Redis 缓存每次点击首页都打了全表查询把数据库连接池占满。解决思路分两步。第一步先从代码层面修复给这个接口加缓存装饰器设置过期时间可以把核心数据的 Redis 命中率提到 90% 以上。第二步在 Gunicorn 配置里加超时限制防止个别慢请求长时间占据 worker拖垮整个进程组。其实 502 真正的原因往往不是 Nginx而是后端慢查询和资源耗尽。4.3 MySQL 连接频繁报 2006 gone away另一个高频错误是 MySQL 的 “2006, MySQL server has gone away”。这个错在路飞学城刚部署时几乎每天都能看到。排查后定位到两个原因。第一个原因是 wait_timeout 设置太短。MySQL 默认的 wait_timeout 是 8 小时但 Django 的数据库连接池里那些长期没有新请求的连接超过时间后被 MySQL 服务端主动断掉。后续请求再用这个空闲连接就会直接 gone away。解决方式是延长 MySQL 的 wait_timeout并在 Django 的连接配置里设置 CONN_MAX_AGE让连接生命周期小于 MySQL 的超时时间。第二个原因是大批量数据操作导致报文超过 max_allowed_packet。管理员批量导入课程封面时图片 base64 字符串特别长单条 SQL 超出限制就会触发 2006。把 max_allowed_packet 从默认的 4M 调整到 64M问题就消失了。4.4 Redis 队列安静地丢任务路飞学城有一个功能是用户下单后异步发送学习资料到邮箱。上线后我发现部分订单根本没有收到邮件查了很久才意识到 Celery 的 worker 进程没有随系统启动。我起初以为只要后端跑起来了异步任务就会自动消费结果 worker 根本就没拉起来Redis 里的任务越堆越多最终被内存淘汰机制清掉。后来我把 Celery worker 的 systemd 托管补上并把日志接入同一个日志目录。顺手加了一个每小时的定时任务检查 Redis 队列长度超过阈值就报警。这个坑对我的启发很大异步任务链路的健康度不能等到用户反馈邮件没到才发现必须有监控。4.5 上线排错工具清单如果你没有现成的监控平台至少要熟练使用下面这些命令。它们就够排查大多数问题了。现象常用命令或日志位置服务不响应systemctl status luffy-backend; journalctl -u luffy-backend -f502 网关错误tail -f /var/log/nginx/error.log404 静态资源检查 Nginx access log 和 root 路径一致性数据库断连tail -f /var/log/mysql/error.log; show processlist;队列积压redis-cli llen celery 或对应的队列名内存不足free -m; dmesg | tail -20;5. 上线后的监控、备份与回滚策略5.1 用简单命令搭一套“人工监控”正式环境的监控体系当然可以上 Prometheus 和 Grafana 那套全家桶。但路飞学城初期没有那么重的运维投入我先用最简单的脚本 crontab 搭了一套“人工监控”性价比极高。首先是健康检查脚本定期访问一个后端健康检查接口比如 /health/ 这个接口内部会连一次 MySQL 和 Redis确保依赖层都正常。如果连续三次失败脚本就调用 systemctl restart luffy-backend自动拉起服务并把异常记录到文件。#!/bin/bash status$(curl -s -o /dev/null -w %{http_code} http://127.0.0.1:8000/health/) if [ $status ! 200 ]; then echo $(date) health check failed: $status /var/log/luffy/health.log systemctl restart luffy-backend fi再配合 crontab每五分钟执行一次。这种做法在项目规模不大时特别实用虽然是“人工监控”但至少把故障响应时间从用户投诉后的一小时缩短到了五分钟内。5.2 数据库备份数据是最贵的资产路飞学城上线前团队内部对“服务挂了可以重启代码错了可以回滚数据丢了怎么办”达成了共识数据必须每天定时全量备份同时开启 binlog 做增量点。MySQL 全量备份我用 mysqldump压缩后保存在独立目录并保留最近 14 天版本mysqldump -uluffy_app -p luffy --single-transaction --quick --routines | gzip /data/backup/luffy_$(date %Y%m%d_%H%M%S).sql.gz find /data/backup -name luffy_*.sql.gz -mtime 14 -delete这个命令里的 --single-transaction 很关键它可以在不锁全表的情况下完成 InnoDB 表的逻辑备份线上业务基本无感知。定期找个冷门时间点实际演练一次还原而不是备份完就扔在那否则真到要恢复的时候才发现备份文件是坏的那才叫欲哭无泪。5.3 一键回滚把新版本变成“软链接切换”路飞学城的前端版本回滚我采用了一个很简洁的方案发布目录不做原地覆盖而是按版本号建目录再用软链接指向当前版本。# 当前版本 /data/www/luffy_frontend/releases/v1.2.3 # 软链接 /data/www/luffy_frontend/current - /data/www/luffy_frontend/releases/v1.2.3Nginx 的 root 指向 /data/www/luffy_frontend/current。发布新版本的时候先构建新的 release 目录测试没问题后把 current 软链接切到新版本再执行 nginx -s reload。如果新版本有问题软链接一秒钟切回旧版本等于实现了“秒级回滚”。这个思路也可以推广到后端代码核心就是避免原地覆盖。路飞学城后端我用 Git tag 管理版本回滚时在发布目录里 checkout 上一个 tag再重启服务整个过程不超过三分钟。上线这条路很多知识不是看文档能真正理解的。我在路飞学城上线的过程中体会最深的一件事就是几乎所有故障都不是单一原因造成的而是某个看似不起眼的配置项叠加了另一个没被重视的边界条件最后在流量压力下一起爆发。所以不要怕踩坑要有意记录每一次故障的排查过程慢慢形成自己的运维感觉。如果你也正在准备自己的第一个项目上线先把这篇文章里的基础配置跑通把备份、监控、回滚三件事补齐大概率能避开 80% 以上的常见问题。