1. 为什么配置文件里的明文密码必须干掉做过几年后端的人大概都有过这种经历某次代码提交之后安全扫描工具突然报警说配置文件里出现了数据库密码明文。或者更尴尬的是测试环境的配置被误传到了公开仓库里面连生产环境的连接串都带着。这类问题不是“可能发生”而是“早晚会发生”。SpringBoot 的配置文件体系天然是明文的。不管是application.yml还是application.properties你写进去的数据库密码、Redis 密码、第三方接口的 AppSecret、短信服务的 AccessKey全都是裸奔状态。开发阶段觉得无所谓一旦到了多人协作、代码审计、镜像分发这些环节风险就指数级上升了。Jasypt 这个库就是来解决这个问题的。它的全称是 Java Simplified Encryption核心能力是让你在配置文件里写密文应用启动时自动解密业务代码完全无感知。你不需要改任何Value注入的逻辑也不需要手动写解密工具类只要加依赖、配密钥、把明文换成ENC(密文)就行。这篇文章适合谁看如果你正在用 SpringBoot 做后端开发配置文件里有任何不想让人直接看到的敏感信息或者你们团队正在过安全合规审查那这篇内容可以直接抄作业。我会把三种集成方式都拆开讲清楚包括纯 API 方式、SpringBoot 自动装配方式、以及自定义加密器方式同时把版本兼容的坑一个个标出来。这些都是我在实际项目里踩过的不是从文档里抄的。2. Jasypt 加密方案的整体设计思路2.1 核心原理启动时解密运行时无感Jasypt 的工作机制其实很朴素。它在 Spring 容器启动阶段介入扫描所有配置属性值发现符合ENC(xxx)格式的内容就调用解密器还原成明文然后塞回 Environment 里。后续 Bean 初始化时拿到的已经是解密后的值业务代码根本感知不到加密的存在。这个设计的好处是侵入性极低。你不需要在业务层做任何改造也不用担心某个地方漏了解密。只要配置项走了 Spring 的 Environment 体系Jasypt 就能统一处理。但这里有个关键点解密密钥不能放在配置文件里。如果你把jasypt.encryptor.password也写在application.yml里那等于把钥匙和锁放在同一个盒子加密就失去意义了。密钥必须通过外部渠道注入比如启动参数、环境变量、或者配置中心。2.2 三种集成方式的选型逻辑Jasypt 和 SpringBoot 的集成有三条路选哪条取决于你的项目阶段和团队习惯。第一种是纯 API 方式不依赖 SpringBoot 的自动装配自己写工具类调用StandardPBEStringEncryptor。这种方式最灵活适合老项目改造或者非 Spring 环境。缺点是你要自己管理加密器的生命周期代码量稍多。第二种是 SpringBoot Starter 方式引入jasypt-spring-boot-starter加几行配置就完事。这是最主流的选择适合新项目或者愿意加依赖的项目。自动装配帮你处理了加密器注册、属性解密、环境变量读取这些脏活。第三种是自定义加密器方式在第二种的基础上替换默认的加密算法或密钥获取逻辑。比如你们公司要求用国密算法或者密钥要从特定的配置中心拉取那就需要自定义StringEncryptorBean。选型建议很直接新项目无脑选第二种有特殊算法要求选第三种老项目不想动依赖选第一种。下面我会把三种都展开讲每种都给出可运行的代码。2.3 加密算法的选择与参数含义Jasypt 默认用的是PBEWithMD5AndDES这个算法现在看已经不够安全了。DES 密钥长度只有 56 位MD5 也不是抗碰撞的哈希。生产环境建议换成PBEWithHMACSHA512AndAES_256这是目前比较稳妥的选择。算法参数里有两个东西容易搞混password和salt。password是加密密钥必须外部注入salt是盐值默认随机生成但如果你希望每次加密结果可复现就需要固定盐值。不过固定盐值会降低安全性一般不建议。还有一个ivGenerator参数控制初始化向量的生成策略。默认是RandomIvGenerator每次加密结果不同这是正确的做法。如果你看到有人用NoIvGenerator那说明他在追求加密结果一致性但牺牲了安全性生产环境不要这么干。3. 方式一纯 API 手动集成实战3.1 依赖引入与版本选择纯 API 方式只需要核心库不依赖 SpringBoot Starter。在pom.xml里加这么一段dependency groupIdorg.jasypt/groupId artifactIdjasypt/artifactId version1.9.3/version /dependency版本选择有个坑要注意1.9.3是org.jasypt这个 groupId 下的最后一个稳定版之后项目迁移到了com.github.ulisesbocchio下面。如果你用的是 SpringBoot StartergroupId 是com.github.ulisesbocchio版本号是3.x。这两个是不同的东西不要混用。1.9.3这个版本足够稳定纯 API 方式用它没问题。但如果你打算后续迁移到 Starter 方式建议一开始就用com.github.ulisesbocchio的依赖避免后面改 groupId 引起混乱。3.2 加密工具类的编写纯 API 方式需要自己写一个工具类核心是构造StandardPBEStringEncryptor并设置算法和密钥。下面是我常用的一个模板import org.jasypt.encryption.pbe.StandardPBEStringEncryptor; import org.jasypt.encryption.pbe.config.SimpleStringPBEConfig; public class JasyptUtil { private static final String ALGORITHM PBEWithHMACSHA512AndAES_256; private static final String PASSWORD System.getenv(JASYPT_PASSWORD); private static StandardPBEStringEncryptor encryptor; static { encryptor new StandardPBEStringEncryptor(); SimpleStringPBEConfig config new SimpleStringPBEConfig(); config.setPassword(PASSWORD); config.setAlgorithm(ALGORITHM); config.setKeyObtentionIterations(1000); config.setPoolSize(1); config.setProviderName(SunJCE); config.setSaltGeneratorClassName(org.jasypt.salt.RandomSaltGenerator); config.setIvGeneratorClassName(org.jasypt.iv.RandomIvGenerator); config.setStringOutputType(base64); encryptor.setConfig(config); } public static String encrypt(String plainText) { return encryptor.encrypt(plainText); } public static String decrypt(String cipherText) { return encryptor.decrypt(cipherText); } }这段代码里有几个细节值得说。keyObtentionIterations设成 1000 是默认值它表示密钥派生函数的迭代次数次数越高越安全但启动越慢。生产环境可以调到 10000 甚至更高但要注意启动时间会相应增加。poolSize设成 1 是因为纯 API 方式下通常只在启动阶段用一次不需要连接池。如果你要在高并发场景下频繁加解密可以调大这个值。providerName设成SunJCE是 JDK 自带的加密提供者兼容性最好。如果你用了 BouncyCastle 之类的第三方提供者这里要改成对应的名称。3.3 在 SpringBoot 中手动注册解密器纯 API 方式下SpringBoot 不会自动解密配置项你需要自己写一个BeanFactoryPostProcessor或者EnvironmentPostProcessor来介入。最简单的方式是实现BeanFactoryPostProcessor在 Bean 初始化之前把配置项解密。import org.springframework.beans.BeansException; import org.springframework.beans.factory.config.BeanFactoryPostProcessor; import org.springframework.beans.factory.config.ConfigurableListableBeanFactory; import org.springframework.core.env.ConfigurableEnvironment; import org.springframework.core.env.PropertySource; import org.springframework.stereotype.Component; Component public class JasyptEnvironmentProcessor implements BeanFactoryPostProcessor { Override public void postProcessBeanFactory(ConfigurableListableBeanFactory beanFactory) throws BeansException { ConfigurableEnvironment environment beanFactory.getBean(ConfigurableEnvironment.class); for (PropertySource? propertySource : environment.getPropertySources()) { if (propertySource instanceof EnumerablePropertySource) { EnumerablePropertySource? source (EnumerablePropertySource?) propertySource; for (String name : source.getPropertyNames()) { Object value source.getProperty(name); if (value instanceof String ((String) value).startsWith(ENC()) { String cipherText ((String) value).substring(4, ((String) value).length() - 1); String plainText JasyptUtil.decrypt(cipherText); // 这里需要把解密后的值写回 Environment // 实际实现中通常用 MapPropertySource 包装 } } } } } }这段代码是示意性的实际写回 Environment 需要更复杂的处理因为PropertySource本身是不可变的。更稳妥的做法是自定义一个PropertySource包装原始源在getProperty方法里做解密。这也是 Starter 方式内部的做法所以如果你不想折腾直接用 Starter 更省事。注意纯 API 方式下Value注入的配置项解密时机很关键。如果解密发生在 Bean 初始化之后注入的就是密文。所以BeanFactoryPostProcessor是最晚的介入点再晚就来不及了。4. 方式二SpringBoot Starter 自动装配实战4.1 依赖引入与版本避坑Starter 方式的依赖是这样的dependency groupIdcom.github.ulisesbocchio/groupId artifactIdjasypt-spring-boot-starter/artifactId version3.0.5/version /dependency版本选择是最大的坑区。3.0.5是目前比较稳定的版本支持 SpringBoot 2.x 和 3.x。但如果你用的是 SpringBoot 3.x要注意3.0.5之前的版本可能有兼容问题建议直接用3.0.5或更高。另一个坑是jasypt-spring-boot和jasypt-spring-boot-starter的区别。前者是核心库后者是 Starter 封装。如果你只需要在非 SpringBoot 环境用引前者如果是 SpringBoot 项目引后者。两个都引会导致 Bean 冲突不要干这种事。还有一个历史遗留问题2.x版本的 Starter 和3.x版本的配置项名称有变化。比如jasypt.encryptor.password在2.x里是jasypt.encryptor.password在3.x里也是但jasypt.encryptor.algorithm的默认值变了。升级时一定要看 Release Notes不要盲目改版本号。4.2 最小化配置与启动验证Starter 方式的最小配置只需要一行jasypt: encryptor: password: ${JASYPT_PASSWORD}这行配置的意思是加密密钥从环境变量JASYPT_PASSWORD读取。如果你在本地开发可以在 IDE 的 Run Configuration 里设置这个环境变量或者用启动参数--jasypt.encryptor.passwordxxx传入。配置完之后把配置文件里的明文密码换成ENC(密文)格式spring: datasource: password: ENC(3q2w5e8r7t9y0u1i2o3p4a5s6d7f8g9h)启动应用如果数据库能正常连接说明解密生效了。如果报错说Decryption of Properties failed大概率是密钥不对或者密文格式有问题。提示Starter 方式默认会解密所有ENC()包裹的属性值包括系统属性和环境变量。如果你不想让它扫描某些源可以通过jasypt.encryptor.property.prefix和jasypt.encryptor.property.suffix自定义前后缀默认是ENC(和)。4.3 密钥外部注入的几种姿势密钥不能写在配置文件里这是铁律。实际项目中有几种注入方式各有适用场景。第一种是环境变量最通用。在 Linux 服务器上可以写在/etc/profile或者 systemd 的 service 文件里。在容器环境里可以通过 Docker 的-e参数或者 K8s 的 Secret 注入。这种方式的好处是密钥不落盘坏处是排查问题时容易忘记设置。第二种是启动参数适合临时调试。java -jar app.jar --jasypt.encryptor.passwordxxx。这种方式密钥会出现在进程列表里安全性一般不建议生产环境用。第三种是配置中心适合微服务架构。把密钥放在配置中心的一个独立命名空间里应用启动时拉取。这种方式管理方便但配置中心本身的安全性要保证。第四种是自定义StringEncryptorBean从数据库或者密钥管理服务获取密钥。这种方式最灵活但代码量最大适合对安全性要求极高的场景。我个人的建议是中小项目用环境变量微服务项目用配置中心金融级项目用自定义加密器加密钥管理服务。不要为了省事把密钥写在配置文件里这是底线。5. 方式三自定义加密器与国密算法替换5.1 为什么要自定义加密器Starter 方式默认用的是PBEWithMD5AndDES这个算法在安全扫描里会被标记为弱加密。虽然可以通过jasypt.encryptor.algorithm配置项换成更强的算法但有些场景下配置项不够用。比如你们公司要求用国密 SM4 算法Jasypt 本身不支持就需要自己实现StringEncryptor接口。再比如密钥需要从特定的密钥管理服务动态获取每次启动时拉取这也需要自定义加密器。还有一种情况是加密结果需要兼容旧系统。比如旧系统用的是 AES/CBC/PKCS5Padding新系统用 Jasypt 默认算法加密出来的结果旧系统解不了这时候就需要自定义加密器来对齐算法。5.2 自定义 StringEncryptor 的完整实现自定义加密器的核心是实现StringEncryptor接口然后注册成 Bean。下面是一个用 AES/GCM 模式的实现示例import org.jasypt.encryption.StringEncryptor; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import javax.crypto.Cipher; import javax.crypto.spec.GCMParameterSpec; import javax.crypto.spec.SecretKeySpec; import java.nio.charset.StandardCharsets; import java.security.SecureRandom; import java.util.Base64; Configuration public class CustomEncryptorConfig { private static final String ALGORITHM AES/GCM/NoPadding; private static final int GCM_TAG_LENGTH 128; private static final int IV_LENGTH 12; Bean(jasyptStringEncryptor) public StringEncryptor stringEncryptor() { return new StringEncryptor() { private final SecretKeySpec keySpec; { String password System.getenv(JASYPT_PASSWORD); byte[] keyBytes new byte[32]; byte[] passwordBytes password.getBytes(StandardCharsets.UTF_8); System.arraycopy(passwordBytes, 0, keyBytes, 0, Math.min(passwordBytes.length, 32)); this.keySpec new SecretKeySpec(keyBytes, AES); } Override public String encrypt(String message) { try { byte[] iv new byte[IV_LENGTH]; new SecureRandom().nextBytes(iv); Cipher cipher Cipher.getInstance(ALGORITHM); cipher.init(Cipher.ENCRYPT_MODE, keySpec, new GCMParameterSpec(GCM_TAG_LENGTH, iv)); byte[] cipherText cipher.doFinal(message.getBytes(StandardCharsets.UTF_8)); byte[] combined new byte[iv.length cipherText.length]; System.arraycopy(iv, 0, combined, 0, iv.length); System.arraycopy(cipherText, 0, combined, iv.length, cipherText.length); return Base64.getEncoder().encodeToString(combined); } catch (Exception e) { throw new RuntimeException(Encryption failed, e); } } Override public String decrypt(String encryptedMessage) { try { byte[] combined Base64.getDecoder().decode(encryptedMessage); byte[] iv new byte[IV_LENGTH]; System.arraycopy(combined, 0, iv, 0, IV_LENGTH); byte[] cipherText new byte[combined.length - IV_LENGTH]; System.arraycopy(combined, IV_LENGTH, cipherText, 0, cipherText.length); Cipher cipher Cipher.getInstance(ALGORITHM); cipher.init(Cipher.DECRYPT_MODE, keySpec, new GCMParameterSpec(GCM_TAG_LENGTH, iv)); return new String(cipher.doFinal(cipherText), StandardCharsets.UTF_8); } catch (Exception e) { throw new RuntimeException(Decryption failed, e); } } }; } }这个实现有几个关键点。Bean 名称必须是jasyptStringEncryptor这是 Starter 约定的名称改了就不会生效。GCM 模式需要每次加密生成随机 IV并把 IV 和密文拼在一起存储解密时再拆开。密钥长度必须是 16、24 或 32 字节这里用 32 字节对应 AES-256。注意自定义加密器时encrypt和decrypt必须成对实现且加密结果要能跨版本兼容。如果后续换了算法旧密文就解不开了所以生产环境换算法一定要做数据迁移。5.3 国密 SM4 替换的实操要点如果要用国密 SM4需要引入 BouncyCastle 依赖dependency groupIdorg.bouncycastle/groupId artifactIdbcprov-jdk15on/artifactId version1.70/version /dependency然后在自定义加密器里用SM4Engine和PaddedBufferedBlockCipher实现加解密。SM4 的密钥长度固定 16 字节分组长度也是 16 字节模式一般用 CBC 或 ECB。ECB 模式不需要 IV但安全性较低建议用 CBC。实现时要注意 BouncyCastle 的 Provider 注册。可以在静态代码块里调用Security.addProvider(new BouncyCastleProvider())或者在Cipher.getInstance时指定 Provider 名称。国密算法的性能比 AES 稍慢但差距不大。实测下来加密 1000 个配置项SM4 比 AES 慢大约 15% 左右对启动时间的影响可以忽略。6. 加密解密操作与配置替换全流程6.1 生成密文的正确姿势生成密文有两种方式写个临时 Main 方法调用JasyptUtil.encrypt()或者用 Starter 提供的命令行工具。我习惯用前者因为可控性强。写 Main 方法时要注意加密器和应用启动时用的加密器必须配置一致。算法、密钥、盐值生成器、IV 生成器这些参数都要对齐否则加密出来的密文应用解不开。public class EncryptMain { public static void main(String[] args) { String plainText mySecretPassword123; String cipherText JasyptUtil.encrypt(plainText); System.out.println(ENC( cipherText )); } }输出结果直接复制到配置文件里替换原来的明文。注意ENC()括号是英文括号不要写成中文括号否则 Starter 识别不了。6.2 批量替换配置项的策略一个项目里可能有几十个敏感配置项一个个手动替换效率太低。我通常写个脚本批量处理。思路是先用正则表达式扫描配置文件找出所有疑似敏感项比如包含password、secret、key、token的配置名然后逐个加密替换。替换时保留原有的缩进和格式只改值。import re import subprocess def encrypt_value(plain_text): # 调用 Java 加密工具实际项目中可以封装成 HTTP 接口 result subprocess.run( [java, -cp, jasypt.jar, EncryptMain, plain_text], capture_outputTrue, textTrue ) return result.stdout.strip() def process_config(file_path): with open(file_path, r, encodingutf-8) as f: lines f.readlines() pattern re.compile(r^(\s*)(\w*(?:password|secret|key|token)\w*)\s*:\s*(.)$, re.IGNORECASE) for i, line in enumerate(lines): match pattern.match(line) if match and not match.group(3).startswith(ENC(): indent, key, value match.groups() encrypted encrypt_value(value.strip()) lines[i] f{indent}{key}: ENC({encrypted})\n with open(file_path, w, encodingutf-8) as f: f.writelines(lines)这个脚本是示意性的实际使用时要注意处理引号、注释、多行值等情况。替换完成后一定要人工复核一遍确认没有漏掉或者误改。6.3 启动验证与回滚方案替换完成后启动应用验证。如果启动失败先看日志里的报错信息。常见的错误有密钥不对、密文格式错误、算法不匹配。验证通过后不要急着删掉明文备份。保留一份加密前的配置文件在安全的地方万一需要回滚可以快速恢复。回滚的方式很简单把ENC()包裹的值换回明文重启应用即可。提示生产环境替换配置项时建议先在预发环境验证一遍。预发环境的密钥和生产环境可以不同但算法和参数必须一致否则验证结果没有参考价值。7. 版本兼容与常见报错排查7.1 版本兼容性对照表Jasypt 和 SpringBoot 的版本兼容是个高频踩坑点。下面这张表是我实测过的组合SpringBoot 版本Jasypt Starter 版本是否兼容备注2.1.x2.1.0是稳定组合2.3.x2.1.2是需要 JDK 82.7.x3.0.4是推荐组合3.0.x3.0.5是需要 JDK 173.2.x3.0.5是实测稳定3.2.x3.0.3否启动报错如果版本不匹配最常见的报错是NoSuchMethodError或ClassNotFoundException。这是因为 Starter 内部依赖了 SpringBoot 的某些 API版本差异导致方法签名不一致。7.2 常见报错与解决方案速查下面这张表整理了我在实际项目中遇到的报错和解决方法报错信息原因解决方案Decryption of Properties failed密钥不对或密文损坏检查密钥是否一致重新生成密文NoSuchMethodError: org.springframework...版本不兼容对照兼容表调整版本Bean name jasyptStringEncryptor not found自定义加密器 Bean 名称不对改名为jasyptStringEncryptorENC() format not recognized括号是中文或格式错误确保是英文括号且无空格Salt generator not found盐值生成器类名写错检查saltGeneratorClassName配置Key length not valid密钥长度不符合算法要求AES-256 需要 32 字节密钥排查时建议先看完整堆栈定位到具体的类和方法。Jasypt 的报错信息通常比较明确顺着堆栈找基本能定位到问题。7.3 启动性能优化的几个技巧Jasypt 解密是在启动阶段完成的如果配置项很多启动时间会明显增加。我实测过一个项目200 个加密配置项启动时间增加了大约 1.5 秒。优化思路有几个。第一是减少加密项数量只加密真正敏感的配置不要把普通配置也加密。第二是调整keyObtentionIterations从 1000 降到 100 可以显著加快解密速度但安全性会降低需要权衡。第三是启用加密器池poolSize设成 CPU 核心数可以并行解密。还有一个技巧是延迟解密。如果某些配置项只在特定场景下用到可以配置成懒加载启动时不解密第一次访问时再解密。不过 Jasypt 本身不支持这个特性需要自己扩展。8. 生产环境落地的经验与避坑清单8.1 密钥管理的三条铁律第一条密钥永远不要提交到代码仓库。不管是 Git 还是 SVN只要提交了就等于泄露了。密钥要通过环境变量、配置中心、密钥管理服务这些外部渠道注入。第二条不同环境用不同密钥。开发、测试、预发、生产每个环境的密钥都应该独立。这样即使开发环境的密钥泄露也不会影响生产环境。第三条密钥要定期轮换。建议每季度或每半年换一次密钥。轮换时先加密新密文再切换密钥最后删除旧密钥。这个过程要自动化手动操作容易出错。8.2 团队协作中的配置规范团队协作时配置文件的管理要有规范。我的建议是配置文件里只保留ENC()密文明文一律不出现。开发人员本地调试时通过 IDE 的环境变量配置密钥。代码审查时把配置文件作为重点检查对象。如果发现明文密码直接打回。可以配置 Git Hook在提交前扫描配置文件发现疑似明文就阻止提交。文档里要写清楚密钥的获取方式但不要写密钥本身。新同事入职时通过安全渠道单独告知密钥不要发在群里或者邮件里。8.3 我踩过的五个坑第一个坑用jasypt-spring-boot而不是jasypt-spring-boot-starter结果自动装配不生效排查了半天才发现依赖引错了。第二个坑密钥里包含特殊字符比如#或$在 YAML 里被解析成了注释或变量。解决方法是用引号包裹密钥或者用 Base64 编码后再作为密钥。第三个坑加密时用的算法和启动时配置的算法不一致导致解密失败。后来养成了习惯加密和解密用同一份配置类避免参数漂移。第四个坑在 Docker 容器里忘记传环境变量应用启动时报密钥为空。后来在 Dockerfile 里加了默认值检查密钥为空时直接启动失败避免带病运行。第五个坑升级 SpringBoot 版本时没有同步升级 Jasypt Starter导致启动报NoSuchMethodError。后来在 CI 流程里加了版本兼容检查升级前先跑一遍兼容性测试。8.4 安全加固的延伸思考Jasypt 解决了配置文件明文的问题但安全加固不止这一步。日志里不要打印敏感信息接口返回里不要带密钥数据库连接要加密这些都要考虑。另外Jasypt 的加密强度取决于密钥的复杂度。如果密钥是123456这种加密了等于没加密。建议密钥长度至少 16 位包含大小写字母、数字和特殊字符。最后安全是一个持续的过程不是一次配置就完事。定期做安全扫描定期轮换密钥定期审查配置这些习惯比任何工具都重要。我在实际项目中的体会是把安全规范融入到日常开发流程里比事后补救要省事得多。