你是不是也在某一天翻代码仓库的时候看到application.yml里明晃晃写着数据库地址、账号、密码我之前就在一个项目里遇到过这种场面当时第一反应是赶紧让数据库管理员改密码第二反应是这事没那么简单。配置文件一旦泄露连带着 dev、test、prod 好几套环境的账号密码全得重来一遍研发、运维、DBA 都得跟着加班波及面远比想象中大。Spring Boot 项目里application.yml和application.properties几乎是明文密码的重灾区。数据库连接、Redis 密码、短信服务密钥、对象存储的 AccessKey、第三方支付的私钥全都会不自觉地堆在里面。这篇博文围绕一个核心问题展开Spring Boot 配置文件中账号密码等敏感信息到底怎么做加解密才可靠我会把从事故反思、方案选型、Jasypt 落地实操、自定义 AES 解密器实现到日常运维排坑的完整过程记录下来适合正在做安全整改的开发者也适合刚接触 Spring Boot 但想了解配置安全机制的初学者。1. 先说说为什么配置里的明文密码是个大隐患1.1 一个真实事故引出的反思说一个我亲历过的场景。某次内部安全扫描发现代码仓库里一个老项目的配置文件被某个离职外包人员下载过里面正好包含生产数据库的账号密码。当时这只账号有三四年没轮换过权限还是 DBA 权限。虽然从访问记录看对方没有真的连库但那次之后整个团队花了两周时间处理潜在风险改密码、梳理权限、排查日志、检查审计记录所有联调环境都被迫中断。这事让我意识到一个点很多人觉得“内部仓库没事”“代码不公开就不会泄露”但现实中配置泄露的渠道太多了。代码仓库权限放开、云效或者 GitHub 被误设为公开、开发机被植入后门、同事把代码打包发到聊天工具里任何一条链路出问题配置文件都会跟着出去。而明文密码一旦出现在配置文件里它不是“可能泄露”而是“已经泄露”只是你还没发现而已。数据库密码这种凭据跟代码本身完全不是一个量级。代码泄露了可能被人抄走业务逻辑但密码泄露了别人是直接拿到你系统的钥匙。很多公司对线上数据库都舍不得开白名单安全组一配就是 0.0.0.0/0这种情况下再不加个密等于把家门钥匙放在门口脚垫下面顺手就能摸到。1.2 常见的“伪加密”做法为什么不靠谱我知道有些团队其实已经意识到了这个问题但解决方式很敷衍。我见过几种典型的“伪加密”每一种都有明显漏洞。第一种只改密码不加密。把数据库密码改得很长很复杂然后继续写在配置里。这其实只是提高了暴力破解的成本但泄露路径一点没堵住。密码再长只要别人拿到了配置就等于拿到了明文。第二种做字符串混淆。有人会把密码拆成几段在代码里拼接或者用 Base64 编码一下再放进去。Base64 根本不是加密它只是编码随便找个在线工具三秒钟就能解码。拆段拼接稍微好一点但代码里只要出现完整的拼接逻辑反编译、搜索一下也很快能还原。第三种把加密密钥也写在同一个配置文件里。我曾经在一个项目里看到有人自己写了个 AES 工具类加密逻辑没问题但密钥就放在application-security.yml的同级目录下注释还写着“生产环境记得换密钥”。这就好比保险箱做得再结实钥匙放在保险箱旁边的抽屉里这个保险箱一点意义都没有。第四种用 MD5、SHA 这类哈希算法处理配置密码。这类算法是单向的不可逆根本不适用于配置解密场景。Spring Boot 启动时要拿原始密码去连数据库如果配置里存的是哈希值应用根本无法还原出明文。凡是把配置加解密做成“不可逆”的方案都是没搞清楚需求就动手了。1.3 加解密方案需要满足的三条底线我后来在团队内部定了一套原则凡是往配置文件里写入敏感信息方案都必须满足三条底线。第一加密算法必须可逆。这是最基本的Spring Boot 解析完配置后需要把密文还原成明文去建立连接不能像用户密码一样存哈希。对称加密是首选AES 是当前最靠谱的算法密钥管理得当的情况下安全性足够。第二密钥必须和密文分离存放。无论用哪种方案加密后的密文放在配置文件里而主密钥只能放在环境变量、启动参数、密钥管理服务或专门的密钥文件里。如果密钥和密文放在同一个可被一起泄露的载体中加密就形同虚设。第三解密过程对业务代码透明。尽量做到 Spring Boot 启动时自动解密业务代码拿到的已经是明文不需要在每个Value注入的地方手动调解密方法。如果把解密散落到各业务代码里不仅容易遗漏还会让后续维护的人觉得非常混乱。这三条底线可以拿保险箱来类比明文密码是里面的现金配置文件是保险箱主密钥是钥匙。真正要防的是别人同时拿到保险箱和钥匙。所以方案设计的所有功夫其实都花在“把钥匙放到一个别人拿不到的地方”。2. 主流的敏感信息加解密方案对比完再做选择2.1 用现成工具库Jasypt 系是省心且稳妥的路径目前行业里最常用的解决方案是集成了一个叫 JasyptJava Simplified Encryption的 Spring Boot 扩展库。它的核心思路很简单你在配置文件里写ENC(密文)框架在启动阶段截获属性解析过程遇到ENC()开头的内容就用配置的主密钥解密然后把解密后的明文喂给 Spring 环境。我第一次用 Jasypt 的感觉是它把我最不想碰的边角问题都处理好了。比如算法的选择、随机盐salt和初始化向量IV的生成、加密器的线程安全性、跟 Spring Boot 属性源的衔接顺序这些细节自己实现很容易踩坑交给成熟的库反而稳妥。社区里用的人多遇到问题搜索一下基本都有答案。版本方面要注意不同的 Spring Boot 版本对应的 starter 版本不一样。Spring Boot 2.x 和 3.x 项目需要引入jasypt-spring-boot-starter的 3.0.x 版本比如 3.0.5它同时兼容了 Java 8 到 Java 17 的编译发行。老项目如果还在用 1.9.x 版本遇到 Spring Boot 2.6 之后的配置变化启动时经常报算法不匹配的问题这个后面我会详细讲。2.2 自己写 AES 解密可定制性强但要处理一堆细节有些团队不用 Jasypt原因是公司内部有统一的安全组件要求或者不想引入第三方依赖或者需要在解密前后做额外的审计、权限校验。这种场景下自己实现一套基于 AES 的配置解密器是完全可行的核心就是两个东西一个加解密工具类一个 Spring Boot 启动早期的环境后处理器EnvironmentPostProcessor。自己做的好处是可控性强。算法由你定密钥从哪个配置中心拉取由你定解密失败后的告警逻辑由你定还能顺便记录每一次解密操作日志。坏处也很明显细节非常多。类加载时机不对解密器在 Spring 容器启动前根本没被注册密钥配置文件处理不当又会引发新的泄露算法参数用错可能通不过安全审计。我自己的判断是如果团队有专门的安全中间件团队或者公司强制要求统一的安全 SDK那就值得自己写。如果是普通业务项目只是想快速把明文密码换掉直接上工具库更务实。这条路上最怕的就是“自己写了一个月最后发现踩的坑全是别人早就填好的”。2.3 交给配置中心统一托管适合微服务不适合单机还有一种更彻底的做法把配置全部迁到配置中心去管理敏感字段在配置中心里就做加密存储应用侧启动时通过 SDK 拉取配置。微服务架构下这种方案很常见因为配置中心本身就提供了权限管理、变更审计、版本回滚、灰度发布这些能力比本地配置文件强太多了。但这种方案不是没有代价。引入配置中心意味着你的部署链路多了一个强依赖单机小项目或者内网离线环境搭建和维护配置中心的成本可能比省下的那点事还高。而且配置中心本身也只是把“配置文件”搬了个家敏感字段该加密还是得加密并不是说上了配置中心就可以明文存储了。所以我通常建议业务系统已经上了微服务配套基础设施齐全那就用配置中心还在单体应用阶段引入外部配置中心反而会拖慢开发节奏不如老老实实做本地配置加密。2.4 选型决策表我把三类方案在几个关键维度上的表现整理成了表格方便你对着自己的项目情况做选择。维度Jasypt工具库自定义 AES 解密器配置中心托管上手成本低加依赖改配置即可高需要自己写代码和注册机制中取决于配置中心的运维成本可控性中支持自定义加密器高所有逻辑都在自己手里中依赖平台能力和权限体系安全性高算法规范、社区验证充分取决于自己的实现质量高通常配合平台审计使用适用场景单体应用、中小团队快速整改有统一安全组件要求的大型团队微服务体系完善、基础设施齐全密钥管理环境变量、启动参数、KMS自定义接入任意密钥源配置中心内置或外部 KMS运维复杂度低中需维护自研组件较高需维护配置中心集群3. 实操记录用 Jasypt 把数据库密码换成密文3.1 引入依赖并确认算法组合先看第一步在pom.xml里引入依赖dependency groupIdcom.github.ulisesbocchio/groupId artifactIdjasypt-spring-boot-starter/artifactId version3.0.5/version /dependency引入依赖后还要在application.yml里加上 Jasypt 的配置jasypt: encryptor: algorithm: PBEWITHHMACSHA512ANDAES_256 iv-generator-classname: org.jasypt.iv.RandomIvGenerator password: ${JASYPT_ENCRYPTOR_PASSWORD}这三个配置我必须解释一下因为很多人就是在这里随便复制结果后面解密对不上。algorithm是加密算法PBEWITHHMACSHA512ANDAES_256表示基于口令的加密底层用 SHA-512 做 HMAC 来派生密钥再用 AES-256 做实际加密这是 Jasypt 3.x 里比较推荐的强算法组合。如果老项目曾经用PBEWithMD5AndDES这种弱算法加密过新老配置混在一起时启动会报错或者解不出来这点要特别小心。iv-generator-classname配的是RandomIvGenerator它会为每次加密生成一个随机的初始化向量。为什么要随机因为如果初始化向量固定那么同样的明文每次加密结果都一样攻击者可以通过比对密文来反推信息。加了随机 IV同样的密码每次加密出来的密文都不同安全性更高。password就是主密钥我这里没有写死而是通过${JASYPT_ENCRYPTOR_PASSWORD}从环境变量里读取。这一条至关重要后面专门展开。3.2 用命令行生成第一批密文依赖配好后接下来要生成密文。可以用 Jasypt 自带的命令行工具也可以自己写个 main 方法。这里推荐直接下载jasypt-1.9.3.jar然后执行java -cp jasypt-1.9.3.jar org.jasypt.intf.cli.JasyptPBEStringEncryptionCLI \ input你的数据库密码 \ password你的主密钥 \ algorithmPBEWITHHMACSHA512ANDAES_256 \ ivGeneratorClassNameorg.jasypt.iv.RandomIvGenerator命令执行完后控制台会输出类似这样的结果----ENVIRONMENT----------------- Runtime: ... ----ARGUMENTS------------------- algorithmPBEWITHHMACSHA512ANDAES_256 input你的数据库密码 password你的主密钥 ... ----OUTPUT---------------------- ENC(2pV2A0uX0rZmn0hK0x5fMq...)把这串ENC(...)完整复制下来它就是配置里要填的密文。如果不想下载 jar 包也可以直接写个测试类在本地跑一段 Java 代码import org.jasypt.encryption.pbe.StandardPBEStringEncryptor; import org.jasypt.iv.RandomIvGenerator; public class EncryptMain { public static void main(String[] args) { StandardPBEStringEncryptor encryptor new StandardPBEStringEncryptor(); encryptor.setAlgorithm(PBEWITHHMACSHA512ANDAES_256); encryptor.setPassword(你的主密钥); encryptor.setIvGenerator(new RandomIvGenerator()); String encrypted encryptor.encrypt(你的数据库密码); System.out.println(ENC( encrypted )); } }这里要提醒一句生成的密文跟主密钥是绑定的密钥换掉之后密文就不能用了所以生成了密文之后第一件事就是把主密钥妥善保存到密码管理器里而不是放在聊天记录里。3.3 修改配置文件并验证启动拿到密文后把原来明文的密码替换成ENC(...)形式spring: datasource: url: jdbc:mysql://localhost:3306/app_db username: ENC(xxx) password: ENC(xxx)注意ENC(和密文之间不要有空格ENC(foo)这种形式最好因为解析器是按字符串前缀匹配的一旦中间多了空格或者换行匹配就会失败。同样的逻辑也适用于其他任何想加密的配置项Redis 密码、MongoDB 密码、短信平台密钥凡是要注入到 Spring 环境里的 String 配置都可以这么写。然后正常启动应用观察两件事。第一日志中会出现 Jasypt 相关的解析器初始化信息说明扩展被成功加载第二数据库连接能够建立成功说明配置文件里的密文被正确解密成了可用的明文。如果启动时报错先不要慌常见问题我在第 5 节会集中梳理。3.4 密钥怎么传才安全环境变量与启动参数的选择这一步是整个方案里最重要的环节但很多人会忽略。主密钥不能写在application.yml里哪怕你用${}占位符如果默认值直接填了真实密钥等于又把钥匙放回了保险箱旁边。我在团队里强制要求项目代码里不准出现真实密钥的痕迹哪怕注释里也不行。推荐的做法是用环境变量注入。比如在 Linux 服务器上通过 systemd 服务或者容器编排平台为应用设置环境变量export JASYPT_ENCRYPTOR_PASSWORD这里填真实主密钥然后启动应用配置里的${JASYPT_ENCRYPTOR_PASSWORD}就会被环境变量自动填充。这样做的核心价值在于代码仓库泄露了别人拿到的只是密文和占位符真实密钥仍然在服务器环境里。也可以用启动参数传递java -jar app.jar -Djasypt.encryptor.password这里填真实主密钥但启动参数会被进程列表、监控系统记录到泄露面比环境变量大一些所以能选环境变量就尽量选环境变量。再高一级的做法是对接 KMS 服务启动时先从密钥管理服务拉取主密钥再赋值给 Jasypt这个适合已经有密钥管理体系的公司普通项目用环境变量已经够了。3.5 多个环境多套密钥的落地配置实践里经常碰到这种情况dev、test、prod 三套环境各自的数据源密码不一样所以密文也不一样。最简单的做法是每个环境维护各自的application-dev.yml、application-prod.yml里面密文不同配合各自的JASYPT_ENCRYPTOR_PASSWORD环境变量。我见过有人试图只用一套密钥加密所有环境的密码结果开发环境密钥泄露导致生产环境密码也受影响这是非常不合理的做法。正确的安全边界是每个环境独立密钥独立密文。哪怕 dev 环境的配置全部泄露攻击者也不能拿 dev 的密钥解 prod 的密文。多环境落地时还可以顺带约定密钥的命名规范比如JASYPT_ENCRYPTOR_PASSWORD_DEV、JASYPT_ENCRYPTOR_PASSWORD_PROD在 CI/CD 流水线里按环境注入。这样研发本地启动时用本地密钥测试环境用测试密钥生产环境用生产密钥互不干扰。4. 更高阶自定义 AES 解密器的完整实现4.1 设计思路与整体流程如果你决定不走工具库路线下面这套自定义实现是经过实践验证的。整体思路分为三层。第一层是加密工具类负责把明文加密成密文、把密文还原成明文使用 AES/GCM/NoPadding 对称加密算法。第二层是环境后处理器EnvironmentPostProcessor它在 Spring Boot 启动的最早期介入扫描所有 PropertySource 里以ENC(开头的字符串调用工具类解密然后把解密后的配置放回到环境中。第三层是注册文件告诉 Spring Boot 启动时要加载这个后处理器。为什么用EnvironmentPostProcessor而不是写一个普通的 Bean 或者配置类因为配置解密这个动作必须发生在整个 Spring 容器创建之前。如果等到 Bean 初始化阶段才解密那些Value(${spring.datasource.password})注入早就完成了解密就晚了。EnvironmentPostProcessor是 Spring Boot 提供的一个扩展点时机非常靠前能保证在任何 Bean 读取配置以前环境里的敏感值就已经是明文。4.2 实现加解密工具类先写加密工具类使用 AES-GCM密钥通过 PBKDF2 从主密钥派生。下面这段代码可以直接用作参考import javax.crypto.Cipher; import javax.crypto.SecretKey; import javax.crypto.SecretKeyFactory; import javax.crypto.spec.GCMParameterSpec; import javax.crypto.spec.PBEKeySpec; import javax.crypto.spec.SecretKeySpec; import java.nio.charset.StandardCharsets; import java.security.SecureRandom; import java.util.Base64; public class AesUtil { private static final String ALGORITHM AES/GCM/NoPadding; private static final String KEY_ALGORITHM PBKDF2WithHmacSHA256; private static final int GCM_IV_LENGTH 12; private static final int GCM_TAG_LENGTH 128; private static final int SALT_LENGTH 16; private static final int ITERATION_COUNT 10000; private static final int KEY_LENGTH 256; public static String encrypt(String plaintext, char[] password) throws Exception { byte[] salt new byte[SALT_LENGTH]; new SecureRandom().nextBytes(salt); byte[] iv new byte[GCM_IV_LENGTH]; new SecureRandom().nextBytes(iv); SecretKey key deriveKey(password, salt); Cipher cipher Cipher.getInstance(ALGORITHM); cipher.init(Cipher.ENCRYPT_MODE, key, new GCMParameterSpec(GCM_TAG_LENGTH, iv)); byte[] encrypted cipher.doFinal(plaintext.getBytes(StandardCharsets.UTF_8)); byte[] combined new byte[salt.length iv.length encrypted.length]; System.arraycopy(salt, 0, combined, 0, salt.length); System.arraycopy(iv, 0, combined, salt.length, iv.length); System.arraycopy(encrypted, 0, combined, salt.length iv.length, encrypted.length); return Base64.getEncoder().encodeToString(combined); } public static String decrypt(String payload, char[] password) throws Exception { byte[] combined Base64.getDecoder().decode(payload); byte[] salt new byte[SALT_LENGTH]; byte[] iv new byte[GCM_IV_LENGTH]; byte[] encrypted new byte[combined.length - SALT_LENGTH - GCM_IV_LENGTH]; System.arraycopy(combined, 0, salt, 0, SALT_LENGTH); System.arraycopy(combined, SALT_LENGTH, iv, 0, GCM_IV_LENGTH); System.arraycopy(combined, SALT_LENGTH GCM_IV_LENGTH, encrypted, 0, encrypted.length); SecretKey key deriveKey(password, salt); Cipher cipher Cipher.getInstance(ALGORITHM); cipher.init(Cipher.DECRYPT_MODE, key, new GCMParameterSpec(GCM_TAG_LENGTH, iv)); return new String(cipher.doFinal(encrypted), StandardCharsets.UTF_8); } private static SecretKey deriveKey(char[] password, byte[] salt) throws Exception { PBEKeySpec spec new PBEKeySpec(password, salt, ITERATION_COUNT, KEY_LENGTH); SecretKeyFactory factory SecretKeyFactory.getInstance(KEY_ALGORITHM); SecretKey tmp factory.generateSecret(spec); return new SecretKeySpec(tmp.getEncoded(), AES); } }这里有几个参数我说一下为什么这么定。GCM 模式下的初始化向量推荐长度是 12 字节也就是 96 位这是 NIST 推荐的标准值短于这个值安全性会下降长于这个值有些 JDK 实现也不支持。GCM 认证标签 128 位是主流选择太长会带来额外开销128 位在当前安全水位下足够。PBKDF2 的迭代次数示例里写的是 10000但生产环境建议按 OWASP 的推荐拉高到几十万次甚至更多代价是启动时密钥派生会变慢这个要实测权衡。密文的存储格式是Base64(salt iv encrypted)解密时按长度切分格式简单也便于调试。4.3 通过环境后处理器接管配置解密有了工具类接下来写EnvironmentPostProcessorimport org.springframework.boot.SpringApplication; import org.springframework.boot.env.EnvironmentPostProcessor; import org.springframework.core.env.ConfigurableEnvironment; import org.springframework.core.env.EnumerablePropertySource; import org.springframework.core.env.MapPropertySource; import org.springframework.core.env.PropertySource; import java.util.HashMap; import java.util.Map; public class SecurePropertyEnvironmentPostProcessor implements EnvironmentPostProcessor { private static final String PREFIX ENC(; private static final String SUFFIX ); private static final String SECRET_KEY_PROPERTY app.config.encryptor.password; Override public void postProcessEnvironment(ConfigurableEnvironment environment, SpringApplication application) { String password environment.getProperty(SECRET_KEY_PROPERTY); if (password null || password.isEmpty()) { throw new IllegalStateException(缺少解密密钥配置: SECRET_KEY_PROPERTY); } for (PropertySource? propertySource : environment.getPropertySources()) { if (propertySource instanceof EnumerablePropertySource) { EnumerablePropertySource? source (EnumerablePropertySource?) propertySource; MapString, Object decrypted new HashMap(); for (String name : source.getPropertyNames()) { Object value source.getProperty(name); if (value instanceof String) { String strValue (String) value; if (strValue.startsWith(PREFIX) strValue.endsWith(SUFFIX)) { String raw strValue.substring(PREFIX.length(), strValue.length() - SUFFIX.length()); try { decrypted.put(name, AesUtil.decrypt(raw, password.toCharArray())); } catch (Exception e) { throw new IllegalStateException(解密配置项失败: name, e); } } } } if (!decrypted.isEmpty()) { environment.getPropertySources().addFirst( new MapPropertySource(decrypted- propertySource.getName(), decrypted)); } } } } }说明一下这段代码的行为。它遍历环境中所有可枚举的配置源找到ENC(...)开头的配置项解密后放入一个新的 MapPropertySource并插到所有配置源的最前面。这样 Spring 后续读取任何配置时都会优先命中解密后的值。主密钥从哪里来上面代码里是从app.config.encryptor.password这个配置项读取的。这个配置项本身可以通过环境变量覆盖也就是启动前设置APP_CONFIG_ENCRYPTOR_PASSWORDSpring Boot 的宽松绑定会自动映射过来。同样主密钥不能写在application.yml里作为默认值。4.4 注册方式与启动顺序注意事项写好后处理类还不算完Spring Boot 需要知道这个类的存在。在 Spring Boot 2.4 及以后版本推荐在src/main/resources/META-INF/spring/目录下创建文件org.springframework.boot.env.EnvironmentPostProcessor文件内容就是类的全限定名com.example.config.SecurePropertyEnvironmentPostProcessor以前老版本会在META-INF/spring.factories里配置org.springframework.boot.env.EnvironmentPostProcessorcom.example.config.SecurePropertyEnvironmentPostProcessor新项目不要再走spring.factories那条路了Spring Boot 3 已经逐步收紧对它的支持用新的独立注册文件更干净。这里有一个我在实践中踩过的坑EnvironmentPostProcessor里不要调用业务日志框架。因为这个后处理器初始化时间非常早日志框架可能还没完成配置你在里面打日志不但日志输出不了还可能引发类加载顺序问题。我当时排查了很久才发现是日志类提前初始化导致配置文件里的日志级别没有生效。如果需要记录解密过程建议把解密结果放到一个启动后的监听器里再输出或者干脆先在内存里记着等容器起来后统一打日志。4.5 自定义方案的边界与优化空间自己写的方案虽然灵活但有些地方要特别注意。AES-GCM 是认证加密模式密文如果被篡改解密时 GCM 的标签校验会直接失败抛异常这其实是好事能防止攻击者篡改配置。但这也意味着哪怕只是配置里多了一个字符、换行符被 IDE 自动格式化动了解密都会失败报错往往不直观。所以生产环境我建议在解密失败时抛出明确异常并且把配置项名称打印出来方便快速定位而不是笼统地报一个“解密失败”。如果以后要接配置中心或者 KMS也可以在EnvironmentPostProcessor里扩展。比如主密钥不让应用直接拿到而是通过 KMS 接口解密一次后再把解密后的口令传给deriveKey这样真正的密钥材料永远不会落盘到应用配置文件里。这个方向的优化空间很大但底层流程跟上面这套是共通的。5. 日常运维中的排坑记录与经验清单5.1 启动报错解密失败先查这四件事这类问题我处理过太多次基本每次启动时报“decryption error”或者“Encryption operation failed”都逃不出这几个原因我已经整理成一个速查表。排查项具体说明主密钥不一致加密时用的密钥和启动环境变量里配置的密钥不是同一个几乎占这类问题的一半算法不匹配密文是旧的PBEWithMD5AndDES算法生成的配置里却用了新的强算法或者反过来依赖版本不对用了 jasypt-spring-boot-starter 1.9.x 配 Spring Boot 2.6解析器没有被自动装配占位符格式错误ENC(前有空格、密文被 IDE 格式化拆行、括号不匹配等我在一个项目里遇到过最诡异的情况是配置在本地能解开部署到服务器就报错。查了很久最后发现是服务器的环境变量里有特殊字符被某个运维脚本在导出时转义坏了导致 Jasypt 拿到的密钥跟本地不一致。从那以后我养成了一个习惯先写一个单独的启动检查端点在应用启动完成后打印“当前使用的密钥指纹”和“解密后的配置项列表”但不打印明文值。这样排查问题的时候先对比密钥指纹一分钟就能判断是不是密钥不一致。5.2 密码里带特殊字符导致 YAML 解析异常还有一个高发问题数据库密码或者密钥本身带#、、:、{}这类特殊字符。YAML 语法里这些字符有特殊含义直接写明文时经常导致解析失败或者值被截断。举个例子如果密码是Pssw0rd:{#safe}直接写在application.yml里YAML 解析器会把:后面的内容当 map 处理导致配置结构错乱。用 Jasypt 之后密文是字母数字和、/、的 Base64 组合基本不会触发 YAML 解析问题这是加密方案额外带来的一个好处。但如果密钥本身包含特殊字符而且是通过环境变量传递就要注意转义问题。Shell 里设置环境变量时应该用单引号而不是双引号包裹防止$被 shell 解析export JASYPT_ENCRYPTOR_PASSWORDAb#$cd123另外无论是明文还是密文凡是配置项的值里可能出现特殊字符我都习惯给 YAML 里的值加上单引号或双引号包裹避免踩坑。5.3 日志打印和健康检查泄露敏感信息的防护配置加密只解决了“静态存储”问题运行时的泄露路径同样不能忽视。最常见的是两类日志打印和 Spring Boot Actuator 端点。SQL 日志打印明文密码参数这种事情我在生产环境见过不止一次。某些 ORM 框架把执行的 SQL 完整打出来如果 SQL 里恰好拼接了带密码的查询条件或者连接池初始化时打印了带密码的 JDBC URL那密码就通过日志管道泄出去了。解决思路是统一调整 SQL 日志格式对参数部分打码连接池的初始化日志通过日志级别控制或日志过滤器过滤掉包含password的字符串。Actuator 端点更隐蔽。/actuator/configprops会把带有ConfigurationProperties的配置项全部暴露出来如果数据库密码恰好被绑定到某个配置类里这个端点就会把明文值返回。我建议线上环境把configprops、env这类敏感端点关掉或者至少加一层认证。配合配置加密一起做才能形成一个完整的闭环。5.4 密钥轮换与批量密文迁移流程密钥不是永久的。员工离职、疑似泄露、合规审计都可能触发密钥轮换。轮换流程的核心是先让新密钥和旧密钥在过渡期内同时可用再把配置全部更新成新密文最后下线旧密钥。由于 Jasypt 启动时只认一个主密钥所以不能真正做到新旧同时可用要么直接把所有配置切换成新密文再重启要么写一个批量迁移工具。批量迁移的思路很简单用旧密钥解密旧配置用新密钥重新加密然后写回文件。我以前写过一个迁移脚本流程是扫描配置文件里所有ENC(...)字段用AesUtil.decrypt配合旧密钥还原出明文再用AesUtil.encrypt配合新密钥生成新密文按原路径写回。执行这一步之前一定先备份原配置文件。我见过有人在生产服务器上直接跑批量脚本正则没写对把整个配置文件替换得面目全非应用直接起不来最后靠备份才恢复。另外迁移完之后要立刻验证启动不要隔一天再重启否则排查问题时新旧环境变量互相干扰很难定位是哪个环节出了问题。6. 关于密钥安全还想再多说几句我做了这么多年配置安全和权限整改最深的体会是加密其实不是技术难点难的是习惯和流程。很多团队花半天时间把密文写进了配置文件但主密钥还是放在一个共享文档里或者同事之间私聊发来发去这样的加密意义大打折扣。真正稳妥的做法是把密钥当成跟数据库密码同等重要的资产来管理。用专门的密码管理器保存访问要有审计记录轮换要有固定周期离职员工一律回收相关权限。我也建议每个项目组都约定一个“配置泄露应急清单”一旦发现密钥泄露按清单快速响应禁用旧密钥、切换备用密钥、检查日志、评估影响范围。有了这套机制加密方案才能从上线的第一天起就持续有效而不是变成一个走形式的安全项。最后再分享一个小技巧每次迁移完密钥或者改完配置文件都手动跑一次应用启动验证确认所有的密文都能正确解开。这个动作看着简单但能帮你避开百分之八十的“部署后启动失败”问题。配置安全这件事慢一点、稳一点永远比追求速度值得。 
长河君 · 2026/10/21 9:04:41 · 阅读 1.2k Spring Boot 配置文件敏感信息加密：从明文密码到 Jasypt 与 AES 实战
你是不是也在某一天翻代码仓库的时候看到application.yml里明晃晃写着数据库地址、账号、密码我之前就在一个项目里遇到过这种场面当时第一反应是赶紧让数据库管理员改密码第二反应是这事没那么简单。配置文件一旦泄露连带着 dev、test、prod 好几套环境的账号密码全得重来一遍研发、运维、DBA 都得跟着加班波及面远比想象中大。Spring Boot 项目里application.yml和application.properties几乎是明文密码的重灾区。数据库连接、Redis 密码、短信服务密钥、对象存储的 AccessKey、第三方支付的私钥全都会不自觉地堆在里面。这篇博文围绕一个核心问题展开Spring Boot 配置文件中账号密码等敏感信息到底怎么做加解密才可靠我会把从事故反思、方案选型、Jasypt 落地实操、自定义 AES 解密器实现到日常运维排坑的完整过程记录下来适合正在做安全整改的开发者也适合刚接触 Spring Boot 但想了解配置安全机制的初学者。1. 先说说为什么配置里的明文密码是个大隐患1.1 一个真实事故引出的反思说一个我亲历过的场景。某次内部安全扫描发现代码仓库里一个老项目的配置文件被某个离职外包人员下载过里面正好包含生产数据库的账号密码。当时这只账号有三四年没轮换过权限还是 DBA 权限。虽然从访问记录看对方没有真的连库但那次之后整个团队花了两周时间处理潜在风险改密码、梳理权限、排查日志、检查审计记录所有联调环境都被迫中断。这事让我意识到一个点很多人觉得“内部仓库没事”“代码不公开就不会泄露”但现实中配置泄露的渠道太多了。代码仓库权限放开、云效或者 GitHub 被误设为公开、开发机被植入后门、同事把代码打包发到聊天工具里任何一条链路出问题配置文件都会跟着出去。而明文密码一旦出现在配置文件里它不是“可能泄露”而是“已经泄露”只是你还没发现而已。数据库密码这种凭据跟代码本身完全不是一个量级。代码泄露了可能被人抄走业务逻辑但密码泄露了别人是直接拿到你系统的钥匙。很多公司对线上数据库都舍不得开白名单安全组一配就是 0.0.0.0/0这种情况下再不加个密等于把家门钥匙放在门口脚垫下面顺手就能摸到。1.2 常见的“伪加密”做法为什么不靠谱我知道有些团队其实已经意识到了这个问题但解决方式很敷衍。我见过几种典型的“伪加密”每一种都有明显漏洞。第一种只改密码不加密。把数据库密码改得很长很复杂然后继续写在配置里。这其实只是提高了暴力破解的成本但泄露路径一点没堵住。密码再长只要别人拿到了配置就等于拿到了明文。第二种做字符串混淆。有人会把密码拆成几段在代码里拼接或者用 Base64 编码一下再放进去。Base64 根本不是加密它只是编码随便找个在线工具三秒钟就能解码。拆段拼接稍微好一点但代码里只要出现完整的拼接逻辑反编译、搜索一下也很快能还原。第三种把加密密钥也写在同一个配置文件里。我曾经在一个项目里看到有人自己写了个 AES 工具类加密逻辑没问题但密钥就放在application-security.yml的同级目录下注释还写着“生产环境记得换密钥”。这就好比保险箱做得再结实钥匙放在保险箱旁边的抽屉里这个保险箱一点意义都没有。第四种用 MD5、SHA 这类哈希算法处理配置密码。这类算法是单向的不可逆根本不适用于配置解密场景。Spring Boot 启动时要拿原始密码去连数据库如果配置里存的是哈希值应用根本无法还原出明文。凡是把配置加解密做成“不可逆”的方案都是没搞清楚需求就动手了。1.3 加解密方案需要满足的三条底线我后来在团队内部定了一套原则凡是往配置文件里写入敏感信息方案都必须满足三条底线。第一加密算法必须可逆。这是最基本的Spring Boot 解析完配置后需要把密文还原成明文去建立连接不能像用户密码一样存哈希。对称加密是首选AES 是当前最靠谱的算法密钥管理得当的情况下安全性足够。第二密钥必须和密文分离存放。无论用哪种方案加密后的密文放在配置文件里而主密钥只能放在环境变量、启动参数、密钥管理服务或专门的密钥文件里。如果密钥和密文放在同一个可被一起泄露的载体中加密就形同虚设。第三解密过程对业务代码透明。尽量做到 Spring Boot 启动时自动解密业务代码拿到的已经是明文不需要在每个Value注入的地方手动调解密方法。如果把解密散落到各业务代码里不仅容易遗漏还会让后续维护的人觉得非常混乱。这三条底线可以拿保险箱来类比明文密码是里面的现金配置文件是保险箱主密钥是钥匙。真正要防的是别人同时拿到保险箱和钥匙。所以方案设计的所有功夫其实都花在“把钥匙放到一个别人拿不到的地方”。2. 主流的敏感信息加解密方案对比完再做选择2.1 用现成工具库Jasypt 系是省心且稳妥的路径目前行业里最常用的解决方案是集成了一个叫 JasyptJava Simplified Encryption的 Spring Boot 扩展库。它的核心思路很简单你在配置文件里写ENC(密文)框架在启动阶段截获属性解析过程遇到ENC()开头的内容就用配置的主密钥解密然后把解密后的明文喂给 Spring 环境。我第一次用 Jasypt 的感觉是它把我最不想碰的边角问题都处理好了。比如算法的选择、随机盐salt和初始化向量IV的生成、加密器的线程安全性、跟 Spring Boot 属性源的衔接顺序这些细节自己实现很容易踩坑交给成熟的库反而稳妥。社区里用的人多遇到问题搜索一下基本都有答案。版本方面要注意不同的 Spring Boot 版本对应的 starter 版本不一样。Spring Boot 2.x 和 3.x 项目需要引入jasypt-spring-boot-starter的 3.0.x 版本比如 3.0.5它同时兼容了 Java 8 到 Java 17 的编译发行。老项目如果还在用 1.9.x 版本遇到 Spring Boot 2.6 之后的配置变化启动时经常报算法不匹配的问题这个后面我会详细讲。2.2 自己写 AES 解密可定制性强但要处理一堆细节有些团队不用 Jasypt原因是公司内部有统一的安全组件要求或者不想引入第三方依赖或者需要在解密前后做额外的审计、权限校验。这种场景下自己实现一套基于 AES 的配置解密器是完全可行的核心就是两个东西一个加解密工具类一个 Spring Boot 启动早期的环境后处理器EnvironmentPostProcessor。自己做的好处是可控性强。算法由你定密钥从哪个配置中心拉取由你定解密失败后的告警逻辑由你定还能顺便记录每一次解密操作日志。坏处也很明显细节非常多。类加载时机不对解密器在 Spring 容器启动前根本没被注册密钥配置文件处理不当又会引发新的泄露算法参数用错可能通不过安全审计。我自己的判断是如果团队有专门的安全中间件团队或者公司强制要求统一的安全 SDK那就值得自己写。如果是普通业务项目只是想快速把明文密码换掉直接上工具库更务实。这条路上最怕的就是“自己写了一个月最后发现踩的坑全是别人早就填好的”。2.3 交给配置中心统一托管适合微服务不适合单机还有一种更彻底的做法把配置全部迁到配置中心去管理敏感字段在配置中心里就做加密存储应用侧启动时通过 SDK 拉取配置。微服务架构下这种方案很常见因为配置中心本身就提供了权限管理、变更审计、版本回滚、灰度发布这些能力比本地配置文件强太多了。但这种方案不是没有代价。引入配置中心意味着你的部署链路多了一个强依赖单机小项目或者内网离线环境搭建和维护配置中心的成本可能比省下的那点事还高。而且配置中心本身也只是把“配置文件”搬了个家敏感字段该加密还是得加密并不是说上了配置中心就可以明文存储了。所以我通常建议业务系统已经上了微服务配套基础设施齐全那就用配置中心还在单体应用阶段引入外部配置中心反而会拖慢开发节奏不如老老实实做本地配置加密。2.4 选型决策表我把三类方案在几个关键维度上的表现整理成了表格方便你对着自己的项目情况做选择。维度Jasypt工具库自定义 AES 解密器配置中心托管上手成本低加依赖改配置即可高需要自己写代码和注册机制中取决于配置中心的运维成本可控性中支持自定义加密器高所有逻辑都在自己手里中依赖平台能力和权限体系安全性高算法规范、社区验证充分取决于自己的实现质量高通常配合平台审计使用适用场景单体应用、中小团队快速整改有统一安全组件要求的大型团队微服务体系完善、基础设施齐全密钥管理环境变量、启动参数、KMS自定义接入任意密钥源配置中心内置或外部 KMS运维复杂度低中需维护自研组件较高需维护配置中心集群3. 实操记录用 Jasypt 把数据库密码换成密文3.1 引入依赖并确认算法组合先看第一步在pom.xml里引入依赖dependency groupIdcom.github.ulisesbocchio/groupId artifactIdjasypt-spring-boot-starter/artifactId version3.0.5/version /dependency引入依赖后还要在application.yml里加上 Jasypt 的配置jasypt: encryptor: algorithm: PBEWITHHMACSHA512ANDAES_256 iv-generator-classname: org.jasypt.iv.RandomIvGenerator password: ${JASYPT_ENCRYPTOR_PASSWORD}这三个配置我必须解释一下因为很多人就是在这里随便复制结果后面解密对不上。algorithm是加密算法PBEWITHHMACSHA512ANDAES_256表示基于口令的加密底层用 SHA-512 做 HMAC 来派生密钥再用 AES-256 做实际加密这是 Jasypt 3.x 里比较推荐的强算法组合。如果老项目曾经用PBEWithMD5AndDES这种弱算法加密过新老配置混在一起时启动会报错或者解不出来这点要特别小心。iv-generator-classname配的是RandomIvGenerator它会为每次加密生成一个随机的初始化向量。为什么要随机因为如果初始化向量固定那么同样的明文每次加密结果都一样攻击者可以通过比对密文来反推信息。加了随机 IV同样的密码每次加密出来的密文都不同安全性更高。password就是主密钥我这里没有写死而是通过${JASYPT_ENCRYPTOR_PASSWORD}从环境变量里读取。这一条至关重要后面专门展开。3.2 用命令行生成第一批密文依赖配好后接下来要生成密文。可以用 Jasypt 自带的命令行工具也可以自己写个 main 方法。这里推荐直接下载jasypt-1.9.3.jar然后执行java -cp jasypt-1.9.3.jar org.jasypt.intf.cli.JasyptPBEStringEncryptionCLI \ input你的数据库密码 \ password你的主密钥 \ algorithmPBEWITHHMACSHA512ANDAES_256 \ ivGeneratorClassNameorg.jasypt.iv.RandomIvGenerator命令执行完后控制台会输出类似这样的结果----ENVIRONMENT----------------- Runtime: ... ----ARGUMENTS------------------- algorithmPBEWITHHMACSHA512ANDAES_256 input你的数据库密码 password你的主密钥 ... ----OUTPUT---------------------- ENC(2pV2A0uX0rZmn0hK0x5fMq...)把这串ENC(...)完整复制下来它就是配置里要填的密文。如果不想下载 jar 包也可以直接写个测试类在本地跑一段 Java 代码import org.jasypt.encryption.pbe.StandardPBEStringEncryptor; import org.jasypt.iv.RandomIvGenerator; public class EncryptMain { public static void main(String[] args) { StandardPBEStringEncryptor encryptor new StandardPBEStringEncryptor(); encryptor.setAlgorithm(PBEWITHHMACSHA512ANDAES_256); encryptor.setPassword(你的主密钥); encryptor.setIvGenerator(new RandomIvGenerator()); String encrypted encryptor.encrypt(你的数据库密码); System.out.println(ENC( encrypted )); } }这里要提醒一句生成的密文跟主密钥是绑定的密钥换掉之后密文就不能用了所以生成了密文之后第一件事就是把主密钥妥善保存到密码管理器里而不是放在聊天记录里。3.3 修改配置文件并验证启动拿到密文后把原来明文的密码替换成ENC(...)形式spring: datasource: url: jdbc:mysql://localhost:3306/app_db username: ENC(xxx) password: ENC(xxx)注意ENC(和密文之间不要有空格ENC(foo)这种形式最好因为解析器是按字符串前缀匹配的一旦中间多了空格或者换行匹配就会失败。同样的逻辑也适用于其他任何想加密的配置项Redis 密码、MongoDB 密码、短信平台密钥凡是要注入到 Spring 环境里的 String 配置都可以这么写。然后正常启动应用观察两件事。第一日志中会出现 Jasypt 相关的解析器初始化信息说明扩展被成功加载第二数据库连接能够建立成功说明配置文件里的密文被正确解密成了可用的明文。如果启动时报错先不要慌常见问题我在第 5 节会集中梳理。3.4 密钥怎么传才安全环境变量与启动参数的选择这一步是整个方案里最重要的环节但很多人会忽略。主密钥不能写在application.yml里哪怕你用${}占位符如果默认值直接填了真实密钥等于又把钥匙放回了保险箱旁边。我在团队里强制要求项目代码里不准出现真实密钥的痕迹哪怕注释里也不行。推荐的做法是用环境变量注入。比如在 Linux 服务器上通过 systemd 服务或者容器编排平台为应用设置环境变量export JASYPT_ENCRYPTOR_PASSWORD这里填真实主密钥然后启动应用配置里的${JASYPT_ENCRYPTOR_PASSWORD}就会被环境变量自动填充。这样做的核心价值在于代码仓库泄露了别人拿到的只是密文和占位符真实密钥仍然在服务器环境里。也可以用启动参数传递java -jar app.jar -Djasypt.encryptor.password这里填真实主密钥但启动参数会被进程列表、监控系统记录到泄露面比环境变量大一些所以能选环境变量就尽量选环境变量。再高一级的做法是对接 KMS 服务启动时先从密钥管理服务拉取主密钥再赋值给 Jasypt这个适合已经有密钥管理体系的公司普通项目用环境变量已经够了。3.5 多个环境多套密钥的落地配置实践里经常碰到这种情况dev、test、prod 三套环境各自的数据源密码不一样所以密文也不一样。最简单的做法是每个环境维护各自的application-dev.yml、application-prod.yml里面密文不同配合各自的JASYPT_ENCRYPTOR_PASSWORD环境变量。我见过有人试图只用一套密钥加密所有环境的密码结果开发环境密钥泄露导致生产环境密码也受影响这是非常不合理的做法。正确的安全边界是每个环境独立密钥独立密文。哪怕 dev 环境的配置全部泄露攻击者也不能拿 dev 的密钥解 prod 的密文。多环境落地时还可以顺带约定密钥的命名规范比如JASYPT_ENCRYPTOR_PASSWORD_DEV、JASYPT_ENCRYPTOR_PASSWORD_PROD在 CI/CD 流水线里按环境注入。这样研发本地启动时用本地密钥测试环境用测试密钥生产环境用生产密钥互不干扰。4. 更高阶自定义 AES 解密器的完整实现4.1 设计思路与整体流程如果你决定不走工具库路线下面这套自定义实现是经过实践验证的。整体思路分为三层。第一层是加密工具类负责把明文加密成密文、把密文还原成明文使用 AES/GCM/NoPadding 对称加密算法。第二层是环境后处理器EnvironmentPostProcessor它在 Spring Boot 启动的最早期介入扫描所有 PropertySource 里以ENC(开头的字符串调用工具类解密然后把解密后的配置放回到环境中。第三层是注册文件告诉 Spring Boot 启动时要加载这个后处理器。为什么用EnvironmentPostProcessor而不是写一个普通的 Bean 或者配置类因为配置解密这个动作必须发生在整个 Spring 容器创建之前。如果等到 Bean 初始化阶段才解密那些Value(${spring.datasource.password})注入早就完成了解密就晚了。EnvironmentPostProcessor是 Spring Boot 提供的一个扩展点时机非常靠前能保证在任何 Bean 读取配置以前环境里的敏感值就已经是明文。4.2 实现加解密工具类先写加密工具类使用 AES-GCM密钥通过 PBKDF2 从主密钥派生。下面这段代码可以直接用作参考import javax.crypto.Cipher; import javax.crypto.SecretKey; import javax.crypto.SecretKeyFactory; import javax.crypto.spec.GCMParameterSpec; import javax.crypto.spec.PBEKeySpec; import javax.crypto.spec.SecretKeySpec; import java.nio.charset.StandardCharsets; import java.security.SecureRandom; import java.util.Base64; public class AesUtil { private static final String ALGORITHM AES/GCM/NoPadding; private static final String KEY_ALGORITHM PBKDF2WithHmacSHA256; private static final int GCM_IV_LENGTH 12; private static final int GCM_TAG_LENGTH 128; private static final int SALT_LENGTH 16; private static final int ITERATION_COUNT 10000; private static final int KEY_LENGTH 256; public static String encrypt(String plaintext, char[] password) throws Exception { byte[] salt new byte[SALT_LENGTH]; new SecureRandom().nextBytes(salt); byte[] iv new byte[GCM_IV_LENGTH]; new SecureRandom().nextBytes(iv); SecretKey key deriveKey(password, salt); Cipher cipher Cipher.getInstance(ALGORITHM); cipher.init(Cipher.ENCRYPT_MODE, key, new GCMParameterSpec(GCM_TAG_LENGTH, iv)); byte[] encrypted cipher.doFinal(plaintext.getBytes(StandardCharsets.UTF_8)); byte[] combined new byte[salt.length iv.length encrypted.length]; System.arraycopy(salt, 0, combined, 0, salt.length); System.arraycopy(iv, 0, combined, salt.length, iv.length); System.arraycopy(encrypted, 0, combined, salt.length iv.length, encrypted.length); return Base64.getEncoder().encodeToString(combined); } public static String decrypt(String payload, char[] password) throws Exception { byte[] combined Base64.getDecoder().decode(payload); byte[] salt new byte[SALT_LENGTH]; byte[] iv new byte[GCM_IV_LENGTH]; byte[] encrypted new byte[combined.length - SALT_LENGTH - GCM_IV_LENGTH]; System.arraycopy(combined, 0, salt, 0, SALT_LENGTH); System.arraycopy(combined, SALT_LENGTH, iv, 0, GCM_IV_LENGTH); System.arraycopy(combined, SALT_LENGTH GCM_IV_LENGTH, encrypted, 0, encrypted.length); SecretKey key deriveKey(password, salt); Cipher cipher Cipher.getInstance(ALGORITHM); cipher.init(Cipher.DECRYPT_MODE, key, new GCMParameterSpec(GCM_TAG_LENGTH, iv)); return new String(cipher.doFinal(encrypted), StandardCharsets.UTF_8); } private static SecretKey deriveKey(char[] password, byte[] salt) throws Exception { PBEKeySpec spec new PBEKeySpec(password, salt, ITERATION_COUNT, KEY_LENGTH); SecretKeyFactory factory SecretKeyFactory.getInstance(KEY_ALGORITHM); SecretKey tmp factory.generateSecret(spec); return new SecretKeySpec(tmp.getEncoded(), AES); } }这里有几个参数我说一下为什么这么定。GCM 模式下的初始化向量推荐长度是 12 字节也就是 96 位这是 NIST 推荐的标准值短于这个值安全性会下降长于这个值有些 JDK 实现也不支持。GCM 认证标签 128 位是主流选择太长会带来额外开销128 位在当前安全水位下足够。PBKDF2 的迭代次数示例里写的是 10000但生产环境建议按 OWASP 的推荐拉高到几十万次甚至更多代价是启动时密钥派生会变慢这个要实测权衡。密文的存储格式是Base64(salt iv encrypted)解密时按长度切分格式简单也便于调试。4.3 通过环境后处理器接管配置解密有了工具类接下来写EnvironmentPostProcessorimport org.springframework.boot.SpringApplication; import org.springframework.boot.env.EnvironmentPostProcessor; import org.springframework.core.env.ConfigurableEnvironment; import org.springframework.core.env.EnumerablePropertySource; import org.springframework.core.env.MapPropertySource; import org.springframework.core.env.PropertySource; import java.util.HashMap; import java.util.Map; public class SecurePropertyEnvironmentPostProcessor implements EnvironmentPostProcessor { private static final String PREFIX ENC(; private static final String SUFFIX ); private static final String SECRET_KEY_PROPERTY app.config.encryptor.password; Override public void postProcessEnvironment(ConfigurableEnvironment environment, SpringApplication application) { String password environment.getProperty(SECRET_KEY_PROPERTY); if (password null || password.isEmpty()) { throw new IllegalStateException(缺少解密密钥配置: SECRET_KEY_PROPERTY); } for (PropertySource? propertySource : environment.getPropertySources()) { if (propertySource instanceof EnumerablePropertySource) { EnumerablePropertySource? source (EnumerablePropertySource?) propertySource; MapString, Object decrypted new HashMap(); for (String name : source.getPropertyNames()) { Object value source.getProperty(name); if (value instanceof String) { String strValue (String) value; if (strValue.startsWith(PREFIX) strValue.endsWith(SUFFIX)) { String raw strValue.substring(PREFIX.length(), strValue.length() - SUFFIX.length()); try { decrypted.put(name, AesUtil.decrypt(raw, password.toCharArray())); } catch (Exception e) { throw new IllegalStateException(解密配置项失败: name, e); } } } } if (!decrypted.isEmpty()) { environment.getPropertySources().addFirst( new MapPropertySource(decrypted- propertySource.getName(), decrypted)); } } } } }说明一下这段代码的行为。它遍历环境中所有可枚举的配置源找到ENC(...)开头的配置项解密后放入一个新的 MapPropertySource并插到所有配置源的最前面。这样 Spring 后续读取任何配置时都会优先命中解密后的值。主密钥从哪里来上面代码里是从app.config.encryptor.password这个配置项读取的。这个配置项本身可以通过环境变量覆盖也就是启动前设置APP_CONFIG_ENCRYPTOR_PASSWORDSpring Boot 的宽松绑定会自动映射过来。同样主密钥不能写在application.yml里作为默认值。4.4 注册方式与启动顺序注意事项写好后处理类还不算完Spring Boot 需要知道这个类的存在。在 Spring Boot 2.4 及以后版本推荐在src/main/resources/META-INF/spring/目录下创建文件org.springframework.boot.env.EnvironmentPostProcessor文件内容就是类的全限定名com.example.config.SecurePropertyEnvironmentPostProcessor以前老版本会在META-INF/spring.factories里配置org.springframework.boot.env.EnvironmentPostProcessorcom.example.config.SecurePropertyEnvironmentPostProcessor新项目不要再走spring.factories那条路了Spring Boot 3 已经逐步收紧对它的支持用新的独立注册文件更干净。这里有一个我在实践中踩过的坑EnvironmentPostProcessor里不要调用业务日志框架。因为这个后处理器初始化时间非常早日志框架可能还没完成配置你在里面打日志不但日志输出不了还可能引发类加载顺序问题。我当时排查了很久才发现是日志类提前初始化导致配置文件里的日志级别没有生效。如果需要记录解密过程建议把解密结果放到一个启动后的监听器里再输出或者干脆先在内存里记着等容器起来后统一打日志。4.5 自定义方案的边界与优化空间自己写的方案虽然灵活但有些地方要特别注意。AES-GCM 是认证加密模式密文如果被篡改解密时 GCM 的标签校验会直接失败抛异常这其实是好事能防止攻击者篡改配置。但这也意味着哪怕只是配置里多了一个字符、换行符被 IDE 自动格式化动了解密都会失败报错往往不直观。所以生产环境我建议在解密失败时抛出明确异常并且把配置项名称打印出来方便快速定位而不是笼统地报一个“解密失败”。如果以后要接配置中心或者 KMS也可以在EnvironmentPostProcessor里扩展。比如主密钥不让应用直接拿到而是通过 KMS 接口解密一次后再把解密后的口令传给deriveKey这样真正的密钥材料永远不会落盘到应用配置文件里。这个方向的优化空间很大但底层流程跟上面这套是共通的。5. 日常运维中的排坑记录与经验清单5.1 启动报错解密失败先查这四件事这类问题我处理过太多次基本每次启动时报“decryption error”或者“Encryption operation failed”都逃不出这几个原因我已经整理成一个速查表。排查项具体说明主密钥不一致加密时用的密钥和启动环境变量里配置的密钥不是同一个几乎占这类问题的一半算法不匹配密文是旧的PBEWithMD5AndDES算法生成的配置里却用了新的强算法或者反过来依赖版本不对用了 jasypt-spring-boot-starter 1.9.x 配 Spring Boot 2.6解析器没有被自动装配占位符格式错误ENC(前有空格、密文被 IDE 格式化拆行、括号不匹配等我在一个项目里遇到过最诡异的情况是配置在本地能解开部署到服务器就报错。查了很久最后发现是服务器的环境变量里有特殊字符被某个运维脚本在导出时转义坏了导致 Jasypt 拿到的密钥跟本地不一致。从那以后我养成了一个习惯先写一个单独的启动检查端点在应用启动完成后打印“当前使用的密钥指纹”和“解密后的配置项列表”但不打印明文值。这样排查问题的时候先对比密钥指纹一分钟就能判断是不是密钥不一致。5.2 密码里带特殊字符导致 YAML 解析异常还有一个高发问题数据库密码或者密钥本身带#、、:、{}这类特殊字符。YAML 语法里这些字符有特殊含义直接写明文时经常导致解析失败或者值被截断。举个例子如果密码是Pssw0rd:{#safe}直接写在application.yml里YAML 解析器会把:后面的内容当 map 处理导致配置结构错乱。用 Jasypt 之后密文是字母数字和、/、的 Base64 组合基本不会触发 YAML 解析问题这是加密方案额外带来的一个好处。但如果密钥本身包含特殊字符而且是通过环境变量传递就要注意转义问题。Shell 里设置环境变量时应该用单引号而不是双引号包裹防止$被 shell 解析export JASYPT_ENCRYPTOR_PASSWORDAb#$cd123另外无论是明文还是密文凡是配置项的值里可能出现特殊字符我都习惯给 YAML 里的值加上单引号或双引号包裹避免踩坑。5.3 日志打印和健康检查泄露敏感信息的防护配置加密只解决了“静态存储”问题运行时的泄露路径同样不能忽视。最常见的是两类日志打印和 Spring Boot Actuator 端点。SQL 日志打印明文密码参数这种事情我在生产环境见过不止一次。某些 ORM 框架把执行的 SQL 完整打出来如果 SQL 里恰好拼接了带密码的查询条件或者连接池初始化时打印了带密码的 JDBC URL那密码就通过日志管道泄出去了。解决思路是统一调整 SQL 日志格式对参数部分打码连接池的初始化日志通过日志级别控制或日志过滤器过滤掉包含password的字符串。Actuator 端点更隐蔽。/actuator/configprops会把带有ConfigurationProperties的配置项全部暴露出来如果数据库密码恰好被绑定到某个配置类里这个端点就会把明文值返回。我建议线上环境把configprops、env这类敏感端点关掉或者至少加一层认证。配合配置加密一起做才能形成一个完整的闭环。5.4 密钥轮换与批量密文迁移流程密钥不是永久的。员工离职、疑似泄露、合规审计都可能触发密钥轮换。轮换流程的核心是先让新密钥和旧密钥在过渡期内同时可用再把配置全部更新成新密文最后下线旧密钥。由于 Jasypt 启动时只认一个主密钥所以不能真正做到新旧同时可用要么直接把所有配置切换成新密文再重启要么写一个批量迁移工具。批量迁移的思路很简单用旧密钥解密旧配置用新密钥重新加密然后写回文件。我以前写过一个迁移脚本流程是扫描配置文件里所有ENC(...)字段用AesUtil.decrypt配合旧密钥还原出明文再用AesUtil.encrypt配合新密钥生成新密文按原路径写回。执行这一步之前一定先备份原配置文件。我见过有人在生产服务器上直接跑批量脚本正则没写对把整个配置文件替换得面目全非应用直接起不来最后靠备份才恢复。另外迁移完之后要立刻验证启动不要隔一天再重启否则排查问题时新旧环境变量互相干扰很难定位是哪个环节出了问题。6. 关于密钥安全还想再多说几句我做了这么多年配置安全和权限整改最深的体会是加密其实不是技术难点难的是习惯和流程。很多团队花半天时间把密文写进了配置文件但主密钥还是放在一个共享文档里或者同事之间私聊发来发去这样的加密意义大打折扣。真正稳妥的做法是把密钥当成跟数据库密码同等重要的资产来管理。用专门的密码管理器保存访问要有审计记录轮换要有固定周期离职员工一律回收相关权限。我也建议每个项目组都约定一个“配置泄露应急清单”一旦发现密钥泄露按清单快速响应禁用旧密钥、切换备用密钥、检查日志、评估影响范围。有了这套机制加密方案才能从上线的第一天起就持续有效而不是变成一个走形式的安全项。最后再分享一个小技巧每次迁移完密钥或者改完配置文件都手动跑一次应用启动验证确认所有的密文都能正确解开。这个动作看着简单但能帮你避开百分之八十的“部署后启动失败”问题。配置安全这件事慢一点、稳一点永远比追求速度值得。