GitLab在Ubuntu上的故障排查

Ubuntu 上 GitLab 故障排查速查手册

一 快速定位与通用检查

• 查看整体状态与组件健康：sudo gitlab-ctl status；如修改过配置，先执行 sudo gitlab-ctl reconfigure 再重启。
• 查看关键日志：
  • 应用日志：/var/log/gitlab/gitlab-rails/production.log
  • Unicorn/Puma 日志：/var/log/gitlab/unicorn/current 或 /var/log/gitlab/puma/current（旧版多为 unicorn）
  • Nginx 日志：/var/log/gitlab/nginx/error.log、access.log
• 资源与依赖：free -m（关注可用内存与 Swap）、df -h（磁盘空间）、top/htop（CPU/IO）、ss -tulpen | grep -E ‘80|443|22’（端口占用）、systemctl list-jobs（是否有阻塞的 job）。
• 网络连通与解析：ping 域名、nslookup/dig 解析、curl -Iv https://你的域名（排查 TLS/证书/反向代理）。
• 版本与依赖匹配：cat /opt/gitlab/embedded/service/gitlab-rails/VERSION；核对系统 glibc 是否满足 GitLab 包要求，避免跨版本安装导致运行库不兼容。

二 高频故障与修复

• 全部或多数组件报 runsv not running
  现象：gitlab-ctl status 显示大量组件为 fail: xxx: runsv not running。
  处理：

  1. 启动 runit 管理服务：sudo systemctl start gitlab-runsvdir.service
  2. 若卡住，检查是否有阻塞任务：systemctl list-jobs；若看到 plymouth-quit-wait.service 占用，先停止它：sudo systemctl stop plymouth-quit-wait.service，再启动 runsvdir 并重启 GitLab：sudo gitlab-ctl restart。
  3. 验证：gitlab-ctl status 应恢复为 run 状态。
     说明：runit 是 GitLab 的服务编排，gitlab-runsvdir 未起会导致所有组件无法被托管运行。

• 访问出现 502 Bad Gateway
  现象：浏览器返回 502。
  处理：

  1. 看组件状态：gitlab-ctl status，重点确认 unicorn/puma、nginx、gitlab-workhorse、sidekiq 是否 run。
  2. 若 unicorn/puma 反复重启，查看 /var/log/gitlab/unicorn/current 或 /var/log/gitlab/puma/current 与 stderr 日志，常见为内存不足、数据库/Redis 连接异常、端口冲突。
  3. 检查端口占用与 Nginx 配置：ss -tulpen | grep -E ‘80|443|8080’；必要时修正 /etc/gitlab/gitlab.rb 中的端口与 external_url，执行 reconfigure 并重启。
  4. 资源不足时，临时增加 Swap 或优化内存占用（见下一节）。

• 安装或启动时报 GLIBC 版本过低
  现象：/opt/gitlab/embedded/bin/ruby: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.25’ not found。
  处理：不要手动编译升级 glibc（风险高），而是选择与当前 Ubuntu 版本匹配的 GitLab 包（使用官方安装脚本自动匹配仓库与版本），或升级操作系统到受支持的版本。

• 断电或异常重启后无法启动
  现象：大量组件报 runsv not running。
  处理：同“runsv not running”流程，优先启动 gitlab-runsvdir；若被 plymouth-quit-wait.service 阻塞，先停止它再启动 runsvdir 与 GitLab。

• APT 找不到包 gitlab-ee 或安装缓慢失败
  现象：apt-get install gitlab-ee 报 E: Unable to locate package。
  处理：使用官方脚本添加仓库，注意脚本参数与网络连通性：curl -s https://packages.gitlab.com/install/repositories/gitlab/gitlab-ee/script.deb.sh | sudo bash；随后再安装。

• 使用 NFS 仓库路径出现权限或挂载问题
  现象：仓库读写异常、偶发中断。
  处理：使用推荐的 NFSv4 挂载参数，例如：
  /etc/fstab：192.168.10.194:/mnt/storage/gitlab_nfs /mnt/gitlab_nfs nfs4 defaults,vers=4.1,hard,rsize=1048576,wsize=1048576,noatime,nofail,lookupcache=positive 0 2
  并确保目录权限与 GitLab 运行用户一致。

三 性能与资源优化

• 内存不足导致 502 或组件反复重启
  现象：free -m 显示可用内存极低，日志出现 Cannot allocate memory。
  处理：
  1. 临时增加 Swap（示例创建 1GB）：
     dd if=/dev/zero of=/swapfile bs=1M count=1024
     mkswap /swapfile && chmod 0600 /swapfile && swapon /swapfile
     echo ‘/swapfile none swap sw 0 0’ >> /etc/fstab
  2. 调整内核参数（如 vm.swappiness=10），并优化 GitLab 工作进程数（在 /etc/gitlab/gitlab.rb 中调优 puma/unicorn 相关并发与超时，再 reconfigure）。
  3. 关闭不必要的服务/进程，释放内存。

四 一键排查命令清单

• 快速巡检：
  sudo gitlab-ctl status
  sudo tail -n100 /var/log/gitlab/{gitlab-rails/production.log,nginx/error.log,unicorn/current}
  free -m && df -h && top -b -d 1 -n 20
  ss -tulpen | grep -E ‘80|443|22’
  systemctl list-jobs
• 恢复 runsv 异常：
  sudo systemctl start gitlab-runsvdir.service
  sudo systemctl stop plymouth-quit-wait.service # 如阻塞
  sudo gitlab-ctl restart
• 配置变更生效：
  sudo gitlab-ctl reconfigure && sudo gitlab-ctl restart
• 安装源与连通性：
  curl -s https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh | sudo bash
  ping 你的域名 && nslookup 你的域名 && curl -Iv https://你的域名