跳到主要内容

GitLab 故障排查

本章按 症状 → 检查命令 → 常见修复 组织，适用于 Omnibus 部署。排查时先收集日志，避免未定位根因就整站重启。

通用日志入口：

sudo gitlab-ctl tail          # 所有服务
sudo gitlab-ctl tail nginx    # 单服务
sudo gitlab-ctl tail gitaly

1. GitLab服务无法启动​

症状：gitlab-ctl start 后服务反复 down；reconfigure 报错退出。

检查命令：

sudo gitlab-ctl status
sudo gitlab-ctl reconfigure 2>&1 | tee /tmp/reconfigure.log
sudo tail -100 /var/log/gitlab/reconfigure/reconfigure.log
sudo gitlab-rake gitlab:check
# 配置语法
sudo gitlab-ctl diff-config

常见修复：

  • gitlab.rb 语法错误：回滚最近修改，gitlab-ctl reconfigure
  • 端口冲突：ss -tlnp | grep -E ':80|:443|:8080'，调整 nginx/puma 端口
  • 磁盘满：df -h /var/opt/gitlab，清理日志/备份后重启
  • PostgreSQL 未就绪：gitlab-ctl restart postgresql && sleep 10 && gitlab-ctl restart puma sidekiq
  • 权限问题：gitlab-ctl reset-permissions

2. Web页面无法访问​

症状：浏览器超时或 502/504；curl 本地也失败。

检查命令：

curl -vI http://127.0.0.1/
curl -vI http://127.0.0.1:8080/   # Puma 直连
sudo gitlab-ctl status nginx puma workhorse
sudo tail -50 /var/log/gitlab/nginx/error.log
sudo tail -50 /var/log/gitlab/puma/puma_stderr.log

常见修复：

  • Nginx 502 + Puma down：gitlab-ctl restart puma
  • Workhorse 异常：gitlab-ctl restart gitlab-workhorse
  • external_url 与访问 URL 不一致：修正 gitlab.rb 中 external_url 后 reconfigure
  • 上游超时（大文件上传）：调大 nginx['proxy_read_timeout'] 和 gitlab_rails['max_attachment_size']
  • SELinux 拦截（RHEL）：setsebool -P httpd_can_network_connect 1

3. SSH无法连接​

症状：git clone git@gitlab.example.com:... 超时或 Permission denied (publickey)。

检查命令：

ssh -vvv -T git@gitlab.example.com
sudo gitlab-ctl status gitlab-sshd  # 或 sshd
sudo tail -50 /var/log/gitlab/gitlab-shell/gitlab-shell.log
# 验证用户公钥是否入库
sudo gitlab-rails runner "puts User.find_by(username:'git').keys.count"
grep gitlab /etc/ssh/sshd_config

常见修复：

  • 端口不一致：UI 显示的 SSH 端口须与 gitlab_shell_ssh_port 一致
  • 公钥未添加：用户在 Preferences → SSH Keys 重新上传
  • gitlab-sshd 与系统 sshd 冲突：只启用一种，Omnibus 默认 gitlab-sshd
  • 防火墙未放行：ufw allow 22 或自定义端口
  • AuthorizedKeys 损坏：gitlab-rake gitlab:shell:setup 后 reconfigure

4. Pipeline执行失败​

症状：Pipeline 状态 failed；部分 job 红叉。

检查命令：

# 查看具体 job 日志（UI 或 API）
curl --header "PRIVATE-TOKEN: <token>" \
  "https://gitlab.example.com/api/v4/projects/<id>/pipelines/<pipeline_id>/jobs"

# Runner 是否在线
sudo gitlab-rails runner "Ci::Runner.all.each { |r| puts \"#{r.id} #{r.description} #{r.contacted_at}\" }"

# Sidekiq 是否处理 CI 状态
sudo gitlab-rails runner "puts Sidekiq::Queue.new('pipeline_processing').size"

常见修复：

  • Runner offline：在 Runner 主机 gitlab-runner restart，检查 token 是否过期
  • 无匹配 Runner：检查 .gitlab-ci.yml 的 tags 与 Runner tags
  • 脚本错误：修复 job 脚本（非平台问题）
  • 变量缺失：检查 CI/CD Variables 是否 Protected/Mask 导致未注入
  • 镜像拉取失败：配置 CI_REGISTRY 凭证或镜像代理
  • 磁盘满导致 artifact 上传失败：清理 Runner 缓存与 GitLab 磁盘

5. Runner异常​

症状：Job 长时间 pending；Runner 显示 stale；Docker executor 报错。

检查命令：

sudo gitlab-runner verify
sudo gitlab-runner list
sudo journalctl -u gitlab-runner -n 100 --no-pager
docker info   # Docker executor
sudo gitlab-rails runner "Ci::Runner.find(<id>).runner_projects.count"

常见修复：

  • Token 失效：在 GitLab UI 重置 Runner token，更新 /etc/gitlab-runner/config.toml
  • Docker 权限：usermod -aG docker gitlab-runner
  • 并发过高：降低 concurrent 配置
  • 残留容器占满资源：docker system prune -f（确认无影响后执行）
  • 网络不通 Runner → GitLab：检查防火墙与 clone_url

6. Git操作缓慢​

症状：clone/push/fetch 极慢；大仓库超时。

检查命令：

# Gitaly 延迟
curl -s http://127.0.0.1:9236/metrics | grep gitaly_service_client_duration
sudo gitlab-ctl tail gitaly

# 磁盘 IO
iostat -x 1 5
df -h /var/opt/gitlab/git-data

# 网络
ping -c 5 gitlab.example.com

常见修复：

  • 磁盘 IO 瓶颈：迁移 git-data 到 SSD；启用 Gitaly 缓存
  • 超大 monorepo：启用 partial clone、GIT_DEPTH 限制 CI clone 深度
  • Gitaly 内存不足：调大 gitaly['env'] = { 'GITALY_COMMAND_SPAWN_MAX_PARALLEL' => '4' }
  • 网络带宽：部署 Geo 或就近 Runner；大文件走 LFS
  • pack-objects CPU 高：低峰期执行 git gc，考虑 Gitaly Cluster 分散负载

7. 数据库异常​

症状：500 错误日志含 PG::；reconfigure 报 PostgreSQL 连接失败；页面极慢。

检查命令：

sudo gitlab-ctl status postgresql
sudo gitlab-psql -c "SELECT 1;"
sudo gitlab-psql -c "SELECT count(*) FROM pg_stat_activity;"
sudo gitlab-psql -c "SELECT pg_size_pretty(pg_database_size('gitlabhq_production'));"
sudo tail -50 /var/log/gitlab/postgresql/current

常见修复：

  • 连接数耗尽：调大 postgresql['max_connections']，排查泄漏的长连接
  • 磁盘满导致 WAL 无法写入：紧急扩容或清理
  • 索引膨胀：gitlab-rake gitlab:db:reindex（低峰期）
  • 迁移中断：查看 /var/opt/gitlab/postgresql/data/log，必要时从备份恢复
  • 外部 PostgreSQL 切换后连错库：核对 gitlab.rb 中 postgresql['enable'] = false 及连接参数

8. Redis异常​

症状：登录/session 异常；Sidekiq 不消费；报 Redis::CannotConnectError。

检查命令：

sudo gitlab-ctl status redis
sudo gitlab-redis-cli PING
sudo gitlab-redis-cli INFO memory
sudo gitlab-redis-cli INFO persistence
sudo tail -50 /var/log/gitlab/redis/current

常见修复：

  • Redis down：gitlab-ctl restart redis
  • 内存满触发 eviction：调大 redis['maxmemory'] 或扩容；检查异常大 key
  • AOF/RDB 持久化失败：检查磁盘权限与空间
  • Sentinel HA 脑裂：确认 sentinel quorum，手动 failover 测试
  • 外部 Redis 密码错误：核对 gitlab.rb 中 redis['password']

9. Gitaly异常​

症状：push/pull 失败；报 GitalyClientError；仓库操作 500。

检查命令：

sudo gitlab-ctl status gitaly
sudo gitlab-ctl tail gitaly
curl -s http://127.0.0.1:9236/metrics | grep gitaly_errors
sudo gitlab-rake gitlab:gitaly:check
ls -la /var/opt/gitlab/git-data/repositories/

常见修复：

  • Gitaly 进程挂：gitlab-ctl restart gitaly
  • 磁盘只读或满：修复文件系统后重启
  • 仓库权限损坏：gitlab-rake gitlab:check SANITIZE=true，按提示修复
  • storage 配置不一致：核对 gitlab.rb 中 git_data_dirs 与 config.toml
  • Gitaly Cluster 节点不一致：检查 Praefect 日志，gitlab-ctl restart praefect

10. 备份失败排查​

症状：cron 备份无新文件；gitlab-backup create 报错；备份 tar 体积异常小。

检查命令：

sudo gitlab-backup create CRON=1 2>&1 | tee /tmp/backup.log
ls -lht /var/opt/gitlab/backups/ | head -5
sudo tail -100 /var/log/gitlab/gitlab-rails/production.log | grep -i backup
df -h /var/opt/gitlab/backups
sudo gitlab-rake gitlab:backup:verify PARTS=db,repositories,uploads

常见修复：

  • 磁盘空间不足：扩容或清理旧备份
  • 权限问题：chown git:git /var/opt/gitlab/backups
  • PostgreSQL 备份超时：低峰期执行；调大 backup 脚本 timeout
  • 跳过了 secrets：确认同时备份 /etc/gitlab/gitlab-secrets.json
  • 对象存储未纳入：启用 gitlab_rails['backup_upload_connection'] 上传异地
  • 版本不匹配恢复失败：备份与恢复 GitLab 版本必须一致（大版本）

备份成功后验证：

# 记录校验和
sha256sum /var/opt/gitlab/backups/<timestamp>_gitlab_backup.tar
# 定期在测试机执行 restore 演练（见 05-backup 章节）