Ubuntu GitLab日志分析与故障排查指南

一、GitLab日志的位置与管理

GitLab在Ubuntu系统中的日志集中存储在/var/log/gitlab/目录下，按组件分类（如Rails应用、Sidekiq后台任务、Nginx反向代理等）。常用日志文件及查看方式如下：

• Rails应用日志：记录GitLab核心业务逻辑（如用户操作、项目操作），路径为/var/log/gitlab/gitlab-rails/production.log，可使用tail -f实时查看最新请求与错误。
• Sidekiq后台任务日志：记录异步任务（如CI/CD流水线、邮件发送）的执行情况，路径为/var/log/gitlab/sidekiq/current，适合排查任务失败问题。
• Nginx访问/错误日志：记录HTTP请求（如访问GitLab页面）及服务器错误（如502、404），路径分别为/var/log/gitlab/nginx/gitlab_access.log（访问日志）和/var/log/gitlab/nginx/gitlab_error.log（错误日志）。
• PostgreSQL数据库日志：记录数据库操作（如查询、连接），路径为/var/log/postgresql/postgresql-<version>-main.log，用于排查数据库性能或连接问题。

此外，可使用gitlab-ctl tail命令查看所有GitLab服务的实时日志，或指定特定服务（如gitlab-ctl tail nginx查看Nginx日志）；通过journalctl -u gitlab-runsvdir查看GitLab服务的系统级日志。

二、常见故障及排查步骤

1. 服务无法启动

• 排查步骤：
  ① 使用sudo gitlab-ctl status检查各组件状态（如unicorn、sidekiq、nginx），若某组件显示“down”或“fail”，则为故障点。
  ② 查看对应组件的实时日志（如sudo gitlab-ctl tail unicorn），定位具体错误（如端口冲突、配置文件错误）。
  ③ 常见原因：端口被占用（如Nginx默认80端口被其他服务占用）、配置文件错误（如/etc/gitlab/gitlab.rb中external_url设置错误）、资源不足（如内存不足导致unicorn无法启动）。
  ④ 解决方案：停止占用端口的服务（sudo systemctl stop <service_name>）；修正配置文件后运行sudo gitlab-ctl reconfigure重新加载配置；增加系统内存或调整GitLab资源限制（如unicorn的worker_processes）。

2. 502 Bad Gateway错误

• 排查步骤：
  ① 502错误通常由Nginx与后端应用（unicorn）通信失败引起，首先查看Nginx错误日志（/var/log/gitlab/nginx/gitlab_error.log），常见提示为“upstream prematurely closed connection”。
  ② 查看unicorn日志（/var/log/gitlab/unicorn/current），若日志显示“failed to start a new unicorn master”，则unicorn无法启动。
  ③ 解决方案：检查unicorn的PID文件（/var/opt/gitlab/unicorn/pid），若存在残留PID文件，删除后重启GitLab（sudo gitlab-ctl restart）；确保unicorn配置（/etc/gitlab/gitlab.rb中的unicorn['port']）与Nginx配置一致。

3. CI/CD流水线失败

• 排查步骤：
  ① 进入GitLab项目的“CI/CD”→“Pipelines”页面，查看流水线状态（如“failed”），点击“Jobs”查看具体任务失败详情。
  ② 查看Sidekiq日志（/var/log/gitlab/sidekiq/current），定位任务执行中的错误（如依赖安装失败、脚本执行错误）。
  ③ 解决方案：检查流水线配置文件（.gitlab-ci.yml），确保语法正确（如缩进、指令格式）；确认Runner已正确注册（gitlab-runner status）且具有执行任务的权限；安装任务所需的依赖（如在流水线中添加apt-get install -y <package>）。

4. 权限问题

• 排查步骤：
  ① 若用户无法克隆、推送代码或访问项目，首先检查SSH密钥（~/.ssh/id_rsa.pub）是否已添加到GitLab账户的“SSH Keys”设置中，或HTTPS令牌是否有效。
  ② 查看GitLab日志（/var/log/gitlab/gitlab-rails/production.log），搜索“permission denied”关键词，确认是用户权限还是项目权限问题。
  ③ 解决方案：为用户分配正确角色（如“Developer”“Maintainer”）；检查项目的分支保护规则（“Settings”→“Repository”→“Protected Branches”），避免非必要用户直接推送至主分支。

5. 系统资源不足

• 排查步骤：
  ① 使用top或htop命令查看系统资源使用情况，若CPU、内存占用率持续高于80%，则需优化。
  ② 查看GitLab日志（如/var/log/gitlab/gitlab-rails/production.log），搜索“out of memory”或“timeout”关键词，确认是否因资源不足导致任务失败。
  ③ 解决方案：启用swap分区（sudo fallocate -l 2G /swapfile→sudo chmod 600 /swapfile→sudo mkswap /swapfile→sudo swapon /swapfile）；清理过期流水线的缓存与构建产物（gitlab-rake gitlab:cleanup:orphan_job_artifacts）；优化unicorn配置（如减少worker_processes数量）。

三、日常维护建议

• 定期清理日志：使用logrotate工具自动压缩或删除旧日志（/etc/logrotate.d/gitlab），避免日志文件占用过多磁盘空间。
• 备份与恢复：定期执行GitLab备份（sudo gitlab-backup create），将备份文件保存至异地（如云存储），故障时可快速恢复（sudo gitlab-backup restore BACKUP=xxx）。
• 监控系统：集成Prometheus+Grafana监控GitLab的性能指标（如CPU、内存、请求延迟），及时预警资源瓶颈。