Spring Boot 项目开启 HTTPS 完整指南：从原理到实践

在当今网络环境中，数据传输的安全性至关重要。HTTPS 作为 HTTP 的安全增强版本，通过 SSL/TLS 协议对数据进行加密传输，有效防止信息被窃取或篡改。对于 Spring Boot 开发的 Web 应用而言，开启 HTTPS 是保障用户数据安全的基础操作。本文将从 HTTPS 的核心原理出发，手把手教你完成 Spring Boot 项目的 HTTPS 配置，同时解决配置过程中常见的问题。

一、HTTPS 核心原理快速理解

在配置 HTTPS 之前，我们需要先明确两个关键概念，这是后续操作的基础：

1. SSL/TLS 证书

SSL/TLS 证书是由权威证书机构（CA） 颁发的数字凭证，用于证明服务器的身份，并为数据传输提供加密密钥。证书包含三部分核心信息：

服务器的公钥（用于加密数据）；

证书机构的数字签名（证明证书的合法性）；

证书有效期、服务器域名等元数据。

根据获取方式，证书可分为两类：

自签名证书：开发者通过工具自行生成，仅用于本地测试（浏览器会提示 "不安全"，因为未经过 CA 认证）；

CA 签名证书：向阿里云、腾讯云等服务商申请（免费或付费），适用于生产环境（浏览器会显示 "安全" 标识）。

2. HTTPS 通信流程

HTTPS 并非完全替代 HTTP，而是在 HTTP 基础上增加了 SSL/TLS 握手环节，具体流程如下：

客户端（浏览器）向服务器发起 HTTPS 请求，携带支持的 SSL/TLS 版本和加密算法；

服务器返回自身的 SSL/TLS 证书（包含公钥）；

客户端验证证书合法性（是否由可信 CA 颁发、域名是否匹配、是否过期）；

验证通过后，客户端生成随机 "会话密钥"，并使用服务器公钥加密后发送给服务器；

服务器使用自身私钥解密，获取 "会话密钥"；

后续客户端与服务器的所有通信，均通过 "会话密钥" 进行对称加密（效率更高）。

二、前置准备：生成 SSL/TLS 证书

配置 HTTPS 的第一步，是获取 SSL/TLS 证书。我们分 "本地测试" 和 "生产环境" 两种场景讲解：

1. 本地测试：生成自签名证书

自签名证书可通过 JDK 自带的keytool工具生成（无需额外安装，确保java -version可正常执行）。

步骤 1：执行生成命令

打开终端（Windows cmd/PowerShell，Mac/Linux Terminal），输入以下命令：

keytool -genkeypair -alias springboothttps -keyalg RSA -keysize 2048 -storetype PKCS12 -keystore springboothttps.p12 -validity 3650

命令参数说明：

-alias：证书别名（自定义，后续配置会用到）；

-keyalg：加密算法（推荐 RSA，安全性高）；

-keysize：密钥长度（2048 位及以上，符合安全标准）；

-storetype：证书存储格式（PKCS12，跨平台通用，替代旧的 JKS 格式）；

-keystore：证书输出路径和文件名（生成后会在当前目录下，如springboothttps.p12）；

-validity：证书有效期（单位：天，3650 表示 10 年，足够测试使用）。

步骤 2：填写证书信息

执行命令后，会提示输入一系列信息，按提示填写即可（部分信息可自定义，无需严格对应）：

输入密钥库口令: 123456（自定义密码，后续配置会用到，建议记下来）

再次输入新口令: 123456（确认密码）

您的名字与姓氏是什么?

[Unknown]: localhost（本地测试填localhost，生产环境填实际域名）

您的组织单位名称是什么?

[Unknown]: test（自定义，如"研发部"）

您的组织名称是什么?

[Unknown]: testcompany（自定义，如"我的公司"）

您所在的城市或区域名称是什么?

[Unknown]: beijing（自定义）

您所在的省/市/自治区名称是什么?

[Unknown]: beijing（自定义）

该单位的双字母国家/地区代码是什么?

[Unknown]: CN（中国填CN）

CN=localhost, OU=test, O=testcompany, L=beijing, ST=beijing, C=CN是否正确?

[否]: y（确认信息正确，输入y）

步骤 3：确认证书生成

执行完成后，在终端当前目录下会生成springboothttps.p12文件，这就是我们需要的自签名证书。

2. 生产环境：获取 CA 签名证书

生产环境不能使用自签名证书（浏览器会提示不安全，影响用户信任），需向权威 CA 机构申请证书。以阿里云为例，申请流程如下：

登录阿里云控制台，进入 "SSL 证书" 服务；

选择 "免费证书"（适合个人或小型项目）或 "付费证书"（适合企业级项目），点击 "申请"；

填写域名信息（如www.example.com），并完成域名验证（DNS 验证或文件验证，按提示操作）；

验证通过后，CA 机构会颁发证书，下载时选择 "JKS/PKCS12" 格式（Spring Boot 支持）；

下载后会得到证书文件（如example.p12）和密码，妥善保存。

三、Spring Boot 项目配置 HTTPS

证书准备完成后，开始配置 Spring Boot 项目。本文以 Spring Boot 2.x/3.x 版本为例（两者配置方式一致）。

1. 放置证书文件

将生成或下载的证书文件（如springboothttps.p12）复制到项目的src/main/resources目录下（确保项目能读取到证书）。

2. 配置 application.yml/application.properties

Spring Boot 支持通过配置文件直接指定 HTTPS 相关参数，推荐使用application.yml（格式更清晰），若使用application.properties可参考对应格式。

方式 1：application.yml 配置

在src/main/resources/application.yml中添加以下配置：

server:

port: 443 # HTTPS默认端口是443（可选，也可填8443等，浏览器访问时需加端口）

ssl:

key-store: classpath:springboothttps.p12 # 证书路径（classpath表示resources目录下）

key-store-password: 123456 # 证书生成时的密码

key-store-type: PKCS12 # 证书存储格式（与生成时的-storetype一致）

key-alias: springboothttps # 证书别名（与生成时的-alias一致）

方式 2：application.properties 配置

若使用application.properties，配置如下：

# HTTPS端口

server.port=443

# 证书路径

server.ssl.key-store=classpath:springboothttps.p12

# 证书密码

server.ssl.key-store-password=123456

# 证书格式

server.ssl.key-store-type=PKCS12

# 证书别名

server.ssl.key-alias=springboothttps

3. （可选）配置 HTTP 自动跳转 HTTPS

默认情况下，配置 HTTPS 后，项目只能通过https://访问，http://访问会失败。为了提升用户体验，可配置 HTTP 请求自动跳转至 HTTPS（例如用户输入http://localhost，自动跳转到https://localhost）。

需在项目中添加一个配置类，注册 Servlet 过滤器：

java 复制代码

import org.springframework.boot.web.embedded.tomcat.TomcatServletWebServerFactory;
import org.springframework.boot.web.servlet.server.ServletWebServerFactory;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class HttpsConfig {

    @Bean
    public ServletWebServerFactory servletContainer() {
        TomcatServletWebServerFactory tomcat = new TomcatServletWebServerFactory() {
            @Override
            protected void postProcessContext(org.apache.catalina.Context context) {
                // 配置HTTP请求跳转HTTPS的规则：返回301永久重定向
                org.apache.tomcat.util.descriptor.web.SecurityConstraint constraint = new org.apache.tomcat.util.descriptor.web.SecurityConstraint();
                constraint.setUserConstraint("CONFIDENTIAL"); // 表示需要HTTPS
                org.apache.tomcat.util.descriptor.web.SecurityCollection collection = new org.apache.tomcat.util.descriptor.web.SecurityCollection();
                collection.addPattern("/*"); // 匹配所有请求路径
                constraint.addCollection(collection);
                context.addConstraint(constraint);
            }
        };
        // 添加HTTP连接器：监听80端口（HTTP默认端口），并跳转至443端口（HTTPS端口）
        tomcat.addAdditionalTomcatConnectors(redirectConnector());
        return tomcat;
    }

    private org.apache.catalina.connector.Connector redirectConnector() {
        org.apache.catalina.connector.Connector connector = new org.apache.catalina.connector.Connector(
                org.apache.coyote.http11.Http11NioProtocol.class.getName());
        connector.setScheme("http");
        connector.setPort(80); // HTTP监听端口
        connector.setSecure(false);
        connector.setRedirectPort(443); // 跳转到HTTPS的端口（与server.port一致）
        return connector;
    }
}

说明：

上述配置中，HTTP 监听 80 端口（默认端口，用户访问时无需加端口），HTTPS 监听 443 端口（默认端口）；

若 HTTPS 端口不是 443（如 8443），需将redirectPort改为对应的端口（如 8443）。

四、验证 HTTPS 配置效果

配置完成后，启动 Spring Boot 项目，通过以下方式验证是否生效：

1. 本地测试验证（自签名证书）

步骤 1：启动项目

运行 Spring Boot 的主启动类（带有@SpringBootApplication注解的类），确保项目无报错启动。

步骤 2：访问项目

打开浏览器，输入https://localhost（若 HTTPS 端口是 8443，需输入https://localhost:8443）。

步骤 3：处理浏览器提示

由于使用的是自签名证书，浏览器会提示 "您的连接不是私密连接"（Chrome）或 "此网站的安全证书有问题"（Edge），这是正常现象（本地测试无需担心）：

Chrome：点击 "高级" → "继续前往localhost（不安全）"；

Edge：点击 "详细信息" → "继续访问localhost（不安全）"。

步骤 4：确认 HTTPS 生效

访问成功后，浏览器地址栏会显示 "锁形" 图标（可能带有 "不安全" 提示，自签名证书特有），点击锁形图标可查看证书信息，确认是我们生成的证书，说明 HTTPS 配置成功。

2. 生产环境验证（CA 签名证书）

生产环境配置 CA 证书后，启动项目，访问https://你的域名（如https://www.example.com）：

浏览器地址栏会显示 "绿色锁形" 图标，无 "不安全" 提示；

点击锁形图标 → "证书"，可查看 CA 机构颁发的证书信息（如阿里云、Let's Encrypt 等）；

可通过在线工具（如SSL Labs）检测 HTTPS 配置的安全性，确保评分达到 A 及以上。

五、常见问题及解决方案

在配置 HTTPS 过程中，可能会遇到各种问题，以下是高频问题的解决方法：

1. 证书路径错误：FileNotFoundExceptions

报错信息 ：java.io.FileNotFoundException: class path resource [springboothttps.p12] cannot be opened because it does not exist

原因：证书文件未放在src/main/resources目录下，或文件名 / 路径拼写错误。

解决方案：

确认证书文件在src/main/resources目录下；

检查配置文件中key-store的路径是否正确（如classpath:springboothttps.p12，注意文件名大小写是否匹配）。

2. 证书密码错误：InvalidKeystorePasswordException

报错信息 ：java.io.IOException: Invalid keystore password

原因：配置文件中key-store-password与证书生成时的密码不一致。

解决方案：

重新生成证书（确保密码正确并记录）；

核对配置文件中的密码，确保与生成证书时的密码完全一致（区分大小写）。

3. 端口被占用：BindException

报错信息 ：java.net.BindException: Address already in use: bind

原因：配置的 HTTPS 端口（如 443、8443）或 HTTP 端口（如 80）已被其他程序占用。

解决方案：

更换端口（如将 HTTPS 端口改为 8443，HTTP 端口改为 8080）；

关闭占用端口的程序（Windows 用netstat -ano | findstr "443"查找进程，Mac/Linux 用lsof -i :443）。

4. 浏览器提示 "证书域名不匹配"

原因：证书中的域名（生成时填写的 "您的名字与姓氏"）与访问时的域名不一致（如证书填localhost，访问时用127.0.0.1）。

解决方案：

本地测试：访问时用localhost，而非127.0.0.1；

生产环境：申请证书时填写的域名必须与实际访问的域名一致（如www.example.com）。

六、总结

本文从 HTTPS 原理出发，详细讲解了 Spring Boot 项目开启 HTTPS 的完整流程：

理解 HTTPS 的核心是 SSL/TLS 证书和加密通信流程；

本地测试用keytool生成自签名证书，生产环境申请 CA 签名证书；

通过application.yml配置 HTTPS 参数，可选配置 HTTP 自动跳转；

启动项目后，通过浏览器或在线工具验证配置效果；

遇到问题时，根据报错信息定位原因（如路径、密码、端口问题）。

开启 HTTPS 是 Web 应用安全的基础，建议所有生产环境的 Spring Boot 项目都配置 HTTPS，保障用户数据安全，同时提升用户信任度。