📦 第05章 · gitlab.rb 配置

external_url/反代/邮件/HTTPS

gitlab.rb 配置¶

这一章讲 GitLab 的核心配置文件 /etc/gitlab/gitlab.rb,重点讲"外部 nginx 反代"这种最常见的部署形态,以及怎么配域名、关掉 GitLab 自带 letsencrypt、配邮件。本机就是这么配的。

作用与"改后必 reconfigure"¶

gitlab.rb 是 Omnibus 的"声明式配置"入口。你在这里写 external_url、nginx[...]、gitlab_rails[...] 等,然后运行:

sudo gitlab-ctl reconfigure

reconfigure 才会把你的配置落到实处(生成 /var/opt/gitlab/**/gitlab.yml 等并在服务中生效)。改完 gitlab.rb 不 reconfigure 是无效的。

外部 nginx 反代的完整配置(本机实际)¶

这是最推荐的架构:外部 nginx(机外层,监听 0.0.0.0:443,负责 TLS/Let's Encrypt) → GitLab 自带 nginx(仅 127.0.0.1:8090) → GitLab 内部组件(puma/sidekiq 等)。

# ===== 访问地址 =====
external_url 'https://gitlab.bangdream.xyz'

# ===== GitLab 自带 nginx:只监听回环 + 纯 HTTP,TLS 交给外层 =====
nginx['enable'] = true
nginx['listen_address'] = ['127.0.0.1']
nginx['listen_port'] = 8090
nginx['listen_https'] = false
nginx['http2'] = false

# 让 GitLab 正确识别"前面有 https 反代"
nginx['proxy_set_headers'] = {
  "X-Forwarded-Proto" => "https",
  "X-Forwarded-Ssl" => "on",
  "X-Forwarded-For" => "$proxy_add_x_forwarded_for",
  "X-Forwarded-Host" => "$http_host",
  "Host" => "$http_host",
  "Upgrade" => "$http_upgrade",
  "Connection" => "$connection_upgrade"
}

# 不让 GitLab 自动申请 Let's Encrypt(由外层 nginx 统一签发)
letsencrypt['enable'] = false

关键 | listen_https = false 加上 proxy_set_headers 里把 X-Forwarded-Proto 设为 https,GitLab 才知道自己实际是在 HTTPS 后面,否则会让用户/一些链接跑成 http,出现"登录后跳转错、或页面总提示不安全"。

外层 nginx 怎么反代 GitLab¶

外层 nginx(如 /etc/nginx/sites-available/gitlab.bangdream.xyz.conf)注意:

server {
    server_name gitlab.bangdream.xyz;
    client_max_body_size 0;          # 允许大文件(如大仓库推送)
    location / {
        proxy_pass http://127.0.0.1:8090;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_read_timeout 300s;
    }
    # ssl_certificate ... 由 certbot 托管
}

注意 | GitLab 需要 WebSocket 支持(终端/SSH 等),所以外层 nginx 要配 Upgrade/Connection 升级头。还要把 client_max_body_size 设大(或 0),否则上传大仓库/附件会 413。

邮件发送(SMTP)配置¶

本机用 QQ 邮箱 SMTP 发邮件(通知/找回密码):

gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = "smtp.qq.com"
gitlab_rails['smtp_port'] = 465
gitlab_rails['smtp_user_name'] = "1807523025@qq.com"
gitlab_rails['smtp_password'] = "你的QQ邮箱SMTP授权码"
gitlab_rails['smtp_domain'] = "smtp.qq.com"
gitlab_rails['smtp_authentication'] = "login"
gitlab_rails['smtp_enable_starttls_auto'] = false
gitlab_rails['smtp_tls'] = true
gitlab_rails['smtp_ssl'] = false

gitlab_rails['gitlab_email_from'] = '1807523025@qq.com'
gitlab_rails['gitlab_email_reply_to'] = '1807523025@qq.com'
gitlab_rails['gitlab_email_display_name'] = 'GitLab'

注意 | QQ 邮箱要用授权码而非登录密码(在 QQ 邮箱设置里生成)。若报"无法连接发送服务器",检查端口/加密方式是否被运营商屏蔽,或换发件服务。

常用配置项小结¶

配置	作用
`external_url`	对外访问地址,决定链接里显示的域名
`nginx['enable']/listen_*`	控制自带 nginx 是否用、监听哪、是否 TLS
`letsencrypt['enable']`	GitLab 是否自动申请证书(反代场景通常关)
`gitlab_rails['smtp_*']`	邮件发送
`gitlab_rails['time_zone']`	时区(如 `'Asia/Shanghai'`)
`gitlab_rails['initial_root_password']`	首次 root 密码
`postgresql['password']`	内嵌 PostgreSQL 密码

改完怎么让配置生效¶

sudo gitlab-ctl reconfigure     # 应用 gitlab.rb 改动(必须)
sudo gitlab-ctl restart         # 如 nece 需要重启相关组件
gitlab-ctl status               # 看各组件是否 ok

常见坑¶

坑	现象	解决
改了没生效	链接/端口没变	忘了 `reconfigure`,或语法错误
登录后跳 http	反代没设 X-Forwarded-Proto	补 `proxy_set_headers` 里的 https
上传大仓库 413	nginx 客户端大小限制	外层 nginx `client_max_body_size 0`
邮件发不出去	SMTP 参数/授权码/端口错	换授权码;确认 465/587 可出站
`nginx[listen_https]` 冲突	重复 TLS/证书冲突	统一只让一层终止 TLS