GitLab 配置管理

GitLab Omnibus 的配置中枢是 /etc/gitlab/gitlab.rb。修改后必须 gitlab-ctl reconfigure 才会渲染到各组件配置文件并重启相关服务。不要直接改 /var/opt/gitlab/nginx/conf/ 等生成目录——下次 reconfigure 会被覆盖。

1. GitLab配置文件介绍

路径	说明
/etc/gitlab/gitlab.rb	主配置（唯一应手工编辑的入口）
/etc/gitlab/gitlab-secrets.json	加密密钥，必须备份，权限 0600
/var/opt/gitlab/	运行时数据（Git、DB、Redis、Registry）
/var/log/gitlab/	各组件日志

查看渲染后的某组件配置：

sudo gitlab-ctl show-config | less
# 或
sudo cat /var/opt/gitlab/nginx/conf/gitlab-http.conf | head -30

Docker 场景对应挂载的 ./config/gitlab.rb。

2. gitlab.rb配置详解

gitlab.rb 是 Ruby DSL，常用模式：

# 注释掉的键表示默认值；取消注释并赋值才会生效
external_url 'https://gitlab.example.com'

gitlab_rails['time_zone'] = 'Asia/Shanghai'
gitlab_rails['backup_keep_time'] = 604800   # 备份保留 7 天

puma['worker_processes'] = 4
sidekiq['max_concurrency'] = 20

按组件前缀分组：

前缀	组件
gitlab_rails	Rails 应用
nginx	Nginx
gitlab_workhorse	Workhorse
gitaly	Gitaly
postgresql	内置 PostgreSQL
redis	内置 Redis
registry	Container Registry
gitlab_shell	Git SSH

提示

变更前备份：sudo cp /etc/gitlab/gitlab.rb /etc/gitlab/gitlab.rb.bak.$(date +%F)，并用 Git 或配置管理工具跟踪差异。

3. external_url配置

external_url 影响 Web 地址、克隆 URL 生成、OAuth 回调、Registry 地址推导。

# HTTPS 主站
external_url 'https://gitlab.example.com'

# 若 Web 走 443 但 SSH 用 2222（常见于 Docker 端口映射）
gitlab_rails['gitlab_shell_ssh_port'] = 2222

修改后：

sudo gitlab-ctl reconfigure
sudo gitlab-rake cache:clear

验证克隆地址是否在 Project → Clone 中显示正确 HTTPS/SSH URL。

注意

external_url 与浏览器实际访问不一致会导致 OAuth、CI CI_SERVER_URL、Container Registry 登录失败。

4. SSH配置

4.1 sshd 端口

gitlab_rails['gitlab_shell_ssh_port'] = 2222

防火墙与 ~/.ssh/config 需同步：

Host gitlab.example.com
  HostName gitlab.example.com
  Port 2222
  User git

4.2 gitlab-shell

gitlab_shell['auth_file'] = "/var/opt/gitlab/.ssh/authorized_keys"

用户 SSH Key 在 GitLab UI 管理，由 gitlab-shell 写入 authorized_keys。排查 git@gitlab.example.com 连接：

sudo gitlab-ctl tail gitlab-shell
ssh -vvv -T -p 2222 git@gitlab.example.com

5. SMTP邮件配置

Merge Request、Pipeline 失败通知依赖邮件。示例（SMTP 提交端口 587）：

gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = "smtp.example.com"
gitlab_rails['smtp_port'] = 587
gitlab_rails['smtp_user_name'] = "gitlab@example.com"
gitlab_rails['smtp_password'] = "替换为应用专用密码"
gitlab_rails['smtp_domain'] = "example.com"
gitlab_rails['smtp_authentication'] = "login"
gitlab_rails['smtp_enable_starttls_auto'] = true
gitlab_rails['gitlab_email_from'] = 'gitlab@example.com'
gitlab_rails['gitlab_email_reply_to'] = 'noreply@example.com'

sudo gitlab-ctl reconfigure
sudo gitlab-rails console -e production
# Notify.test_email('you@example.com', 'GitLab Test', 'Body').deliver_now

密码不要提交 Git；生产用 Vault/K8s Secret 注入 gitlab.rb 模板。

6. Registry配置

独立 Registry 域名示例：

registry_external_url 'https://registry.example.com'
gitlab_rails['registry_enabled'] = true

registry['storage'] = {
  's3' => {
    'bucket' => 'gitlab-registry-prod',
    'region' => 'ap-southeast-1',
    'accesskey' => 'AKIA...',
    'secretkey' => '...'
  }
}

本地磁盘（小规模）：

registry_external_url 'https://gitlab.example.com:5050'
registry['enable'] = true

sudo gitlab-ctl reconfigure
curl -sI "https://registry.example.com/v2/"

Pipeline 变量：CI_REGISTRY、CI_REGISTRY_IMAGE、CI_REGISTRY_USER。

7. 日志配置

logging['log_level'] = 'INFO'   # 排障时可临时 WARN/ DEBUG（注意磁盘）
nginx['access_log_format'] = 'combined'

常用 tail：

sudo gitlab-ctl tail nginx/gitlab_access.log
sudo gitlab-ctl tail puma
sudo gitlab-ctl tail sidekiq
sudo gitlab-ctl tail gitaly

日志轮转由 logrotate 管理；磁盘满时优先清理旧 backup 与 oversized log。

8. 性能相关配置

按机器规格调整，需压测验证：

puma['worker_processes'] = 4
puma['min_threads'] = 4
puma['max_threads'] = 4

sidekiq['max_concurrency'] = 25

postgresql['shared_buffers'] = "256MB"
postgresql['max_connections'] = 200

gitaly['configuration'] = {
  concurrency: [
    {
      'rpc' => "/gitaly.SmartHTTPService/PostReceivePack",
      'max_per_repo' => 3,
    },
  ],
}

外部 PostgreSQL/Redis 时，在 gitlab_rails['db_*'] 和 Redis 相关键中配置连接，并关闭内置服务：

postgresql['enable'] = false
redis['enable'] = false
# 并配置 gitlab_rails['db_*']、redis 连接

注意

盲目增大 puma['worker_processes'] 会导致内存耗尽；先 free -h 与监控，再逐步调高。

9. 配置生效与检查

9.1 标准流程

sudo gitlab-ctl diff-config    # 查看相对上次 reconfigure 的 gitlab.rb 差异（若支持）
sudo gitlab-ctl reconfigure    # 应用配置，必要时重启服务
sudo gitlab-ctl restart        # 仅当 reconfigure 后仍异常时整体重启

reconfigure 会运行 Chef 配方，耗时 2～10 分钟；生产建议在低峰执行。

9.2 验证

sudo gitlab-rake gitlab:check SANITIZE=true
sudo gitlab-rake gitlab:doctor
sudo gitlab-ctl status
curl -fsS "https://gitlab.example.com/-/readiness"

9.3 常见错误

错误	处理
reconfigure 报 nginx 配置错误	nginx['ssl_certificate'] 路径或权限
邮件仍不发	SMTP 凭据、防火墙 587、Sidekiq mailers 队列
Registry 401	registry_external_url 与登录域名不一致
502 after 调 puma	降低 worker 数或加内存

下一章：用户与权限管理。