上周把一个Flask项目从开发环境往生产迁折腾到深夜最后卡住我的就是uWSGI和nginx这对组合。以前我一直觉得uWSGI配置项又多又绕一堆参数看半天不知道在讲什么远不如gunicorn来得清爽。但真正上手之后才发现只要你理解了它的进程模型和通信方式uWSGI的每一条配置都是有理由的配合nginx做静态资源分离性能天花板也明显更高。这篇就把我从零部署uWSGI、再接到nginx后面的整个过程整理出来包括systemd托管、权限处理、踩坑链路适合刚接触Python Web项目部署的朋友参考也适合团队里需要有人把部署这块扛起来的同学。1. 为什么选uWSGIWSGI协议、进程模型与Gunicorn对比1.1 WSGI协议到底解决了什么问题在聊uWSGI之前得先把WSGI这个概念说清楚。你在Flask或Django里写的视图函数本质上是接收一个HTTP请求、返回一个HTTP响应。但应用本身不会直接监听端口它是被一个应用服务器调用的。WSGIPython Web Server Gateway Interface就是Python社区定义的一套接口规范它规定了应用服务器如何把请求数据传给Python应用以及应用如何把响应结果交还给服务器。所以前端nginx接收到浏览器请求后并不会直接去找你的Flask代码而是把请求转发给uWSGI这样的应用服务器uWSGI再把请求按WSGI标准翻译成environ字典和一个start_response回调交给你的应用。反过来应用的返回值也经过uWSGI再传回nginx。理解这条链路后面看任何配置文件都不会懵。1.2 uWSGI的进程模型master、worker、threads三者关系uWSGI之所以在配置上显得复杂是因为它的进程模型不是单一的。运行起来后你会看到一个master进程若干个worker进程每个worker里还可以开多个threads。master进程不处理业务它只负责管理worker监听信号、拉起挂掉的worker、在reload时保持服务不中断。真正干活的是worker进程每个worker都是独立的Python解释器互不共享内存。而每个worker内部的threads则是共享解释器状态的线程适合处理IO密集操作比如数据库查询等待、外部API调用这时候线程可以把时间片让给别人。进程和线程的搭配本质上是在CPU核心数、内存占用、并发能力之间找平衡。如果进程数开太多每多一个进程就多一份Python解释器的内存开销如果全开线程又要面对Python的GIL限制。所以常规做法是少量进程 适量线程的混合模式。1.3 为什么有人用uWSGI有人用GunicornGunicorn是纯Python实现的WSGI服务器配置简单上手快小项目或者内部系统用起来很舒服。uWSGI是用C实现的功能面广得多除了WSGI服务还能做静态文件服务、cron调度、各种协议转发性能调优的旋钮也非常多。我的观点是如果你的项目并发不高、团队里没人愿意研究部署细节gunicorn足够。但如果你要扛住真实的生产流量或者已经有nginx在前面做负载和缓存那uWSGI和nginx的uwsgi协议配合是经过大规模验证的成熟方案。后面我会详细说明这个uwsgi协议和普通HTTP转发有什么区别。2. 部署前的准备安装、虚拟环境与编译依赖2.1 依赖清单用apt还是yum先装对编译工具uWSGI本质是一个C扩展pip安装时需要编译所以环境里必须有Python的头文件和相关编译工具。这一步漏掉的报错信息非常典型Python.h: No such file or directory。看到这个就是系统里缺少python3-dev或python3-devel包。以Ubuntu/Debian系为例sudo apt update sudo apt install -y build-essential python3-dev python3-venvCentOS/RHEL系则是sudo yum install -y gcc python3-devel装完编译依赖后我习惯先建一个项目专用目录再创建虚拟环境。虚拟环境的作用是隔离项目依赖避免把系统Python环境搞乱尤其是一台机器上跑多个Python项目时。sudo mkdir -p /opt/www/myapp sudo chown -R $USER:$USER /opt/www/myapp cd /opt/www/myapp python3 -m venv venv source venv/bin/activate2.2 pip安装与源码编译安装怎么选绝大多数情况pip install uwsgi就够了。它会自动下载源码包并在本机编译生成一个可直接执行的uwsgi二进制文件。为了可复现我通常固定版本号pip install uwsgi2.0.26 uwsgi --versionuwsgi --version能打印出版本号就算装成功了。如果提示找不到命令先确认你是不是在虚拟环境里以及用的是不是venv/bin/uwsgi。源码编译安装主要出现在两个场景一是需要给uWSGI打自定义补丁或启用特殊插件二是某些离线内网环境没法直接pip。那种情况下需要把源码包拷贝到目标机器执行make再手动安装。对绝大多数项目来说没有这个必要。2.3 虚拟环境与uWSGI的绑定关系这里有个特别容易踩的坑你用系统自带的uwsgi命令启动项目基本都会报ModuleNotFoundError因为系统uWSGI解释器看到的Python环境是系统级的它不认你的venv。正确的做法是把venv/bin/uwsgi当作启动程序同时在uWSGI配置里通过virtualenv参数显式指定虚拟环境路径这样worker进程加载项目代码时才能正确导入Flask、Django等依赖。记住这个原则uWSGI运行时的Python环境必须和你项目依赖所在的虚拟环境一致。后面写的配置里会反复体现这一点。3. 第一个uWSGI实例ini配置逐个参数讲清楚3.1 先准备一个最小可运行的应用为了把注意力集中在部署本身我写一个最简单的Flask应用# app.py from flask import Flask app Flask(__name__) app.route(/) def index(): return Hello, uWSGI nginx如果你连Flask都不想装也可以用Python标准库的WSGI应用# app.py def application(environ, start_response): status 200 OK headers [(Content-type, text/plain; charsetutf-8)] start_response(status, headers) return [bHello, uWSGI]这里有个概念要区分module app这种写法是把app.py当作Python模块导入而wsgi-file /path/to/app.py是直接加载文件不要求文件在sys.path里。我建议生产配置用modulechdir组合因为模块方式更符合Python的导入逻辑也方便后续加包路径。3.2 命令行启动参数先理解每个参数再上配置文件先从最简单的命令行方式启动这样能直观看到每个参数的作用uwsgi --http 127.0.0.1:8080 --module app --callable app --virtualenv /opt/www/myapp/venv --processes 4 --threads 2--http 127.0.0.1:8080以HTTP模式监听8080端口。这种模式适合本地验证因为浏览器直接就能访问。但生产环境不要用这个模式对接nginx后面会讲为什么。--module app加载app.py这个模块。--callable app模块里WSGI可调用对象的名字。Flask的实例名是appDjango项目一般是application所以Django启动时通常是--module project.wsgi:application。--virtualenv指定虚拟环境路径。--processes 4启动4个worker进程。--threads 2每个worker内部开2个线程。启动后直接在浏览器访问http://127.0.0.1:8080看到Hello就说明uWSGI本身工作正常。这时把--http换成--socket /run/uwsgi/myapp.sock再让nginx来转发就进入生产模式了。3.3 正式ini配置每行都说明白命令行参数一多就难维护所以生产环境我习惯写一个uwsgi.ini放到项目目录代码和配置放在一起也方便走版本管理。[uwsgi] project myapp base /opt/www/myapp chdir %(base) module app callable app virtualenv %(base)/venv master true processes 4 threads 2 thunder-lock true socket /run/uwsgi/myapp.sock chmod-socket 660 vacuum true uid www-data gid www-data die-on-term true harakiri 60 max-requests 2000 reload-on-rss 192 logto /var/log/uwsgi/myapp.log logdate true pidfile /run/uwsgi/myapp.pid逐个解释chdiruWSGI启动前先进入这个目录相当于命令行里的cd这样module app才能正确找到app.py。master true开启master进程。这是生产环境的必须项它的意义在于reload时master能平滑拉起新worker旧worker处理完当前请求再退出用户无感知。thunder-lock多个worker同时被唤醒时防止惊群配合master开启。请求量一大这个参数能减少不必要的上下文切换。socket监听Unix socket文件而不是HTTP端口。Unix socket比TCP loopback性能更好而且不会暴露到外部网络只给本机nginx访问。chmod-socket 660给socket文件设置权限。nginx进程要能访问这个文件660表示属主和属组有读写权限。这里搭配后面的uid/gid让uWSGI和nginx运行在同一个用户/组下权限问题最省心。vacuum trueuWSGI退出时自动删除socket文件和pid文件避免残留脏文件。die-on-term true收到SIGTERM信号时直接退出。这个参数在systemd和Docker场景下特别重要不然容器或服务停止时uWSGI可能不响应终止信号。harakiri 60单个请求如果超过60秒还没处理完强制杀掉worker。防止某个慢请求把整个worker拖死。max-requests 2000每个worker处理完2000个请求后自动重启。Python项目跑久了容易有内存缓慢上涨的问题这个参数是兜底手段。reload-on-rss 192worker的常驻内存RSS超过192MB就自动重载。这个数值可以按项目实际内存占用去调我一般先看free -m再结合top观察正常运行时的内存水位设成1.5倍左右。logto logdate把日志输出到文件并带时间戳。启动方式变成uwsgi --ini /opt/www/myapp/uwsgi.ini如果没有输出错误用ps aux | grep uwsgi能看到master和4个worker进程同时/run/uwsgi/目录下会生成myapp.sock文件。4. systemd托管uWSGI生产环境下进程的生老病死4.1 为什么不用nohup而是在systemd里管手动启动的uWSGI终端一关进程就没了机器一重启还得手动拉起。生产环境要做的是开机自启、崩溃自动拉起、日志统一管理。systemd就是干这个的现在的Linux发行版基本都内置比写rc.local和crontab靠谱得多。4.2 编写unit文件在/etc/systemd/system/myapp-uwsgi.service下新建服务文件[Unit] DescriptionuWSGI instance for myapp Afternetwork.target [Service] Userwww-data Groupwww-data WorkingDirectory/opt/www/myapp RuntimeDirectoryuwsgi EnvironmentPATH/opt/www/myapp/venv/bin ExecStart/opt/www/myapp/venv/bin/uwsgi --ini /opt/www/myapp/uwsgi.ini Restartalways KillSignalSIGQUIT Typenotify NotifyAccessall NoNewPrivilegestrue PrivateTmptrue [Install] WantedBymulti-user.target几个关键设计Userwww-data / Groupwww-data让uWSGI以www-data用户运行。Ubuntu上nginx的worker默认也是www-data这样socket文件的属主/属组和nginx保持一致权限配置最简单。CentOS上nginx用户一般是nginx要按实际发行版调整。RuntimeDirectoryuwsgisystemd会在/run/uwsgi自动创建目录服务停止后自动清理。这个比你自己mkdir -p /run/uwsgi好使因为/run是tmpfs临时文件系统重启机器后就清空手动建的目录每次开机都得重建。ExecStart执行的是虚拟环境里的uwsgi二进制不是系统的。这样Python环境就锁定了。Restartalways进程异常退出时自动拉起。KillSignalSIGQUITuWSGI收到SIGQUIT时做优雅停止处理完当前请求再退出。systemd默认发SIGTERM而uWSGI对SIGTERM的默认行为不一定合规这里显式指定最稳。TypenotifyuWSGI在启动完成、可以接受请求时会通过sd_notify通知systemd。这样systemctl start命令会等到uWSGI真正就绪才返回比盲目sleep几秒可靠得多。注意要用notify类型uWSGI必须开启master模式我们在ini里已经开了。NoNewPrivilegestrue和PrivateTmptrue安全加固选项限制进程提权能力并隔离临时目录属于部署时的基本卫生习惯。另外我在uWSGI配置里已经写了die-on-term true这和systemd的进程管理配合起来就是一个完整的生命周期启动、运行、优雅停止、崩溃拉起、开机自启。4.3 日志管理文件方式和journalctl怎么选uWSGI的logto会把日志写到文件这在手动部署时很好用。但既然交给了systemd我更推荐把uWSGI.ini里的logto和logdate注释掉让它把日志输出到标准输出这样systemd会自动收集到journal日志里。sudo systemctl daemon-reload sudo systemctl start myapp-uwsgi sudo systemctl enable myapp-uwsgi sudo systemctl status myapp-uwsgi journalctl -u myapp-uwsgi -fjournalctl -u myapp-uwsgi -f相当于实时滚动的日志尾巴不需要再去tail -f /var/log/uwsgi/myapp.log。如果要持久化journal日志改/etc/systemd/journald.conf里的Storagepersistent即可。如果你还是习惯传统日志文件保留logto也完全可以但要注意日志目录的写权限/var/log/uwsgi/必须允许www-data用户写入否则uWSGI启动时就会报Permission denied。5. nginx侧配合uwsgi_pass、静态资源与反向代理5.1 nginx和uWSGI的分工nginx在前、uWSGI在后两者不是竞争关系而是分工。nginx负责接收HTTP连接、处理静态文件、做访问控制、负载均衡、TLS终止uWSGI专门跑Python应用。静态文件请求图片、CSS、JS直接由nginx从磁盘返回根本不进Python进程这样宝贵的worker进程只处理动态逻辑。5.2 uwsgi_pass和proxy_pass的区别nginx转发到后端有两种常见方式proxy_pass走HTTP协议uwsgi_pass走uwsgi协议。uwsgi协议是uWSGI服务器自定义的二进制协议比HTTP更加紧凑少了大量HTTP头部的重复解析开销而且nginx对它有原生支持。配置一个站点时先建配置文件。Ubuntu习惯放在/etc/nginx/sites-available/下CentOS放在/etc/nginx/conf.d/下按发行版的习惯来就行。server { listen 80; server_name example.com; client_max_body_size 100m; location /static/ { alias /opt/www/myapp/static/; expires 30d; access_log off; } location /media/ { alias /opt/www/myapp/media/; } location / { include uwsgi_params; uwsgi_pass unix:///run/uwsgi/myapp.sock; uwsgi_read_timeout 60s; uwsgi_send_timeout 60s; uwsgi_ignore_client_abort on; } }核心是这一行uwsgi_pass unix:///run/uwsgi/myapp.sock;它告诉nginx把所有非静态请求通过uwsgi协议发送给那个Unix socket。uWSGI和nginx在同一台机器上时用Unix socket比TCP端口少一层网络栈开销性能更好。include uwsgi_params;会自动把请求的URI、User-Agent等参数以uwsgi协议的格式传给后端。这个文件通常位于/etc/nginx/uwsgi_params内容不需要你操心include进来就行。如果后端是通过TCP端口通信的比如uWSGI配置里写的是socket 127.0.0.1:3031那么nginx对应写成uwsgi_pass 127.0.0.1:3031;但我个人强烈建议同一台机器用Unix socket省掉TCP连接管理的开销。5.3 静态资源的alias和root差异静态文件配置看起来简单实际上alias和root的区别最容易翻车。location /static/ { alias /opt/www/myapp/static/; }请求/static/css/app.css时nginx会把location匹配到的/static/部分替换成alias后面的路径实际读取/opt/www/myapp/static/css/app.css。如果把alias换成rootlocation /static/ { root /opt/www; }请求/static/css/app.css时nginx不替换URI而是直接拼在root路径后面实际读取/opt/www/static/css/app.css。一句话总结root是把URI拼在根路径后alias是把匹配前缀替换成指定路径。用错的结果就是静态文件404后面我会讲排查方法。5.4 加一层upstream为多worker或横向扩展做准备单机场景下uwsgi_pass unix:///run/uwsgi/myapp.sock;直接指向socket就够了。但如果一台机器上有多个uWSGI实例比如同一个服务按项目拆分或者想用多socket分担压力可以用upstream定义后端池upstream uwsgi_backend { server unix:///run/uwsgi/myapp.sock; server 127.0.0.1:3031; } server { listen 80; server_name example.com; location / { include uwsgi_params; uwsgi_pass uwsgi_backend; } }upstream还可以配置权重、备胎节点这在后面做多实例部署或滚动发布时非常方便。我这个项目暂时只有一个实例但配置先留着后面扩容只改nginx不需要动应用。配置写好后先做语法检查再优雅重载nginx -t nginx -s reloadnginx -t通过后reloadnginx会平滑地应用新配置正在处理的请求不会中断。6. 上线踩坑实录从502到静态文件404的完整排查链路6.1 502 Bad Gateway先分清是nginx连不上uWSGI还是uWSGI本身挂了上线第一个晚上我就遇到了502页面一片空白。这里我要分享一个完整的排查思路而不是直接给答案。第一步看uWSGI进程是否活着systemctl status myapp-uwsgi如果显示active (running)说明uWSGI没挂那问题大概率出在nginx和uWSGI之间的连接上。第二步看nginx错误日志tail -f /var/log/nginx/error.log我当时看到的是这一行connect() to unix:///run/uwsgi/myapp.sock failed (13: Permission denied) while connecting to upstream问题很清楚nginx没有权限访问socket文件。执行ls -l /run/uwsgi/myapp.sock验证srw-rw-r-- 1 www-data www-data 0 Jul 20 10:30 myapp.sock文件属主是www-data权限是664。如果nginx的worker进程不是www-data而是nginx用户或者systemd服务里uWSGI用了别的uid就会触发权限拒绝。解决方式有两种。一种最省事但也最不推荐把chmod-socket改成666任何进程都能写这个socket相当于把门锁拆了非常危险。正规做法是保证nginx worker和uWSGI运行在同一个组下然后chmod-socket 660再确保/run/uwsgi目录允许nginx用户进入。我在systemd服务里把User和Group都设成www-dataUbuntu nginx默认worker也是www-data两边就对齐了。6.2 换个排查角度socket文件根本不存在另一次502我自信满满检查权限结果发现/run/uwsgi/目录是空的socket文件压根没生成。原因是那台机器重启过而/run是tmpfs开机后目录被清空但uWSGI服务没有启动成功。这种情况下systemctl status会显示failed然后我去看journal日志journalctl -u myapp-uwsgi -f发现报错是chdir() to /opt/www/myapp failed原来项目目录的挂载盘没自动挂上。处理完挂载问题后uWSGI才正常起来。如果你的systemd服务里用了RuntimeDirectoryuwsgi要在启动时自动创建这行配置必须在[Service]段里和User设置配合好。6.3 静态文件404八成的锅都在alias和root页面能打开样式全丢了浏览器控制台一片红。先看一眼请求GET /static/css/app.css 404。这种问题我不建议先去改nginx配置文件反复reload而是先做定位curl -I http://127.0.0.1/static/css/app.css然后对比磁盘上文件的真实路径。如果文件确实存在于/opt/www/myapp/static/css/app.css但nginx返回404多半就是alias拼错了路径。排查手法很简单在nginx配置里加上debug级别的日志或者临时把alias改成对应路径试一下。更直接的是用nginx -t检查语法后用curl看响应头。如果返回404但access_log里显示的是200那可能是location匹配顺序的问题比如有别的location规则抢先把请求拦走了。我个人犯过的典型错误是把alias /opt/www/myapp/static/;末尾的斜杠漏了导致路径拼接变成/opt/www/myapp/static/css/app.css少了一层目录直接404。这类问题没法靠背参数解决就是要在实战里踩一遍才长记性。6.4 代码更新不生效uWSGI不重新加载模块部署新代码后刷新页面看到的还是旧版本。这个问题不属于nginx而是uWSGI默认会缓存已导入的Python模块不会每次请求都重新读代码。开发环境可以开py-autoreload但生产环境绝不能这么做代价太大。正确姿势是用touch-reload指定一个触发文件touch-reload /tmp/myapp.reload部署代码后执行touch /tmp/myapp.reloaduWSGI检测到文件mtime变化就会优雅地重启worker进程。或者直接用pid文件手动reloaduwsgi --reload /run/uwsgi/myapp.pid如果是通过systemd管理也可以直接systemctl restart myapp-uwsgi但这不是平滑重载正在处理的请求会被中断。对于重要的生产服务我建议还是用touch-reload做平滑重载。6.5 日志双写与日志权限的混乱之前我同时在uWSGI的ini里配了logto又在systemd里用Typenotify结果发现journalctl里只看到启动信息业务日志全去了文件。这本身没问题但排错时要记得两个地方都看。后来我干脆注释掉logto让日志统一走journalctl减少一个排查维度。如果你坚持用日志文件要注意/var/log/uwsgi/目录的所有者。我遇到过uWSGI启动直接失败报Permission denied打开日志文件的情况就是因为目录是root所有而服务以www-data身份运行。6.6 常见问题速查表症状可能根因排查命令或手段502 Bad GatewayuWSGI进程没起来systemctl status myapp-uwsgi502 Bad Gatewaysocket权限拒绝ls -l /run/uwsgi/myapp.sock nginx error.log502 Bad Gatewaysocket路径写错对比ini里socket路径和nginx里uwsgi_pass404 静态文件alias路径拼错curl -I 对比磁盘真实路径404 页面location顺序错误检查是否被其他location抢先匹配请求卡死直到超时某个worker被慢请求占住harakirimax-requests兜底内存持续上涨Python代码或第三方库泄漏reload-on-rss自动重启worker服务停止卡住uWSGI不响应SIGTERM开启die-on-term true7. 一点个人收尾我的UWSGI默认开局模板如果你不想从零开始研究我分享一个目前用得最顺的默认模板。单人维护的小项目我会在uWSGI.ini里固定写processes 2、threads 4因为大多数应用其实是IO密集数据库查询和外部API等待占大头线程比进程实惠。等通过top和日志观察到worker内存长期站上150MB以上我再加reload-on-rss上限值让进程在膨胀前自动重置。nginx侧我永远保留静态资源分离即使项目暂时没有多少静态文件也要把location /static/的配置位提前圈好。这样后面接入前端打包产物时只需要往目录里丢文件不用再改nginx结构。部署这套东西最核心的心得是不要试图一次把uWSGI所有高级参数都配上先跑通最小链路——nginx转发、socket连接、worker进程存在、日志有输出再逐步加超时保护、内存限制、自动重载这些保险丝。配置项越多排错时变量就越多。先把主链路走通剩下的都是锦上添花。