Spring Boot多数据源密码安全：dynamic-datasource加密与Vault集成实践

前几年我负责一个订单中台的重构，代码评审时发现一位同事把测试库密码直接写在 application-dev.yml 里，又因为某次误操作把整个仓库推到了公开源上。虽然最后密码改了、仓库也删了，但那天晚上我反复在想：如果当时已经有人扒走了这份配置，整个项目组的数据库账号等于裸奔。也是从那次之后，数据源密码的安全处理，成了我所有项目里不可妥协的一条红线。

今天要聊的就是这个方向上的完整落地经验：使用 dynamic-datasource 作为动态数据源组件的 Spring Boot 项目里，如何安全配置加密存储，并且和 HashiCorp Vault 做集成。dynamic-datasource 是 Java 生态里相当主流的多数据源方案，负责多数据源切换、读写分离、一主多从路由这些能力，但它本身不强制要求密码安全，默认情况下连接串的用户名密码就是明文躺在配置文件和配置中心里。这篇文章会把它的内置加密机制、自定义解密扩展、Vault 集成三条路全部梳理一遍，并附上我在真实项目里踩过的坑和排查思路。适合正在做 Spring Boot 多数据源项目，同时想把数据库凭据安全等级提上来的开发者参考，无论你是刚接触这个组件，还是已经在生产环境跑了好几年，应该都能找到用得上的内容。

1. 数据源密码为什么值得当成头等大事

1.1 明文配置的泄露路径，比你想的宽得多

很多团队对数据库密码的态度是"内网环境，谁能看到"，这个想法我过去也有，直到亲眼见过几种真实的泄露方式之后才彻底改观。

第一类泄露路径是配置文件进版本库。哪怕仓库是私有的，只要协作人数一多，权限边界就变得模糊，某位同学把仓库 fork 走、或者离职时打包带走，密码就跟着扩散了。更普遍的是本地 IDE 缓存、编译输出目录、包管理器缓存里残留的 yml 文件，这些文件一旦被同步工具传到云端，就等于把钥匙挂在了门口。

第二类路径是配置中心本身。很多团队用配置中心统一管理动态数据源配置，但配置中心的权限、审计、操作留痕往往做得比业务系统粗糙，一旦出现越权查询或者配置中心本身被攻破，所有数据源的密码一次性全部暴露。

第三类路径是日志和监控。连接失败时会打印完整 JDBC URL，某些数据库驱动在 Debug 级别会输出连接属性，这些日志进了日志平台之后，检索权限通常比数据库权限宽松得多，密码就顺着日志管道流了出去。

我举一个具体的例子。某电商项目的订单库和库存库在同一个实例，测试环境密码和开发环境密码相同，这个密码同时出现在三份配置文件、两个 shell 脚本和一份交接文档里。后来做安全巡检，发现这份密码已经被一个第三方统计脚本采集走，虽然对方没有恶意，但这件事足以说明：明文密码每多一份拷贝，风险就翻一倍。加密存储的意义不在于让密码"看不见"，而在于让拿到配置的人也无法直接使用，把泄露的影响面从"数据库裸奔"降级为"需要密钥才能解出密码"。

1.2 两条主流路线的本质区别

解决数据源密码安全，市面上成熟的做法本质上只有两条路线，我把自己做过的选型梳理成了一张对照。

第一条路线是静态加密：用对称或非对称算法把密码加密成密文，密文仍然放在配置文件、配置中心里，应用启动时用密钥解密。常见实现包括 Jasypt、dynamic-datasource 内置的 Crypto 机制、以及各种基于自定义注解的解密器。这条路线解决的是"配置文件被拷贝"的问题，只要密钥不泄露，密文就是安全的。但它的短板也很明显：加密用的密钥存储在哪里？如果密钥和密文放在一起，加密就形同虚设。

第二条路线是动态托管：密码根本不落配置文件，应用启动时从外部密钥管理系统拉取。HashiCorp Vault 就是这类系统的代表，密码存储在 Vault 的存储后端里，应用通过认证拿到临时令牌后读取。这条路线解决的是"密钥和密文分离"的问题，泄露配置文件的危害降到了最低，因为文件里连密文都没有。代价是需要额外运维一套密钥管理系统，并且要处理应用启动时的依赖顺序和网络可用性。

用一个生活化的类比：静态加密是把存折放进保险箱，密码是开箱的密码，保险箱和密码分开存放；动态托管是干脆把存折交给银行金库代为保管，你凭钥匙去取，金库的安保措施远好过自家办公室。绝大多数业务系统，这两条路线不是二选一，而是叠着用的，后面我会专门讲这个组合方式。

1.3 不同体量项目的安全定位

先说结论：单机小项目、内部工具类系统，用 dynamic-datasource 内置加密已经足够；涉及多环境、多团队协作、需要审计和凭据轮换的系统，必须上 Vault；如果合规要求严格，比如金融、政务背景的项目，两套机制同时部署是常态。

我见过不少团队在小项目上直接上 Vault，最后运维成本远超收益，Vault 实例无人维护、令牌泄漏了都不知道；也见过业务已经铺到几十个微服务的团队还在用明文密码，出了安全事故才开始补课。判断标准不是"用了多牛的技术"，而是"密码泄露之后，你能不能承受后果"。基于这个标准，我把动态数据源场景拆成了三个档位：开发环境至少要做到密文入库、密钥不进仓库；测试环境要做到密钥与配置分离；生产环境无论多麻烦，都应该做到运行时动态获取凭据，并且保留审计记录。

2. dynamic-datasource 内置加密的正确打开方式

2.1 原理：为什么用 RSA，而不是 AES

dynamic-datasource 从 3.x 版本开始就内置了基于 RSA 的密码加密能力，核心类是com.baomidou.dynamic.datasource.toolkit.Crypto。我在给团队分享的时候，很多人第一个问题就是：为什么不用 AES 这种对称加密，性能好、实现简单？

这里的关键不是性能，而是密钥分发的安全模型。AES 加密解密用的是同一把密钥，那这把密钥必须同时保存在开发者的加密工具里和应用服务的配置里。应用配置在服务器上、在镜像里、在配置中心里，任何一个环节被拿到，密钥就泄露了，密文随之失去意义。

RSA 非对称机制下，加密和解密分别使用私钥和公钥。开发者手里持有私钥，用私钥对明文密码加密；应用端只配置公钥，启动时用公钥解密。公钥的作用是把密文还原成明文，但公钥本身无法加密内容，即使攻击者拿到了公钥和密文，也无法反推私钥去解密其他敏感信息。这等于把安全边界划在了"应用进程之外"：私钥只存在于开发者的工作环境，生产服务器上永远没有解密的全部材料。

而且这里的用法和常见 RSA 方向相反，通常是公钥加密、私钥解密，但 dynamic-datasource 是私钥加密、公钥解密。数学上 RSA 的可逆性支持这种用法，工程上这样设计是为了满足开发流程：开发者用私钥加密后把密文提交到配置库，应用侧只保留公钥，即便配置库被脱库，攻击者拿到的也只是公钥和密文，没有任何利用价值。

2.2 实操：生成密钥对并加密密码

我在项目里的标准操作流程是这样的，以 Spring Boot + dynamic-datasource 4.x 为例。

首先准备 RSA 密钥对。可以用 OpenSSL 生成，也可以直接用 Java 的 KeyPairGenerator 写个小工具生成。我习惯用 OpenSSL，因为生成结果直观：

# 生成 2048 位 RSA 私钥 openssl genrsa -out private_key.pem 2048 # 从私钥导出公钥 openssl rsa -in private_key.pem -pubout -out public_key.pem

注意私钥是 PKCS#8 还是 PKCS#1 格式，dynamic-datasource 的 Crypto 工具解析时可能需要标准格式。为了省事，我更推荐直接把私钥转成 PKCS#8 并使用 Base64 编码内容：

openssl pkcs8 -topk8 -inform PEM -in private_key.pem -outform PEM -nocrypt

接着用 dynamic-datasource 自带的 Crypto 工具加密明文密码。从依赖包里找到对应的 jar，或者直接写一个调用入口：

public class EncryptPasswordRunner { public static void main(String[] args) { // 参数1：明文密码，参数2：私钥字符串 String cipher = Crypto.encrypt(args[0], args[1]); System.out.println("ENC(" + cipher + ")"); } }

我在实际使用中不会直接把私钥粘贴到命令行，因为 shell 历史会记录。更稳妥的做法是把私钥放在环境变量里引用，或者用一个临时脚本执行完毕后立即销毁。这一条经验是当时在某个金融项目上被安全评审打回之后总结出来的，命令行里的私钥和配置文件里的明文密码一样危险。

2.3 配置 application.yml 让运行时自动解密

加密后的密文格式是ENC(密文Base64)，配置到 dynamic-datasource 的密码字段，同时配置public-key属性：

spring: datasource: dynamic: public-key: MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEArvX... datasource: master: username: root password: ENC(IAmCipherTextBase64...) slave_1: username: root password: ENC(IAmCipherTextForSlave...)

启动时 dynamic-datasource 会在构建数据源之前，用公钥解密所有以ENC(开头、以)结尾的密码字段，然后再交给连接池。整个解密过程发生在DynamicRoutingDataSource初始化阶段，所以你在代码里拿到的DataSource已经是解密后的真实连接。

有几个容易踩的细节。第一，ENC()里的密文是去掉换行符的连续 Base64 字符串，直接复制 OpenSSL 输出时经常带换行，会导致解析失败。第二，password如果是 YAML 里包含特殊字符，建议用单引号包起来。第三，public-key本身不要加-----BEGIN PUBLIC KEY-----头尾，只保留 Base64 主体。这三个问题几乎占了官方 issue 区加密相关问题的八成。

如果你已经在用低版本 3.x，配置方式基本一致，4.x 只是增加了更多 SPI 扩展点，核心的public-key + ENC()机制没有变化。

2.4 自定义 Decrypt：接口背后是更灵活的解密策略

内置公钥解密解决了绝大多数需求，但它把密钥形态固定成了"本地公钥"。如果你们公司已经有统一的密钥管理系统，想统一管控所有服务的解密密钥，dynamic-datasource 提供了Decrypt接口让你替换整个解密过程。

接口签名大概是这样的，不同版本所在包名略有差异，建议以你引入版本的源码为准：

public interface Decrypt { String decrypt(String cipherText); }

实现一个自定义解密器，例如对接内部 KMS 或 Vault 的 Transit 引擎：

public class KmsDecrypt implements Decrypt { private final KmsClient kmsClient; public KmsDecrypt(KmsClient kmsClient) { this.kmsClient = kmsClient; } @Override public String decrypt(String cipherText) { // 去掉 ENC() 包裹 String raw = cipherText.substring(4, cipherText.length() - 1); return kmsClient.decrypt(raw); } }

然后在配置类里把它注册为 Bean：

@Configuration public class DataSourceSecurityConfig { @Bean public Decrypt kmsDecrypt() { return new KmsDecrypt(kmsClient()); } }

启动时 dynamic-datasource 会优先使用你提供的DecryptBean；如果没找到，才会退回公钥解密。这个扩展点的价值在于，它把"密码安全策略"从组件内部解耦成了业务代码可以干预的策略，你完全可以做到配置里写的是密文、解密动作发生在远程密钥管理系统、本地不留任何私钥材料。

我在做这个自定义实现时遇到过一个具体问题：Decrypt接口在执行时可能被调用多次，每次解密都请求远程 KMS 会拖慢启动速度。我的做法是加了一层ConcurrentHashMap做本地缓存，只在第一次解密时请求 KMS，后续走缓存。但这个缓存需要考虑过期时间，否则密码轮换之后缓存里的旧值迟迟不失效，反而引入新的故障点。

3. 与 HashiCorp Vault 集成的完整方案

3.1 Vault 里放什么：静态 KV 还是动态数据库凭据

场景切入之前，先把 Vault 的两种存储方式讲清楚，因为很多人一上来就搞混。

静态 KV 存储：把用户名密码当作普通 secret 存进 Vault 的 KV 引擎，比如secret/datasource/order路径下存username和password。应用启动时读取，拿到后用多长时间基本由应用自己决定。这种方式的优点是简单、直观，适合凭据不频繁轮换的业务库。

动态数据库凭据：启用 Vault 的 database secrets engine，Vault 直接对接数据库，为每个应用动态创建短期有效的数据库账号。这个账号有独立的密码，并且设置了 TTL，到期自动失效。这种方式适合对安全要求极高的场景，应用的每次启动都拿到一个全新的、一次性账号，即使密码泄露，影响窗口也只有几分钟。

我的建议是分场景选择：一般业务系统用静态 KV 足够，重点把访问控制和审计做好；如果是核心账务库、生产库和开发库混用的环境，优先考虑动态凭据，把风险敞口压到最小。下面先讲静态 KV 的接入，这是最常用也最容易上手的路径，动态凭据相关的内容我会在 3.4 节展开。

3.2 Spring Cloud Vault 接入的完整配置

接入 Vault 最顺滑的方式是使用 Spring Cloud Vault，它能在 Spring 应用上下文刷新之前，把 Vault 里的 secret 加载到 Environment 中，这样一来 dynamic-datasource 的配置可以直接用占位符引用，完全不需要写额外的读取代码。

项目依赖先加好：

<dependency> <groupId>org.springframework.cloud</groupId> <artifactId>spring-cloud-starter-vault-config</artifactId> </dependency> <dependency> <groupId>org.springframework.vault</groupId> <artifactId>spring-vault-core</artifactId> </dependency>

Spring Cloud 2020 之后推荐用spring.config.import的方式引入 Vault，而不是老的 bootstrap 机制。在application.yml里这样配置：

spring: application: name: order-service config: import: vault://secret/order-service cloud: vault: host: vault.internal.example.com port: 8200 scheme: https authentication: TOKEN token: ${VAULT_TOKEN} kv: enabled: true backend: secret

使用 Vault CLI 写入对应路径的密钥：

vault kv put secret/order-service \ db-url='jdbc:mysql://10.0.0.5:3306/order_db' \ db-username='order_service_user' \ db-password='S0m3L0ngRand0mP@ss'

然后在 dynamic-datasource 的配置里用占位符引用：

spring: datasource: dynamic: datasource: master: url: ${db-url} username: ${db-username} password: ${db-password}

这里的关键点在于加载顺序：Spring Cloud Vault 会在配置属性绑定之前把db-url、db-username、db-password注入 Environment，等 dynamic-datasource 开始创建数据源时，占位符已经能解析到真实值。整个过程对业务代码完全透明，你甚至连解密逻辑都不用写。

上述配置里我特别推荐给 Vault 开 HTTPS，否则令牌在网络传输中是明文的，这一点在跨网段部署时尤其重要。另外，生产环境的令牌别写死在配置文件里，优先用环境变量或者 Kubernetes Secret 注入。

3.3 多数据源场景下的 Vault 组织方式

动态数据源项目的典型特征是数据源数量多，订单库、库存库、用户库、日志库，甚至每个分片都有自己的连接配置。直接往secret/order-service里塞一堆字段会很快变得不可维护，我推荐按照"一个数据源一个子路径"的方式组织：

spring: config: import: - vault://secret/order-service/order - vault://secret/order-service/inventory - vault://secret/order-service/user

对应 Vault 路径：

vault kv put secret/order-service/order \ url='jdbc:mysql://10.0.0.5:3306/order_db' \ username='order_user' \ password='OrderP@ssw0rd' vault kv put secret/order-service/inventory \ url='jdbc:mysql://10.0.0.6:3306/inventory_db' \ username='inventory_user' \ password='Inventory@2024'

application.yml 里再引用：

spring: datasource: dynamic: datasource: order: url: ${url} username: ${username} password: ${password} inventory: url: ${url} username: ${username} password: ${password}

但这里有一个非常隐蔽的坑：多个 context 的 key 可能重名。比如 order 和 inventory 两个 secret 都定义了url，Spring Cloud Vault 加载时后者会覆盖前者，结果两个数据源拿到同一个 URL。我第一次这样配置的时候，排查了很久才发现问题。

解决办法有两个。第一，Vault 侧把 key 加上前缀区分，比如order-url、inventory-url。第二，更推荐的做法是自定义一个PropertySourceLocator，把 Vault 返回的扁平 key 重新组织成带命名空间的形式。我实际用的是第二种，因为第一种在 secret 数量多的时候命名会变得很混乱。具体实现就是实现PropertySourceLocator接口，遍历secret/order-service/*下所有路径，把返回的 Properties 以路径名作为前缀重写一遍，这样配置文件里的占位符可以写成${order.url}、${inventory.url}，语义清晰，也不会互相覆盖。

3.4 进阶：用加载器接口直连 Vault，实现动态凭据

如果你不想依赖 Spring Cloud Vault 的配置加载机制，或者你的数据源列表本身就是动态的，可以考虑实现 dynamic-datasource 的LoadDataSource接口，完全接管数据源配置的加载过程。这个接口在所有数据源初始化之前被调用，返回一个以数据源名为 key、以DataSourceProperty为 value 的 Map。

@Component public class VaultDataSourceLoader implements LoadDataSource { private final VaultTemplate vaultTemplate; public VaultDataSourceLoader(VaultTemplate vaultTemplate) { this.vaultTemplate = vaultTemplate; } @Override public Map<String, DataSourceProperty> loadDataSources() { Map<String, DataSourceProperty> result = new HashMap<>(); // 从 Vault 读取数据源清单 List<String> datasourceKeys = fetchDatasourceKeys(); for (String key : datasourceKeys) { VaultResponseSupport<Map<String, Object>> response = vaultTemplate.read("secret/datasource/" + key); Map<String, Object> data = response.getData(); DataSourceProperty property = new DataSourceProperty(); property.setUrl((String) data.get("url")); property.setUsername((String) data.get("username")); property.setPassword((String) data.get("password")); result.put(key, property); } return result; } }

这种方案的价值在于数据源配置完全集中在 Vault，应用本地不配置任何数据源信息，新增一个数据源只需要在 Vault 里加一条 secret，重启服务即可生效，不需要改代码、重新发版。适合需要频繁调整数据源映射的中台类项目。

如果进一步叠加 Vault 的 database secrets engine，这里拿到的password就是动态生成的短期凭据。每次应用启动都会向 Vault 申请一个新的数据库账号和密码，Vault 再把这个动态账号创建到目标数据库上。这套组合是目前我做过的最接近"零静态凭据"的方案，应用进程里不存在任何长期有效的数据库口令。代价是动态凭据的生命周期管理相当复杂，连接池里的连接在 TTL 到期后需要重建，连接池参数必须配合调整，否则会出现运行一段时间后连接突然全部失效的问题。我的经验是，除非安全评审强制要求，否则优先用静态 KV 加定期轮换的方式，成本可控得多。

4. 两种方案怎么选：一张对比表和一个兜底建议

4.1 从五个维度看内置加密与 Vault 集成的差别

我把两种方案放在一起做了个横向对比，这张表来自我自己的踩坑和复盘，不算是官方结论，但应该能帮你快速判断：

从这个表可以明显看出，内置加密胜在轻量，Vault 胜在管控。我个人的判断标准是：如果你的团队没有专门的运维人力，或者项目规模在三个服务以内，不要犹豫，直接用内置加密；如果你所在的团队已经具备基本的 Vault 运维能力，或者项目需要对外接受安全审计，那就一步到位上 Vault。

4.2 纵深防御：Vault 管密钥，Crypto 管最后一公里

真正成熟的系统不会只用其中一种。我最近参与的一个跨平台系统用的就是组合方案，具体来说分两层。

第一层，Vault 作为密钥的唯一来源。数据库密码、KMS 密钥、敏感配置项全部存放在 Vault，通过策略控制谁能读、谁能写，所有读取行为都有审计记录。这一层解决的是"密钥集中管控"问题。

第二层，应用侧仍然保留 dynamic-datasource 的加密配置。从 Vault 取回来的密码本身也是密文，配置里写入的是经过 RSA 加密的ENC()形式，应用启动时先用公钥解开第一层，拿到密文后再调用自定义Decrypt向 Vault 发起解密请求。有人会觉得这一步是脱裤子放屁，Vault 返回的已经是明文了，为什么还要再包装一层？

原因是网络信任模型不一样。Vault 和应用之间走的是网络，网络上的数据有可能被嗅探，尤其是微服务架构下应用从 Vault 拿到的凭据还要经过配置中心中转的时候。在凭据的传输链路上每增加一层加密，中间环节能直接看到明文的概率就降低一分。另外，如果 Vault 临时不可用，有了这一层降级方案，应用可以短暂使用本地公钥缓存继续启动，不至于整个服务集群跟着 Vault 一起宕机。这个设计理念在安全领域叫纵深防御，不把鸡蛋放在一个篮子里。

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

5.1 高频报错与排查速查表

这些年帮团队和社区朋友排查过不少 dynamic-datasource 加密和 Vault 集成的问题，我把最高频的几类整理成了速查表：

5.2 几个容易忽略的坑

第一个坑是 Vault KV 引擎版本导致的路径差异。Vault 默认的 KV 引擎可能是 v2，v2 的读写路径是secret/data/xxx，而 Spring Cloud Vault 的kv.backend配置需要明确指向引擎挂载点。如果你用老版本习惯直接配置secret，很可能会遇到 404。新版本里 KV v2 对应用层透明，但 CLI 操作时vault kv put secret/xxx和实际 HTTP 路径/v1/secret/data/xxx的差异，排查时容易让人怀疑人生。

第二个坑是动态数据源场景下，url里如果有特殊字符，比如查询参数带&，在 YAML 和 Vault CLI 的传递中会被转义破坏。我的习惯是连接串里不携带任何查询参数，需要的参数全部在连接池层面配置，从源头避免这一类字符问题。

第三个坑是关于ENC()包裹格式的大小写和空格。有的同学从文档复制密文时把ENC(后面的空格也带进去了，导致解密时截取的子串多了一个字符。我建议在实现里做一次 trim 和严格匹配，宁可多写两行防御代码。

第四个坑是开发环境与生产环境的配置漂移。很多团队开发环境用明文密码方便调试，生产环境才上加密，结果两套配置长期分叉，某次发版时把开发配置直接推到了生产，线上应用用明文跑了一周才发现。我在项目里定了一条规则：配置文件模板从第一天就使用占位符和加密形式，开发环境的明文只存在于本地 profile 的 untracked 文件中，不允许进入版本库。这样从源头上杜绝了环境配置漂移。

5.3 排查逻辑与方法论

加密相关的问题有个共同特点：报错信息可能出现在启动早期，但真正原因往往藏在配置格式里。我总结了一套自己的排查顺序。

第一步，先确认组件和配置版本匹配。dynamic-datasource 各版本对ENC()和Decrypt的支持程度不一样，很多问题升级版本后自然消失。

第二步，复现问题时脱离 Spring 容器，单独用 Crypto 工具做一次加密和解密往返。如果工具本身能解出明文，说明密钥和密文没有问题，问题在 Spring 装配层；如果工具都解不出来，问题大概率在密钥格式或密文完整性上。这个二分法能帮你快速砍掉一半的排查范围。

第三步，打开日志观察数据源初始化的完整时序。DynamicRoutingDataSource的初始化日志会显示每个数据源的关键信息，确认解密发生在连接池创建之前，还是连接池已经拿着密文去连接数据库。前者说明解密器生效，后者说明解密器没被正确注册。

第四步，Vault 场景下务必看 Vault 的 audit log。Vault 的审计日志会记录每次读取 secret 的时间和调用方身份，能直接告诉你到底有没有读到密钥、读的是哪个路径，比在应用里打日志定位问题高效得多。这也是我坚持推 Vault 的另一个原因：它自带一本账，出了事情有据可查。

结尾

写到这里，关于 dynamic-datasource 加密存储和 Vault 集成的完整思路就梳理清楚了。我个人在实际操作中最深的体会是：安全配置这件事，方案选型只占三成，剩下七成是日常习惯。比如私钥不要出现在命令行和 shell 历史里，配置文件模板从第一天就按加密形式写，Vault 的审计日志养成定期回看的习惯，这些不起眼的细节才是真正决定数据源密码安全等级的东西。

最后再分享一个小技巧：无论你选内置加密还是 Vault 集成，都建议给数据源密码加一道"定期轮换"的日历提醒。密码轮换可以不用很频繁，但一定要有，因为这个动作能逼着团队把加密和解密的流程真正跑通，而不是只在架构文档里存在。等哪天真出了安全事故，你会发现定期轮换过的系统，恢复起来比从未轮换过的系统从容得多。