CentOS上GitLab的故障排查方法有哪些

CentOS 上 GitLab 故障排查方法

一 快速定位与通用检查

• 检查服务状态与组件健康：执行 sudo gitlab-ctl status，确认 nginx、puma/unicorn、sidekiq、postgresql、redis 等组件均为 run 状态；若异常，优先查看对应组件日志。必要时执行 sudo gitlab-ctl reconfigure 使配置生效，再 sudo gitlab-ctl restart 重启服务。
• 查看全局与组件日志：实时查看全部日志 sudo gitlab-ctl tail；查看 Rails 日志 sudo gitlab-ctl tail gitlab-rails；查看 Nginx 错误日志 sudo gitlab-ctl tail nginx/gitlab_error.log；或直达文件 /var/log/gitlab/ 下对应子目录。
• 核对关键配置：编辑 /etc/gitlab/gitlab.rb，确保 external_url 正确（如 http://your_ip:port 或域名）；修改后必须执行 reconfigure。
• 网络与端口可达：确认服务器可访问外网（如 ping 测试）；在防火墙放行 80/443/22（或自定义端口），例如：
  sudo firewall-cmd --permanent --add-service=http
  sudo firewall-cmd --permanent --add-service=https
  sudo firewall-cmd --permanent --add-service=ssh
  sudo firewall-cmd --reload
• 资源与系统环境：检查内存与磁盘（建议至少 4GB 内存，磁盘空间充足）；若 reconfigure 卡在 ruby_block[supervise_redis_sleep]，可先 systemctl restart gitlab-runsvdir 再重试；若 /tmp 或根分区满，清理后再启动。

二 常见故障场景与处理

• 端口冲突导致访问异常或启动失败：用 lsof -i:80、lsof -i:443 检查占用；必要时在 /etc/gitlab/gitlab.rb 调整端口并重配：
  external_url ‘http://localhost:90’
  修改后执行 gitlab-ctl reconfigure 与 gitlab-ctl restart。
• 访问出现 502 Bad Gateway：多由 Nginx 与 Puma/Unicorn 未就绪或端口冲突引起；先 gitlab-ctl status 定位异常组件，查看 /var/log/gitlab/nginx/gitlab_error.log 与 gitlab-rails/production.log，按日志报错修复（如端口、权限、进程未起）。
• 防火墙或端口未放行：外部访问被拒时，确认 firewalld 已放行 80/443/22（或自定义端口），并重新加载规则。
• 邮件功能异常：核对 gitlab.rb 中 SMTP 参数（如 smtp_enable、smtp_address、smtp_port=587、smtp_user_name、smtp_password、smtp_domain、smtp_authentication、smtp_enable_starttls_auto、smtp_tls、gitlab_email_from），修改后 reconfigure 并测试。
• SELinux 权限拦截：若启用 SELinux 导致目录不可读写，执行 sestatus 检查；按需设置上下文并恢复：
  sudo semanage fcontext -a -t httpd_sys_rw_content_t “/var/log/gitlab(/.*)?”
  sudo restorecon -Rv /var/log/gitlab。
• 升级或配置变更后异常：可能存在版本或配置兼容性问题；回滚最近变更或按官方升级指南分步执行，变更前做好备份。

三 日志分析与深入排查

• 组件日志定位：
  • Rails 应用：/var/log/gitlab/gitlab-rails/production.log（业务错误、异常堆栈）、production_json.log（结构化日志）。
  • Nginx：/var/log/gitlab/nginx/gitlab_access.log、gitlab_error.log（访问与错误）。
  • 后台任务：/var/log/gitlab/sidekiq/sidekiq.log（任务失败、卡死）。
• 实时与历史检索：
  • 实时跟踪：sudo gitlab-ctl tail、sudo gitlab-ctl tail gitlab-rails。
  • 系统日志：在 systemd 系统可用 journalctl -u gitlab、journalctl -u gitlab-rails，并可按时间过滤（如 –since/–until）。
• 集中化与可视化：将 /var/log/gitlab 接入 ELK 或 Splunk，结合 Prometheus + Grafana 做指标监控与告警，便于发现持续性问题与容量瓶颈。

四 预防性维护与最佳实践

• 变更流程标准化：修改 /etc/gitlab/gitlab.rb 后统一执行 gitlab-ctl reconfigure；变更前备份关键目录（如 /etc/gitlab、/var/opt/gitlab、/var/log/gitlab）。
• 资源与健康基线：保持至少 4GB 内存与充足磁盘；通过 /admin/monitoring（内置监控）或 Prometheus/Grafana 观察 CPU、内存、Unicorn 队列、Sidekiq 延迟 等关键指标。
• 日志生命周期管理：启用 logrotate 对 /var/log/gitlab 进行按日轮转与保留策略配置，避免日志膨胀影响磁盘与性能。
• 版本与兼容性：升级前核对目标版本与依赖、数据库、操作系统及现有插件的兼容性，严格按官方步骤执行，并在灰度环境验证。