在 Debian 上配置 GitLab 邮件通知

一 准备与选择邮件发送方式

• 准备一个可用于发信的邮箱或 SMTP 服务，记录：SMTP 服务器地址、端口、用户名、密码、发信域名，并确定使用 STARTTLS（端口 587） 或 SSL/TLS（端口 465）。
• 方式一：使用外部 SMTP（推荐，便于审计与隔离）。
• 方式二：使用本机 Postfix 作为 MTA 转发（适合已有本地邮件体系）。下文分别给出配置要点。

二 方式一 配置外部 SMTP（推荐）

• 编辑配置文件：
  sudo nano /etc/gitlab/gitlab.rb
• 在文件中添加或修改以下关键项（按你的 SMTP 信息替换示例值）：
  gitlab_rails[‘gitlab_email_enabled’] = true
  gitlab_rails[‘gitlab_email_from’] = ‘gitlab@example.com’
  gitlab_rails[‘gitlab_email_display_name’] = ‘GitLab’
  gitlab_rails[‘smtp_enable’] = true
  gitlab_rails[‘smtp_address’] = “smtp.example.com”
  gitlab_rails[‘smtp_port’] = 587
  gitlab_rails[‘smtp_user_name’] = “your-smtp-user@example.com”
  gitlab_rails[‘smtp_password’] = “your-smtp-password”
  gitlab_rails[‘smtp_domain’] = “example.com”
  gitlab_rails[‘smtp_authentication’] = “login”
  gitlab_rails[‘smtp_enable_starttls_auto’] = true

  如使用 SSL/TLS（端口 465），将上一行改为 false，并开启：

  gitlab_rails[‘smtp_tls’] = true

• 使配置生效：
  sudo gitlab-ctl reconfigure
  sudo gitlab-ctl restart
• 说明：多数云邮箱/企业邮箱常用 587 + STARTTLS；若用 465 + SSL/TLS，请将 starttls_auto 关闭并启用 smtp_tls。完成后可用管理界面测试发信。

三 方式二 使用本机 Postfix 转发

• 安装并初始化 Postfix：
  sudo apt update
  sudo apt install postfix
  安装向导中选择 Internet Site，并设置系统邮件名称（如：yourdomain.com）。
• 按需调整 Postfix 主配置 /etc/postfix/main.cf（示例为 IPv4、允许本机与内网发信）：
  myhostname = yourdomain.com
  myorigin = /etc/mailname
  inet_interfaces = all
  inet_protocols = ipv4
  mydestination = $myhostname, localhost.$mydomain, localhost, $mydomain
  mynetworks = 127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128 192.168.0.0/16
  relayhost = [your.smtp.provider]:587 # 如通过外部 SMTP 转发
  smtp_sasl_auth_enable = yes
  smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd
  smtp_sasl_security_options = noanonymous
  smtp_tls_security_level = encrypt
  smtp_use_tls = yes
• 如使用账号密码，创建 /etc/postfix/sasl_passwd：
  [your.smtp.provider]:587 username:password
  生成哈希并保护：
  sudo postmap /etc/postfix/sasl_passwd
  sudo chmod 600 /etc/postfix/sasl_passwd /etc/postfix/sasl_passwd.db
  sudo systemctl restart postfix
• GitLab 侧可保持使用本地 MTA 的最小配置（不启用 SMTP）：
  gitlab_rails[‘gitlab_email_enabled’] = true
  gitlab_rails[‘gitlab_email_from’] = ‘gitlab@yourdomain.com’
  gitlab_rails[‘gitlab_email_display_name’] = ‘GitLab’
  然后执行：sudo gitlab-ctl reconfigure && sudo gitlab-ctl restart。

四 测试与常见问题

• 发送测试邮件：
  • 管理界面路径：Admin Area → Settings → General → Email/SMTP，点击 Test email configuration。
  • 或命令行：sudo gitlab-rails console，执行 Notify.test_email(‘you@example.com’, ‘Message Subject’, ‘This is a test.’).deliver_now。
• 常见问题排查：
  • 连接被拒或超时：核对 SMTP 地址/端口、服务器是否允许你的来源 IP 发信，云邮箱需开启 SMTP 权限/应用专用密码。
  • 认证失败：检查 用户名/密码 与 smtp_authentication（常见为 login）。
  • 证书/加密问题：如自签证书或内网中继，可将 gitlab_rails[‘smtp_openssl_verify_mode’] 设为 ‘none’（仅测试环境），生产环境建议使用有效证书。
  • 本机 Postfix 发信失败：查看 /var/log/mail.log，确认 relayhost、SASL 凭据与网络连通性。