Ubuntu如何配置GitLab邮件通知

Ubuntu 配置 GitLab 邮件通知

一 准备与前提

• 准备一个可用的SMTP账号（如公司邮箱或公共邮箱），并开启SMTP 服务与“授权码/应用专用密码”。
• 可选：安装本地 Postfix 作为发送代理（安装 GitLab 时常被一起安装；若使用外部 SMTP，可不启用本机 MTA）。
• 修改 GitLab 配置后需执行 gitlab-ctl reconfigure 使配置生效。

二 配置步骤

1. 编辑配置文件
   打开：sudo vim /etc/gitlab/gitlab.rb，在文件末尾添加或修改如下关键项（示例为通用 SMTP，端口 587/STARTTLS）：

   # 启用 SMTP
   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_smtp_password_or_app_token"
   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'
   # gitlab_rails['smtp_ca_file'] = '/path/to/cacert.pem'
   # gitlab_rails['smtp_pool'] = true
   

   说明：

   • 使用端口 465 + SSL 时，将 smtp_port=465、smtp_enable_starttls_auto=false、smtp_tls=true。
   • gitlab_email_from 与 gitlab_email_reply_to 建议设置为你的发信域名邮箱。

2. 使配置生效

   sudo gitlab-ctl reconfigure
   sudo gitlab-ctl restart
   

3. 发送测试邮件

   sudo gitlab-rails console
   Notify.test_email('recipient@example.com', 'GitLab 邮件测试', 'Hello, this is a test from GitLab').deliver_now
   

   若收件箱未收到，可在控制台查看异常堆栈，或执行 sudo gitlab-ctl tail 查看相关日志。

三 常见邮箱示例

• QQ 邮箱（端口 587/STARTTLS）
  要点：开启“SMTP 服务”，密码填写“授权码”；smtp_address=smtp.qq.com，smtp_port=587，smtp_enable_starttls_auto=true，smtp_tls=false。
  参考片段：

  gitlab_rails['smtp_enable'] = true
  gitlab_rails['smtp_address'] = "smtp.qq.com"
  gitlab_rails['smtp_port'] = 587
  gitlab_rails['smtp_user_name'] = "12345678@qq.com"
  gitlab_rails['smtp_password'] = "your_qq_smtp_auth_code"
  gitlab_rails['smtp_domain'] = "smtp.qq.com"
  gitlab_rails['smtp_authentication'] = "login"
  gitlab_rails['smtp_enable_starttls_auto'] = true
  gitlab_rails['smtp_tls'] = false
  gitlab_rails['gitlab_email_from'] = '12345678@qq.com'
  

  说明：部分环境在端口 465/SSL 下需将 smtp_tls 设为 true 才能建立连接，遇到 SSL 握手失败时尝试切换端口与 TLS 开关组合。

• 163 邮箱（端口 465/SSL）
  要点：开启“客户端授权密码”；smtp_address=smtp.163.com，smtp_port=465，smtp_enable_starttls_auto=false，smtp_tls=true。
  参考片段：

  gitlab_rails['smtp_enable'] = true
  gitlab_rails['smtp_address'] = "smtp.163.com"
  gitlab_rails['smtp_port'] = 465
  gitlab_rails['smtp_user_name'] = "your@163.com"
  gitlab_rails['smtp_password'] = "your_163_client_auth_code"
  gitlab_rails['smtp_domain'] = "smtp.163.com"
  gitlab_rails['smtp_authentication'] = "login"
  gitlab_rails['smtp_enable_starttls_auto'] = false
  gitlab_rails['smtp_tls'] = true
  gitlab_rails['gitlab_email_from'] = 'your@163.com'
  

四 故障排查

• 配置未生效：确认已执行 gitlab-ctl reconfigure 与 gitlab-ctl restart。
• 连接/握手失败：核对 端口（587 vs 465） 与 TLS/STARTTLS 的组合；必要时切换 smtp_tls 与 smtp_enable_starttls_auto 的 true/false。
• 认证失败：核对用户名与“授权码/应用专用密码”，而非网页登录密码。
• 证书校验问题：可临时设置 gitlab_rails['smtp_openssl_verify_mode'] = 'none'（仅测试环境），或配置 smtp_ca_file 指向可信 CA。
• 日志定位：执行 sudo gitlab-ctl tail 查看邮件发送相关日志，或在控制台观察异常。