Ubuntu 中 GitLab 邮件服务配置指南

一 准备与前提

• 系统环境建议：Ubuntu 20.04/22.04/24.04，已安装 curl、openssh-server、ca-certificates。
• 邮件方式二选一：
  1. 应用内 SMTP（推荐，灵活）；
  2. 系统级 Postfix 作为 SMTP 中继（适合统一发信与审计）。
• 安装 GitLab 社区版（CE）常用命令：
  sudo apt update
  sudo apt install -y curl openssh-server ca-certificates postfix
  curl -sS https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh | sudo bash
  sudo apt install -y gitlab-ce
  安装 Postfix 时选择“Internet Site”，并设置系统邮件域名。以上步骤为后续邮件配置的基础。

二 方案一 应用内 SMTP 配置（推荐）

• 编辑配置文件：sudo vim /etc/gitlab/gitlab.rb，按需填入你的 SMTP 参数（示例为 QQ 邮箱与通用 SMTP 587/STARTTLS 场景）：

  发件人标识

  gitlab_rails[‘gitlab_email_enabled’] = true
  gitlab_rails[‘gitlab_email_from’] = ‘yourname@qq.com’
  gitlab_rails[‘gitlab_email_display_name’] = ‘Your GitLab’

  SMTP 参数

  gitlab_rails[‘smtp_enable’] = true
  gitlab_rails[‘smtp_address’] = “smtp.qq.com”
  gitlab_rails[‘smtp_port’] = 587
  gitlab_rails[‘smtp_user_name’] = “yourname@qq.com”
  gitlab_rails[‘smtp_password’] = “your_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

  可选：与发件人保持一致

  user[“git_user_email”] = “yourname@qq.com”
  说明：
  • 端口 465/SSL 与 587/STARTTLS 二选一；使用 465 时将 smtp_tls 设为 true，将 smtp_enable_starttls_auto 设为 false；使用 587 时相反。
  • 多数邮箱（如 QQ）需要使用“授权码”而非登录密码。
• 使配置生效：
  sudo gitlab-ctl reconfigure
  sudo gitlab-ctl restart
• 测试：
  sudo gitlab-rails console
  Notify.test_email(‘recipient@example.com’, ‘Message Subject’, ‘This is a test email body.’).deliver_now
  若收到测试邮件，说明 SMTP 配置成功。

三 方案二 系统 Postfix 作为 SMTP 中继

• 配置 Postfix 中继（示例为公司/公共 SMTP）：
  sudo vim /etc/postfix/main.cf
  追加或修改：
  relayhost = [smtp.example.com]:587
  smtp_sasl_auth_enable = yes
  smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd
  smtp_sasl_security_options = noanonymous
  smtp_tls_CAfile = /etc/ssl/certs/ca-certificates.crt
  smtp_use_tls = yes
  创建密码文件并安全设置：
  echo “[smtp.example.com]:587 your_username:your_password” | sudo tee /etc/postfix/sasl_passwd
  sudo chmod 600 /etc/postfix/sasl_passwd
  sudo postmap /etc/postfix/sasl_passwd
  sudo systemctl reload postfix
• GitLab 侧最小化 SMTP（使用本地 MTA 投递）：
  gitlab_rails[‘smtp_enable’] = false
  或仅保留发件人信息：
  gitlab_rails[‘gitlab_email_from’] = ‘gitlab@yourdomain.com’
  user[“git_user_email”] = ‘gitlab@yourdomain.com’
• 使配置生效：
  sudo gitlab-ctl reconfigure
  sudo gitlab-ctl restart
• 测试：同上使用 Rails 控制台发送测试邮件。

四 常见问题与排查

• 端口与加密不匹配：
  • 465/SSL：smtp_tls=true，smtp_enable_starttls_auto=false
  • 587/STARTTLS：smtp_tls=false，smtp_enable_starttls_auto=true
• 认证失败：确认使用邮箱的“授权码/应用专用密码”，而非网页登录密码；核对用户名与发件人一致。
• 本机防火墙/云安全组：放行 25/465/587（如启用）与 80/443（访问 GitLab）。
• 配置未生效：每次修改 /etc/gitlab/gitlab.rb 后执行：sudo gitlab-ctl reconfigure；必要时 sudo gitlab-ctl restart。
• 查看日志定位：
  sudo tail -f /var/log/gitlab/gitlab-rails/production.log | grep -i email
  sudo tail -f /var/log/mail.log（使用 Postfix 时）。