ubuntu gitlab如何配置邮件

Ubuntu 上 GitLab 邮件配置指南

一 准备与总体思路

• 准备一个可用于发信的邮箱（如 QQ 邮箱、163 邮箱、Gmail 等），并开启 SMTP 服务，获取对应的 SMTP 地址、端口 与 授权码/密码。注意：多数邮箱的“密码”项需填写授权码而非登录密码。
• 选择发信方式：
  • 直接配置 GitLab 内置 SMTP（推荐，灵活可控）。
  • 使用本机 Postfix 作为中继（简单场景可用，但需额外邮件服务支持）。
• 修改 GitLab 配置后，务必执行 gitlab-ctl reconfigure 使配置生效。

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

• 编辑配置文件：sudo vim /etc/gitlab/gitlab.rb，按需添加或修改如下关键项（示例为 QQ 邮箱与 163 邮箱两种常见场景，二选一或按你的邮箱调整）：

# 启用 SMTP
gitlab_rails['smtp_enable'] = true
# 发件人邮箱（与 smtp_user_name 保持一致更稳妥）
gitlab_rails['gitlab_email_from'] = 'your_email@qq.com'
# 系统用户邮箱（可选，保持一致）
user['git_user_email'] = 'your_email@qq.com'

# 示例 A：QQ 邮箱（端口 465，SSL）
gitlab_rails['smtp_address'] = "smtp.qq.com"
gitlab_rails['smtp_port'] = 465
gitlab_rails['smtp_user_name'] = "your_email@qq.com"
gitlab_rails['smtp_password'] = "your_smtp_auth_code"   # 注意是授权码
gitlab_rails['smtp_domain'] = "qq.com"
gitlab_rails['smtp_authentication'] = "login"
gitlab_rails['smtp_enable_starttls_auto'] = false
gitlab_rails['smtp_tls'] = true

# 示例 B：163 邮箱（端口 465，SSL）
# gitlab_rails['smtp_address'] = "smtp.163.com"
# gitlab_rails['smtp_port'] = 465
# gitlab_rails['smtp_user_name'] = "your_email@163.com"
# gitlab_rails['smtp_password'] = "your_smtp_auth_code"   # 注意是授权码
# gitlab_rails['smtp_domain'] = "163.com"
# gitlab_rails['smtp_authentication'] = "login"
# gitlab_rails['smtp_enable_starttls_auto'] = false
# gitlab_rails['smtp_tls'] = true

• 使配置生效并重启相关服务：
  • sudo gitlab-ctl reconfigure
  • sudo gitlab-ctl restart
• 说明：
  • 使用 465/SSL 时通常将 smtp_tls = true、smtp_enable_starttls_auto = false；使用 587/STARTTLS 时相反。
  • 不同邮箱的 smtp_domain 与端口要求不同，请以邮箱服务商说明为准。

三 方案二 使用本机 Postfix 作为中继

• 安装 Postfix（安装 GitLab 时通常已一并安装；安装向导中选择 Internet Site）：sudo apt-get install -y postfix
• 如需用外部 SMTP 中继（可选），编辑 /etc/postfix/main.cf，示例：
  • relayhost = [smtp.xx.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/postfix/cacert.pem
  • smtp_use_tls = yes
  • 创建 /etc/postfix/sasl_passwd：
    • [smtp.xx.com]:587 your_username:your_password
  • 生成哈希并重启：sudo postmap /etc/postfix/sasl_passwd && sudo systemctl restart postfix
• 在 GitLab 中可仅保留基本发信身份（SMTP 可关闭），确保发件人一致：
  • gitlab_rails[‘gitlab_email_from’] = ‘gitlab@your.domain’
  • user[‘git_user_email’] = ‘gitlab@your.domain’

四 发送测试邮件与常见问题

• 发送测试邮件（进入 Rails 控制台）：
  • sudo gitlab-rails console
  • Notify.test_email(‘to@example.com’, ‘Subject’, ‘Body’).deliver_now
• 常见排错要点：
  • 认证失败：确认填写的是授权码而非登录密码；核对 smtp_address/smtp_port/smtp_domain。
  • 端口与加密不匹配：
    • 465/SSL：smtp_tls = true，smtp_enable_starttls_auto = false
    • 587/STARTTLS：smtp_tls = false，smtp_enable_starttls_auto = true
  • 配置未生效：每次修改 /etc/gitlab/gitlab.rb 后必须执行 gitlab-ctl reconfigure，必要时 gitlab-ctl restart。
  • 本机 Postfix 连通性：可测试本地 25/587 端口连通性（如 telnet），确保服务运行与防火墙放行。