通过 Swagger 提升 Linux API 安全性的实践指南
一 安全基线
- 强制启用 HTTPS/TLS，使用 Let’s Encrypt 或企业 CA 签发证书，禁用明文 HTTP；将证书与私钥权限设为仅服务账户可读（如 600）。
- 在 生产环境 禁用或严格限制 Swagger UI 访问；通过环境变量（如 SWAGGER_ENABLED=false）控制开关，仅在测试/预发环境开启。
- 对文档与接口实施 访问控制：启用 OAuth 2.0 / OpenID Connect 或 JWT，必要时叠加 API Key；为 Swagger UI 单独配置认证与授权策略。
- 对 Swagger UI 与 /v3/api-docs 等端点实施 IP 白名单（如仅内网网段可访问），减少暴露面。
- 在 Nginx/Apache 前置反向代理统一处理 TLS、压缩、缓存与鉴权，避免在应用内分散配置。
二 访问控制与鉴权配置
- 使用 Spring Security 为 Swagger 路径（如 /swagger-ui/、/v3/api-docs/）启用 HTTP Basic 或 OAuth 2.0 访问；示例（Spring Boot 3.x + SpringDoc OpenAPI 3.x）：
- 依赖：spring-boot-starter-security、springdoc-openapi-starter-webmvc-ui
- 安全规则：对 Swagger 路径要求认证，其他业务接口按 RBAC 控制
- 说明：SpringDoc 为当前官方推荐实现，旧版 SpringFox 已停止维护，存在如 CVE-2020-8908 等风险，建议迁移
- 为 UI 与 API Key 提供独立方案：
- UI 访问：Basic 认证或基于会话/OIDC 的登录
- API 调用：在 OpenAPI/Swagger 配置中定义 securitySchemes（如 apiKey 放在 Header: X-API-Key），并在需要保护的端点上应用
- 对不需要复杂用户体系的内部 API，可使用 API Key 方案，但务必放在 Header 而非 Query，并在服务端严格校验来源与权限
- 旧项目若仍使用 SpringFox 2.x 的 “swagger.basic” 方式，需知其为历史方案，存在维护与安全风险，应尽快迁移至 SpringDoc 并与 Spring Security 深度集成
三 网络与运行环境加固
- 在 Linux 层面用 iptables/ufw 限制访问：仅放行业务与文档所需端口（如 443），对 Swagger UI 与 /v3/api-docs 再叠加 IP 白名单 规则
- 将文档与后端置于 VPC/内网，对外仅暴露网关或反向代理；必要时通过 反向代理 过滤路径、添加鉴权头与速率限制
- 启用 WAF（Web 应用防火墙）识别与阻断常见攻击（SQLi、XSS、扫描器等），为文档与 API 增加一层运行时防护
- 全程使用 HTTPS，禁用弱加密套件与协议；证书到期自动续期（如 certbot）
四 输入校验与最小暴露
- 对所有输入执行 严格校验（类型、长度、范围、格式），使用 参数化查询/ORM 防止 SQL 注入，输出编码防止 XSS
- 在文档中避免泄露 敏感信息（如数据库凭据、内部密钥、错误堆栈）；必要时对 /v3/api-docs 响应做字段过滤或在网关层剥离敏感内容
- 仅公开必要的接口与模型字段；对 Beta/内部 接口使用独立分组与鉴权，避免被 UI 直接消费
五 运维监控与持续改进
- 启用 访问日志 与 审计日志，集中到 ELK（Elasticsearch/Logstash/Kibana） 或 Prometheus + Grafana 进行可视化与告警；对异常访问（频繁 401/403、探测路径）设置阈值告警
- 持续 更新 操作系统、运行时、依赖与文档组件，修补已知漏洞；对 SpringDoc/Swagger 等组件关注 CVE 并及时升级
- 建立 安全审计 与 渗透测试 流程，定期核查文档配置、鉴权策略与网络规则的有效性；将检查结果纳入变更评审与发布准入