CentOS 上 GitLab 故障排查流程
一 快速判定与最小处置
- 查看整体状态与组件存活：运行 gitlab-ctl status，若大量组件显示 fail: … runsv not running，优先检查系统资源与日志，再执行 gitlab-ctl reconfigure && gitlab-ctl restart。
- 一键查看日志定位错误：执行 gitlab-ctl tail（或进入 /var/log/gitlab 查看对应组件日志，如 gitlab-rails/production.log、puma/current、nginx/error.log）。
- 资源与端口快速体检：
- 资源：free -h、top（关注 CPU、内存、Swap）。
- 端口：ss -tulpen | egrep ‘:(80|443|8080|10022)’ 或 lsof -i:80,443,8080。
- 防火墙与云安全组：
- firewalld：firewall-cmd --list-ports/services；必要时放行 http/https/ssh 或自定义端口。
- 云主机：同时检查安全组入站规则。
- 配置变更后务必执行：gitlab-ctl reconfigure 再重启相关组件。
二 常见症状与对应处置
| 症状 |
快速检查 |
处理要点 |
| 访问返回 502/504 |
top 看 CPU；gitlab-ctl tail puma；ss 检查 8080/80/443 |
常见于资源不足或端口冲突。内存不足先扩容或临时启用 Swap；端口冲突则调整 external_url 端口或 puma[‘port’]，必要时停止占用进程后 reconfigure && restart |
| 访问超时/连接被拒绝 |
ss/iptables/firewalld；云安全组 |
放行对应端口（如 80/443/10022）；检查云厂商安全组；确认服务监听在 0.0.0.0 而非仅 127.0.0.1 |
| 页面 422 |
浏览器开发者工具与 gitlab-rails/production.log |
多与 CSRF/会话或请求参数校验相关；清理浏览器缓存/Cookie，确认 external_url 与访问协议一致，必要时重启 Rails/Puma |
| 大量组件 down |
gitlab-ctl status；gitlab-ctl tail |
先看系统日志与资源（OOM、磁盘满），再执行 reconfigure 恢复；若异常持续，按组件日志逐个排查 |
| 运行缓慢/卡顿 |
top/htop；iostat；gitlab-ctl tail sidekiq |
关注 CPU/内存/磁盘 I/O；优化 Puma/Sidekiq 并发；数据库与缓存参数；必要时增加 Swap 作为缓冲 |
| 容器化部署反复 Restarting |
docker logs gitlab；数据卷权限 |
检查容器日志、卷权限（常见为 1000:1000）、内存是否充足、配置是否正确 |
说明：GitLab 14+ 使用 Puma 作为默认应用服务器（早期版本为 Unicorn）；502 常与 CPU 打满或端口冲突相关，需结合日志与端口占用确认根因。
三 深入定位与修复
- 组件与日志定位
- 核心组件：puma、sidekiq、nginx、postgresql、redis、gitaly。
- 日志路径：/var/log/gitlab/；命令：gitlab-ctl tail <组件名>。
- 端口与进程冲突
- 冲突示例：Puma 默认 8080 与系统或内置 Nginx 监听冲突，表现为 EADDRINUSE 与 502。
- 处置：修改 /etc/gitlab/gitlab.rb 中的 puma[‘port’]（如改为 8081），执行 gitlab-ctl reconfigure && gitlab-ctl restart。
- 配置与权限
- 修改 /etc/gitlab/gitlab.rb（如 external_url）后必须 reconfigure。
- 目录权限与 SELinux：确保 /var/log/gitlab 等目录可写；必要时执行 semanage fcontext 与 restorecon 修复上下文。
- 资源瓶颈
- 内存不足会引发 OOM 与频繁 502/卡顿；临时方案可启用 Swap，长期应优化 Puma/Sidekiq 并发与内存上限。
- 数据库与后台任务
- Sidekiq 堆积会导致页面响应慢；通过日志与监控确认任务积压与失败原因，适当调整 sidekiq[‘concurrency’] 与重试策略。
四 高频命令与路径速查
- 服务管理：gitlab-ctl start|stop|restart|status|reconfigure
- 日志查看：gitlab-ctl tail；组件日志位于 /var/log/gitlab/
- 配置与版本：/etc/gitlab/gitlab.rb；版本查看 cat /opt/gitlab/embedded/service/gitlab-rails/VERSION
- 仓库与数据：/var/opt/gitlab/git-data/repositories
- 备份与恢复：
- 备份：/opt/gitlab/bin/gitlab-rake gitlab:backup:create（默认目录 /var/opt/gitlab/backups）
- 恢复：在备份目录执行 /opt/gitlab/bin/gitlab-rake gitlab:backup:restore BACKUP=时间戳
- 防火墙：
- 放行端口：firewall-cmd --permanent --add-port=10022/tcp && firewall-cmd --reload
- 放行服务：firewall-cmd --permanent --add-service=http --add-service=https && firewall-cmd --reload
- Docker 场景：docker logs gitlab；数据卷权限常见为 1000:1000
五 预防与优化建议
- 资源基线：建议至少 4 核 CPU / 4GB 内存（推荐 8GB+），并使用 SSD 以降低 I/O 瓶颈。
- 配置优化：根据负载调整 Puma worker 数量与内存上限，合理设置 Sidekiq 并发，避免资源争用。
- 稳定性增强：在内存紧张环境下配置适量 Swap，作为 OOM 的缓冲；持续监控 CPU/内存/磁盘/网络。
- 维护与升级：定期更新至稳定版本，清理无用日志与数据，保持系统健康。
