Quarkus配置Gmail邮件服务时遭遇SSL握手异常求助

问题原因 #

• 465端口SSL连接失败：Gmail SMTP 465端口要求SSL直连，但Quarkus邮件器默认SSL配置未适配，或JVM信任库缺少对应根证书，导致握手失败。
• 587端口PKIX错误：JVM默认信任库中无Gmail SMTP服务器的证书链，无法验证证书有效性，引发路径构建失败。
• openssl命令卡住：openssl s_client建立连接后会保持会话不自动退出，Windows环境下sed的文本处理逻辑也导致证书内容未被正确写入文件。

解决方案 #

1. 修正Quarkus邮件器配置（推荐使用587 TLS） #

使用TLS时无需手动指定ssl: true，Quarkus会自动启动STARTTLS握手，简化配置如下：

quarkus:
  mailer:
    auth-methods: PLAIN LOGIN
    from: mymail@gmail.com
    host: smtp.gmail.com
    port: 587
    username: "mydevmail@gmail.com"
    password: "generated application password"
    mock: false
    start-tls: REQUIRED  # 强制启用STARTTLS，确保TLS握手触发

注：auth-methods简化为PLAIN LOGIN即可，Gmail SMTP在TLS环境下主要支持这两种认证方式，多余配置可能引发协商冲突。

2. 解决JVM证书信任问题 #

方法一：将Gmail根证书导入JVM全局信任库

• 打开浏览器访问https://smtp.gmail.com，点击地址栏锁图标，查看证书详情，导出GTS Root R1根证书为Base64编码的CER文件。
• 找到JDK安装目录下的jre/lib/security/cacerts文件（默认密码为changeit），以管理员身份执行命令导入证书：

keytool -import -alias gmail-root -file "C:\path\to\GTSRootR1.cer" -keystore "C:\Program Files\Java\jdk-xxx\jre\lib\security\cacerts"

方法二：Quarkus指定自定义PEM信任文件

若不想修改全局JVM配置，可通过PowerShell正确导出证书链：

openssl s_client -starttls smtp -connect smtp.gmail.com:587 -showcerts < NUL | Select-String -Pattern "-BEGIN CERTIFICATE-","-END CERTIFICATE-" -Context 0,100 | Out-File google-smtp-ca.pem -Encoding ASCII

加入< NUL让openssl自动结束输入避免卡住，用PowerShell的Select-String替代sed提取证书内容。

然后在application.yml中配置：

quarkus:
  ssl:
    truststore:
      file: google-smtp-ca.pem
      type: PEM  # 必须指定类型为PEM，否则Quarkus会默认解析为JKS格式

3. 验证配置 #

编写简单测试接口验证邮件发送：

import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import io.quarkus.mailer.Mail;
import io.quarkus.mailer.Mailer;

@Path("/send-test-mail")
public class MailTestResource {

    @Inject
    Mailer mailer;

    @GET
    public String sendTestMail() {
        mailer.send(Mail.withText("your-test-email@example.com", "Quarkus Gmail Test", "邮件发送成功！"));
        return "测试邮件已发送";
    }
}

启动应用后访问http://localhost:8080/send-test-mail即可测试。

内容的提问来源于stack exchange，提问作者Tanveer