一、问题背景

我开发了一个原生微信小程序，后端使用 Spring Boot，部署在微信云托管。

技术环境：

• 微信小程序原生开发
• Spring Boot 4.x
• Java 17
• Docker 镜像部署
• 微信云托管

登录链路如下：

本地环境中登录正常，但部署到云托管后，小程序调用登录接口返回 502。云端日志显示：

WeChat code2Session request failed with SSLHandshakeException

一开始我怀疑是 AppSecret、环境变量或微信接口配置错误；但继续排查后发现，请求还没有进入微信业务校验阶段，就在 HTTPS TLS 握手阶段失败了。

二、SSLHandshakeException 到底是什么？

HTTPS 请求并不是直接发送 HTTP 数据，而是先建立可信的 TLS 加密连接。

本质不是“微信接口不通”，而是：

Java 容器无法确认微信服务器证书链是否可信，因此拒绝建立 HTTPS 连接。

本地电脑与云端容器的证书环境不同，是这类问题常见的原因。精简运行镜像中，系统 CA、Java CA 信任库及二者同步关系可能不完整或不一致。

三、真实排查过程：从 TLS 握手失败到微信业务错误

这次排查过程很有代表性：

修复证书后，日志变成：

WeChat code2Session returned errcode=40163

这个错误并不表示证书修复失败。40163表示微信登录临时code已经使用过。

这反而说明 HTTPS 请求已经成功到达微信服务器，问题从“网络/TLS 层”进入了“微信业务层”。

处理方式是重新调用：

wx.login()

拿到新的临时 code 后再次登录。

四、Dockerfile 修复方案

我的后端运行时镜像使用 Java 17：

FROM eclipse-temurin:17-jre

修复后，在运行时镜像中加入：

FROM maven:3.9.9-eclipse-temurin-17 AS build WORKDIR /workspace COPY pom.xml ./ RUN mvn -B -q -DskipTests dependency:go-offline COPY src ./src RUN mvn -B -q -DskipTests package FROM eclipse-temurin:17-jre RUN apt-get update \ && apt-get install -y --no-install-recommends \ ca-certificates \ ca-certificates-java \ && update-ca-certificates \ && rm -rf /var/lib/apt/lists/* ENV JAVA_TOOL_OPTIONS="-Djavax.net.ssl.trustStore=/etc/ssl/certs/java/cacerts" WORKDIR /app COPY --from=build /workspace/target/*.jar /app/app.jar EXPOSE 8080 ENTRYPOINT ["java", "-jar", "/app/app.jar"]

完整含义如下：

镜像结构可以理解为：

五、为什么只安装 ca-certificates 还不够？

一开始我只考虑安装系统证书：

apt-get install -y ca-certificates

但 Java 发起 HTTPS 请求时，主要依赖 JVM 的信任库，而不是一定直接读取 Linux 系统的 PEM 证书文件。

因此更稳妥的链路是：

Linux 系统 CA 证书 ↓ ca-certificates-java 同步 ↓ Java cacerts 信任库 ↓ Java HttpClient 校验微信 HTTPS 证书

所以最终需要同时完成：

ca-certificates + ca-certificates-java + update-ca-certificates + 指定 JVM trustStore

六、针对确认属于偶发握手失败场景增加有限重试

证书环境修复后，我还给微信code2Session请求增加了轻量保护：

首次出现 TLS 握手异常 ↓ 等待 250ms ↓ 重试一次 ↓ 仍失败则返回“微信登录服务暂不可用”

这里的重点是：

• 只对 TLS 握手异常重试；
• 只重试一次；
• 不无限重试；
• 不记录 AppSecret、完整请求 URL 等敏感信息。

重试只是提升偶发网络抖动下的成功率，不能替代正确的证书配置。

七、修复前后对比

八、常见错误与正确处理方式

不要采用以下做法：

• 关闭 SSL 校验；
• 跳过 HTTPS 主机名校验；
• 将 AppSecret 写入 Dockerfile；
• 在日志中输出完整微信请求 URL；
• 看到40163后反复提交同一个 code。

九、如何验证修复成功？

不要只测试：

GET /api/hello

它只能证明 Spring Boot 已启动。

正确验证步骤：

1. 推送 Dockerfile 修改，等待云托管重新构建部署；
2. 在微信开发者工具重新编译小程序；
3. 清除本地登录态或点击“重新登录”；
4. 触发新的wx.login()；
5. 查看云端日志，确认不再出现SSLHandshakeException；
6. 确认后端成功返回登录结果，小程序进入正常页面。

最终链路如下：

十、总结

这次问题并不是微信接口不可用，而是云托管 Docker 容器中 Java HTTPS 信任链配置不完整或不一致。

最终解决方案：

系统 CA 证书 + Java CA 证书同步 + 更新证书库 + 显式指定 JVM trustStore + TLS 异常有限重试

这类问题不仅会出现在微信登录中。只要 Java Docker 容器需要访问 AI 服务、对象存储、支付接口或其他 HTTPS 第三方服务，都值得提前检查 CA 与 Java trustStore 配置。

十一、这次踩坑得到的经验

1. 本地正常 ≠ Docker环境正常

2. HTTP接口正常 ≠ HTTPS第三方调用正常

3. SSL错误不要第一时间关闭校验

4. 业务错误码出现，反而说明网络链路已经恢复