CentOS中GitLab如何进行故障排查
小樊
36
2025-12-21 10:44:57
CentOS 上 GitLab 故障排查实操指南
一 快速定位流程
- 检查服务状态与端口连通：执行 sudo gitlab-ctl status 查看各组件；用 ss -lntp | egrep ‘:(80|443|8080|22)’; 或 lsof -i:80,443,8080 排查端口占用；必要时用 curl -I http://127.0.0.1 与从外网 curl -Iv 验证访问链路。
- 查看关键日志：优先用 sudo gitlab-ctl tail 实时跟踪；或到 /var/log/gitlab 下查看对应组件日志，如 gitlab-rails/production.log、nginx/.log、gitlab-shell/gitlab-shell.log、sidekiq/.log。
- 配置与生效：修改 /etc/gitlab/gitlab.rb 后必须执行 sudo gitlab-ctl reconfigure；重启用 sudo gitlab-ctl restart。
- 资源与系统：用 free -m、df -h、top 检查内存与磁盘；异常关机或“卡住不动”可先 systemctl restart gitlab-runsvdir 再 reconfigure。
- 环境依赖：确保系统时间同步（chrony/ntpd）、防火墙/SELinux 策略放行、邮件/外部依赖可达。
二 常见故障与修复
- 访问 502/超时：多由后端端口冲突或超时导致。检查端口占用并调整：在 /etc/gitlab/gitlab.rb 设置 unicorn[‘port’]=新端口 与 gitlab_workhorse[‘auth_backend’]=“http://localhost:新端口”，再 gitlab-ctl reconfigure && gitlab-ctl restart；同时可适度增大超时（如 gitlab_rails[‘gitlab_workhorse_timeout’]）。
- 端口被占用（80/443/8080 等）：用 ss/lsof 找到占用进程并停用或迁移；若需变更 GitLab 端口，修改 external_url 与相应服务端口后 reconfigure。
- 启动卡在 reconfigure 或异常关机后出现 “runsv not running”：执行 systemctl restart gitlab-runsvdir 后再次 reconfigure；必要时直接运行 /opt/gitlab/embedded/bin/runsvdir-start 拉起 runsvdir，再查看日志与组件状态。
- 403 Forbidden（Rack Attack 限流）：编辑 /etc/gitlab/gitlab.rb，配置 gitlab_rails[‘rack_attack_git_basic_auth’] 将可信 IP 加入 ip_whitelist，适当调大 maxretry/findtime/bantime，然后 reconfigure。
- 邮件发送失败：核对 /etc/gitlab/gitlab.rb 中 SMTP 参数（地址、端口、TLS/STARTTLS、账号、密码、发件人），确保外网连通与证书可信，最后 reconfigure。
三 日志与定位技巧
- 组件化实时日志：sudo gitlab-ctl tail；按组件过滤如 sudo gitlab-ctl tail nginx/gitlab_error.log、sidekiq、gitlab-shell。
- 文件与关键字定位：到 /var/log/gitlab 查看对应子目录；生产问题优先检索 gitlab-rails/production.log 的错误堆栈与 SQL 耗时，Nginx 错误日志用于定位反向代理/证书/连接问题。
- 系统侧日志：必要时用 journalctl -u gitlab-rails 或查看系统 messages/syslog，辅助判断服务启动与依赖异常。
四 配置与网络要点
- 修改默认端口：编辑 /etc/gitlab/gitlab.rb 的 external_url（如 “http://ip:端口”）；若需变更 Web/后端端口，同步调整 nginx[‘listen_port’] 与 unicorn[‘port’]/workhorse 的 auth_backend，执行 reconfigure 与 restart。
- 使用外部 Nginx：在 gitlab.rb 中将 nginx[‘enable’] = false；将 /var/opt/gitlab/nginx/conf/{nginx.conf,gitlab-http.conf} 的内容合并到外部 Nginx 配置中，注意反向代理到 workhorse（默认端口 8181）与 Git 协议端口（22），然后 reconfigure 并重启外部 Nginx。
- 防火墙与 SELinux：放行 80/443/22 等端口；SELinux 异常可用 sestatus 检查，必要时 restorecon -Rv /var/log/gitlab 修复日志目录上下文。
- 资源建议：GitLab 对资源较敏感，生产环境建议至少 4GB 内存，并关注磁盘 I/O 与 swap 使用。
五 一键排障命令清单
- 服务与端口：gitlab-ctl status；ss -lntp | egrep ‘:(80|443|8080|22)’；lsof -i:80,443,8080；curl -I http://127.0.0.1
- 日志：gitlab-ctl tail；tail -f /var/log/gitlab/gitlab-rails/production.log；gitlab-ctl tail nginx/gitlab_error.log
- 配置生效：gitlab-ctl reconfigure；gitlab-ctl restart
- 异常恢复：systemctl restart gitlab-runsvdir；/opt/gitlab/embedded/bin/runsvdir-start
- 资源与健康：free -m；df -h；top；chronyc tracking 或 timedatectl status
