Debian下GitLab的故障排查步骤

Debian下GitLab故障排查步骤

一 快速定位与通用检查

• 查看整体服务状态：sudo gitlab-ctl status，异常时先 sudo gitlab-ctl restart 恢复服务，再定位根因。
• 查看 Omnibus 日志：sudo gitlab-ctl tail（实时），或定位到组件：sudo gitlab-ctl tail nginx/gitlab_error.log、sudo gitlab-ctl tail gitlab-rails。
• 查看系统日志：sudo tail -f /var/log/syslog，内核与启动信息用 dmesg，systemd 单元日志用 sudo journalctl -u gitlab-rails。
• 检查资源配置：/etc/gitlab/gitlab.rb 中的 external_url、端口、域名等是否正确；修改后执行 sudo gitlab-ctl reconfigure 使配置生效。
• 资源与连通性：用 top/free -h/df -h 检查 CPU/内存/磁盘；ping 与 curl 测试内外网连通；必要时调整防火墙放行 80/443（如 sudo ufw allow 80,443）。
• 变更前务必做好备份，避免数据丢失。

二 常见故障与处理要点

• 访问出现 502/504：常见于端口被占用或 内存不足。检查占用：ss -ltnp | grep ':80\|:443'，释放或调整端口；内存紧张时临时启用 swap 或降低并发工作进程（如 Puma/Unicorn 的 worker 数）。
• 配置错误导致启动失败：检查 /etc/gitlab/gitlab.rb 语法与参数，修正后 sudo gitlab-ctl reconfigure && sudo gitlab-ctl restart。
• 数据库连接/迁移失败：使用 sudo gitlab-rake gitlab:check SANITIZE=true 排查连接与配置；升级时若迁移卡住，可在维护窗口按官方指引跳过未迁移数据检查（如设置 gitlab_skip_unmigrated_data_check true）后再恢复。
• Runner 卡顿或任务超时：排查 CPU/IO 异常（如 top/iotop/strace 跟踪 docker.sock），必要时迁移到独占宿主机或优化存储与调度。
• 克隆/推送异常：
  • permission denied (publickey)：重新生成 SSH 密钥 并在用户设置中添加公钥；
  • rejected non-fast-forward：先 git pull --rebase 再推送；
  • failed to push some refs：先同步远端 git fetch && git merge 或 git pull 后重试。

三 日志与数据恢复

• 关键日志路径与用途：
  • /var/log/gitlab/gitlab-rails/production.log：Rails 请求与错误；
  • /var/log/gitlab/gitlab-rails/production_json.log：结构化错误；
  • /var/log/gitlab/gitlab-shell/gitlab-shell.log：SSH 与 git 命令；
  • /var/log/gitlab/nginx/gitlab_error.log：Nginx 错误；
  • 使用 sudo gitlab-ctl tail <service|file> 快速定位问题。
• 日志轮转与保留：通过 /etc/gitlab/gitlab.rb 配置 logging['logrotate_frequency'] 与 logging['logrotate_rotate']，执行 sudo gitlab-ctl reconfigure 生效。
• 数据备份与恢复：
  • 备份：sudo gitlab-rake gitlab:backup:create；
  • 恢复：在新环境停止服务后执行 sudo gitlab-rake gitlab:backup:restore（按提示输入时间戳），随后 sudo gitlab-ctl reconfigure && sudo gitlab-ctl restart。

四 维护与优化建议

• 保持系统与软件包最新：sudo apt update && sudo apt upgrade，并定期执行 sudo gitlab-ctl reconfigure 应用变更。
• 资源基线：GitLab 在生产环境建议至少 4GB 内存，并结合负载调整 Puma/Unicorn worker 数量与数据库连接池。
• 时间同步：确保 NTP 正常，避免证书校验、Sidekiq 与 Webhook 时序问题。
• 安全与合规：严格管控 firewalld/ufw 规则，仅暴露必要端口；备份与恢复流程纳入日常演练。