GitLab在Ubuntu上的故障排查技巧

Ubuntu 上 GitLab 故障排查技巧

一 快速定位与通用检查

• 查看整体状态与组件健康：运行 sudo gitlab-ctl status，关注状态为 down 或频繁重启的服务（如 unicorn/puma、sidekiq、nginx、postgresql、redis 等）。
• 实时查看日志：
  • 全量跟踪：sudo gitlab-ctl tail
  • 指定组件：sudo gitlab-ctl tail nginx|postgresql|redis|sidekiq|unicorn|puma|gitlab-workhorse
  • 关键应用日志：/var/log/gitlab/gitlab-rails/production.log（500/页面异常优先看这里）
• 配置与连通性自检：
  • 重新加载配置：sudo gitlab-ctl reconfigure
  • 配置语法与依赖检查：sudo gitlab-rake gitlab:check SANITIZE=true
  • 版本与环境信息：sudo gitlab-rake gitlab:env:info
• 资源与网络：用 free -m、df -h、top 检查内存/磁盘/CPU；确认 防火墙/安全组 已放行 80/443（或自定义端口）。

二 高频故障与修复

• 502 Bad Gateway
  • 现象：nginx 正常但上游应用无响应。
  • 处理：
    • 查看 /var/log/gitlab/unicorn/current 或 /var/log/gitlab/puma/current 与 stderr 报错；
    • 若 Unicorn/Puma 反复重启，检查内存是否不足、数据库连接、端口冲突；
    • 必要时清理陈旧的 .pid 文件后重启：sudo gitlab-ctl restart。
• 500 内部服务器错误
  • 现象：页面显示 “Whoops, something went wrong”。
  • 处理：
    • 查 /var/log/gitlab/gitlab-rails/production.log 定位异常堆栈；
    • 结合 gitlab-ctl tail 观察相关组件日志，按报错修复（如 DB 连接、权限、磁盘满等）。
• 大量服务启动失败并提示 runsv not running
  • 现象：gitlab-ctl start/restart 出现多项 “fail: xxx: runsv not running”。
  • 处理：
    • 重启 runit 服务：sudo systemctl restart gitlab-runsvdir；
    • 若卡在 systemd 目标，检查是否有阻塞任务：systemctl list-jobs，必要时停止阻塞任务后再启动 GitLab。
• 安装或更新时报错 E: Unable to locate package gitlab-ee/ce
  • 现象：apt 找不到包。
  • 处理：
    • 确认已添加官方仓库并执行 sudo apt update；
    • 使用官方安装脚本时建议加 -s 静默参数以正确写入源后再安装。
• WSL2 环境 reconfigure 卡住或启动大量 failed
  • 现象：卡在 “wait for redis service socket” 或 “runsv not running”。
  • 处理：
    • 另开终端执行：sudo /opt/gitlab/embedded/bin/runsvdir-start，保持窗口运行；
    • 如提示与 systemctl 相关错误，可在 WSL2 中安装并使用 systemctl 兼容包。
• 内存不足导致异常（如添加 SSH Key 报 Cannot allocate memory）
  • 现象：操作触发 ENOMEM。
  • 处理：
    • 临时增加 Swap（示例创建 1G Swap），缓解 OOM；
    • 长期建议升级实例内存或优化服务并发。

三 日志与关键排查路径

四 预防性维护与最佳实践

• 资源基线：至少 4 核 CPU、4GB 内存（低配易触发 502/500），并预留一定 Swap；监控 磁盘空间 与 I/O。
• 变更流程：修改 /etc/gitlab/gitlab.rb 后执行 sudo gitlab-ctl reconfigure；变更前备份配置与数据。
• 备份与恢复：
  • 备份：sudo gitlab-backup create（生成时间戳 _gitlab_backup.tar 文件）；
  • 恢复：先停服务，执行 gitlab-rake gitlab:backup:restore BACKUP=时间戳。
• 版本与兼容：优先使用 Ubuntu 20.04/22.04 LTS 等受支持版本；保持 GitLab 与 GitLab Runner 主次版本一致（如均为 17.x）。
• 网络与端口：确保 80/443 或自定义端口对客户端与 Let’s Encrypt（如使用）可达；核对 external_url 与 Nginx 监听一致。