CentOS 上 GitLab 故障排查与修复步骤
一 快速定位与恢复
- 查看整体状态与组件健康：执行 gitlab-ctl status，定位异常组件（如 nginx、puma/unicorn、postgresql、redis 等）。随后用 gitlab-ctl tail 实时查看日志，或查看 /var/log/gitlab 下对应组件的日志文件。若修改过配置，先执行 gitlab-ctl reconfigure 再 gitlab-ctl restart 使配置生效。以上步骤能覆盖大多数启动与运行异常的首轮排查。
二 常见故障与处理要点
- 端口冲突导致无法访问或启动失败：用 lsof -i:80、lsof -i:443 检查占用；必要时在 /etc/gitlab/gitlab.rb 调整端口，例如将 nginx[‘listen_port’] 改为未占用的端口（如 8099），保存后执行 gitlab-ctl reconfigure 与 gitlab-ctl restart。若访问出现 502 Bad Gateway，高概率是 80/443 或应用端口被占用，或后端服务未就绪。对于 GitLab 13.0+，默认 Web 服务器是 Puma（旧版为 Unicorn），需确认对应端口（如 puma[‘port’]=8080）未被占用并相应调整。
- 资源不足引发 502 或卡顿：GitLab 对资源较敏感，生产环境建议至少 4GB 内存、2 核 CPU；内存不足会导致进程被 OOM 或被系统限速，表现为页面 502 或响应极慢。
- 防火墙与网络连通性：确保访问端口（如 80/443/22 或自定义端口）已在防火墙放行，例如 firewall-cmd --permanent --add-port=8080/tcp && firewall-cmd --reload；同时排查云安全组/外部网络策略。
- 配置语法或参数错误：编辑 /etc/gitlab/gitlab.rb 后若 reconfigure 失败，优先检查语法与参数拼写；修改 external_url 等核心参数后务必重新配置并重启。
- 邮件功能异常：若注册、通知、密码重置不可用，检查 gitlab_rails[‘smtp_enable’] 及 smtp_address/smtp_port/smtp_user_name/smtp_password/smtp_domain 等 SMTP 配置是否正确，必要时调整并重配。
三 高频场景速查表
| 症状 |
快速检查 |
处理建议 |
| 访问返回 502 |
gitlab-ctl status；gitlab-ctl tail；检查 80/443 与后端端口占用 |
释放或更换端口；确认 Puma/Unicorn 端口未被占用；资源不足时先扩容或释放内存 |
| 页面打不开或端口不通 |
ss/ lsof 检查端口；firewall-cmd 与云安全组策略 |
放行对应端口（如 80/443/22/自定义端口）；验证本机与网络路径连通性 |
| 修改配置后异常 |
检查 /etc/gitlab/gitlab.rb 语法；查看 reconfigure 报错 |
修正参数后执行 gitlab-ctl reconfigure 与 gitlab-ctl restart |
| 安装/依赖报错 |
yum 安装日志；网络连通性；SELinux 状态 |
安装缺失依赖（如 policycoreutils 等）；必要时配置代理；排查 SELinux/权限问题 |
| 邮件发送失败 |
查看 production.log 与邮件配置 |
核对 SMTP 参数与发信域名；确保邮件服务可达与凭据正确 |
四 变更前的备份与回滚
- 在执行重大变更（升级、迁移、调整网络/端口、替换存储）前，先创建备份：执行 gitlab-backup create 将备份文件保存至 /var/opt/gitlab/backups。需要回滚时，先停止相关服务（如 gitlab-ctl stop puma/unicorn nginx），恢复备份后执行 gitlab-ctl reconfigure 与 gitlab-ctl start。确保备份文件完整且目标环境磁盘空间充足。