Debian系统下GitLab的故障排查方法是什么

Debian 下 GitLab 故障排查方法

一 快速定位流程

• 查看组件状态：运行 sudo gitlab-ctl status，快速确认哪些组件异常（如 puma、sidekiq、nginx、postgresql、redis、gitaly 等）。
• 查看实时日志：
  • Omnibus 日志：sudo gitlab-ctl tail（或指定组件，如 gitlab-ctl tail nginx/gitlab_error.log）
  • Rails 日志：tail -f /var/log/gitlab/gitlab-rails/production.log
  • 系统日志：sudo journalctl -u gitlab -b 或 tail -f /var/log/syslog
• 全量重配置与重启：修改 /etc/gitlab/gitlab.rb 后执行 sudo gitlab-ctl reconfigure，再 sudo gitlab-ctl restart。
• 配置与连通性自检：核对 external_url 与端口；必要时执行 gitlab-rake gitlab:check SANITIZE=true 做健康检查。
• 资源与网络：用 df -h、free -m、top 检查磁盘/内存/CPU；用 ss -plnt、lsof -i :端口 检查监听与占用；用 ping、dig/nslookup、traceroute 排查 DNS 与连通性；检查防火墙放行 HTTP/HTTPS/SSH。
• 变更前务必备份关键数据与配置。

二 常见故障与修复

• 全部组件显示 “runsv not running”
  原因多为底层 gitlab-runsvdir 未启动。执行：
  1）sudo systemctl start gitlab-runsvdir.service
  2）sudo gitlab-ctl restart
  若启动卡住，可能因 plymouth-quit-wait.service 阻塞，先执行 sudo systemctl stop plymouth-quit-wait.service 再启动 runsvdir 并重启。
• 服务启动失败或反复重启（如 puma、sidekiq）
  1）查看对应日志：/var/log/gitlab/puma/puma_stderr.log、/var/log/gitlab/gitlab-rails/production.log
  2）核对 /etc/gitlab/gitlab.rb 关键项（如 external_url）并 reconfigure
  3）检查资源是否不足（磁盘满、内存紧张）
  4）排查端口冲突（如 puma、postgresql、redis 端口被占用）
  5）必要时仅重启异常组件：gitlab-ctl restart puma/sidekiq
• Runner 卡顿或任务积压
  检查 /var/run/docker.sock 响应、系统 CPU/IO 使用率、虚拟机资源复用情况；优化并发与资源配额。
• 页面访问异常或登录缓慢
  核对 external_url 与证书；确认 nginx/gitlab_error.log 报错；排查网络与防火墙策略。
• 时间与权限问题
  校准服务器时间与时区；确保 /var/opt/gitlab 等目录属主为 git:git，权限正确。

三 日志与关键文件定位

• 日志目录与常用文件
  • Omnibus 聚合日志：/var/log/gitlab/gitlab-ctl/production.log
  • Rails 请求与错误：/var/log/gitlab/gitlab-rails/production.log
  • Nginx 访问与错误：/var/log/gitlab/nginx/gitlab_access.log、gitlab_error.log
  • 后台任务：/var/log/gitlab/sidekiq/current
  • Shell/SSH 操作：/var/log/gitlab/gitlab-shell/gitlab-shell.log
  • 组件日志：/var/log/gitlab/<组件名>/（如 puma/、postgresql/）
• 查看方式
  • 实时查看：sudo gitlab-ctl tail 或 tail -f /var/log/gitlab/…
  • 关键字检索：grep -2 “ERROR” /var/log/gitlab/gitlab-rails/production.log
  • 系统级日志：journalctl -u gitlab -b、journalctl --since “2024-01-01” --until “2024-01-31”
• 配置与重配置
  • 主配置：/etc/gitlab/gitlab.rb（修改后执行 gitlab-ctl reconfigure 使生效）

四 性能与资源优化

• 资源瓶颈排查
  • 磁盘与空间：df -h、du -hd 1、find / -type f -size +100M
  • 内存与负载：free -m、top（必要时优化应用或扩容）
• 工作进程与内存匹配
  • 调整 puma[‘worker_processes’] 等参数，避免超出 CPU/内存 能力导致 OOM 或抖动。
• Runner 与构建环境
  • 控制并发与资源配额，避免 CPU/IO 被构建任务打满。
• 时间与时钟同步
  • 设置正确时区并启用 NTP 同步，避免时间漂移引发认证/调度异常。

五 维护与变更建议

• 变更流程
  • 修改 /etc/gitlab/gitlab.rb → gitlab-ctl reconfigure → gitlab-ctl restart；变更前做好配置与数据备份。
• 升级与兼容性
  • 保持系统与依赖更新：sudo apt update && sudo apt upgrade；如遇到兼容性问题，评估升级 GitLab 版本或更换为 Docker 部署以降低环境耦合。
• 文档与求助
  • 参考 GitLab 官方文档 与社区支持渠道，提供复现步骤、日志片段与版本信息以便高效定位。