ubuntu gitlab邮件通知设置

Ubuntu 上 GitLab 邮件通知设置指南

一 准备与通用配置

• 准备一个可用于发信的邮箱账号，并确认其 SMTP 服务器、端口、是否需要授权码 等信息。
• 编辑配置文件：sudo vim /etc/gitlab/gitlab.rb，按需添加或修改以下关键项（示例为通用 SMTP 587/STARTTLS）：
  • gitlab_rails[‘smtp_enable’] = true
  • gitlab_rails[‘smtp_address’] = “smtp.example.com”
  • gitlab_rails[‘smtp_port’] = 587
  • gitlab_rails[‘smtp_user_name’] = “your_email@example.com”
  • gitlab_rails[‘smtp_password’] = “your_password_or_app_password”
  • gitlab_rails[‘smtp_domain’] = “example.com”
  • gitlab_rails[‘smtp_authentication’] = “login”
  • gitlab_rails[‘smtp_enable_starttls_auto’] = true
  • gitlab_rails[‘smtp_tls’] = false
  • gitlab_rails[‘gitlab_email_from’] = ‘gitlab@example.com’
  • gitlab_rails[‘gitlab_email_reply_to’] = ‘noreply@example.com’
  • gitlab_rails[‘smtp_openssl_verify_mode’] = ‘peer’
• 说明：
  • 使用端口 465 + SSL 时，将 smtp_port 改为 465，设置 smtp_tls = true，并将 smtp_enable_starttls_auto 设为 false。
  • 某些邮箱（如 QQ 邮箱、Gmail）需要使用授权码/应用专用密码，而非登录密码。
  • 修改后执行：sudo gitlab-ctl reconfigure；必要时 sudo gitlab-ctl restart。

二 常见邮箱快速配置示例

• 提示：QQ 邮箱需开启 SMTP 并使用授权码；Gmail 需开启 两步验证 并生成应用专用密码。

三 应用配置与发送测试

• 应用配置：
  • sudo gitlab-ctl reconfigure
  • sudo gitlab-ctl restart
• 发送测试邮件（Rails 控制台）：
  • sudo gitlab-rails console
  • Notify.test_email(‘you@example.com’, ‘Subject’, ‘Body’).deliver_now
• 看到控制台输出成功信息且邮箱收到邮件，即表示配置生效。

四 故障排查与进阶

• 控制台检查：
  • ActionMailer::Base.delivery_method 应返回 :smtp
  • ActionMailer::Base.smtp_settings 可核对实际生效的 SMTP 参数
• 日志定位：
  • 查看 /var/log/gitlab/gitlab-rails/production.log 中的邮件发送错误
• 常见错误与处理：
  • EOFError / SSL 握手失败：端口 465 请启用 smtp_tls = true；端口 587 请启用 smtp_enable_starttls_auto = true，并确保证书校验模式（如 peer）与服务器匹配
  • Net::OpenTimeout：检查服务器到 SMTP 主机的网络连通性、端口是否被防火墙阻断、SMTP 地址与端口是否正确
  • 认证失败：确认使用授权码/应用专用密码，且用户名、域名与发信邮箱一致
• 进阶方案（系统级 MTA 中继）：
  • 安装 Postfix：sudo apt-get install postfix
  • 在 /etc/postfix/main.cf 中配置 relayhost = [smtp.yourmail.com]:587、启用 SASL 认证等
  • 使用 postmap 生成凭据映射并重启 Postfix，然后在 GitLab 中按 MTA 的主机与端口进行 SMTP 配置。