1. 项目概述与核心痛点做后端开发的朋友对Knife4j或者它的前身Swagger-Bootstrap-UI肯定不陌生。它是个好东西能根据代码注解自动生成漂亮又实用的接口文档前后端联调、测试的时候简直是“生产力神器”。但这个东西用不好就是个“安全炸弹”。我经历过不止一次这样的场景一个SpringBoot项目开发阶段为了方便把Knife4j的文档地址配得清清楚楚比如http://prod-server:8080/doc.html。项目上线后大家忙着处理业务逻辑谁也没想起来去关掉它。结果呢某天安全扫描报告出来赫然写着“未授权接口文档信息泄露”。里面所有的API路径、参数结构、甚至部分接口的模拟数据都暴露在公网上。这相当于把自家大门的结构图纸和锁芯型号直接贴在了门口攻击者可以轻松地研究你的接口逻辑寻找潜在的漏洞进行攻击比如未经验证的参数注入、越权访问等等。所以今天要聊的就是怎么在享受Knife4j便利的同时彻底堵上这个安全漏洞。我们的目标很明确在开发、测试环境Knife4j文档正常可用一旦部署到生产环境必须让它“消失”或者至少只有授权人员才能访问。这不是简单地注释掉EnableKnife4j注解那么简单我们需要一套精准、可靠、可配置的解决方案。2. 方案选型与设计思路拆解面对生产环境隐藏接口文档的需求常见的做法有好几种但各有优劣。我们先来拆解一下为什么有些“偷懒”的办法行不通。2.1 常见“踩坑”方案分析第一种依赖Maven Profile或启动参数手动开关。在application-prod.yml里设置knife4j.enable: false或者启动时加--knife4j.enablefalse。这方法理论上可行但太依赖“人”的记性。上线流程一忙很可能就忘了加这个参数或者配置文件被意外覆盖风险依然存在。我们需要的是尽可能自动化的方案。第二种利用ConditionalOnProperty或Profile注解。在配置类上添加ConditionalOnProperty(name “knife4j.enable”, havingValue “true”)或者Profile(“!prod”)。这比第一种进步了能和环境绑定。但问题在于Knife4j的自动配置类通常已经由starter包引入了仅仅在自己写的配置类上加条件可能无法完全禁用所有Knife4j自动注入的Bean导致文档页面虽然打不开但相关的接口扫描和资源映射可能还在留下隐患。第三种通过Security等权限框架拦截/doc.html等路径。这是很多团队的第一反应用Spring Security配置URL权限只允许内网IP或特定角色访问。这个方法不错增加了访问控制层。但它有个问题它只是藏起了入口并没有让Knife4j的相关功能在生产环境“消失”。那些用于生成文档的API比如/v2/api-docs,/v3/api-docs可能依然在运行、占用资源理论上仍存在被探测到的可能。我们的目标是更彻底的“隐身”。2.2 本方案核心设计环境感知的Bean装配综合比较后我选择的方案核心思想是利用Spring Boot强大的条件化配置能力根据当前激活的Profile动态决定是否装配整个Knife4j的配置类。这样就能从根源上在生产环境阻止Knife4j任何Bean的创建包括文档页面、接口描述端点、静态资源等真正做到“物理隔离”。具体来说我们会创建一个独立的Knife4j配置类将所有的Bean声明如Docket放在里面。在这个配置类上使用ConditionalOnExpression或ConditionalOnProperty注解使其绑定到非生产环境如dev,test。确保生产环境的配置文件application-prod.yml中没有激活任何会启用该配置类的属性。这个方案的优势在于彻底性生产环境下相关Bean根本不会实例化没有残留。清晰性配置意图明确与业务环境强关联。可维护性开关集中在一处易于管理。3. 精准配置Knife4j的详细步骤下面我们一步步来实现这个方案。假设你已经有一个基础的SpringBoot 2.x或3.x项目并引入了Knife4j依赖。3.1 环境与依赖准备首先确认你的pom.xml中已经正确引入了Knife4j的Starter。对于SpringBoot 2.x项目通常使用dependency groupIdcom.github.xiaoymin/groupId artifactIdknife4j-spring-boot-starter/artifactId version3.0.3/version !-- 请使用最新稳定版 -- /dependency对于SpringBoot 3.x需要使用适配的版本例如dependency groupIdcom.github.xiaoymin/groupId artifactIdknife4j-openapi3-spring-boot-starter/artifactId version4.4.0/version !-- 请使用最新稳定版 -- /dependency注意SpringBoot 3.x 移除了对 Jakarta EE 9之前版本的支持因此必须使用专门适配的Knife4j starter否则会出现java.lang.ClassNotFoundException: javax.servlet.http.HttpServletRequest等兼容性错误。3.2 核心配置类实现接下来我们创建核心的配置类。这里以SpringBoot 2.x Knife4j 3.x为例SpringBoot 3.x的配置类在包名和注解上略有不同但核心逻辑一致。package com.yourproject.config; import org.springframework.beans.factory.annotation.Value; import org.springframework.boot.autoconfigure.condition.ConditionalOnExpression; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.context.annotation.Profile; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.service.ApiInfo; import springfox.documentation.service.Contact; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc; /** * Knife4j 接口文档配置 * 使用 ConditionalOnExpression 控制仅在非生产环境加载 */ Configuration EnableSwagger2WebMvc // SpringBoot 2.x 使用此注解 // 关键点1使用条件注解当配置文件中 knife4j.enable 为 true 时加载 // ConditionalOnProperty(name knife4j.enable, havingValue true) // 关键点2更推荐使用表达式匹配多个非生产环境profile ConditionalOnExpression(${spring.profiles.active:dev} ! prod) // 关键点3也可以使用Profile注解但不如Expression灵活无法处理默认情况 // Profile({dev, test}) public class Knife4jConfig { Value(${spring.profiles.active:dev}) private String activeProfile; Bean public Docket createRestApi() { // 打印当前环境用于调试 System.out.println(Knife4j Config loaded for profile: activeProfile); return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() // 指定Controller扫描包路径 .apis(RequestHandlerSelectors.basePackage(com.yourproject.controller)) .paths(PathSelectors.any()) .build() // 生产环境可以关闭 try-host 功能避免暴露内网地址虽然Bean不会创建 .host(activeProfile.equals(prod) ? : null); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title(项目API文档 - activeProfile.toUpperCase() 环境) .description(这是一个在 activeProfile 环境下的接口文档生产环境不可见。) .contact(new Contact(YourName, https://your-domain.com, contactemail.com)) .version(1.0.0) .build(); } }代码解读与关键点ConditionalOnExpression(“‘${spring.profiles.active:dev}’ ! ‘prod’”)这是本方案的精髓。它通过SpEL表达式读取应用当前激活的Profilespring.profiles.active。如果激活的Profile是prod生产环境则整个配置类不会被加载其中的Bean方法自然也不会执行。${…:dev}表示如果active属性不存在则默认值为dev确保开发时默认开启。EnableSwagger2WebMvc这是启用Swagger 2Knife4j基于此的必要注解。在SpringBoot 3.x中对应的可能是EnableSwagger2或由starter自动配置具体看版本。Docket Bean这是定义API文档分组和扫描规则的核心。我们通过RequestHandlerSelectors.basePackage()限定了只扫描特定包下的Controller避免扫描到不必要的依赖库。PathSelectors.any()表示扫描所有路径。动态API信息在apiInfo()中我们通过注入的activeProfile变量动态设置文档标题和描述清晰标明当前文档所属环境避免混淆。Host设置在非生产环境host(null)让Knife4j使用当前请求的host。在生产环境虽然Bean不会创建但这里是个好习惯可以设置为空或具体的域名防止文档内出现内网IP。3.3 多环境配置文件适配接下来我们需要配置不同环境的配置文件以配合上面的条件注解。application-dev.yml(开发环境)spring: profiles: active: dev # 可以显式启用但配置类条件已涵盖 knife4j: enable: true setting: language: zh_cnapplication-test.yml(测试环境)spring: profiles: active: test # 同上application-prod.yml(生产环境)spring: profiles: active: prod # 关键生产环境不设置任何 knife4j.enabletrue 的属性 # 甚至可以显式关闭虽然配置类条件已阻止加载但双重保险 # knife4j: # enable: false server: # 生产环境服务器配置 port: 8080 servlet: context-path: /api3.4 验证与访问完成配置后我们通过启动命令来验证启动开发环境java -jar your-app.jar --spring.profiles.activedev访问http://localhost:8080/doc.html应该能看到完整的Knife4j文档界面。访问http://localhost:8080/v2/api-docs应该能看到原始的OpenAPI JSON数据。启动生产环境java -jar your-app.jar --spring.profiles.activeprod访问http://localhost:8080/doc.html应返回404错误。访问http://localhost:8080/v2/api-docs同样应返回404错误。检查应用启动日志不应该看到“Knife4j Config loaded for profile: prod”这行调试信息如果配置类被加载了说明条件注解未生效需要检查。实操心得在IDEA中可以通过“Edit Configurations”直接为启动项指定Active profiles为prod来模拟生产环境启动方便测试。另外强烈建议在Knife4jConfig类中临时去掉ConditionalOnExpression注解以prod环境启动确认文档页和API端点确实能访问即漏洞存在然后再加上注解验证其“消失”这样你对整个机制的理解会更深刻。4. 进阶结合Spring Security实现访问控制可选增强虽然通过条件化配置已经实现了生产环境的“物理隐藏”但有些团队可能希望在测试环境或预发布环境也对文档访问加以限制只允许公司内网或特定测试人员访问。这时可以结合Spring Security进行第二层防护。4.1 添加Security依赖dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-security/artifactId /dependency4.2 配置Security规则创建一个Security配置类针对Knife4j的路径进行访问控制。package com.yourproject.config; import org.springframework.boot.autoconfigure.condition.ConditionalOnWebApplication; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.core.env.Environment; import org.springframework.security.config.annotation.web.builders.HttpSecurity; import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity; import org.springframework.security.web.SecurityFilterChain; import org.springframework.security.config.annotation.web.configurers.AbstractHttpConfigurer; import static org.springframework.security.config.Customizer.withDefaults; Configuration EnableWebSecurity ConditionalOnWebApplication public class SecurityConfig { private final Environment env; public SecurityConfig(Environment env) { this.env env; } Bean public SecurityFilterChain filterChain(HttpSecurity http) throws Exception { // 获取当前激活的Profile String[] activeProfiles env.getActiveProfiles(); boolean isProd false; for (String profile : activeProfiles) { if (prod.equalsIgnoreCase(profile)) { isProd true; break; } } http .authorizeHttpRequests(auth - auth // 1. 生产环境禁止访问所有Knife4j相关路径 .requestMatchers(isProd, /doc.html, /webjars/**, /swagger-resources/**, /v2/api-docs, /v3/api-docs, /v3/api-docs/**).denyAll() // 2. 非生产环境可以限制访问来源例如只允许内网IP段。这里示例为允许所有认证用户访问。 // .requestMatchers(/doc.html, /v2/api-docs).hasRole(DEVELOPER) // 需要DEVELOPER角色 // .requestMatchers(/doc.html, /v2/api-docs).hasIpAddress(192.168.1.0/24) // 只允许内网IP // 3. 其他所有请求根据业务需要配置例如permitAll或需要认证 .anyRequest().permitAll() // 示例其他API暂时全部放行实际项目请按需配置 ) // 禁用CSRF通常对API服务是安全的但请根据实际情况决定 .csrf(AbstractHttpConfigurer::disable) // 如果需要表单登录可以启用。这里仅为示例API项目常用无状态认证如JWT。 .formLogin(withDefaults()); return http.build(); } }配置解读环境判断通过注入Environment对象在运行时判断当前是否为prod环境。denyAll()在生产环境下对所有Knife4j的访问路径/doc.html,/v2/api-docs等直接拒绝所有请求返回403。这是最严格的策略。精细控制在非生产环境dev,test注释部分展示了如何做精细控制。例如可以通过.hasRole(“DEVELOPER”)要求用户具备特定角色或通过.hasIpAddress(“192.168.1.0/24”)限制只能从公司内网访问。这需要你集成具体的用户认证体系如数据库、LDAP、JWT等。业务API安全.anyRequest().permitAll()仅为示例。真实项目中你的业务API必须配置恰当的安全策略例如需要携带有效的JWT Token才能访问。注意事项Spring Security的配置非常灵活且复杂。上述配置提供了一个基础框架。请务必根据你项目的实际安全需求进行调整特别是业务接口的权限控制切勿直接照搬.anyRequest().permitAll()到生产环境。5. 生产环境部署检查清单与问题排查配置完成后在上线前请务必执行以下检查清单确保万无一失。5.1 部署前检查清单Profile确认确保部署脚本、容器编排文件如Dockerfile、K8s Deployment YAML中正确设置了SPRING_PROFILES_ACTIVEprod环境变量。配置覆盖检查检查生产环境配置文件application-prod.yml或外部化配置中心确保没有包含knife4j.enable: true或任何可能覆盖条件注解的配置。依赖排除可选但推荐在pom.xml中可以考虑为生产环境构建单独的Profile将knife4j依赖的scope设置为provided或直接排除从依赖层面彻底移除。profiles profile idprod/id dependencies dependency groupIdcom.github.xiaoymin/groupId artifactIdknife4j-spring-boot-starter/artifactId scopeprovided/scope !-- 打包时排除 -- /dependency /dependencies /profile /profiles安全扫描使用SAST静态应用安全测试或DAST动态应用安全测试工具对生产环境包进行扫描确认/doc.html、/v2/api-docs等端点返回404或403。手动验证在部署后尝试从外网访问生产服务的/doc.html和/v2/api-docs路径确认无法访问。5.2 常见问题排查实录即使配置看起来正确有时也会遇到问题。下面是我踩过的一些坑和解决办法问题1生产环境配置类依然被加载文档还能访问。排查首先查看应用启动日志搜索你的配置类名看是否有初始化日志。然后在Knife4jConfig类中增加一个PostConstruct方法打印日志确认Bean是否被创建。可能原因1spring.profiles.active未正确设置为prod。检查启动命令、环境变量、application.yml中的默认配置。可能原因2存在其他配置类或自动配置类引入了Knife4j的Bean。尝试在application-prod.yml中增加spring.autoconfigure.exclude: com.github.xiaoymin.knife4j.spring.configuration.Knife4jAutoConfiguration具体类名需根据版本确定尝试排除自动配置。可能原因3条件注解表达式写错。检查ConditionalOnExpression中的SpEL语法确保字符串比较正确。可以用‘${spring.profiles.active}’.contains(‘prod’)来匹配包含prod的Profile名如prod-east。问题2文档页面404但/v2/api-docs接口却能访问返回了JSON。排查这说明Knife4j的核心BeanDocket可能被条件注解成功禁用了但Swagger或Knife4j的一些基础Bean如资源处理器可能被其他自动配置或你的其他配置加载了。解决这通常是因为项目中可能存在多个Swagger/Knife4j配置或者引入了其他依赖如某些Spring Cloud组件触发了相关自动配置。你需要找到并统一配置入口。最彻底的方法是在Knife4jConfig中不仅配置Docket也尝试通过Import或统一配置来管理所有相关组件。或者采用上述的spring.autoconfigure.exclude方式排除特定的自动配置类。问题3Spring Security配置后所有接口包括业务API都被要求认证了。排查这是Spring Security配置的常见问题。HttpSecurity的配置是链式的规则顺序很重要。anyRequest()必须放在最后且它代表“除了上面明确配置过的所有请求”。解决仔细检查你的SecurityFilterChain配置确保业务API的放行规则如.requestMatchers(“/api/**”).permitAll()写在anyRequest()规则之前。并且用于公开访问的静态资源路径如果有也需要提前配置。问题4SpringBoot 3.x下出现兼容性错误。排查确认依赖是否正确。SpringBoot 3.x必须使用knife4j-openapi3-spring-boot-starter并且版本要兼容。解决访问Knife4j的官方GitHub仓库查看其README或Issues获取针对SpringBoot 3.x的最新配置示例。通常包名和注解会从springfox变为io.swagger.core.v3相关。6. 总结与最佳实践建议通过“条件化Bean装配”为主“Security路径拦截”为辅的策略我们为Knife4j接口文档构建了一套可靠的生产环境隐身方案。这套方案的核心在于利用了Spring Boot“约定大于配置”但“配置可覆盖约定”的哲学通过精确的条件控制让功能只在需要的环境中生效。回顾整个实践有几个关键点值得再次强调环境隔离是根本不要依赖人的自觉性去开关配置。将环境Profile作为功能启用的决策依据是符合DevOps理念的可靠做法。条件注解要精准ConditionalOnExpression提供了强大的灵活性但表达式要写得严谨充分考虑默认值、多环境如prod,prod-us等情况。安全需要纵深防御即使Knife4j的Bean没有创建配置Spring Security对相关路径进行denyAll()也是一个良好的安全习惯构成了另一道防线。依赖管理可优化对于追求极致部署包纯净度和安全性的团队可以考虑通过Maven/Profile或Docker多阶段构建在生产环境打包时彻底移除Knife4j的依赖jar包。持续验证将“生产环境接口文档不可访问”作为上线前的一个必检项目纳入自动化部署流水线或检查清单中。最后接口文档是开发阶段的利器但绝不能成为生产环境的软肋。通过今天分享的这套配置方法你可以安心地在开发测试阶段享受Knife4j带来的高效同时确保线上系统的安全无虞。技术方案的选型往往就是在便利和安全之间寻找最佳平衡点而清晰、自动化的配置正是维持这种平衡的关键。
SpringBoot生产环境安全配置：基于条件注解精准控制Knife4j接口文档
1. 项目概述与核心痛点做后端开发的朋友对Knife4j或者它的前身Swagger-Bootstrap-UI肯定不陌生。它是个好东西能根据代码注解自动生成漂亮又实用的接口文档前后端联调、测试的时候简直是“生产力神器”。但这个东西用不好就是个“安全炸弹”。我经历过不止一次这样的场景一个SpringBoot项目开发阶段为了方便把Knife4j的文档地址配得清清楚楚比如http://prod-server:8080/doc.html。项目上线后大家忙着处理业务逻辑谁也没想起来去关掉它。结果呢某天安全扫描报告出来赫然写着“未授权接口文档信息泄露”。里面所有的API路径、参数结构、甚至部分接口的模拟数据都暴露在公网上。这相当于把自家大门的结构图纸和锁芯型号直接贴在了门口攻击者可以轻松地研究你的接口逻辑寻找潜在的漏洞进行攻击比如未经验证的参数注入、越权访问等等。所以今天要聊的就是怎么在享受Knife4j便利的同时彻底堵上这个安全漏洞。我们的目标很明确在开发、测试环境Knife4j文档正常可用一旦部署到生产环境必须让它“消失”或者至少只有授权人员才能访问。这不是简单地注释掉EnableKnife4j注解那么简单我们需要一套精准、可靠、可配置的解决方案。2. 方案选型与设计思路拆解面对生产环境隐藏接口文档的需求常见的做法有好几种但各有优劣。我们先来拆解一下为什么有些“偷懒”的办法行不通。2.1 常见“踩坑”方案分析第一种依赖Maven Profile或启动参数手动开关。在application-prod.yml里设置knife4j.enable: false或者启动时加--knife4j.enablefalse。这方法理论上可行但太依赖“人”的记性。上线流程一忙很可能就忘了加这个参数或者配置文件被意外覆盖风险依然存在。我们需要的是尽可能自动化的方案。第二种利用ConditionalOnProperty或Profile注解。在配置类上添加ConditionalOnProperty(name “knife4j.enable”, havingValue “true”)或者Profile(“!prod”)。这比第一种进步了能和环境绑定。但问题在于Knife4j的自动配置类通常已经由starter包引入了仅仅在自己写的配置类上加条件可能无法完全禁用所有Knife4j自动注入的Bean导致文档页面虽然打不开但相关的接口扫描和资源映射可能还在留下隐患。第三种通过Security等权限框架拦截/doc.html等路径。这是很多团队的第一反应用Spring Security配置URL权限只允许内网IP或特定角色访问。这个方法不错增加了访问控制层。但它有个问题它只是藏起了入口并没有让Knife4j的相关功能在生产环境“消失”。那些用于生成文档的API比如/v2/api-docs,/v3/api-docs可能依然在运行、占用资源理论上仍存在被探测到的可能。我们的目标是更彻底的“隐身”。2.2 本方案核心设计环境感知的Bean装配综合比较后我选择的方案核心思想是利用Spring Boot强大的条件化配置能力根据当前激活的Profile动态决定是否装配整个Knife4j的配置类。这样就能从根源上在生产环境阻止Knife4j任何Bean的创建包括文档页面、接口描述端点、静态资源等真正做到“物理隔离”。具体来说我们会创建一个独立的Knife4j配置类将所有的Bean声明如Docket放在里面。在这个配置类上使用ConditionalOnExpression或ConditionalOnProperty注解使其绑定到非生产环境如dev,test。确保生产环境的配置文件application-prod.yml中没有激活任何会启用该配置类的属性。这个方案的优势在于彻底性生产环境下相关Bean根本不会实例化没有残留。清晰性配置意图明确与业务环境强关联。可维护性开关集中在一处易于管理。3. 精准配置Knife4j的详细步骤下面我们一步步来实现这个方案。假设你已经有一个基础的SpringBoot 2.x或3.x项目并引入了Knife4j依赖。3.1 环境与依赖准备首先确认你的pom.xml中已经正确引入了Knife4j的Starter。对于SpringBoot 2.x项目通常使用dependency groupIdcom.github.xiaoymin/groupId artifactIdknife4j-spring-boot-starter/artifactId version3.0.3/version !-- 请使用最新稳定版 -- /dependency对于SpringBoot 3.x需要使用适配的版本例如dependency groupIdcom.github.xiaoymin/groupId artifactIdknife4j-openapi3-spring-boot-starter/artifactId version4.4.0/version !-- 请使用最新稳定版 -- /dependency注意SpringBoot 3.x 移除了对 Jakarta EE 9之前版本的支持因此必须使用专门适配的Knife4j starter否则会出现java.lang.ClassNotFoundException: javax.servlet.http.HttpServletRequest等兼容性错误。3.2 核心配置类实现接下来我们创建核心的配置类。这里以SpringBoot 2.x Knife4j 3.x为例SpringBoot 3.x的配置类在包名和注解上略有不同但核心逻辑一致。package com.yourproject.config; import org.springframework.beans.factory.annotation.Value; import org.springframework.boot.autoconfigure.condition.ConditionalOnExpression; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.context.annotation.Profile; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.service.ApiInfo; import springfox.documentation.service.Contact; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc; /** * Knife4j 接口文档配置 * 使用 ConditionalOnExpression 控制仅在非生产环境加载 */ Configuration EnableSwagger2WebMvc // SpringBoot 2.x 使用此注解 // 关键点1使用条件注解当配置文件中 knife4j.enable 为 true 时加载 // ConditionalOnProperty(name knife4j.enable, havingValue true) // 关键点2更推荐使用表达式匹配多个非生产环境profile ConditionalOnExpression(${spring.profiles.active:dev} ! prod) // 关键点3也可以使用Profile注解但不如Expression灵活无法处理默认情况 // Profile({dev, test}) public class Knife4jConfig { Value(${spring.profiles.active:dev}) private String activeProfile; Bean public Docket createRestApi() { // 打印当前环境用于调试 System.out.println(Knife4j Config loaded for profile: activeProfile); return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() // 指定Controller扫描包路径 .apis(RequestHandlerSelectors.basePackage(com.yourproject.controller)) .paths(PathSelectors.any()) .build() // 生产环境可以关闭 try-host 功能避免暴露内网地址虽然Bean不会创建 .host(activeProfile.equals(prod) ? : null); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title(项目API文档 - activeProfile.toUpperCase() 环境) .description(这是一个在 activeProfile 环境下的接口文档生产环境不可见。) .contact(new Contact(YourName, https://your-domain.com, contactemail.com)) .version(1.0.0) .build(); } }代码解读与关键点ConditionalOnExpression(“‘${spring.profiles.active:dev}’ ! ‘prod’”)这是本方案的精髓。它通过SpEL表达式读取应用当前激活的Profilespring.profiles.active。如果激活的Profile是prod生产环境则整个配置类不会被加载其中的Bean方法自然也不会执行。${…:dev}表示如果active属性不存在则默认值为dev确保开发时默认开启。EnableSwagger2WebMvc这是启用Swagger 2Knife4j基于此的必要注解。在SpringBoot 3.x中对应的可能是EnableSwagger2或由starter自动配置具体看版本。Docket Bean这是定义API文档分组和扫描规则的核心。我们通过RequestHandlerSelectors.basePackage()限定了只扫描特定包下的Controller避免扫描到不必要的依赖库。PathSelectors.any()表示扫描所有路径。动态API信息在apiInfo()中我们通过注入的activeProfile变量动态设置文档标题和描述清晰标明当前文档所属环境避免混淆。Host设置在非生产环境host(null)让Knife4j使用当前请求的host。在生产环境虽然Bean不会创建但这里是个好习惯可以设置为空或具体的域名防止文档内出现内网IP。3.3 多环境配置文件适配接下来我们需要配置不同环境的配置文件以配合上面的条件注解。application-dev.yml(开发环境)spring: profiles: active: dev # 可以显式启用但配置类条件已涵盖 knife4j: enable: true setting: language: zh_cnapplication-test.yml(测试环境)spring: profiles: active: test # 同上application-prod.yml(生产环境)spring: profiles: active: prod # 关键生产环境不设置任何 knife4j.enabletrue 的属性 # 甚至可以显式关闭虽然配置类条件已阻止加载但双重保险 # knife4j: # enable: false server: # 生产环境服务器配置 port: 8080 servlet: context-path: /api3.4 验证与访问完成配置后我们通过启动命令来验证启动开发环境java -jar your-app.jar --spring.profiles.activedev访问http://localhost:8080/doc.html应该能看到完整的Knife4j文档界面。访问http://localhost:8080/v2/api-docs应该能看到原始的OpenAPI JSON数据。启动生产环境java -jar your-app.jar --spring.profiles.activeprod访问http://localhost:8080/doc.html应返回404错误。访问http://localhost:8080/v2/api-docs同样应返回404错误。检查应用启动日志不应该看到“Knife4j Config loaded for profile: prod”这行调试信息如果配置类被加载了说明条件注解未生效需要检查。实操心得在IDEA中可以通过“Edit Configurations”直接为启动项指定Active profiles为prod来模拟生产环境启动方便测试。另外强烈建议在Knife4jConfig类中临时去掉ConditionalOnExpression注解以prod环境启动确认文档页和API端点确实能访问即漏洞存在然后再加上注解验证其“消失”这样你对整个机制的理解会更深刻。4. 进阶结合Spring Security实现访问控制可选增强虽然通过条件化配置已经实现了生产环境的“物理隐藏”但有些团队可能希望在测试环境或预发布环境也对文档访问加以限制只允许公司内网或特定测试人员访问。这时可以结合Spring Security进行第二层防护。4.1 添加Security依赖dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-security/artifactId /dependency4.2 配置Security规则创建一个Security配置类针对Knife4j的路径进行访问控制。package com.yourproject.config; import org.springframework.boot.autoconfigure.condition.ConditionalOnWebApplication; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.core.env.Environment; import org.springframework.security.config.annotation.web.builders.HttpSecurity; import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity; import org.springframework.security.web.SecurityFilterChain; import org.springframework.security.config.annotation.web.configurers.AbstractHttpConfigurer; import static org.springframework.security.config.Customizer.withDefaults; Configuration EnableWebSecurity ConditionalOnWebApplication public class SecurityConfig { private final Environment env; public SecurityConfig(Environment env) { this.env env; } Bean public SecurityFilterChain filterChain(HttpSecurity http) throws Exception { // 获取当前激活的Profile String[] activeProfiles env.getActiveProfiles(); boolean isProd false; for (String profile : activeProfiles) { if (prod.equalsIgnoreCase(profile)) { isProd true; break; } } http .authorizeHttpRequests(auth - auth // 1. 生产环境禁止访问所有Knife4j相关路径 .requestMatchers(isProd, /doc.html, /webjars/**, /swagger-resources/**, /v2/api-docs, /v3/api-docs, /v3/api-docs/**).denyAll() // 2. 非生产环境可以限制访问来源例如只允许内网IP段。这里示例为允许所有认证用户访问。 // .requestMatchers(/doc.html, /v2/api-docs).hasRole(DEVELOPER) // 需要DEVELOPER角色 // .requestMatchers(/doc.html, /v2/api-docs).hasIpAddress(192.168.1.0/24) // 只允许内网IP // 3. 其他所有请求根据业务需要配置例如permitAll或需要认证 .anyRequest().permitAll() // 示例其他API暂时全部放行实际项目请按需配置 ) // 禁用CSRF通常对API服务是安全的但请根据实际情况决定 .csrf(AbstractHttpConfigurer::disable) // 如果需要表单登录可以启用。这里仅为示例API项目常用无状态认证如JWT。 .formLogin(withDefaults()); return http.build(); } }配置解读环境判断通过注入Environment对象在运行时判断当前是否为prod环境。denyAll()在生产环境下对所有Knife4j的访问路径/doc.html,/v2/api-docs等直接拒绝所有请求返回403。这是最严格的策略。精细控制在非生产环境dev,test注释部分展示了如何做精细控制。例如可以通过.hasRole(“DEVELOPER”)要求用户具备特定角色或通过.hasIpAddress(“192.168.1.0/24”)限制只能从公司内网访问。这需要你集成具体的用户认证体系如数据库、LDAP、JWT等。业务API安全.anyRequest().permitAll()仅为示例。真实项目中你的业务API必须配置恰当的安全策略例如需要携带有效的JWT Token才能访问。注意事项Spring Security的配置非常灵活且复杂。上述配置提供了一个基础框架。请务必根据你项目的实际安全需求进行调整特别是业务接口的权限控制切勿直接照搬.anyRequest().permitAll()到生产环境。5. 生产环境部署检查清单与问题排查配置完成后在上线前请务必执行以下检查清单确保万无一失。5.1 部署前检查清单Profile确认确保部署脚本、容器编排文件如Dockerfile、K8s Deployment YAML中正确设置了SPRING_PROFILES_ACTIVEprod环境变量。配置覆盖检查检查生产环境配置文件application-prod.yml或外部化配置中心确保没有包含knife4j.enable: true或任何可能覆盖条件注解的配置。依赖排除可选但推荐在pom.xml中可以考虑为生产环境构建单独的Profile将knife4j依赖的scope设置为provided或直接排除从依赖层面彻底移除。profiles profile idprod/id dependencies dependency groupIdcom.github.xiaoymin/groupId artifactIdknife4j-spring-boot-starter/artifactId scopeprovided/scope !-- 打包时排除 -- /dependency /dependencies /profile /profiles安全扫描使用SAST静态应用安全测试或DAST动态应用安全测试工具对生产环境包进行扫描确认/doc.html、/v2/api-docs等端点返回404或403。手动验证在部署后尝试从外网访问生产服务的/doc.html和/v2/api-docs路径确认无法访问。5.2 常见问题排查实录即使配置看起来正确有时也会遇到问题。下面是我踩过的一些坑和解决办法问题1生产环境配置类依然被加载文档还能访问。排查首先查看应用启动日志搜索你的配置类名看是否有初始化日志。然后在Knife4jConfig类中增加一个PostConstruct方法打印日志确认Bean是否被创建。可能原因1spring.profiles.active未正确设置为prod。检查启动命令、环境变量、application.yml中的默认配置。可能原因2存在其他配置类或自动配置类引入了Knife4j的Bean。尝试在application-prod.yml中增加spring.autoconfigure.exclude: com.github.xiaoymin.knife4j.spring.configuration.Knife4jAutoConfiguration具体类名需根据版本确定尝试排除自动配置。可能原因3条件注解表达式写错。检查ConditionalOnExpression中的SpEL语法确保字符串比较正确。可以用‘${spring.profiles.active}’.contains(‘prod’)来匹配包含prod的Profile名如prod-east。问题2文档页面404但/v2/api-docs接口却能访问返回了JSON。排查这说明Knife4j的核心BeanDocket可能被条件注解成功禁用了但Swagger或Knife4j的一些基础Bean如资源处理器可能被其他自动配置或你的其他配置加载了。解决这通常是因为项目中可能存在多个Swagger/Knife4j配置或者引入了其他依赖如某些Spring Cloud组件触发了相关自动配置。你需要找到并统一配置入口。最彻底的方法是在Knife4jConfig中不仅配置Docket也尝试通过Import或统一配置来管理所有相关组件。或者采用上述的spring.autoconfigure.exclude方式排除特定的自动配置类。问题3Spring Security配置后所有接口包括业务API都被要求认证了。排查这是Spring Security配置的常见问题。HttpSecurity的配置是链式的规则顺序很重要。anyRequest()必须放在最后且它代表“除了上面明确配置过的所有请求”。解决仔细检查你的SecurityFilterChain配置确保业务API的放行规则如.requestMatchers(“/api/**”).permitAll()写在anyRequest()规则之前。并且用于公开访问的静态资源路径如果有也需要提前配置。问题4SpringBoot 3.x下出现兼容性错误。排查确认依赖是否正确。SpringBoot 3.x必须使用knife4j-openapi3-spring-boot-starter并且版本要兼容。解决访问Knife4j的官方GitHub仓库查看其README或Issues获取针对SpringBoot 3.x的最新配置示例。通常包名和注解会从springfox变为io.swagger.core.v3相关。6. 总结与最佳实践建议通过“条件化Bean装配”为主“Security路径拦截”为辅的策略我们为Knife4j接口文档构建了一套可靠的生产环境隐身方案。这套方案的核心在于利用了Spring Boot“约定大于配置”但“配置可覆盖约定”的哲学通过精确的条件控制让功能只在需要的环境中生效。回顾整个实践有几个关键点值得再次强调环境隔离是根本不要依赖人的自觉性去开关配置。将环境Profile作为功能启用的决策依据是符合DevOps理念的可靠做法。条件注解要精准ConditionalOnExpression提供了强大的灵活性但表达式要写得严谨充分考虑默认值、多环境如prod,prod-us等情况。安全需要纵深防御即使Knife4j的Bean没有创建配置Spring Security对相关路径进行denyAll()也是一个良好的安全习惯构成了另一道防线。依赖管理可优化对于追求极致部署包纯净度和安全性的团队可以考虑通过Maven/Profile或Docker多阶段构建在生产环境打包时彻底移除Knife4j的依赖jar包。持续验证将“生产环境接口文档不可访问”作为上线前的一个必检项目纳入自动化部署流水线或检查清单中。最后接口文档是开发阶段的利器但绝不能成为生产环境的软肋。通过今天分享的这套配置方法你可以安心地在开发测试阶段享受Knife4j带来的高效同时确保线上系统的安全无虞。技术方案的选型往往就是在便利和安全之间寻找最佳平衡点而清晰、自动化的配置正是维持这种平衡的关键。
