Ubuntu 上 GitLab 故障排查思路
一 快速定位与最小闭环
sudo gitlab-ctl status、sudo gitlab-ctl tail（或指定组件如 sudo gitlab-ctl tail nginx）。gitlab-ctl 工具与日志目录 /var/log/gitlab/，适用于 Ubuntu 上的常见部署形态。二 常见症状与对应处置
| 症状 | 高概率原因 | 快速检查 | 处置要点 |
|---|---|---|---|
| 访问返回 502/504 | 上游应用（Puma/Unicorn）未启动或反复重启；端口冲突；工作进程异常 | gitlab-ctl status 观察 puma/unicorn；gitlab-ctl tail puma/unicorn；netstat -nlpt 查端口占用 |
调整 puma['port'] 或 unicorn['port'] 避开占用；gitlab-ctl reconfigure && gitlab-ctl restart puma；必要时清理陈旧 PID 文件后重启 |
| 控制台显示大量 runsv not running | runit 未启动（gitlab-runsvdir 异常） | systemctl status gitlab-runsvdir；gitlab-ctl status 全为 runsv not running |
systemctl start gitlab-runsvdir；若卡住，先 systemctl stop plymouth-quit-wait.service 再启动 runsvdir，随后 gitlab-ctl restart |
| 页面 500 或后台任务失败 | 数据库/缓存不可用；资源不足（如内存） | gitlab-ctl tail postgresql/redis；free -m 查内存与 swap；gitlab-ctl tail 看 Rails 错误 |
启动/修复 postgresql/redis；内存不足时增加 swap；必要时回滚近期配置变更 |
| 配置变更后异常 | 配置未生效或语法不当 | gitlab-ctl reconfigure 输出；gitlab-ctl tail |
修正 /etc/gitlab/gitlab.rb 后 reconfigure 再重启相关组件 |
| 端口被占用导致启动失败 | 其他服务占用了 8080/80/443/22 等 | `netstat -nlpt | grep <端口>` |
| 以上症状与处置覆盖了 502/504、runsv not running、500、配置生效与端口冲突等高频场景，命令与路径均为 Omnibus 在 Ubuntu 上的通用做法。 |
三 关键日志与配置速查
sudo gitlab-ctl tail nginx、sudo gitlab-ctl tail puma、sudo gitlab-ctl tail postgresql、sudo gitlab-ctl tail redis、sudo gitlab-ctl tail gitlab-rails/production.log。sudo gitlab-ctl reconfigure 使配置落地，再按需重启组件（如 gitlab-ctl restart puma）。netstat -nlpt 排查冲突。/opt/gitlab/var/unicorn/unicorn.pid），再重启。四 系统层面的检查与恢复
free -m 检查，必要时增加 swap（创建 swap 文件并启用），再重启服务。gitlab-ctl 大面积报 runsv not running，多为 gitlab-runsvdir 未运行；使用 systemctl start gitlab-runsvdir 恢复，若卡住可先停止 plymouth-quit-wait.service 再启动，随后 gitlab-ctl restart。sudo ufw status，必要时放行对应端口。docker ps -a、容器日志 docker logs <容器名>，并确认宿主机与容器端口映射及防火墙策略正确。