GitLab在Ubuntu上的故障排除

GitLab在Ubuntu上的常见故障及排除方法

1. 安装过程中的常见问题

• 依赖包缺失：安装GitLab前需确保系统已安装curl、openssh-server、ca-certificates、postfix等基础依赖，若缺失会导致安装失败。可通过sudo apt install -y curl openssh-server ca-certificates postfix命令补全。
• 无法定位GitLab包：若使用apt安装时提示“E: Unable to locate package gitlab-ee/ce”，多为包源未正确配置。需通过GitLab官方脚本添加存储库（如curl -fsSL https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh | sudo bash），再执行安装。
• 内存不足：GitLab最低需要4GB内存（社区版建议），若系统内存不足，会导致服务崩溃或启动失败。可通过sudo fallocate -l 2G /swapfile创建2GB交换分区，并设置权限sudo chmod 600 /swapfile、sudo mkswap /swapfile、sudo swapon /swapfile启用。

2. 配置问题

• external_url配置错误：修改/etc/gitlab/gitlab.rb中的external_url（如external_url 'http://your_server_ip'）后，需运行sudo gitlab-ctl reconfigure使配置生效，否则GitLab无法正常启动。
• 邮件通知配置失败：若需开启邮件提醒，需在/etc/gitlab/gitlab.rb中配置SMTP参数（如gitlab_rails['smtp_enable'] = true、gitlab_rails['smtp_address'] = "smtp.example.com"等），修改后同样需reconfigure。

3. 服务运行故障

• 502 Bad Gateway错误：常见原因包括unicorn进程崩溃、端口冲突（如80端口被占用）或内存不足。
  • 检查unicorn状态：sudo gitlab-ctl status（若unicorn反复重启，需查看日志）；
  • 查看unicorn日志：sudo tail -f /var/log/gitlab/unicorn/current（定位具体错误，如端口占用需修改/etc/gitlab/gitlab.rb中的unicorn['port']）；
  • 重启服务：sudo gitlab-ctl restart。
• 服务无法启动：若gitlab-ctl start失败，需检查runsvdir服务（GitLab服务管理核心），运行sudo systemctl start gitlab-runsvdir启动，再尝试重启GitLab。

4. 日志分析与排查

GitLab日志集中存储在/var/log/gitlab目录下，不同组件的日志路径如下：

• Nginx访问/错误日志：/var/log/gitlab/nginx/；
• Unicorn应用日志：/var/log/gitlab/unicorn/；
• PostgreSQL数据库日志：/var/log/gitlab/postgresql/；
• Sidekiq后台任务日志：/var/log/gitlab/sidekiq/。
  通过tail -f /var/log/gitlab/gitlab-ctl/production.log可实时查看整体服务日志，快速定位问题根源。

5. 常见业务功能问题

• 合并请求被拒绝：需检查代码质量门禁（如CI流水线中的rubocop、eslint检查结果）、单元测试通过率（rspec/pytest结果）或代码编译错误（如Java项目的maven build），修复问题后重新提交。
• CI/CD构建失败：常见原因包括依赖未安装（如package.json未执行npm install）、环境变量未配置（如DATABASE_URL未设置）或镜像错误（如使用了不兼容的基础镜像）。需检查.gitlab-ci.yml文件，确保before_script中包含依赖安装步骤，variables中配置了必要环境变量。
• GitLab Runner离线：Runner状态可通过sudo gitlab-runner status查看，若离线需检查：
  • Runner Token是否过期（需在GitLab项目→Settings→CI/CD→Runners中重新获取并注册）；
  • Runner服务是否运行（sudo systemctl restart gitlab-runner）；
  • 网络是否可达（ping gitlab.example.com）。
• 磁盘空间不足：通过df -h查看磁盘使用情况，若/var/opt/gitlab（GitLab数据目录）占用过高，需清理过期流水线缓存（sudo gitlab-rake cache:clear）、过期构建产物（sudo rm -rf /var/opt/gitlab/gitlab-ci/builds/*）或Docker Registry未使用镜像（docker image prune -a）。

6. 性能优化建议

• 调整内存配置：修改/etc/gitlab/gitlab.rb中的unicorn['worker_processes']（如设为2，减少内存占用）、sidekiq['concurrency']（如设为10，避免过多并发任务），优化Redis内存限制（redis['maxmemory'] = "1gb"）。
• 数据库优化：定期执行sudo gitlab-rake db:migrate更新数据库结构，使用pg_dump备份并压缩数据库（减少存储占用）。