GitLab 核心组件详解

理解各组件职责后，502/503、Git push 失败、Pipeline 不触发等问题才能快速定位到具体进程。Omnibus 通过 gitlab-ctl status 统一查看；Docker 内进程结构相同。

1. GitLab Rails

GitLab Rails 是基于 Ruby on Rails 的应用层，提供 Web UI、REST API、GraphQL 和部分 Git 相关 HTTP 逻辑。

• 进程：Puma（Web 服务器），Omnibus 中通常为 puma 服务；
• 职责：用户认证、Project/Group 权限、Merge Request、Issue、CI 配置解析、Pipeline 创建；
• 数据：业务元数据读写 PostgreSQL；热点数据与队列依赖 Redis；
• 配置：gitlab.rb 中 gitlab_rails[...]、puma[...]。

sudo gitlab-ctl status puma
sudo gitlab-ctl tail puma
curl -s "https://gitlab.example.com/api/v4/version" | head -c 200

Rails 慢或崩溃时，页面与 API 报错，但已建立的 Git SSH 会话可能仍由 Gitaly 处理部分操作。

2. Gitaly

Gitaly 是用 Go 实现的 Git RPC 服务，所有 Git 仓库对象实际存储在 Gitaly 管理的磁盘上（路径如 /var/opt/gitlab/git-data/repositories）。

• 职责：git receive-pack、upload-pack、ref 更新、hook 回调；
• 扩展：Gitaly Cluster（ Praefect ）用于多节点高可用；
• 配置：gitaly['configuration']、git_data_dirs。

sudo gitlab-ctl status gitaly
sudo gitlab-rake gitlab:gitaly:check
du -sh /var/opt/gitlab/git-data/repositories

注意

禁止手动 rm 仓库目录或绕过 Gitaly 直接改 .git；备份使用 gitlab-backup 或 Gitaly 官方流程。

3. PostgreSQL

GitLab 使用 PostgreSQL 存储用户、项目、MR、Pipeline、Job 日志索引等元数据（不是 Git 对象本身）。

• Omnibus：内置 PostgreSQL，数据目录 /var/opt/gitlab/postgresql/data；
• 生产：可改为外部 PostgreSQL（RDS 等），减轻单机压力并便于 DBA 备份；
• 配置：postgresql[...] 或 gitlab_rails['db_*'] 指向外部库。

sudo gitlab-ctl status postgresql
sudo gitlab-psql -c "SELECT version();"
sudo gitlab-rake db:migrate:status | tail -5

磁盘满或连接池耗尽时，会出现 500 错误和 Sidekiq 积压。

4. Redis

Redis 在 GitLab 中用于：

• Rails 缓存与会话；

• Sidekiq 任务队列；

• Rate limiting、Action Cable 等。

• Omnibus：内置 Redis，通常仅监听本地；

• 生产：可使用 Redis Sentinel/Cluster 或云 Redis，需在 gitlab.rb 配置多个 Redis 实例角色（queues、cache 等，视版本而定）。

sudo gitlab-ctl status redis
sudo gitlab-rails console -e production
# 在 console 中: Gitlab::Redis::Cache.with { |r| r.ping }

Redis 不可用时，登录、Pipeline 调度、后台邮件会大面积失败。

5. Sidekiq

Sidekiq 消费 Redis 中的异步 Job：发送邮件、Webhook、Pipeline 处理、Repository 维护、Elasticsearch 索引等。

• 进程：Omnibus 中可能有多组 sidekiq（不同 queue）；
• 队列：default、mailers、pipeline 等，积压时在 Admin → Monitoring → Background Jobs 查看；
• 配置：sidekiq['max_concurrency']、队列拆分。

sudo gitlab-ctl status sidekiq
sudo gitlab-ctl tail sidekiq
sudo gitlab-rake gitlab:sidekiq:check

提示

「MR 已合并但邮件没发」「Pipeline 卡在 pending」——先查 Sidekiq 队列深度和 Redis，再查 Runner。

6. Workhorse

GitLab Workhorse 是 Go 写的智能反向代理，坐在 Nginx 与 Rails 之间。

• 职责：大文件上传、Git HTTP（git clone/push over HTTPS）流式转发到 Gitaly 或 Rails；
• 避免：大 pack 文件经 Ruby 进程内存；
• 配置：gitlab_workhorse[...]。

sudo gitlab-ctl status gitlab-workhorse
sudo gitlab-ctl tail gitlab-workhorse

Git over HTTPS 失败时，同时查看 Workhorse 与 Gitaly 日志，而不是只看 Rails。

7. Nginx

Nginx 作为入口反向代理：

• 终结 TLS（或由上游 LB 终结）；
• 静态资源、Pages、Registry 路由；
• 将 API/UI 请求转发 Workhorse/Rails。

sudo gitlab-ctl status nginx
sudo nginx -t   # Omnibus 使用嵌入式 nginx 配置
curl -sI "https://gitlab.example.com"

502 Bad Gateway 常见原因：Puma 未就绪、Workhorse socket 错误、磁盘满。

8. Container Registry

Container Registry 基于 Distribution，存储 OCI 镜像，与 Project 路径关联。

• 地址：registry.example.com 或 gitlab.example.com:5050（取决于 registry_external_url）；
• 鉴权：JWT 与 GitLab 用户/Deploy Token 集成；
• 存储：本地磁盘或 S3/GCS 等对象存储。

sudo gitlab-ctl status registry
grep registry /etc/gitlab/gitlab.rb
curl -sI "https://registry.example.com/v2/"

Pipeline 中 docker login 使用 CI_REGISTRY_USER / CI_REGISTRY_PASSWORD 或 Deploy Token。

9. 各组件之间的调用关系

Web/API、Git over HTTPS、Git over SSH 和 CI/CD 会经过不同的入口与后端组件。排障时先确认请求类型，再按图中箭头逐段检查。

9.5 排障对照表

现象	优先检查
网页 502	nginx, puma, workhorse
git push SSH 失败	sshd, gitlab-shell, gitaly
git push HTTPS 失败	nginx, workhorse, gitaly
Pipeline pending	sidekiq, redis, runner
镜像 push 失败	registry, nginx, 证书
全站慢	postgresql, redis, 磁盘 I/O

# 一键概览
sudo gitlab-ctl status
sudo gitlab-rake gitlab:check

下一章：配置管理。