Flask Gunicorn应用对接Nginx出现502 Bad Gateway错误如何解决？

第一步：排查Gunicorn与业务应用的绑定问题 #

空Flask应用可正常对接说明Nginx到Gunicorn的基础链路无问题，故障点集中在业务应用对应的Gunicorn服务侧：

• 先终止所有运行中的Gunicorn进程：sudo pkill gunicorn
• 确认Gunicorn要监听的端口没有被其他进程占用：sudo lsof -i:你配置的监听端口，如果有进程占用可以用sudo kill -9 进程PID终止
• 前台启动绑定业务应用的Gunicorn进程，方便直接查看启动报错：gunicorn --bind 0.0.0.0:你配置的监听端口 业务应用入口文件名:Flask实例名
  • 注意业务应用入口文件名需要替换为你定义Flask实例的py文件名称（不带.py后缀），Flask实例名需要替换为你代码中xxx = Flask(__name__)对应的xxx变量名，大部分业务应用启动失败都是该参数和实际代码不匹配导致
• 启动后查看终端输出，存在报错直接对应解决：常见问题包括第三方依赖包未安装、环境变量未配置、数据库/缓存连接失败、代码语法错误，空测试应用无上述依赖所以可以正常启动
• 启动无报错后本地测试服务可用性：curl http://127.0.0.1:你配置的监听端口，返回正常再进入下一步排查，否则先解决Gunicorn侧的运行异常

第二步：核对systemd服务配置 #

如果前台启动Gunicorn正常，systemd托管后出现故障，检查对应.service配置文件：

• 确认WorkingDirectory参数值为业务应用的根目录，不要沿用测试应用的目录
• 确认ExecStart参数中的Gunicorn路径、业务应用入口、Flask实例名完全正确；如果使用虚拟环境，必须填写虚拟环境内Gunicorn的绝对路径，例如/home/用户名/项目目录/venv/bin/gunicorn
• 确认User参数配置的运行用户对业务应用目录有读取、执行权限
• 修改配置后执行sudo systemctl daemon-reload重载systemd配置，再执行sudo systemctl restart 你的服务名称重启服务
• 查看服务运行状态：sudo systemctl status 你的服务名称，查看服务运行日志：sudo journalctl -u 你的服务名称，排查启动及运行时异常

第三步：核对Nginx配置 #

如果Gunicorn侧运行完全正常，排查Nginx侧配置：

• 确认Nginx配置中proxy_pass的地址、端口/套接字路径，和Gunicorn实际监听的配置完全一致，不要沿用测试应用的配置
• 查看Nginx错误日志定位具体问题：sudo tail -n 30 /var/log/nginx/error.log，日志显示Connection refused说明Gunicorn未正常启动或监听地址不匹配，日志显示Connection reset by peer说明业务应用处理请求时触发崩溃
• 验证Nginx配置语法正确性：sudo nginx -t，校验通过后重载配置生效：sudo systemctl reload nginx

内容的提问来源于stack exchange，提问作者domx4q