配置Gitlab与Jenkins Webhook时触发HTTP 502错误的解决与排查

问题本质 #

502 Bad Gateway是Nginx作为反向代理时，无法将GitLab的Webhook请求转发到后端Jenkins服务导致的，核心是Nginx与Jenkins之间的连通性或配置存在问题。

排查步骤 #

• 直接验证Jenkins本地可达性
  登录部署Nginx的服务器，执行命令：

  curl http://localhost:你的Jenkins端口/gitlab/build_now
  

  若返回Jenkins的响应（哪怕是权限错误），说明Jenkins服务正常；若返回Connection refused或超时，证明Jenkins未启动、端口未监听，需先修复Jenkins服务。

• 检查Nginx反向代理配置
  打开Jenkins对应的Nginx配置文件（通常在/etc/nginx/sites-available/或/etc/nginx/conf.d/目录下），重点核对：

  • proxy_pass指令指向的Jenkins地址是否正确（如http://127.0.0.1:8080，避免使用可能解析失败的域名）
  • 是否配置了必要的请求头，比如：

    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    

  • 查看Nginx错误日志（/var/log/nginx/error.log），日志中会明确失败原因，比如connect() failed (111: Connection refused)代表Jenkins端口未开放。

• 核对GitLab Webhook URL正确性
  确认GitLab中填写的Webhook URL是Nginx对外暴露的合法地址，路径需与Jenkins GitLab插件的接收路径一致（默认是/gitlab/build_now），禁止直接填写Jenkins内网端口（GitLab无法访问内网资源）。

• 排查网络与防火墙限制
  若Jenkins与Nginx分属不同服务器，在Nginx服务器上执行：

  telnet 你的Jenkins服务器IP Jenkins端口
  

  若无法连通，需在Jenkins服务器的防火墙/安全组中开放对应端口；同时确认GitLab服务器能访问Nginx的对外端口。

• Jenkins服务与插件排查
  查看Jenkins主日志（/var/log/jenkins/jenkins.log），确认是否有启动异常或请求接收记录：

  • 若日志中无GitWebhook请求痕迹，说明请求未到达Jenkins，问题出在Nginx或网络层面；
  • 确认com.dabsquared.gitlabjenkins插件已正确安装并启用，可尝试重装插件后重启Jenkins。

快速修复尝试 #

• 重启Nginx与Jenkins服务：

  sudo systemctl restart nginx
  sudo systemctl restart jenkins
  

• 在Nginx代理配置中添加超时设置，避免请求被提前截断：

  proxy_connect_timeout 60s;
  proxy_send_timeout 60s;
  proxy_read_timeout 60s;
  

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