GitLab 在 CentOS 上如何进行故障排查

GitLab 在 CentOS 上的故障排查步骤

一 快速定位与基础检查

• 检查服务状态与组件健康：执行 sudo gitlab-ctl status，逐组件确认是否 run 或 down；若异常，优先查看对应日志。随后用 sudo gitlab-ctl tail 实时跟踪全部日志，或指定组件如 sudo gitlab-ctl tail nginx/gitlab_error.log。必要时用 sudo journalctl -u gitlab -f 查看 systemd 日志。以上有助于快速定位异常来源与时间点。
• 核对关键配置：打开 /etc/gitlab/gitlab.rb，确认 external_url 是否为服务器可达的 IP/域名（含端口），以及是否误改了 nginx[‘listen_port’] 等网络参数。修改后执行 sudo gitlab-ctl reconfigure 使配置生效，再 sudo gitlab-ctl restart 重启服务。
• 网络与防火墙：确保服务器可访问外网（如 ping 测试），并在防火墙放行 80/443/22（或自定义端口）。示例：sudo firewall-cmd --permanent --add-service=http --add-service=https --add-service=ssh && sudo firewall-cmd --reload。若使用云主机，还需确认云安全组规则同样放行。
• 资源与端口冲突：用 lsof -i:80、lsof -i:443 检查端口占用；若 GitLab 无法启动或响应慢，检查内存与磁盘（建议至少 4GB 内存，避免因 OOM 或磁盘满导致异常）。

二 常见故障与修复

• 页面无法访问或重定向异常：优先核对 external_url 与 nginx 端口配置，执行 reconfigure/restart 后复查；若仅端口变更，确认防火墙与云安全组已放行新端口。
• 端口冲突：定位占用进程并停止或迁移，或调整 gitlab.rb 中的端口后重配重启。
• 防火墙阻断：放行 http/https/ssh 或自定义端口，重载防火墙规则后复测访问。
• 安装依赖或配置错误：依赖安装失败先排查网络与权限；配置文件语法错误（如未去掉注释、参数错误）会导致 reconfigure 失败，修正后重跑。
• 邮件功能异常：确认 Postfix 等邮件服务已安装并运行，且 gitlab.rb 中 smtp_* 参数正确；必要时查看 /var/log/maillog 与 GitLab 邮件相关日志。
• 升级或版本兼容问题：跨版本升级前做好备份，按官方步骤执行，避免组件不兼容引发故障。

三 日志分析与定位技巧

• Omnibus 日志入口：使用 sudo gitlab-ctl tail 实时查看；按组件定位如 sudo gitlab-ctl tail gitlab-rails、sudo gitlab-ctl tail nginx/gitlab_error.log；或直接查看文件 /var/log/gitlab/ 下对应子目录与 production.log 等。
• systemd 日志：用 journalctl -u gitlab -f 跟踪服务整体日志，或按单元查看（如涉及 Rails、Nginx 等）。
• 历史区间检索：用 journalctl --since “2025-11-01” --until “2025-11-19” 聚焦故障时段，结合 gitlab-ctl tail 精确定位报错行与堆栈信息。

四 高频场景速查表

五 变更与回退建议

• 变更前备份：执行 sudo gitlab-rake gitlab:backup:create 完整备份；保留最近可用版本的包与配置，变更失败可快速回退版本与配置。
• 逐步变更与验证：一次只改一处（如仅改 external_url 或仅改端口），改后立刻 reconfigure/restart 并用 tail/journalctl 验证；验证通过再进行下一步。
• 资源与容量规划：确保磁盘与内存充足（建议 ≥4GB 内存），避免因资源不足引发偶发故障或性能劣化。