ubuntu gitlab 邮件通知如何配置

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’。