GitLab 升级后 502：Puma 反复重启问题处理记录

晓恩h

360人浏览 · 2026-07-03 17:12:40

晓恩h · 2026-07-03 17:12:40 发布

一、问题现象

GitLab 升级后，页面访问返回：

502 Bad Gateway

查看服务状态：

gitlab-ctl status

大部分服务都是 run，但发现 puma 运行时间很短：

run: puma: (pid xxx) 9s

说明 puma 服务在反复重启，并没有真正稳定运行。

二、排查过程

查看 gitlab-workhorse 日志：

tail -n 100 /var/log/gitlab/gitlab-workhorse/current

发现报错：

dial unix /var/opt/gitlab/gitlab-rails/sockets/gitlab.socket:
connect: no such file or directory

说明 gitlab-workhorse 找不到 gitlab.socket。

GitLab Web 请求链路大致是：

nginx -> gitlab-workhorse -> puma -> GitLab Rails

gitlab.socket 是 Puma 启动成功后生成的。
现在 socket 不存在，说明 Puma 没有正常启动。

继续查看 Puma 日志：

tail -n 100 /var/log/gitlab/puma/current

发现核心报错：

TZInfo::DataSources::InvalidZoneinfoFile
The file '/usr/share/zoneinfo/zone_utc' does not start with the expected header.

由此判断：Puma 启动时加载系统时区文件失败，导致服务反复重启。

三、确认原因

检查时区文件：

file /usr/share/zoneinfo/zone_utc
file /usr/share/zoneinfo/UTC
file /usr/share/zoneinfo/Etc/UTC

返回类似：

/usr/share/zoneinfo/zone_utc: UTF-8 Unicode text
/usr/share/zoneinfo/UTC: timezone data
/usr/share/zoneinfo/Etc/UTC: timezone data

正常时区文件应该是 timezone data，但 /usr/share/zoneinfo/zone_utc 是普通文本文件。

所以根因是：

/usr/share/zoneinfo/zone_utc 文件异常，导致 Ruby tzinfo 加载失败，Puma 启动失败，最终 GitLab 返回 502。

四、解决方法

先停止 Puma：

gitlab-ctl stop puma

将异常文件移出 /usr/share/zoneinfo：

mkdir -p /root/zoneinfo_bad_backup

mv /usr/share/zoneinfo/zone_utc /root/zoneinfo_bad_backup/zone_utc.bad.$(date +%F_%H%M%S)

验证 tzinfo 是否正常：

/opt/gitlab/embedded/bin/ruby -e 'require "tzinfo"; TZInfo.eager_load!; puts "tzinfo ok"'

正常输出：

tzinfo ok

启动 Puma：

gitlab-ctl start puma

等待一会儿后检查状态：

sleep 60
gitlab-ctl status

如果看到 Puma 运行时间持续增长，说明已经恢复：

run: puma: (pid xxx) 60s

然后重启 Web 相关组件：

gitlab-ctl restart gitlab-workhorse
gitlab-ctl restart nginx

测试访问：

curl -I http://127.0.0.1

或 HTTPS：

curl -k -I https://127.0.0.1

正常返回 200 或 302，GitLab 页面即可恢复访问。

五、问题总结

本次 GitLab 升级后 502 的根因不是 nginx，也不是 workhorse，而是 Puma 启动失败。

完整链路如下：

zone_utc 时区文件异常
        ↓
Ruby tzinfo 加载失败
        ↓
Puma 启动失败并反复重启
        ↓
gitlab.socket 没有生成
        ↓
gitlab-workhorse 无法连接 Rails 后端
        ↓
GitLab 页面返回 502

六、经验总结

GitLab 升级后如果出现 502，不要只看 gitlab-ctl status 是否都是 run，还要重点关注服务运行时间。

如果 puma 一直只有几秒或几十秒，说明它可能在反复重启。

建议优先排查：

gitlab-ctl status
tail -n 100 /var/log/gitlab/puma/current
tail -n 100 /var/log/gitlab/gitlab-workhorse/current
ls -lh /var/opt/gitlab/gitlab-rails/sockets/

其中，gitlab.socket 是否存在，是判断 Puma 是否真正启动成功的重要依据。