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、內存、請求延遲），及時預警資源瓶頸。