GitLab如何在Linux上进行故障排查

Linux 上 GitLab 故障排查实战手册

一 快速定位流程

• 检查运行状态与组件健康：执行 sudo gitlab-ctl status，确认关键组件（如 nginx、puma/unicorn、sidekiq、gitaly、postgresql、redis）均为 run。若异常，优先查看对应日志。
• 查看实时日志：使用 sudo gitlab-ctl tail 观察全局日志，或指定组件如 sudo gitlab-ctl tail gitlab-rails、sudo gitlab-ctl tail nginx/gitlab_error.log；定位错误关键词如 ERROR、FATAL、PG::Error、permission denied。
• 系统资源与连通性自检：
  • 资源：free -m、df -h、top/htop 检查内存、磁盘、CPU 是否瓶颈。
  • 端口：ss -plnt | grep -E ‘(:80|:443|:22)’ 或 lsof -i :80 排查端口占用与冲突。
  • 网络与 DNS：ping、dig +short、nslookup、traceroute 验证域名解析与链路可达。
• 配置与生效：修改 /etc/gitlab/gitlab.rb 后执行 sudo gitlab-ctl reconfigure，必要时 sudo gitlab-ctl restart 使配置生效。
• 防火墙与安全策略：开放 80/443/22（或自定义端口），在 CentOS 上确认 firewalld 规则；若启用 SELinux，使用 sestatus 检查状态并按需调整策略。
• 版本与升级兼容性：通过 /help 页面或 API 获取版本，排查升级后的兼容性问题。

二 常见症状与处理对照表

三 日志与系统诊断命令清单

• 组件与日志：
  • 全局与组件日志：sudo gitlab-ctl tail，sudo gitlab-ctl tail gitlab-rails，sudo gitlab-ctl tail nginx/gitlab_error.log
  • 直接查看文件：/var/log/gitlab/ 下的 gitlab-rails/production.log、gitlab-rails/production_json.log、sidekiq/current、gitaly/current、nginx/gitlab_access.log、nginx/gitlab_error.log
• 系统与服务日志：
  • systemd：sudo journalctl -u gitlab、sudo journalctl -u gitlab-rails、sudo journalctl --since “2025-12-01” --until “2025-12-10”
• 资源与进程：
  • 资源：free -m、df -h、du -hd 1
  • 进程：top/htop、ps aux | grep puma
• 网络与端口：
  • 监听与占用：ss -plnt、lsof -i :80
  • 连通与解析：ping、dig +short、nslookup、traceroute、ip address
• 深入诊断（慎用）：
  • 系统调用跟踪：strace -tt -T -f -y -yy -s 1024 -p （生产环境谨慎，可能影响性能）

四 系统与安全配置检查

• 防火墙放行：确保 firewalld/iptables 已放行 80/443/22（或自定义端口），避免外部访问被拒。
• SELinux（CentOS 常见）：
  • 检查状态：sestatus
  • 目录上下文与恢复：sudo semanage fcontext -a -t httpd_sys_rw_content_t “/var/log/gitlab(/.*)?”，sudo restorecon -Rv /var/log/gitlab
• 资源与内核参数：
  • 内存压力可临时启用 swap；必要时优化 vm.swappiness 等内核参数，缓解 OOM 与抖动。
• 权限与目录：
  • 确认 /var/opt/gitlab、/var/log/gitlab 等目录属主为 git:git，权限合理（如 755/644），避免因权限导致写入失败。

五 数据一致性与恢复建议

• 配置变更流程：修改 /etc/gitlab/gitlab.rb → sudo gitlab-ctl reconfigure → sudo gitlab-ctl restart，变更前建议备份配置与数据。
• 备份与恢复：定期执行 gitlab-backup create 进行备份；恢复时先确保实例版本一致、数据目录与数据库状态一致，再执行恢复流程。
• 数据库与后台任务：
  • 检查数据库状态：gitlab-ctl status postgresql；必要时在维护窗口重启。
  • 观察后台任务：sudo gitlab-ctl tail sidekiq，异常任务重试或清理卡死任务。
• 升级与兼容性：跨版本升级遵循官方路径，先小版本过渡并充分备份，验证插件/Runner/存储兼容性。