GitLab Gitaly集群故障排查指南

GitLab Gitaly集群故障排查指南

gitlabhq GitLab CE Mirror | Please open new issues in our issue tracker on GitLab.com 项目地址: https://gitcode.com/gh_mirrors/gi/gitlabhq

概述

Gitaly集群（Praefect）是GitLab中负责管理Git仓库存储和访问的核心组件。当集群出现问题时，可能会导致Git操作失败、性能下降或数据不一致等问题。本文将详细介绍如何排查和解决Gitaly集群的常见问题。

集群健康检查

使用praefect check命令可以快速检查集群的健康状态：

gitlab-ctl praefect check

如果使用Praefect Chart部署，则直接运行二进制文件：

/usr/local/bin/praefect check

检查项详解

1. Praefect数据库迁移状态

   • 检查数据库迁移是否是最新的
   • 如果失败：
     • 检查数据库中的schema_migrations表
     • 运行praefect sql-migrate更新迁移

2. 节点连接性和磁盘访问

   • 检查Praefect能否连接到所有Gitaly节点
   • 检查每个Gitaly节点是否有存储目录的读写权限
   • 如果失败：
     • 验证网络地址和令牌配置
     • 确认Gitaly进程以git用户运行
     • 检查网络连接

3. 数据库读写访问

   • 检查Praefect能否读写数据库
   • 如果失败：
     • 检查数据库是否处于恢复模式：select pg_is_in_recovery()
     • 验证用户权限
     • 检查是否处于只读模式：show default_transaction_read_only

4. 不可访问的仓库

   • 检查因主节点分配问题而不可访问的仓库数量
   • 如果失败：
     • 使用praefect ping-nodes检查节点状态
     • 检查数据库负载

日志中的常见错误

检查/var/log/gitlab/gitlab-rails/production.log中的错误：

HTTP 500错误

• ActionView::Template::Error (7:permission denied)

  • Praefect和GitLab的令牌不匹配
  • Sidekiq服务器缺少存储配置

• Unable to save project. Error: 7:permission denied

  • GitLab服务器和Gitaly服务器间的令牌不匹配

HTTP 503错误

• GRPC::Unavailable (14:failed to connect to all addresses)

  • GitLab无法连接Praefect

• GRPC::Unavailable (14:all SubCons are in TransientFailure...)

  • Praefect无法连接一个或多个Gitaly节点

数据库高CPU负载

Praefect数据库高CPU使用率的常见原因：

1. Prometheus指标收集执行了昂贵的查询

   • 解决方案：设置praefect['configuration'][:prometheus_exclude_database_from_default_metrics] = true

2. 读取分布缓存被禁用

   • 解决方案：确保启用读取分布缓存

仓库元数据检查

使用praefect metadata命令查看仓库元数据：

sudo -u git -- /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml metadata -repository-id <repository-id>

或通过虚拟存储和相对路径：

sudo -u git -- /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml metadata -virtual-storage <virtual-storage> -relative-path <relative-path>

元数据字段说明

• Repository ID: Praefect分配的永久唯一ID
• Virtual Storage: 仓库所在的虚拟存储名称
• Relative Path: 仓库在虚拟存储中的路径
• Replica Path: Gitaly节点上仓库副本的存储位置
• Primary: 当前主节点
• Generation: Praefect用于跟踪仓库变更的计数器
• Replicas: 现有或预期存在的副本列表

仓库同步检查

在某些情况下，Praefect数据库可能与底层Gitaly节点不同步。使用Rake任务检查仓库是否在所有节点上完全同步：

gitlab-rake gitlab:praefect:replicas

常见问题解决方案

关系不存在错误

如果出现relation does not exist错误，可能是数据库表未创建。运行迁移：

sudo -u git -- /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml sql-migrate

无效仓库错误

请求失败并显示repository scoped: invalid Repository错误时，检查Praefect配置中的虚拟存储名称是否与GitLab配置匹配。

云平台性能问题

在云平台上，Praefect节点可能因网络带宽限制而出现性能问题。解决方案：

• 使用更大的虚拟机实例
• 监控网络流量使用情况

配置错误

gitlab-ctl reconfigure失败并显示Praefect配置错误时，检查praefect['database_port']和praefect['database_direct_port']是否配置为整数而非字符串。

常见复制错误

锁文件存在

复制失败并显示error: cannot lock ref错误时，可能是锁文件过时。解决方案：

1. 在Rails控制台中触发OptimizeRepositoryRequest
2. 手动检查并删除24小时前的锁文件

Git fsck错误

当仓库包含无效对象时，可能导致复制失败。解决方案：

1. 从Praefect数据库中移除仓库
2. 使用track-repository命令重新跟踪仓库
3. 确保先备份仓库

总结

Gitaly集群的稳定运行对GitLab至关重要。通过本文介绍的排查方法和解决方案，可以有效解决大多数集群问题。定期检查集群健康状态、监控关键指标，并保持配置一致性，是预防问题的关键措施。

gitlabhq GitLab CE Mirror | Please open new issues in our issue tracker on GitLab.com 项目地址: https://gitcode.com/gh_mirrors/gi/gitlabhq