Flask部署NginxuWSGI配置教程

本文深入解析了Flask应用通过uWSGI与Nginx部署的核心配置要点，直击新手高频踩坑场景：uWSGI启动必备的socket（绝对路径+chmod-socket=666）、module（模块名:实例名，非文件名）和callable参数缺一不可；Nginx必须用uwsgi_pass直连Unix socket而非proxy_pass，并精准设置proxy_set_header、关闭proxy_buffering以保障IP透传与流式响应；同时澄清常见误区——uWSGI不应启用http模式而应使用原生uwsgi协议，避免端口冲突与性能损耗；最后提供502错误的三步快速定位法，聚焦socket文件状态、进程用户权限和header转发链路，真正帮你把“部署成功”从玄学变成可验证、可复现的确定性结果。

uWSGI配置文件里哪些参数不能少

不写对socket、module和callable，uWSGI根本起不来。常见错误是把app.py当模块名直接填进module，结果报ImportError: No module named 'app.py'——它要的是模块路径，不是文件名。

• module填app:app（假设Flask实例叫app，且在app.py里），不是app.py:app
• socket必须用绝对路径，比如/tmp/myapp.sock；如果写相对路径，uWSGI默认在当前工作目录找，但启动时工作目录不可控
• 加chmod-socket = 666，否则Nginx可能因权限不足连不上.sock文件
• 别漏master = true和processes = 2，否则单进程扛不住真实请求，又没主进程管理

Nginx反向代理配置的关键字段

配错proxy_pass后面跟的地址，或者忘了清空proxy_set_header，就会出现400错误、静态文件404、或request.remote_addr全变成127.0.0.1。

• proxy_pass末尾带/（如http://unix:/tmp/myapp.sock:/）才能正确转发路径；不带会导致URL多一层myapp/前缀
• 必须显式设置proxy_set_header Host $host;和proxy_set_header X-Real-IP $remote_addr;，不然Flask收不到原始域名和用户IP
• 加proxy_buffering off;避免uWSGI流式响应（比如SSE或大文件下载）被Nginx缓存卡住

为什么uWSGI和Nginx都监听localhost:8000会冲突

这是新手最常踩的坑：以为uWSGI开http = :8000再让Nginxproxy_pass http://127.0.0.1:8000更简单，结果发现Nginx日志里全是Connection refused。

• uWSGI默认不开启HTTP协议栈，http参数是额外开一个HTTP服务器，和它的主worker无关，性能差还绕过Unix socket优势
• 真正该用的是socket = /tmp/myapp.sock + protocol = uwsgi（默认值），然后Nginx用uwsgi_pass直连，不是proxy_pass
• 如果硬要用HTTP模式，得加http-socket = :8000，但http和http-socket不能共存，否则启动失败

部署后502 Bad Gateway的三秒定位法

不是先改配置，而是按顺序查这三项，90%的情况当场解决：

• 运行ls -l /tmp/myapp.sock，看文件是否存在、权限是否为srw-rw-rw-；不存在说明uWSGI根本没跑起来，去journalctl -u myapp看启动日志
• 运行ps aux | grep uwsgi，确认进程用户和Nginx worker用户一致（通常是www-data或nginx），否则socket文件创建后Nginx无权读
• 临时把Nginx配置里的uwsgi_pass改成127.0.0.1:8000并重启uWSGI（加http-socket = :8000），能通就证明是socket路径或权限问题，不是代码逻辑问题

Unix socket路径、用户权限、header透传——这三个点串不起来，配置写得再漂亮也没用。

今天带大家了解了的相关知识，希望对你有所帮助；关于文章的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~