Spring Boot项目里，用knife4j 3.0.2时生产环境屏蔽不彻底？手把手教你排查和修复/v3/api-docs泄露问题

Spring Boot项目中knife4j 3.0.2生产环境屏蔽不彻底问题深度排查与修复指南

现象复现与问题定位

最近在Spring Boot项目中使用knife4j 3.0.2版本时，发现一个令人困扰的安全隐患：尽管按照官方文档配置了knife4j.production=true，但安全扫描时仍然可以访问/v3/api-docs接口，导致API文档信息泄露。这个问题在生产环境中尤为严重，可能成为系统安全的薄弱环节。

让我们先复现这个问题的具体表现：

1. 环境配置：

   <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-spring-boot-starter</artifactId> <version>3.0.2</version> </dependency>

   # application.properties knife4j.enable=true knife4j.production=true

2. 访问测试结果：

   访问路径	预期结果	实际结果
   /doc.html	屏蔽	已屏蔽
   /v2/api-docs	屏蔽	已屏蔽
   /v3/api-docs	屏蔽	未屏蔽

注意：这个问题在OpenAPI 3.0规范的项目中尤为突出，因为/v3/api-docs是OpenAPI 3.0的标准端点

官方文档核对与初步分析

首先，我们查阅knife4j 3.0.2的官方文档中关于生产环境屏蔽的部分。文档明确指出，设置knife4j.production=true会屏蔽以下资源：

• /doc.html
• /v2/api-docs
• /v2/api-docs-ext
• /swagger-resources
• /swagger-ui.html
• /swagger-resources/configuration/ui
• /swagger-resources/configuration/security

然而，文档中确实没有提及/v3/api-docs端点的屏蔽。这解释了为什么我们的配置无法完全屏蔽所有API文档接口。

源码级深度排查

为了彻底理解问题根源，我们需要深入knife4j的源码进行分析。关键点在于ProductionSecurityFilter类的实现：

1. 自动配置入口：

   @Bean @ConditionalOnMissingBean({ProductionSecurityFilter.class}) @ConditionalOnProperty(name = {"knife4j.production"}, havingValue = "true") public ProductionSecurityFilter productionSecurityFilter(Knife4jProperties knife4jProperties) { // 初始化逻辑... return new ProductionSecurityFilter(knife4jProperties.isProduction()); }

2. 继承关系分析：

   • ProductionSecurityFilter继承自BasicFilter
   • BasicFilter中定义了需要屏蔽的URL模式列表

3. 关键问题定位： 在BasicFilter类的构造函数中，我们可以看到被屏蔽的URL模式：

   public BasicFilter() { this.urlFilters = new ArrayList(); this.urlFilters.add(Pattern.compile(".*?/doc\\.html.*", 2)); this.urlFilters.add(Pattern.compile(".*?/v2/api-docs.*", 2)); // 其他v2相关路径... // 注意：缺少/v3/api-docs的模式匹配 }

这就是问题的核心所在：knife4j 3.0.2版本的BasicFilter实现中没有包含对/v3/api-docs路径的屏蔽规则。

解决方案对比与实施

针对这个问题，我们有以下三种解决方案，各有优缺点：

方案一：自定义ProductionSecurityFilter

实施步骤：

1. 创建自定义过滤器类：

   public class CustomProductionSecurityFilter extends ProductionSecurityFilter { public CustomProductionSecurityFilter(boolean production) { super(production); // 添加/v3/api-docs的屏蔽规则 super.urlFilters.add(Pattern.compile(".*?/v3/api-docs.*", 2)); } }

2. 覆盖自动配置：

   @Bean @ConditionalOnProperty(name = "knife4j.production", havingValue = "true") public ProductionSecurityFilter productionSecurityFilter(Knife4jProperties knife4jProperties) { return new CustomProductionSecurityFilter(knife4jProperties.isProduction()); }

优缺点分析：

方案二：升级knife4j到3.0.3版本

实施步骤：

1. 修改pom.xml：

   <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-spring-boot-starter</artifactId> <version>3.0.3</version> </dependency>

2. 验证新版本行为：

   • 检查BasicFilter类，确认已包含/v3/api-docs的屏蔽规则
   • 测试所有API文档端点是否被正确屏蔽

版本变化对比：

方案三：完全禁用springfox自动配置

实施步骤：

1. 修改application.properties：

   springfox.documentation.enabled=false knife4j.enable=false

2. 影响评估：

   • 将完全禁用Swagger和knife4j的所有功能
   • 适用于不需要API文档功能的项目

适用场景：

• 项目已经稳定，不再需要API文档
• 安全性要求极高，宁愿牺牲开发便利性

方案选择建议

根据不同的项目阶段和需求，我们建议：

1. 新项目或可以升级的项目：

   • 直接采用方案二，升级到knife4j 3.0.3或更高版本
   • 这是最干净、最维护友好的解决方案

2. 无法立即升级的现有项目：

   • 采用方案一，自定义过滤器
   • 作为临时解决方案，同时规划升级路径

3. 完全不需要API文档的项目：

   • 考虑方案三，彻底禁用相关功能
   • 确保没有其他功能依赖这些组件

生产环境部署验证

无论采用哪种方案，部署到生产环境前都需要进行充分验证：

1. 测试用例：

   # 测试应被屏蔽的端点 curl -I http://localhost:8080/v3/api-docs curl -I http://localhost:8080/doc.html curl -I http://localhost:8080/v2/api-docs # 预期结果都应返回403或404

2. 安全扫描建议：

   • 使用OWASP ZAP等工具进行自动化扫描
   • 重点关注以下路径的可访问性：
     • /v2/api-docs
     • /v3/api-docs
     • /doc.html
     • /swagger-ui.html

3. 监控配置：

   // 示例：添加日志监控可疑访问 @Component public class ApiDocsAccessMonitor extends HandlerInterceptorAdapter { private static final Logger logger = LoggerFactory.getLogger(ApiDocsAccessMonitor.class); @Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) { String path = request.getRequestURI(); if (path.contains("api-docs") || path.contains("swagger") || path.contains("doc.html")) { logger.warn("Suspicious access attempt to API docs: {}", path); // 可以在这里添加额外的安全措施，如IP黑名单等 } return true; } }

深度防御策略

除了解决这个具体问题外，我们还应该考虑实施更全面的API文档安全策略：

1. 环境感知配置：

   # 根据spring.profiles.active自动设置 knife4j.production=${spring.profiles.active=='prod'}

2. IP白名单限制：

   @Configuration public class ApiDocsSecurityConfig extends WebSecurityConfigurerAdapter { @Override protected void configure(HttpSecurity http) throws Exception { http .antMatcher("/v3/api-docs") .antMatcher("/v2/api-docs") .antMatcher("/doc.html") .authorizeRequests() .anyRequest().hasIpAddress("192.168.1.100") // 只允许特定IP访问 .and() .csrf().disable(); } }

3. 定期安全审计：

   • 建立自动化脚本定期检查API文档端点的可访问性
   • 将检查纳入CI/CD流水线

4. 文档访问日志分析：

   -- 示例：监控异常访问模式 SELECT COUNT(*) as attempt_count, ip_address FROM access_logs WHERE path LIKE '%api-docs%' OR path LIKE '%swagger%' GROUP BY ip_address HAVING COUNT(*) > 3 ORDER BY attempt_count DESC;

经验分享与最佳实践

在实际项目中处理这个问题时，我们发现几个值得注意的点：

1. 版本兼容性：

   • 升级到knife4j 3.0.3时，需要确保Spring Boot版本兼容
   • 某些Spring Boot 2.2.x版本可能需要额外配置

2. 测试覆盖：

   @SpringBootTest public class ApiDocsSecurityTest { @Autowired private WebApplicationContext context; private MockMvc mockMvc; @BeforeEach public void setup() { mockMvc = MockMvcBuilders.webAppContextSetup(context).build(); } @Test public void shouldBlockV3ApiDocs() throws Exception { mockMvc.perform(get("/v3/api-docs")) .andExpect(status().isForbidden()); } }

3. 渐进式部署策略：

   • 先在预发布环境验证方案效果
   • 使用特性开关控制不同方案的切换
   • 准备好回滚方案

4. 团队意识培养：

   • 确保所有开发人员了解API文档的安全风险
   • 在代码审查中加入相关检查项
   • 建立文档安全配置的标准模板