Nginx反向代理Python Web服务需独立运行Python进程（如uvicorn/gunicorn），绑定127.0.0.1，由nginx转发请求并处理静态文件、超时、Header透传及WebSocket升级头；502错误主因是后端未启动、连接超时或Docker网络配置不当。

nginx反向代理到Python Web服务（如Flask/FastAPI）

反向代理不是把Python代码扔进nginx，而是让nginx监听80/443端口，把HTTP请求转发给本地运行的Python服务（比如跑在127.0.0.1:8000的uvicorn或gunicorn）。关键在于：Python进程必须独立启动，nginx只做流量中转。

• 确保Python服务绑定127.0.0.1（不是0.0.0.0或localhost），避免暴露到公网；用netstat -tuln | grep :8000确认端口确实在监听
• nginx配置里proxy_pass末尾带不带/影响路径重写：proxy_pass http://127.0.0.1:8000/;会剥离前缀，proxy_pass http://127.0.0.1:8000;则原样转发
• 必须加proxy_set_header Host $host;和proxy_set_header X-Real-IP $remote_addr;，否则Python框架拿不到真实域名和客户端IP
• 超时要调大：Python服务可能有长任务，proxy_read_timeout 300;比默认60秒更稳妥

静态文件交给nginx直接服务，别让Python处理

Python框架（如Flask的send_from_directory）读文件再吐HTTP响应，既慢又占Python进程资源。nginx天生擅长零拷贝发送静态文件，应该完全接管。

• 前端构建产物（如dist/或static/）路径必须在nginx配置里用root或alias明确指向，且权限对nginx worker用户（通常是www-data或nginx）可读
• 区分root和alias：root /var/www/myapp; + location /static/ → 实际找/var/www/myapp/static/；alias /var/www/myapp/static/; + location /static/ → 实际找/var/www/myapp/static/（结尾斜杠必须一致）
• 加try_files $uri @python_backend;，让nginx先查文件是否存在，不存在才转给Python——这是前后端分离项目的标配
• 记得配expires 1y;和add_header Cache-Control "public, immutable";，避免重复请求JS/CSS

常见502 Bad Gateway的三个硬核原因

502不是nginx挂了，是它连不上后端Python服务。别急着重启nginx，先看这三处：

macOS UI 自动化技能包 —— 用 Python 控制你的 Mac

让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限

下载

• Connection refused：Python服务根本没起来，或端口不对；检查ps aux | grep uvicorn和curl -v http://127.0.0.1:8000/health
• Connection timed out：防火墙拦了回环通信（少见但存在），或Python服务卡死在启动阶段（比如数据库连接超时未设timeout）
• No route to host：Docker场景下，proxy_pass http://host.docker.internal:8000在Linux需手动配置，不能直接抄Mac写法；容器间通信优先用docker network别名

HTTPS下WebSocket支持要额外开两个header

如果Python服务用了WebSocket（如FastAPI的@app.websocket），纯HTTP反向代理会断连。nginx默认不透传升级头，必须显式放开。

立即学习“Python免费学习笔记（深入）”；

• 在location块里加：proxy_http_version 1.1;、proxy_set_header Upgrade $http_upgrade;、proxy_set_header Connection "upgrade";
• 缺任意一个，浏览器控制台就会报WebSocket connection to 'wss://...' failed，且Nginx error log里通常只有upstream prematurely closed connection
• 注意Connection header值必须是字面量"upgrade"（带引号），不是变量$connection——这是最常抄错的地方

部署真正卡点的从来不是配置语法，而是Python服务生命周期管理（怎么开机自启、崩溃后拉起、日志落盘）和nginx与Python之间那层TCP连接的语义对齐。这两块不稳，其他都白搭。