CentOS 上 GitLab 故障排查步骤
一 快速定位与基础检查
- 查看整体状态与组件健康：执行 gitlab-ctl status，确认各组件（如 nginx、puma/unicorn、sidekiq、postgresql、redis）为 run 状态。
- 查看实时日志定位错误：执行 gitlab-ctl tail（或指定组件，如 gitlab-ctl tail nginx/gitlab_access.log；Rails 错误可看 /var/log/gitlab/gitlab-rails/production.log）。
- 核对关键配置：编辑 /etc/gitlab/gitlab.rb，确保 external_url 正确（如 http://服务器IP或域名），修改后执行 gitlab-ctl reconfigure 使配置生效。
- 基础资源与版本：确认系统时间、磁盘空间、内存与 CPU 负载正常；核对 CentOS 与 GitLab RPM 版本匹配（RPM 包名中的 el7/el8 需与系统版本一致，避免如 libcrypt.so.1/GLIBC_2.25 等依赖报错）。
- 服务可达性自检：在服务器本机执行 curl -I http://127.0.0.1 或 ss -ltnp | grep ‘:80|:443|:22’ 检查监听与返回码。
二 访问与网络连通性排查
- 防火墙放行：确保 firewalld 已开放 80/443/22（或自定义端口），执行：
sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --permanent --add-service=ssh
sudo firewall-cmd --reload
- 云厂商安全组：如为云服务器，需在控制台安全组放行对应端口（80/443/22 或自定义端口）。
- 端口冲突与监听：若访问异常，检查是否被其他进程占用：
sudo lsof -i:80
sudo lsof -i:443
sudo ss -ltnp | grep ‘:80|:443|:22’
- 外部连通性测试：从客户端执行 curl -Iv http://你的域名或IP，观察 HTTP 状态码 与 TLS 握手是否成功。
三 服务启动失败与 502 错误专项
- 组件未就绪：执行 gitlab-ctl status 找出 down 的组件，结合 gitlab-ctl tail <组件名> 查看具体报错。
- 端口冲突导致 502：常见于 80/443/8080 被占用或组件间争用端口。示例：
- 检查占用：sudo lsof -i:8080
- 调整 Puma 端口（GitLab 13+ 使用 Puma）：在 /etc/gitlab/gitlab.rb 中设置
puma[‘port’] = 8081
然后执行：gitlab-ctl reconfigure && gitlab-ctl restart
- 若是 Nginx/Unicorn 冲突，按同样思路调整对应端口并重新配置。
- 资源不足导致 502/卡顿：GitLab 建议至少 4GB 内存；内存不足会导致启动缓慢或进程被 OOM 终止。
- 数据库异常：若 PostgreSQL 异常（如异常关机导致 PID 残留），可清理后重启：
sudo rm -f /var/opt/gitlab/postgresql/data/postmaster.pid
sudo gitlab-ctl restart
四 配置语法错误与权限问题
- 配置语法与生效：编辑 /etc/gitlab/gitlab.rb 时避免语法错误与错误参数；每次修改后执行 gitlab-ctl reconfigure 再重启。
- 目录权限与 SELinux：确保 /var/log/gitlab 等目录可写；若启用 SELinux，可用 semanage fcontext/restorecon 修复上下文，或临时 setenforce 0 验证是否为 SELinux 引起（验证后请恢复为 Enforcing）。
- 邮件服务：若注册/通知异常，检查 Postfix 或 SMTP 配置是否正确并已启动（如 systemctl status postfix）。
五 高频场景速查表
| 症状 |
快速检查 |
处理要点 |
| 访问被拒绝/超时 |
本机 curl、ss -ltnp、firewall-cmd --list-all |
放行 80/443/22；检查云安全组；确认监听地址与端口 |
| 502 Bad Gateway |
gitlab-ctl tail puma/nginx；ss -ltnp |
释放冲突端口；调整 puma[‘port’]；重启后等待初始化完成 |
| 页面空白/报错 |
gitlab-ctl tail nginx/gitlab_error.log；gitlab-ctl tail rails |
查 Nginx 与 Rails 错误日志，按提示修复配置或权限 |
| 安装/启动报依赖错误 |
rpm -ivh 输出；ldd --version；uname -r |
使用匹配系统的 el7/el8 包；安装缺失依赖；避免强行忽略依赖 |
| 升级后异常 |
gitlab-ctl status；gitlab-ctl reconfigure |
核对版本兼容；回滚或按官方步骤升级；检查新增配置项 |
以上步骤覆盖了 服务状态、日志定位、端口与防火墙、配置语法、权限与 SELinux、资源与版本匹配 等常见故障面，可据此系统化排查大多数 CentOS 上的 GitLab 问题。
