Ubuntu 上 GitLab 邮件通知配置指南
一 准备与原则
- 所有配置集中在文件：/etc/gitlab/gitlab.rb。修改后必须执行：sudo gitlab-ctl reconfigure 使配置生效。完成后可用控制台测试：sudo gitlab-rails console 后执行 Notify.test_email(‘收件人’,‘主题’,‘正文’).deliver_now。日志排查路径：/var/log/gitlab/gitlab-rails/production.log。这些步骤适用于 Ubuntu 上的 Omnibus 安装。
二 方案一 直接配置 GitLab SMTP（推荐）
- 编辑配置文件
- 打开：sudo vim /etc/gitlab/gitlab.rb
- 按需填入你的 SMTP 参数（示例为端口 587 + STARTTLS；如使用 465 + SSL 见后文差异）
- 常用参数模板（将示例值替换为你的邮箱服务商信息）
- 启用与发件人
- gitlab_rails[‘smtp_enable’] = true
- gitlab_rails[‘gitlab_email_from’] = ‘gitlab@yourdomain.com’
- gitlab_rails[‘gitlab_email_display_name’] = ‘GitLab’
- SMTP 连接
- gitlab_rails[‘smtp_address’] = “smtp.yourmail.com”
- gitlab_rails[‘smtp_port’] = 587
- gitlab_rails[‘smtp_user_name’] = “your_email@yourmail.com”
- gitlab_rails[‘smtp_password’] = “your_password_or_app_password”
- gitlab_rails[‘smtp_domain’] = “yourmail.com”
- gitlab_rails[‘smtp_authentication’] = “login”
- gitlab_rails[‘smtp_enable_starttls_auto’] = true
- gitlab_rails[‘smtp_tls’] = false
- gitlab_rails[‘smtp_openssl_verify_mode’] = ‘peer’ # 自签证书可用 ‘none’
- 使配置生效并测试
- 应用：sudo gitlab-ctl reconfigure
- 测试：sudo gitlab-rails console → Notify.test_email(‘you@example.com’,‘test’,‘body’).deliver_now
- 常见服务商要点
- QQ 邮箱：SMTP 为 smtp.qq.com:587，密码使用授权码；部分环境需要 smtp_tls = false（避免 SSL 冲突）。
- Gmail：SMTP 为 smtp.gmail.com:587；需开启两步验证并使用应用专用密码；保持 smtp_tls = false、enable_starttls_auto = true。
三 方案二 使用系统 Postfix 作为 SMTP 中继
- 安装并配置 Postfix 中继
- 安装：sudo apt-get install postfix
- 编辑 /etc/postfix/main.cf（示例为端口 587 中继）
- relayhost = [smtp.yourmail.com]:587
- smtp_use_tls = yes
- smtp_sasl_auth_enable = yes
- smtp_sasl_security_options = noanonymous
- smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd
- smtp_tls_security_level = encrypt
- header_size_limit = 4096000
- 保存凭据：/etc/postfix/sasl_passwd
- [smtp.yourmail.com]:587 your_email@yourmail.com:your_password
- 生成映射并重启 Postfix
- sudo postmap /etc/postfix/sasl_passwd
- sudo systemctl restart postfix
- 配置 GitLab 使用本地 Postfix
- 在 /etc/gitlab/gitlab.rb 中仅保留发件人等关键信息，SMTP 连接由 Postfix 处理
- gitlab_rails[‘smtp_enable’] = true
- gitlab_rails[‘gitlab_email_from’] = ‘gitlab@yourdomain.com’
- gitlab_rails[‘gitlab_email_display_name’] = ‘GitLab’
- 应用：sudo gitlab-ctl reconfigure；测试同上。
四 465 端口 SSL 与常见排错
- 使用 465/SSL 时的关键差异
- gitlab_rails[‘smtp_port’] = 465
- gitlab_rails[‘smtp_enable_starttls_auto’] = false
- gitlab_rails[‘smtp_tls’] = true
- 其他参数（address、user、password、domain、authentication）不变
- 常见报错与处理
- EOFError / SSL 握手失败：多为 smtp_tls 与端口/加密方式不匹配；587 用 STARTTLS（tls=false），465 用 SSL（tls=true）。
- Net::OpenTimeout：网络不通或端口被防火墙拦截；检查云安全组/本机防火墙是否放行 25/465/587，并确认 SMTP 主机可达。
- 证书校验失败：将 smtp_openssl_verify_mode 设为 ‘none’（仅测试环境），生产环境建议使用有效证书并保持 ‘peer’。