CentOS上优化Swagger的可落地方案
一 基础环境与网络优化
- 启用并优化 HTTPS/TLS 1.3：使用 Let’s Encrypt 证书（Certbot 配置 Nginx/Apache），减少握手开销并提升安全性。
- 开启 HTTP/2 或 HTTP/3（Nginx 启用 http2），多路复用降低文档与静态资源加载延迟。
- 配置 Gzip/Brotli 压缩 与强缓存：对 Swagger UI 的 CSS/JS/HTML 设置长期 Cache-Control（如 max-age=31536000, immutable），对经常变动的 /v2/api-docs 设置较短缓存（如 max-age=60）。
- 系统网络栈优化（/etc/sysctl.conf）：
- net.core.somaxconn=4096；net.ipv4.tcp_max_syn_backlog=4096；net.ipv4.tcp_tw_reuse=1；net.ipv4.tcp_fin_timeout=30
- 开启 BBR：net.core.default_qdisc=fq；net.ipv4.tcp_congestion_control=bbr
- 打开防火墙端口（示例）：firewall-cmd --permanent --add-port=80/tcp；firewall-cmd --permanent --add-port=443/tcp；firewall-cmd --reload。
- 若使用容器化 Swagger UI，映射 80/443 到宿主机，避免直曝 3000/8080 管理端口。
二 反向代理与静态资源加速
- 使用 Nginx 作为反向代理与静态资源服务器，示例关键配置：
- 压缩与类型：gzip on; gzip_types text/css application/javascript application/json;
- 强缓存与协商缓存：
- location ~* .(css|js|png|svg|html)$ { expires 1y; add_header Cache-Control “public, immutable”; }
- location = /v2/api-docs { expires 60s; add_header Cache-Control “public, must-revalidate”; }
- 连接与长连接：worker_processes auto; worker_connections 4096; keepalive_timeout 65;
- 代理与超时：proxy_pass http://127.0.0.1:8080; proxy_http_version 1.1; proxy_set_header Connection “”; proxy_read_timeout 60s;
- 多实例时前置 Nginx/HAProxy 做负载均衡（轮询/权重），避免单实例过载。
三 Java 应用与 Swagger 配置优化（Spring Boot + Springfox/OpenAPI）
- JVM 调优（生产常用）：
- 堆大小固定且充足：如 -Xms2g -Xmx2g（按内存与负载调整）；
- 回收器选择：大堆优先 G1（-XX:+UseG1GC），超低延迟可考虑 ZGC（-XX:+UseZGC）；
- 开启 JMX 监控：便于排查 GC/内存/线程 问题。
- 减少文档生成开销：
- 精简依赖，仅保留必要模块（如 springfox-swagger2 与 springfox-swagger-ui）；
- 通过配置减少默认响应消息、按需扫描包，降低启动时解析成本；
- 对 /v2/api-docs 结果做应用层缓存（如 Redis/Memcached），设置 TTL=60s，显著降低重复生成成本。
- 接口侧配合：为返回大数据量的接口增加 分页/过滤 参数，减少单次响应体积，缩短 UI 渲染与网络传输时间。
四 监控 日志 与安全加固
- 监控与告警：以 Prometheus + Grafana 采集 响应时间、错误率、并发数 等指标，设置阈值告警（如 RT > 2s 触发）。
- 日志策略：生产环境日志级别设为 INFO/WARN，减少 DEBUG 带来的 I/O 压力；结合 ELK 分析高频 4xx/5xx 并修复。
- 访问控制：对 /swagger-ui/ 与 /v2/api-docs 增加 Basic Auth/JWT 或基于 IP 的白名单；启用 HSTS 强制 HTTPS。
- 合规与可用性：将文档纳入 Git 版本控制，路径包含 /api/v1/ 等版本前缀；定期同步文档与实现，避免过期。
五 高可用与扩展
- 水平扩展：将 Swagger UI 与应用服务解耦，多实例部署（物理机/虚拟机或 Docker），前置 Nginx/HAProxy 做负载均衡与健康检查。
- 容器化与编排：使用 Docker Compose/Kubernetes 管理多实例与滚动升级，结合 Ingress 提供统一域名与证书管理。
- 文档存储与分发：在大规模或频繁变更场景下，将 OpenAPI 规范 存入 Git/对象存储 并由 Nginx 直接分发，减少后端渲染压力。
