uWSGI启动必备socket、module和callable参数;module需填模块名:实例名(如app:app),非文件名;socket须用绝对路径并设chmod-socket=666;需启用master=true和processes=2;Nginx须用uwsgi_pass直连Unix socket,正确设置proxy_set_header和proxy_buffering off。

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透传——这三个点串不起来,配置写得再漂亮也没用。










