Debian下GitLab的故障排查技巧
小樊
39
2026-01-03 19:52:09
Debian下GitLab故障排查技巧
一 快速定位流程
- 检查整体健康与资源：查看服务状态与资源使用，确认不是由资源瓶颈引发。
- 命令示例：
- 服务状态：sudo gitlab-ctl status
- 资源监控：top、free -h、df -h
- 查看关键日志：先实时跟踪整体日志，再按服务与文件精确定位。
- 命令示例：
- 整体实时日志：sudo gitlab-ctl tail
- 指定服务：sudo gitlab-ctl tail gitlab-rails
- 指定文件：sudo gitlab-ctl tail nginx/gitlab_error.log
- 系统日志：sudo journalctl -u gitlab -f、或查看系统日志 /var/log/syslog
- 配置与连通性自检：
- 核对主配置：/etc/gitlab/gitlab.rb（如 external_url 与端口）
- 使配置生效：sudo gitlab-ctl reconfigure
- 数据库自检：sudo gitlab-rake gitlab:check SANITIZE=true
- 网络与防火墙：测试连通性（如 ping），确认防火墙放行 HTTP/HTTPS/SSH 端口。
二 日志定位与高效检索
- 常用日志路径与作用
- /var/log/gitlab/gitlab-rails/production.log：请求与SQL执行情况
- /var/log/gitlab/gitlab-rails/production_json.log：结构化请求日志
- /var/log/gitlab/gitlab-shell/gitlab-shell.log：SSH 相关操作
- /var/log/gitlab/nginx/gitlab_error.log：Nginx 错误
- /var/log/gitlab/sidekiq/current：后台任务
- 检索与分析技巧
- 实时跟踪：sudo gitlab-ctl tail
- 关键字过滤：sudo gitlab-ctl tail | grep -i “error|timeout|fatal”
- 时间窗口定位：sudo journalctl --since “2025-12-01 10:00:00” --until “2025-12-01 12:00:00”
- 多文件联查：结合 grep -R “keyword” /var/log/gitlab/ 快速跨文件搜索
三 常见症状与处理要点
- 502/504 或页面长时间空白
- 现象特征：反向代理报 upstream timed out，或 Rails/Unicorn 超时。
- 处理要点：
- 检查后端健康：sudo gitlab-ctl status；必要时重启异常组件
- 调整超时与进程数（示例，按机器规格调优）：
- unicorn[‘worker_timeout’] = 60
- unicorn[‘worker_processes’] = CPU 核数 + 1
- 若有外部 Nginx，确保传递协议头并合理设置代理超时：
- 头部：proxy_set_header X-Forwarded-Proto https;
- 超时：例如 proxy_read_timeout 300; proxy_send_timeout 300;
- 克隆/推送失败
- 可能原因：SSH 密钥未添加或权限不足；HTTPS 令牌错误；分支保护策略限制。
- 处理要点：
- SSH：在本机生成密钥并添加到用户 SSH Keys；确认 external_url 与端口一致
- HTTPS：检查个人访问令牌或密码是否正确
- 提示 rejected non-fast-forward：先执行 git pull --rebase 再推送
- 升级后数据库迁移失败
- 现象特征：升级后访问异常，迁移任务报错。
- 处理要点（临时应急，事后需修复根因）：
- 在 /etc/gitlab/gitlab.rb 中设置：gitlab_rails[‘skip_unmigrated_data_check’] = true
- 执行：sudo gitlab-ctl reconfigure && sudo gitlab-ctl restart
- 迁移通过后移除该开关并重新配置，确保数据一致性
四 配置与维护建议
- 变更与重启
- 修改 /etc/gitlab/gitlab.rb 后务必执行：sudo gitlab-ctl reconfigure
- 必要时重启：sudo gitlab-ctl restart
- 日志轮转与保留
- 内置 logrotate 可按需调整：
- 示例：logging[‘logrotate_frequency’] = “daily”、logging[‘logrotate_rotate’] = 30
- 应用：sudo gitlab-ctl reconfigure
- 系统与安全
- 保持系统更新：sudo apt update && sudo apt upgrade
- 核对 external_url 与证书路径；如有外置 Nginx，确保 X-Forwarded-Proto 正确传递
- 资源基线
- 建议至少 2GB RAM，推荐 4GB+；监控 CPU/内存/磁盘 IO，避免因资源不足导致超时与 502
