Jenkins邮件配置无法发送，SMTP认证失败如何解决？

Question

在Jenkins中配置邮件通知时，常出现“SMTP认证失败”导致邮件无法发送。该问题多因SMTP服务器认证信息错误、未启用SSL/TLS加密、或邮箱账户未开启第三方应用访问权限所致。例如，使用QQ或Gmail邮箱时，需生成专用授权码代替密码进行认证。同时，Jenkins系统设置中SMTP端口与服务器地址配置不当（如应使用`smtp.qq.com:465`并启用SSL）也会引发认证失败。此外，防火墙或代理限制可能阻断连接。需逐一排查凭据准确性、加密协议匹配及网络连通性，确保Jenkins SMTP配置与邮箱服务商要求一致，方可解决认证失败问题。

Answer 1

一、Jenkins邮件通知配置中SMTP认证失败的常见原因分析

在持续集成/持续交付（CI/CD）流程中，Jenkins通过邮件通知机制向开发与运维团队推送构建状态至关重要。然而，在实际部署过程中，“SMTP认证失败”是高频出现的问题之一。

• 认证信息错误：用户名或密码填写不正确，尤其是未使用授权码代替账户登录密码。
• 加密协议不匹配：未启用SSL/TLS，或端口与协议组合错误（如465配SSL，587配STARTTLS）。
• 第三方应用权限未开启：QQ邮箱、Gmail等需手动开启“IMAP/SMTP服务”并生成专用授权码。
• SMTP服务器地址或端口配置错误：例如应使用smtp.qq.com:465而非默认的localhost:25。
• 网络限制：企业防火墙、代理服务器或安全组策略可能阻止出站SMTP连接。

邮箱服务商	SMTP服务器	端口	加密方式	是否需要授权码
QQ邮箱	smtp.qq.com	465	SSL	是
Gmail	smtp.gmail.com	465	SSL	是（App Password）
Outlook/Hotmail	smtp-mail.outlook.com	587	TLS	否（但需开启两步验证）
163邮箱	smtp.163.com	465	SSL	是
阿里云企业邮	smtp.qiye.aliyun.com	465	SSL	是
腾讯企业邮	smtp.exmail.qq.com	465	SSL	是
Yahoo Mail	smtp.mail.yahoo.com	465	SSL	是（App Password）
ProtonMail	smtp.protonmail.com	587	TLS	是（Bridge模式下）
Zoho Mail	smtp.zoho.com	465	SSL	是
FastMail	smtp.fastmail.com	465	SSL	是（App Key）

二、深入排查流程：从基础配置到高级调试

为系统性解决SMTP认证失败问题，建议按照以下层级逐步排查：

1. 确认邮箱账户已开启SMTP服务（如QQ邮箱需进入“设置-账户”开启POP3/SMTP）。
2. 获取正确的授权码（非登录密码），并在Jenkins凭据管理中安全存储。
3. 检查Jenkins全局配置中的SMTP主机名、端口、发件人地址是否准确。
4. 确保勾选“使用SSL”或“使用TLS”选项，并与服务商要求一致。
5. 测试通过telnet或openssl命令行工具验证SMTP服务器连通性。
6. 查看Jenkins日志（Manage Jenkins > System Log）定位具体异常堆栈。
7. 若存在代理环境，需在启动Jenkins时配置JVM参数以绕过或认证代理。
8. 使用Wireshark或tcpdump抓包分析TLS握手过程是否存在证书或协议不兼容。
9. 考虑使用Postfix或Sendmail作为本地邮件中继，避免直接外联SMTP服务器。
10. 对高安全环境，可部署专用SMTP网关并集成OAuth 2.0进行身份验证。

三、典型解决方案示例：以QQ邮箱为例

以下为在Jenkins中成功配置QQ邮箱SMTP的完整步骤：

步骤1：登录QQ邮箱 → 设置 → 账户 → 开启“POP3/SMTP服务”
步骤2：获取授权码（系统将生成16位字符串）
步骤3：Jenkins → Credentials → Add Credentials
        Kind: Username with password
        Scope: Global
        Username: [e-mail]
        Password: 你的授权码
        ID: smtp-qq-credential

步骤4：Jenkins → Manage Jenkins → Configure System
        E-mail Notification:
          SMTP server: smtp.qq.com
          SMTP port: 465
          Credentials: 选择刚创建的smtp-qq-credential
          Use SSL: ✅ 勾选
          From address: [e-mail]
          Reply-To address: [e-mail]
          Test e-mail recipient: [e-mail]
    

点击“Test configuration”发送测试邮件，观察控制台输出是否提示“Successfully sent mail to...”。

四、可视化诊断流程图：SMTP认证失败排查路径

以下Mermaid流程图展示了完整的故障排除逻辑路径：

graph TD
    A[开始] --> B{SMTP配置完成？}
    B -- 否 --> C[填写正确SMTP服务器和端口]
    B -- 是 --> D{凭据正确？}
    D -- 否 --> E[检查是否使用授权码而非密码]
    D -- 是 --> F{加密协议匹配？}
    F -- 否 --> G[调整SSL/TLS设置与端口对应]
    F -- 是 --> H{网络可达？}
    H -- 否 --> I[检查防火墙、代理、DNS解析]
    H -- 是 --> J{测试邮件发送？}
    J -- 失败 --> K[查看Jenkins系统日志]
    J -- 成功 --> L[配置完成]
    K --> M[分析javax.mail.AuthenticationFailedException等异常]
    M --> N{是否提示密码错误？}
    N -- 是 --> O[重新生成授权码并更新凭据]
    N -- 否 --> P[检查JavaMail属性自定义配置]
    P --> Q[考虑使用邮件中继或企业邮件网关]