GitLab在Linux上的故障排查指南是什么

GitLab在Linux上的故障排查指南

一、基础状态检查

1. 服务状态核查
   使用gitlab-ctl status命令检查GitLab各组件（如nginx、postgresql、unicorn等）的运行状态。若组件显示为“down”或“unhealthy”，需进一步排查对应服务的日志或尝试重启服务（gitlab-ctl restart <component_name>）。
2. 系统资源监控
   通过top、htop、free -m（内存）、df -h（磁盘空间）等命令监控系统资源使用情况。若内存占用超过80%、磁盘空间剩余不足10%，可能导致GitLab响应缓慢或服务崩溃，需清理无用文件（如过期构建产物、日志）或扩容服务器。

二、日志深度分析

1. 核心日志路径
   GitLab的主要日志集中于/var/log/gitlab目录，其中：
   • 应用层日志：/var/log/gitlab/gitlab-rails/production.log（记录请求处理、数据库操作等）；
   • 错误日志：/var/log/gitlab/gitlab-rails/production_json.log（JSON格式的异常详情）；
   • Nginx日志：/var/log/gitlab/nginx/gitlab_error.log（网络/代理错误）；
   • 组件日志：/var/log/gitlab/gitlab-shell.log（SSH操作）、/var/log/gitlab/unicorn/*.log（Unicorn服务器日志）。
2. 实时日志查看
   使用gitlab-ctl tail命令实时输出所有组件的日志，或通过tail -f /var/log/gitlab/gitlab-rails/production.log跟踪特定日志文件，快速定位错误发生时间点及相关上下文。

三、配置文件验证

1. 配置文件检查
   GitLab的主配置文件为/etc/gitlab/gitlab.rb，需重点核查以下关键配置：
   • external_url：确保URL格式正确（如http://yourdomain.com或https://yourdomain.com），且与实际访问地址一致；
   • SSL证书：若启用HTTPS，检查nginx['ssl_certificate']和nginx['ssl_certificate_key']路径是否指向有效证书，证书是否过期；
   • 数据库连接：postgresql['host']、postgresql['port']等参数是否正确（默认本地数据库为localhost:5432）。
2. 配置重载
   修改配置文件后，必须执行gitlab-ctl reconfigure命令重新应用配置（该命令会自动检查配置语法并更新服务配置），然后重启GitLab服务（gitlab-ctl restart）使变更生效。

四、常见错误场景及解决方案

1. 服务无法启动
   • 原因：端口冲突（如80/443端口被其他服务占用）、依赖库缺失（如curl、openssh-server）、配置文件错误。
   • 解决：
     • 使用netstat -tulnp | grep <port>检查端口占用情况，终止冲突进程或修改GitLab端口；
     • 执行yum install -y curl policycoreutils-python openssh-server安装缺失依赖；
     • 运行gitlab-ctl reconfigure修复配置语法问题。
2. 权限问题
   • 表现：“Permission denied”错误（如无法推送代码、访问仓库）。
   • 解决：
     • 检查仓库目录权限（如/var/opt/gitlab/git-data/repositories），确保git用户拥有读写权限（chown -R git:git /var/opt/gitlab/git-data）；
     • 验证SSH密钥是否添加至GitLab账户（~/.ssh/id_rsa.pub），或HTTPS Token是否有效。
3. 500/502错误
   • 500错误：通常为后端应用层故障（如数据库连接失败、代码异常）。
     • 解决：查看/var/log/gitlab/gitlab-rails/production.log，定位具体错误（如数据库超时需优化查询，代码异常需修复应用）。
   • 502错误：多为Nginx与GitLab应用层通信失败（如unicorn进程崩溃、端口未监听）。
     • 解决：检查gitlab-ctl status确认unicorn服务运行状态，查看/var/log/gitlab/unicorn/*.log中的错误日志，重启unicorn（gitlab-ctl restart unicorn）。
4. CI/CD构建失败
   • 原因：Runner未注册、依赖未安装、环境变量缺失。
   • 解决：
     • 运行gitlab-runner list检查Runner状态，未注册则执行gitlab-runner register并填写正确的GitLab URL及Token；
     • 确保Runner环境中安装了构建所需的依赖（如gcc、python、docker）；
     • 在项目CI/CD设置中添加必要的环境变量（如API_KEY）。
5. 磁盘空间不足
   • 原因：过期流水线缓存、构建产物堆积、Docker镜像未清理。
   • 解决：
     • 清理过期流水线：gitlab-rake gitlab:cleanup:orphan_pipeline_caches；
     • 删除未使用的Docker镜像：docker image prune -a；
     • 扩容服务器磁盘或迁移GitLab数据至更大存储设备。