SpringBoot3集成Druid：配置、监控与密码加密实战指南

1. 起因：为什么 SpringBoot3 里选 Druid，而不是 HikariCP

SpringBoot 2.x 之后默认的数据库连接池换成了 HikariCP，性能确实强，但很多老项目从 SpringBoot2 迁到 SpringBoot3 时，还是宁愿用 Druid。原因很简单：Druid 自带监控、SQL 防火墙、慢 SQL 统计、密码加密这些能力，HikariCP 基本都要自己另外写代码。尤其在国内的公司内部，很多团队早就把 Druid 监控页当成上线前的必检项，换成 HikariCP 意味着要重新做一套监控方案，成本太高。

我做 SpringBoot3 系列学习笔记这段时间，正好有个项目从 SpringBoot 2.7 升级到 SpringBoot 3.2，顺带把 Druid 从 1.x 升到最新版，踩了一堆坑。这一篇就把 Druid 在 SpringBoot3 里的配置、监控、密码加密、常见坑全部理清楚，给正在迁移或者准备用 SpringBoot3 + Druid 的朋友一个可以直接抄的作业。

先说结论：SpringBoot3 用 Druid，核心就三件事——引入依赖、配置数据源、开启监控页。但真正让人头疼的是版本兼容、过滤器注册、连接池参数调优，以及密码加密那套东西。这篇全展开讲。

2. 版本选择：这一步错了，后面全白搭

2.1 SpringBoot3 对 Druid 版本的硬性要求

SpringBoot3 底层用了 Jakarta EE 规范，包名从javax.*变成了jakarta.*。Druid 如果要适配 SpringBoot3，必须用 1.2.20 以上的版本，早期 1.2.18 以下的版本还是基于javax.servlet写的，直接引入会导致启动报ClassNotFoundException: javax.servlet.Filter。

我实测过几个版本：

所以建议直接上 1.2.2x 最新稳定版。我这次用的是 1.2.21，目前网上普遍反馈这个版本在 SpringBoot3.2 下很稳。如果你的项目是 SpringBoot3.0/3.1，也建议选这个版本。

2.2 引入依赖的正确姿势

Druid 有两个依赖，别搞混。一个是druid-spring-boot3-starter，专为 SpringBoot3 设计；另一个是老的druid-spring-boot-starter，那是给 SpringBoot2 用的。网上很多教程还停留在老版本，直接复制到 SpringBoot3 项目里就会出问题。

<dependency> <groupId>com.alibaba</groupId> <artifactId>druid-spring-boot3-starter</artifactId> <version>1.2.21</version> </dependency>

如果你是 Maven 中央仓库找不到这个 artifact，说明仓库没同步或者你本地仓库缓存太旧，清一下.m2目录再重新拉就行。Gradle 项目对应写法：

implementation 'com.alibaba:druid-spring-boot3-starter:1.2.21'

这里有一个很多人忽略的点：druid-spring-boot3-starter内置了druid核心包和自动配置类，不需要再单独引入druid包。再引入一次反而可能产生类冲突，比如DruidDataSourceAutoConfigure被加载两次。

3. Druid 核心配置详解：每个参数到底在调什么

3.1 基础连接池配置

先看一个标准的application.yml配置，我直接贴出我用在项目里的版本：

spring: datasource: druid: # 数据库连接配置 url: jdbc:mysql://localhost:3306/springboot3_demo?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai username: root password: yourpassword driver-class-name: com.mysql.cj.jdbc.Driver # 初始连接数 initial-size: 5 # 最小空闲连接数 min-idle: 5 # 最大活跃连接数 max-active: 20 # 获取连接最大等待时间，单位毫秒 max-wait: 60000 # 间隔多久才进行一次检测，检测需要关闭的空闲连接，单位毫秒 time-between-eviction-runs-millis: 60000 # 连接保持空闲而不被驱逐的最小时间，单位毫秒 min-evictable-idle-time-millis: 300000 # 验证连接是否有效的 SQL validation-query: SELECT 1 # 申请连接时执行 validation-query 检测 test-while-idle: true # 申请连接时检测，false 会提升性能 test-on-borrow: false # 归还连接时检测，false 会提升性能 test-on-return: false # 是否缓存 preparedStatement pool-prepared-statements: true # 每个连接上缓存的 preparedStatement 数量 max-pool-prepared-statement-per-connection-size: 20 # 配置监控统计拦截的 filters，去掉后无法使用监控页 filters: stat,wall,slf4j # 是否开启连接池的 keep-alive keep-alive: true # 物理连接初始化时创建连接数 phy-max-use-count: 1000

这些参数中，最容易踩坑的是max-wait。我见过不少新人在高并发场景下把max-wait设为 0，表示无限等待，结果数据库一抖动，所有线程全部卡死在拿连接上，接口直接超时。建议设置成 5000~6000ms，配合下面要讲的remove-abandoned才能真正兜底。

3.2 连接池参数背后的原理

initial-size不是越大越好。启动时就创建 5 个连接，对大多数项目够了。如果你把initial-size改成 50，项目启动时会瞬间建立 50 个 MySQL 连接，数据库端的连接数、内存、线程全部被打满，尤其是多实例部署的场景，每个实例启动都来一下，数据库很容易卡死。

time-between-eviction-runs-millis和min-evictable-idle-time-millis这两个参数要注意配合。前者是检测线程多久跑一次，后者是连接闲置多久才被驱逐。我一般设置前者 60 秒、后者 300 秒。如果你的业务对空闲连接很敏感，比如连接被防火墙切断了，可以把min-evictable-idle-time-millis调小一些，但别小于 60 秒，否则检测线程频繁驱逐连接，反而导致新连接反复创建。

keep-alive这个参数很有用。开启之后，Druid 会通过validation-query来保活空闲连接，防止 MySQL 的wait_timeout把连接断开。MySQL 默认wait_timeout是 8 小时，如果你的连接池很少主动检测，8 小时后连接其实已经死了，但 Druid 不知道，下次拿去用就报Communications link failure。开启keep-alive+ 合理的检测间隔就能解决。

3.3 生产环境强烈建议开启的配置

除了基础参数，生产环境我还会加这几项：

spring: datasource: druid: # 开启超时连接回收 remove-abandoned: true # 超时时间，单位秒 remove-abandoned-timeout: 180 # 关闭 abandoned 连接时输出日志 log-abandoned: true # 物理连接最大使用次数，超过后强制重建连接 phy-max-use-count: 1000

remove-abandoned是救命的。它会把那些超过remove-abandoned-timeout还没归还的连接暴力回收。比如你代码里忘了finally { conn.close(); }，连接会被一直占用不放，正常情况下连接池会被耗尽，开启这个参数后，180 秒没归还就直接断了，虽然拿到的连接可能已经不可用，但至少不会造成连接池整体瘫痪。

phy-max-use-count设置物理连接使用次数超过 1000 次后重建，可以避免 MySQL 长时间持有同一个连接导致的报错或者状态残留。

4. 监控页配置：Druid 最亮眼的功能，别浪费了

4.1 开启监控统计功能

Druid 最吸引人的就是自带的 Web 监控页，能展示连接池状态、SQL 执行统计、慢 SQL 日志、Session 监控等功能。在 SpringBoot3 里开启并不复杂，但需要知道几个关键点。

首先，filters配置里要包含stat，否则统计功能不生效。我配置的是stat,wall,slf4j，解释一下：

• stat：开启 SQL 统计，监控页能看到每条 SQL 的执行次数、耗时、并发等
• wall：开启 SQL 防火墙，拦截危险 SQL，比如delete from table_name无 where 条件的操作
• slf4j：把 SQL 执行日志输出到日志系统，调试时很有用

注意，wall过滤器比较严格，有些项目用了大量所谓的“动态 SQL”或者特殊语法，会被误拦截。这时可以根据你的 SQL 特点，拉黑名单或者白名单配置，后面我会讲到。

4.2 注册 Servlet 和 Filter

SpringBoot3 里，如果要访问/druid/index.html监控页，需要注册一个StatViewServlet，拦截/druid/*。同时要注册WebStatFilter，用于采集 Web 应用层的请求监控数据。

我在项目里单独写了一个配置类，这样比在application.yml里配更直观：

package com.example.demo.config; import com.alibaba.druid.pool.DruidDataSource; import com.alibaba.druid.support.http.StatViewServlet; import com.alibaba.druid.support.http.WebStatFilter; import org.springframework.boot.context.properties.ConfigurationProperties; import org.springframework.boot.jdbc.DataSourceBuilder; import org.springframework.boot.web.servlet.FilterRegistrationBean; import org.springframework.boot.web.servlet.ServletRegistrationBean; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import javax.sql.DataSource; import java.util.HashMap; import java.util.Map; @Configuration public class DruidConfig { /** * 绑定 application.yml 中 spring.datasource.druid 配置到 DruidDataSource */ @Bean @ConfigurationProperties(prefix = "spring.datasource.druid") public DataSource druidDataSource() { return new DruidDataSource(); } /** * 注册 Druid 监控页 Servlet */ @Bean public ServletRegistrationBean<StatViewServlet> druidStatViewServlet() { ServletRegistrationBean<StatViewServlet> registrationBean = new ServletRegistrationBean<>(new StatViewServlet(), "/druid/*"); Map<String, String> initParams = new HashMap<>(); // 监控页登录账号 initParams.put("loginUsername", "admin"); // 监控页登录密码 initParams.put("loginPassword", "admin123"); // IP 白名单（留空则允许所有 IP） initParams.put("allow", ""); // IP 黑名单 initParams.put("deny", "192.168.1.100"); registrationBean.setInitParameters(initParams); return registrationBean; } /** * 注册 Web 请求监控过滤器 */ @Bean public FilterRegistrationBean<WebStatFilter> webStatFilter() { FilterRegistrationBean<WebStatFilter> registrationBean = new FilterRegistrationBean<>(); registrationBean.setFilter(new WebStatFilter()); // 拦截所有请求 registrationBean.addUrlPatterns("/*"); Map<String, String> initParams = new HashMap<>(); // 忽略静态资源 initParams.put("exclusions", "*.js,*.gif,*.jpg,*.png,*.css,*.ico,/druid/*"); registrationBean.setInitParameters(initParams); return registrationBean; } }

这段配置有两个坑要提醒你：

坑一：数据源绑定前缀。如果application.yml里除了spring.datasource.druid还有spring.datasource下的基础配置（比如driver-class-name），你使用@ConfigurationProperties(prefix = "spring.datasource.druid")时，一定要保证url、username、password全部在druid节点下面，否则DruidDataSource的属性绑定不到。因为spring.datasource.druid是 Druid 自己的前缀，SpringBoot 的DataSourceAutoConfiguration默认读的是spring.datasource，二者不能混用。

实际上，druid-spring-boot3-starter里的自动配置类DruidDataSourceAutoConfigure已经帮你处理了，它会识别spring.datasource.druid.*配置并绑定到DruidDataSource上。所以如果走自动配置，你不需要再手动写DruidDataSourceBean。如果你写了上面的那个druidDataSource()方法，反而容易和自动配置冲突。我习惯保留手动配置，因为可以更清晰地控制数据源生命周期，但要注意取消自动配置的某些条件。

经过实测，最稳妥的方式还是只使用druid-spring-boot3-starter的自动配置，然后在application.yml里写全spring.datasource.druid配置。因为一旦你自己创建DruidDataSourceBean，SpringBoot 的数据库自动配置会认为你不需要它来初始化数据源，可能会影响事务管理器和 JPA/MyBatis 自动配置，导致启动报错。

坑二：allow 参数。allow默认空字符串是全部放行，deny是黑名单。如果你设置了allow为具体 IP，比如127.0.0.1，那局域网里其他机器就无法访问监控页了。我在公司环境里是留空，然后利用 Nginx 做内网访问控制，这样更灵活。

4.3 访问监控页

配置完成后，启动项目，浏览器访问http://localhost:8080/druid/index.html，输入你配置的账号密码，就能看到监控页了。里面能看：

• 数据源：当前连接数、活跃连接数、空闲连接数、等待次数、错误次数
• SQL 监控：每条 SQL 的执行次数、平均耗时、最大耗时、错误次数
• SQL 防火墙：被拦截的 SQL 记录
• Web 应用：请求 URL、请求次数、耗时
• Session 监控：当前 Session 列表

这些数据对排查性能问题特别有用。我在一次压测中发现有一条 SQL 平均耗时 800ms，通过监控页定位到 SQL，加上索引后直接把接口响应从 1.2 秒降到 200ms。

5. 数据库密码加密：祛魅与实操

5.1 为什么要加密

application.yml里明文写数据库密码，是很多公司安全审计的红线。Druid 支持对密码做 RSA 加密后再配置，启动时自动解密，这样即使配置文件泄露，别人拿到的也是密文。

网上关于这块的教程很多，但有不少人只讲了加密步骤，没说清楚原理，导致看着密文心里没底。这里我把原理拆开讲透。

5.2 加密原理与操作步骤

Druid 的密码加密其实用了 RSA 非对称加密。它生成一对密钥：私钥用于解密，公钥用于加密。在生成密文时，使用公钥对明文密码加密，得到密文；在运行时，Druid 通过配置里的私钥解密得到明文密码。

具体操作分四步：

第一步：生成密文。使用 Druid 的ConfigTools类生成密文和私钥、公钥。最简单的做法是通过 Maven 执行：

mvn com.alibaba:druid:1.2.21:tools

或者直接运行：

java -cp druid-1.2.21.jar com.alibaba.druid.filter.config.ConfigTools yourpassword

屏幕上会输出privateKey、publicKey、password，其中password就是加密后的密文，privateKey是解密时用的，publicKey是理论上给别人加密时用的。

第二步：修改配置。把原来明文密码替换成密文，同时新增publickey配置项，并开启connection-properties里的解密选项：

spring: datasource: druid: username: root password: QmYz4...（上面生成的密文） # 开启数据库密码解密 filters: config,stat,wall,slf4j connection-properties: druid.stat.slowSqlMillis=5000;config.decrypt=true;config.decrypt.key=${DRUID_PRIVATE_KEY}

这里有两个关键点：

1. filters里必须加上config，否则解密过滤器不生效。
2. config.decrypt.key是私钥。私钥不能直接暴露在application.yml里，否则密文形同虚设。正确做法是通过环境变量注入。

第三步：环境变量管理私钥。在启动项目时传入环境变量：

java -jar demo.jar --DRUID_PRIVATE_KEY=你的私钥

或者更规范一点，在服务器上配置环境变量：

export DRUID_PRIVATE_KEY=你的私钥

然后application.yml里用 placeholder 引用：

connection-properties: druid.stat.slowSqlMillis=5000;config.decrypt=true;config.decrypt.key=${DRUID_PRIVATE_KEY}

这样即使配置文件泄露，黑客拿不到环境变量，也解不开密码。

第四步：验证效果。启动项目，看日志是否报druid decrypt fail。如果报错，多半是私钥换行、空格或编码问题。私钥是很长的一串 Base64 字符，复制粘贴时不要带换行，不要在前后加空格。

5.3 若依框架集成的参考

最近很火的若依框架（RuoYi）在它的代码生成模块里也集成了 Druid 密码加密。我特意去翻过源码，它的做法是把私钥配置在druid.yml里，然后通过@ConfigurationProperties读取。如果你用的是若依，直接在application-druid.yml里找到password和publicKey，改成你自己的即可。

不过有一点要提醒：若依框架默认没有开启config过滤器，需要在filters中加上config，否则解密不会执行。这也是很多人在若依里配了加密但启动报密码错误的原因。

6. SpringBoot3 + Druid 实战：整合 MyBatis 并调通监控

6.1 项目依赖一览

这里我放一个完整的pom.xml依赖清单，方便大家照搬：

<dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.mybatis.spring.boot</groupId> <artifactId>mybatis-spring-boot-starter</artifactId> <version>3.0.3</version> </dependency> <dependency> <groupId>com.alibaba</groupId> <artifactId>druid-spring-boot3-starter</artifactId> <version>1.2.21</version> </dependency> <dependency> <groupId>com.mysql</groupId> <artifactId>mysql-connector-j</artifactId> <scope>runtime</scope> </dependency> </dependencies>

如果你的项目用的是 MyBatis-Plus，把mybatis-spring-boot-starter换成mybatis-plus-boot-starter，版本用最新的 3.5.x 系列，兼容 SpringBoot3。

6.2 完整的 application.yml 配置

我给出一个整合了监控、防火墙、慢 SQL 日志、密码加密的生产级配置：

spring: application: name: druid-demo datasource: druid: url: jdbc:mysql://192.168.1.10:3306/demo?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&useSSL=false&allowPublicKeyRetrieval=true username: root password: ${DB_PASSWORD} driver-class-name: com.mysql.cj.jdbc.Driver initial-size: 5 min-idle: 5 max-active: 20 max-wait: 60000 time-between-eviction-runs-millis: 60000 min-evictable-idle-time-millis: 300000 validation-query: SELECT 1 test-while-idle: true test-on-borrow: false test-on-return: false pool-prepared-statements: true max-pool-prepared-statement-per-connection-size: 20 keep-alive: true phy-max-use-count: 1000 filters: stat,wall,slf4j connection-properties: druid.stat.slowSqlMillis=3000 # Web 监控统计 web-stat-filter: enabled: true url-pattern: /* exclusions: '*.js,*.gif,*.jpg,*.png,*.css,*.ico,/druid/*' # 监控页配置 stat-view-servlet: enabled: true url-pattern: /druid/* login-username: admin login-password: admin123 allow: '' deny: ''

这里我用了环境变量${DB_PASSWORD}，而不是明文。如果你的应用部署在 Kubernetes 里，可以将数据库密码放到 Secret 中，然后把环境变量挂载进 Pod，这样配置文件和密钥完全分离。

6.3 防火墙常见误拦截与处理

wall过滤器默认会拦截很多 SQL。我遇到过一些被误伤的典型场景：

• 使用select *且没有 WHERE 条件的大表查询，默认会提示“sql not allow”并被记录
• 包含关键字sleep()、benchmark()的函数调用
• 使用LIMIT子句但有语法变体的查询
• MyBatis 动态 SQL 拼出来的含有concat、ifnull等函数的复杂 SQL

被拦截后在监控页的“SQL 防火墙”里能看到详细的拦截原因。解决办法有三种：

1. 对单个 SQL 不拦截：在防火墙配置里配置白名单 SQL
2. 降低拦截规则：修改wall过滤器的config参数
3. 直接去掉wall过滤器（不推荐生产环境）

我一般用一种折中方案：在application.yml里单独配置wall的拦截策略：

druid: filter: wall: enabled: true config: delete-allow: false drop-table-allow: false alter-table-allow: false set-allow: false

这样只禁止最危险的 DDL 和无 WHERE 的 DELETE，其他 SQL 放行，生产环境更实用。

6.4 慢 SQL 日志配置

connection-properties里设置了druid.stat.slowSqlMillis=3000，表示超过 3000ms 的 SQL 会被记录。配合slf4j过滤器，慢 SQL 会输出到日志中。我建议在项目里也配置 MyBatis 的慢 SQL 日志：

mybatis: configuration: log-impl: org.apache.ibatis.logging.slf4j.Slf4jImpl

再配合 logback 的日志级别，设置 mapper 包下的日志为 debug，就能看到 SQL 执行详情。

7. 常见问题与排查技巧实录

7.1 启动时报ClassNotFoundException: javax.servlet.Filter

这是最经典的 SpringBoot3 迁移问题。原因是你的 Druid 版本低于 1.2.20，或者引错了依赖。解决方式就是换成druid-spring-boot3-starter1.2.2x。如果你的项目还有其他框架引入了老实现，可以通过排除依赖来隔离：

<dependency> <groupId>com.alibaba</groupId> <artifactId>druid-spring-boot3-starter</artifactId> <version>1.2.21</version> <exclusions> <exclusion> <groupId>javax.servlet</groupId> <artifactId>javax.servlet-api</artifactId> </exclusion> </exclusions> </dependency>

7.2 监控页打开白屏或 404

监控页 404 大多是因为StatViewServlet没注册成功。检查三件事：

1. pom.xml里是否引入了spring-boot-starter-web，Druid 的 Web 监控需要 Servlet 容器支持
2. stat-view-servlet.enabled是否为true（默认可能关闭）
3. 项目是否被某个全局过滤器拦截了/druid/*请求

另外注意，如果你的项目使用了 Spring Security，需要把/druid/**加入白名单，否则会被权限拦截，表现为“无权限访问”。

7.3 数据源首次请求报连接错误

排除密码错误后，最常见的两个原因：

• allowPublicKeyRetrieval=true没加。MySQL 8 默认用 caching_sha2_password 认证，连接时如果不允许公钥检索，会报Public Key Retrieval is not allowed。
• serverTimezone没设置。没设置时，Druid 和 MySQL 之间时区不匹配，会报serverTimezone异常。我这里的配置用的Asia/Shanghai。

7.4 密码加密后启动失败

报错信息一般是oracle.net.ns.NetException: Io exception，或者Caused by: java.lang.IllegalStateException: druid decrypt fail。排查顺序：

1. filters里有没有加config过滤器
2. connection-properties里的config.decrypt.key是否引用的环境变量，如果直接在 yml 里写私钥，且私钥有换行，会解析失败
3. 私钥值是否有空格，Base64 里不要有换行符

7.5 采用表格形式汇总排查清单

8. 关于参数调优的个人经验

Druid 参数大都是参考值，最终还是要看压测结果。我分享一套我自己常用的调优思路，不一定适合所有项目，但可以给大家一个起点。

如果业务是读多写少的简单查询，单机并发五百以内，max-active建议 20 就够，initial-size5，min-idle5。这种情况下即使某个慢 SQL 拖慢了数据库，连接池也不会瞬间被打爆。

如果业务有批处理任务，比如定时跑几个小时的报表任务，需要一次性拿大量连接，可以把max-active调到 50，同时调大max-wait到 30000ms。但要注意数据库端max_connections的限制，一般 MySQL 默认 151，你连接池 50 个，加上其他应用和运维工具，很容易打满。这时反而应该给数据库也调大max_connections，或者减少连接池数量。

还有一个小窍门：把time-between-eviction-runs-millis和min-evictable-idle-time-millis的值错开一些，比如前者 60 秒、后者 300 秒。这样检测线程至少每 60 秒跑一次，但空闲连接要等 300 秒才会被清理，避免连接频繁创建销毁。连接创建开销很大，尽量保持池子里有常用连接。

9. 写在后面的小建议

这一篇从版本选择、配置参数、监控页到密码加密、常见问题，基本把 SpringBoot3 集成 Druid 的主要环节都过了一遍。最后给新人一个建议：不要上来就直接复制一大段配置，而是先按照官方文档的最小配置跑通，再逐步加监控、防火墙、加密这些功能。每次只加一个功能，出了问题时你能快速定位是哪个配置引起的。

我用这方案在本周刚把一个生产项目从 SpringBoot2.7 升级到 SpringBoot3.2，从引入依赖到监控页跑通，整个过程花了不到半小时。踩过的坑主要是版本，其次是防火墙误拦截。按这篇文章的配置走，你应该能更顺畅。如果你在集成中遇到其他怪问题，欢迎在评论区把报错日志贴出来，我帮你看看到底是哪一步没到位。