Ubuntu 上 GitLab 运行错误的排查与修复指南
一、快速定位与通用排查
- 查看整体状态与实时日志
- 执行：sudo gitlab-ctl status、sudo gitlab-ctl tail（或指定服务：sudo gitlab-ctl tail postgresql）。Omnibus 包日志默认在 /var/log/gitlab/ 目录。
- 配置变更后使其生效
- 执行：sudo gitlab-ctl reconfigure，必要时再 sudo gitlab-ctl restart。
- 资源与权限检查
- 内存/磁盘/CPU：用 free -m、df -h、top 观察是否资源不足；磁盘满或内存紧张会导致组件反复重启或 502。
- 权限/属主：确保 /var/opt/gitlab、/var/log/gitlab 等目录属主为 git:git，权限合理。
二、高频故障与对应修复
- 全部或多数组件报 runsv not running
- 现象：执行 gitlab-ctl restart 时大量服务显示 “fail: xxx: runsv not running”。
- 处理步骤：
- 重启 runit 管理：sudo systemctl restart gitlab-runsvdir
- 检查是否有阻塞的 systemd 任务：systemctl -t target、systemctl list-jobs
- 若发现 plymouth-quit-wait.service 长时间 running，按官方建议卸载 Plymouth：sudo apt remove --purge plymouth，随后 gitlab-ctl start。
- 访问出现 502 Bad Gateway
- 可能原因与处理：
- 应用进程反复重启（如 Unicorn/Puma 启动失败）：查看 /var/log/gitlab/unicorn/current 或 /var/log/gitlab/puma/current，常见为内存不足或配置错误。
- 端口冲突：检查端口占用 netstat -nlpt；若 8080 等端口被占用，编辑 /etc/gitlab/gitlab.rb，为 puma[‘port’] 或 unicorn[‘port’] 换一个未被占用的端口，执行 reconfigure 与 restart。
- 资源不足导致超时：小内存实例（如仅有 2–4GB）首次启动或高并发时易 502，先扩容内存或启用 swap，并耐心等待初始化完成后再访问。
- 内置数据库（PostgreSQL）连接或启动异常
- 处理步骤：
- 查看状态：sudo gitlab-ctl status postgresql
- 重启组件：sudo gitlab-ctl restart postgresql
- 查看日志定位：sudo gitlab-ctl tail postgresql
- 若提示配置或权限问题，先 gitlab-ctl reconfigure；仍异常时检查磁盘空间、内存与目录权限。
三、最小可用修复操作清单
- 第 1 步：获取现场信息
- sudo gitlab-ctl status；sudo gitlab-ctl tail（必要时指定具体服务）
- 第 2 步：若大量 “runsv not running”
- sudo systemctl restart gitlab-runsvdir → systemctl -t target / systemctl list-jobs → 如 plymouth-quit-wait.service 阻塞则 sudo apt remove --purge plymouth → gitlab-ctl start
- 第 3 步：若是 502
- 查看 unicorn/puma 日志；检查端口冲突 netstat -nlpt 并在 /etc/gitlab/gitlab.rb 调整 puma[‘port’]；执行 reconfigure 与 restart
- 第 4 步：若数据库异常
- sudo gitlab-ctl tail postgresql → sudo gitlab-ctl restart postgresql → 必要时 gitlab-ctl reconfigure
- 第 5 步：资源紧张
- free -m、df -h；扩容内存或启用 swap，再重启服务
四、预防与优化建议
- 资源规划
- 生产环境建议内存不低于 4GB，更稳妥为 8GB 或以上；内存不足易引发 502 与组件反复重启。
- 端口与进程规划
- 避免将 8080/80/443 等常用端口分配给其他服务；变更 external_url 或应用端口后务必 reconfigure 与 restart。
- 变更与回滚
- 修改 /etc/gitlab/gitlab.rb 后统一通过 gitlab-ctl reconfigure 使配置生效；重要变更前做好配置与数据备份。
