Email:2225994292@qq.com
中文
CNY
{{item}}
{{item.title}}
{{items.productName}}
{{items.price}}/年
{{item.title}}
部警SSL证书可实现网站HTTPS加密保护及身份的可信认证，防止传输数据的泄露或算改，提高网站可信度和品牌形象，利于SEO排名，为企业带来更多访问量，这也是网络安全法及PCI合规性的必备要求
前往SSL证书证书类型
品牌选择
证书类型
Swagger UI作为主流的API文档生成工具，以 “实时同步代码与文档、支持在线调试API” 的优势，成为开发者协作与接口测试的核心工具。在实际生产环境中，API接口传输的往往包含用户信息、业务数据等敏感内容，HTTP协议的明文传输特性会导致数据泄露、篡改等安全风险。本文将从HTTPS与SSL证书的基础认知出发，分 “Spring Boot 集成Swagger UI”“Nginx 反向代理Swagger UI” 两大核心场景，详细拆解HTTPS配置流程，同时提供证书管理与常见问题解决方案，帮助开发者快速落地安全的API文档访问方案。
在配置Swagger UI的HTTPS访问前，需先明确HTTPS的工作原理与SSL证书的核心概念，避免因基础认知缺失导致配置失误。
HTTPS并非独立协议，而是 “HTTP协议 + SSL/TLS协议” 的组合，通过 “身份认证、数据加密、完整性校验” 三大机制，解决 HTTP的安全漏洞：
对于Swagger UI而言，HTTPS的核心价值在于：
SSL证书是HTTPS的 “数字身份证”，由权威 CA（证书颁发机构）签发，包含服务器公钥、机构信息、有效期等关键信息。开发者需根据 “使用场景（开发测试 / 生产环境）、部署架构（单域名 / 多域名）” 选择适配的证书类型，常见选型如下：
| 证书类型 | 签发机构 | 适用场景 | 优势 | 劣势 |
|---|---|---|---|---|
| 自签证书 | 开发者自行生成 | 本地开发、测试环境 | 免费、生成速度快 | 不被浏览器信任，访问时触发安全警告 |
| 免费CA证书 | Let's Encrypt | 个人项目、小型企业生产环境（单域名） | 免费、浏览器信任（需定期续期） | 仅支持单域名 / 泛域名（部分免费证书）、有效期短（通常 90 天） |
| 付费OV证书 | 赛门铁克、GeoTrust | 企业生产环境（单域名 / 多域名） | 浏览器信任、包含企业身份验证、有效期 1 年 | 成本较高（每年数百至数千元） |
| 付费EV证书 | 赛门铁克、DigiCert | 金融、电商等高安全需求场景 | 浏览器地址栏显示绿色锁 + 企业名称、最高安全等级 | 成本极高（每年数万元）、审核严格 |
选型建议：
不同 Web 服务器（如 Tomcat、Nginx、Apache）对SSL证书的格式要求不同，需将 CA 签发的证书转换为适配格式，常见格式与对应服务器如下：
格式转换核心工具：
Spring Boot 项目常通过springfox-swagger2（Swagger 2）或springdoc-openapi-starter-webmvc-ui（Swagger 3）集成Swagger UI，默认使用内置 Tomcat 作为 Web 服务器。该场景下的HTTPS配置需完成 “证书准备、Spring Boot 配置、Swagger UI访问验证” 三步，核心是让内置 Tomcat 启用 SSL 协议。
使用 Java 自带的keytool工具生成自签证书，适用于本地开发测试：
# 生成PKCS#12格式证书（别名swagger-https，密码123456，有效期365天）
keytool -genkeypair -alias swagger-HTTPS-keyalg RSA -keysize 2048 -storetype PKCS12 -keystore swagger-https.p12 -validity 365执行命令后，需依次输入：
生成的swagger-https.p12文件需放入 Spring Boot 项目的src/main/resources目录下。
若使用 Let's Encrypt、阿里云等 CA 签发的证书，需先获取证书文件（通常包含cert.pem（证书链）、key.pem（私钥）），再转换为 PKCS#12 格式：
# 将CA证书与私钥转换为PKCS#12格式
openssl pkcs12 -export -in cert.pem -inkey key.pem -out swagger-https.p12 -name swagger-https输入导出密码（如 123456），将生成的swagger-https.p12放入项目resources目录。
通过配置文件启用内置 Tomcat 的HTTPS协议，同时指定证书路径、密码与 SSL 协议版本，以application.yml为例：
server:
port: 443 #HTTPS默认端口（可选，也可使用8443等自定义端口）
ssl:
enabled: true # 启用HTTPS
key-store: classpath:swagger-https.p12 # 证书路径（resources目录下）
key-store-type: PKCS12 # 证书格式
key-store-password: 123456 # 证书密码（与生成时一致）
key-alias: swagger-HTTPS # 证书别名（与生成时一致）
protocol: TLSv1.2 # SSL协议版本（推荐TLSv1.2/TLSv1.3，禁用不安全的SSLv3/TLSv1.0）
ciphers: TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 # 启用安全加密套件（避免弱加密算法）
#Swagger UI配置（Swagger 3示例，Swagger 2配置类似）
springdoc:
API-docs:
path: /v3/api-docs #API文档JSON路径
swagger-ui:
path: /swagger-ui.html #Swagger UI访问路径（HTTPS访问时为https://域名/swagger-ui.html）
operationsSorter: method # 按HTTP方法排序接口
tagsSorter: alpha # 按字母排序标签关键配置说明：
启动 Spring Boot 项目后，通过浏览器访问https://localhost/swagger-ui.html（若使用自定义端口，需添加端口号）：
为避免用户误访问 HTTP地址，需配置 “HTTP请求自动跳转HTTPS”，通过添加 WebServerFactoryCustomizerBean 实现：
import org.springframework.boot.web.embedded.tomcat.TomcatServletWebServerFactory;
import org.springframework.boot.web.server.ConfigurableWebServerFactory;
import org.springframework.boot.web.server.WebServerFactoryCustomizer;
import org.springframework.stereotype.Component;
@Component
public classHTTPSRedirectConfig implements WebServerFactoryCustomizer<ConfigurableWebServerFactory> {
@Override
public void customize(ConfigurableWebServerFactory factory) {
if (factory instanceof TomcatServletWebServerFactory) {
TomcatServletWebServerFactory tomcatFactory = (TomcatServletWebServerFactory) factory;
// 配置HTTP端口（如8080），并将请求跳转至HTTPS端口（443）
tomcatFactory.addAdditionalTomcatConnectors(
new org.apache.catalina.connector.Connector(
org.apache.coyote.http11.Http11NioProtocol.class.getName()
) {{
setPort(8080); // HTTP端口
setRedirectPort(443); // 跳转目标HTTPS端口
}}
);
}
}
}配置后，访问http://localhost:8080/swagger-ui.html会自动跳转至https://localhost/swagger-ui.html，避免 HTTP访问漏洞。
默认情况下，Swagger UI可公开访问，生产环境需添加权限控制（如用户名密码认证），防止未授权用户查看API文档。以 Spring Security 为例，添加依赖并配置：
<!-- pom.xml添加Spring Security依赖 -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-security</artifactId>
</dependency>import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.core.userdetails.User;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.security.core.userdetails.UserDetailsService;
import org.springframework.security.provisioning.InMemoryUserDetailsManager;
import org.springframework.security.web.SecurityFilterChain;
@Configuration
@EnableWebSecurity
public class SwaggerSecurityConfig {
@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
http
.authorizeHttpRequests(auth -> auth
// 仅允许Swagger UI相关路径需要认证
.requestMatchers("/swagger-ui.html", "/v3/api-docs/**", "/swagger-ui/**").authenticated()
// 其他API路径按实际需求配置（如公开/认证）
.anyRequest().permitAll()
)
// 启用表单登录（自定义登录页面可选）
.formLogin(form -> form.permitAll())
// 启用注销
.logout(logout -> logout.permitAll());
// 禁用CSRF（若API调试需跨域，可临时禁用；生产环境建议启用并配置）
http.csrf(csrf -> csrf.disable());
return http.build();
}
// 配置内存用户（生产环境建议替换为数据库存储）
@Bean
public UserDetailsService userDetailsService() {
UserDetails user = User.withDefaultPasswordEncoder()
.username("swagger-admin")
.password("admin123")
.roles("ADMIN")
.build();
return new InMemoryUserDetailsManager(user);
}
}配置后，访问Swagger UI需先输入用户名（swagger-admin）与密码（admin123），进一步保障API文档安全。
当Swagger UI部署在独立服务器（如 Node.js、Tomcat）或多服务集群时，常通过 Nginx 作为反向代理，集中管理HTTPS证书与请求转发。该场景下的核心是 “Nginx 配置HTTPS+ 反向代理至Swagger UI服务”，证书配置与安全优化集中在 Nginx 层面，无需修改Swagger UI服务本身。
编辑 Nginx 主配置文件（如/etc/nginx/nginx.conf）或新增站点配置（如/etc/nginx/conf.d/swagger-https.conf），核心配置如下：
# 定义Swagger UI上游服务（即Swagger UI实际部署地址）
upstream swagger_server {
server 127.0.0.1:8080; # 示例：Swagger UI部署在本地8080端口（HTTP协议）
# 若为多服务集群，可添加多个server节点（如server 192.168.1.100:8080;）
keepalive 5; # 保持连接池，提升性能
}
server {
listen 80;
server_name swagger.example.com; # 你的域名（如API文档专属域名）
# HTTP请求强制跳转HTTPS
return 301HTTPS://$host$request_uri;
}
server {
listen 443 ssl;
server_name swagger.example.com; # 与HTTP服务的域名一致
# SSL证书配置
ssl_certificate /etc/nginx/conf/ssl/cert.pem; # 证书链路径（PEM格式）
ssl_certificate_key /etc/nginx/conf/ssl/key.pem; # 私钥路径（PEM格式）
# SSL协议与加密套件配置
ssl_protocols TLSv1.2 TLSv1.3; #</doubaocanvas>
禁用不安全的 SSLv3、TLSv1.0、TLSv1.1
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384; # 强加密套件列表（参考 Mozilla 推荐）
ssl_prefer_server_ciphers on; # 优先使用服务器端加密套件ssl_session_cache shared:SSL:10m; # 会话缓存（10MB，约可存储 10000 个会话）
ssl_session_timeout 1d; # 会话超时时间（1 天）
ssl_session_tickets on; # 启用会话票据（加速会话复用）add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload" always;add_header X-Content-Type-Options nosniff;
add_header X-Frame-Options DENY;
add_header X-XSS-Protection "1; mode=block";location / {
proxy_pass http://swagger_server; # 转发至上游服务（HTTP协议）
proxy_set_header Host \(host; # 传递客户端请求的Host头
proxy_set_header X-Real-IP \)remote_addr; # 传递客户端真实 IP
proxy_set_header X-Forwarded-For \(proxy_add_x_forwarded_for; # 传递代理链IP
proxy_set_header X-Forwarded-Proto \)scheme; # 传递协议（告知上游服务为HTTPS）
proxy_connect_timeout 5s; # 代理连接超时时间
proxy_read_timeout 10s; # 代理读取超时时间
}location ~* .(js|css|png|jpg|jpeg|gif|ico|svg)\({
proxy_pass http://swagger_server;
proxy_set_header Host\)host;
expires 7d; # 静态资源缓存 7 天，减少重复请求
add_header Cache-Control "public, max-age=604800";
}
}#### 关键配置说明：
- **SSL会话优化**：`ssl_session_cache`与`ssl_session_tickets`可大幅减少重复握手开销，使后续HTTPS连接延迟降低50%以上，尤其适合Swagger UI的频繁访问场景；
- **HSTS头**：`Strict-Transport-Security`头会强制浏览器在`max-age`（此处为2年）内仅用HTTPS访问该域名，避免“HTTP→HTTPS”跳转过程中的安全风险；
- **反向代理头传递**：`X-Forwarded-Proto: $scheme`告知上游Swagger UI服务“客户端实际使用HTTPS访问”，避免Swagger UI生成HTTP链接（如API调试地址）；
- **静态资源缓存**：Swagger UI的JS、CSS等静态资源更新频率低，设置7天缓存可减少Nginx与上游服务的交互，提升页面加载速度。
### 3. 步骤2：Nginx配置验证与访问测试
#### （1）配置语法验证
修改配置后，需先验证Nginx配置是否存在语法错误，避免重启后服务异常：
```bash
# 验证Nginx配置语法
nginx -t若输出 “nginx: configuration file /etc/nginx/nginx.conf test is successful”，说明配置无误；若存在错误（如路径错误、括号不匹配），需根据提示修改。
配置验证通过后，重启 Nginx 使配置生效：
# 重启Nginx（Linux系统，不同发行版命令可能不同）
# CentOS/RHEL
systemctl restart nginx
# Ubuntu/Debian
service nginx restart通过浏览器访问https://swagger.example.com（需确保域名已解析至 Nginx 服务器 IP）：
SSL证书存在有效期（自签证书通常 1 年，CA 证书免费版 90 天、付费版 1-2 年），若证书过期会导致浏览器提示 “安全证书无效”，无法访问Swagger UI。需建立规范的证书管理流程，确保证书持续有效且安全存储。
开发 / 测试环境的自签证书过期后，可通过keytool重新生成或延长有效期：
# 延长自签PKCS#12证书有效期（从当前时间延长365天）
keytool -storepass 123456 -keystore swagger-https.p12 -storetype PKCS12 -alias swagger-HTTPS-validity 365生成后替换项目resources目录或 Nginx conf/ssl目录下的旧证书，重启 Spring Boot/Nginx 服务。
Let's Encrypt 免费证书有效期 90 天，推荐使用Certbot工具自动续期：
# 安装Certbot（Ubuntu系统）
apt-get install certbot python3-certbot-nginx
# 自动续期并更新Nginx配置
certbot renew --nginx --force-renewalCertbot会自动检测即将过期的证书（默认到期前 30 天），续期后更新证书文件并重启 Nginx，可通过crontab设置定时任务确保自动执行：
# 添加定时任务（每天凌晨2点执行续期检查）
crontab -e
# 输入以下内容
0 2 * * * /usr/bin/certbot renew --quiet当 SSL 协议升级（如启用 TLSv1.3）或加密算法更新（如淘汰弱加密套件）时，需同步更新证书配置：
SSL证书的私钥（如key.pem、swagger-https.p12）是核心敏感信息，若泄露会导致攻击者伪造证书发起中间人攻击，需严格控制存储权限：
chmod 400 /path/to/project/src/main/resources/swagger-https.p12
chown tomcat:tomcat /path/to/project/src/main/resources/swagger-https.p12chmod 400 /etc/nginx/conf/ssl/key.pem
chown root:root /etc/nginx/conf/ssl/key.pem开发者在配置Swagger UI HTTPS时，常遇到 “浏览器安全警告、API调试失败、配置不生效” 等问题，以下为高频问题的原因分析与解决方案。
原因：
解决方案：
1. 自签证书场景（开发测试环境）：
2. CA 证书场景：
原因：
解决方案：
在application.yml中添加配置，强制Swagger UI使用HTTPS生成API地址：
springdoc:
swagger-ui:
url:HTTPS://${server.name}:${server.port}/v3/api-docs # 显式指定HTTPS的API文档地址确保location /配置中包含proxy_set_header X-Forwarded-Proto $scheme;，告知Swagger UI客户端实际使用HTTPS访问，示例：
location / {
proxy_pass http://swagger_server;
proxy_set_header X-Forwarded-Proto $scheme; # 关键配置，传递协议类型
# 其他代理头...
}原因：
解决方案：
原因：
解决方案：
# 查看证书modulus
openssl x509 -in cert.pem -noout -modulus | openssl md5
# 查看私钥modulus
openssl rsa -in key.pem -noout -modulus | openssl md5openssl rsa -in key.p8 -out key.pem在生产环境中，除基础配置外，还需结合 “安全加固、性能优化、监控告警”，确保Swagger UI的HTTPS服务稳定可靠。
location / {
allow 192.168.1.0/24; # 允许内网IP段访问
deny all; # 拒绝其他IP
proxy_pass http://swagger_server;
# 其他配置...
}# 定义限流规则（每秒10个请求， burst 5个）
limit_req_zone $binary_remote_addr zone=swagger_limit:10m rate=10r/s;
location / {
limit_req zone=swagger_limit burst=5 nodelay;
proxy_pass http://swagger_server;
}server {
listen 443 ssl http2; # 启用HTTP/2
# 其他配置...
}生产环境中，单一 Nginx 节点或Swagger UI服务易因硬件故障、网络中断导致服务不可用，需通过 “多节点集群 + 负载均衡” 实现高可用：
upstream swagger_server {
server 192.168.1.100:8080;
server 192.168.1.101:8080;
# 启用健康检查（需安装nginx-upstream-check-module）
check interval=3000 rise=2 fall=3 timeout=1000 type=http;
check_http_send "HEAD /swagger-ui.html HTTP/1.0\r\n\r\n";
check_http_expect_alive http_2xx http_3xx;
}无论是小型个人项目还是大型企业系统，随着网络安全风险加剧与合规要求趋严，为Swagger UI配置HTTPS已成为必选项。开发者需结合本文的场景化方案，根据自身技术栈与业务需求选择适配路径，同时建立长期的证书管理与监控机制，让Swagger UI在安全的前提下充分发挥API协作与调试价值。
Dogssl.cn拥有20年网络安全服务经验，提供构涵盖国际CA机构Sectigo、Digicert、GeoTrust、GlobalSign，以及国内CA机构CFCA、沃通、vTrus、上海CA等数十个SSL证书品牌。全程技术支持及免费部署服务，如您有SSL证书需求，欢迎联系!
京公网安备11010702002820号 
