本文详解如何解决 Spring Cloud Vault 与 PostgreSQL 集成时因动态密码过期导致的 FATAL: password authentication failed 连接失效问题，通过启用 Lease 生命周期管理与 HikariCP 运行时凭据热更新，实现无需重启应用的无缝凭证轮换。
本文详解如何解决 spring cloud vault 与 postgresql 集成时因动态密码过期导致的 `fatal: password authentication failed` 连接失效问题，通过启用 lease 生命周期管理与 hikaricp 运行时凭据热更新，实现无需重启应用的无缝凭证轮换。
在使用 Spring Cloud Vault 动态数据库凭证（如 PostgreSQL 的 database/creds/{role}）时，Vault 为每次请求生成带 TTL（如 1 小时）的临时用户名和密码。当 HikariCP 连接池中缓存的连接尝试复用已过期的凭证时，就会触发典型的错误：
FATAL: password authentication failed for user "v-token-xxxxxx-1692899441"
该问题并非网络或权限配置错误，而是 Vault 凭证生命周期与连接池生命周期未对齐所致：Vault 自动吊销旧凭据后，HikariCP 仍尝试用失效密码建立新连接或复用空闲连接。
✅ 核心解决方案：启用 Lease 生命周期 + 运行时数据源热更新
1. 启用 Vault 秘密生命周期管理（关键配置）
在 application.yml 中必须显式启用 Lease 自动续订与事件通知机制：
spring:
cloud:
vault:
config:
lifecycle:
enabled: true # ← 必须开启！否则 lease 事件不触发
min-renewal: 60s # 建议值：避免过于频繁续订（10s 太激进，易触发限流）
expiry-threshold: 2m # 在到期前 2 分钟触发续订/轮换
lease-endpoints: Legacy # 兼容 Vault 1.x 的 database backend（新版推荐使用 DatabaseBackend）
database:
role: database_write_role
# ... 其他 database 配置保持不变⚠️ 注意：
spring.cloud.vault.config.lifecycle.enabled=true是启用SecretLeaseCreatedEvent/SecretLeaseExpiredEvent的前提，缺省为false，极易被忽略。
2. 编写动态凭据热更新配置类
以下 @Configuration 类监听 Vault 凭据变更事件，在获取新凭据后实时更新 HikariCP 数据源配置并软驱逐旧连接：
@Configuration
public class VaultDynamicDataSourceConfig {
private static final Logger log = LoggerFactory.getLogger(VaultDynamicDataSourceConfig.class);
@Autowired
private SecretLeaseContainer leaseContainer;
@Autowired
private HikariDataSource hikariDataSource;
@Value("${spring.cloud.vault.database.role}")
private String databaseRole;
@PostConstruct
public void setupLeaseListener() {
String credsPath = "database/creds/" + databaseRole;
leaseContainer.addLeaseListener(event -> {
// 仅响应目标数据库角色的凭据事件
if (!credsPath.equals(event.getSource().getPath())) return;
if (event instanceof SecretLeaseCreatedEvent createdEvent &&
createdEvent.getSource().getMode() == SecretLeaseMode.ROTATE) {
Map<String, Object> secrets = createdEvent.getSecrets();
String newUsername = (String) secrets.get("username");
String newPassword = (String) secrets.get("password");
log.info("? Vault issued new DB credentials: user='{}'", newUsername);
// ✅ 安全更新 HikariCP 运行时配置（线程安全）
hikariDataSource.getHikariConfigMXBean().setUsername(newUsername);
hikariDataSource.getHikariConfigMXBean().setPassword(newPassword);
// ✅ 软驱逐所有空闲连接（强制后续请求创建新连接）
hikariDataSource.getHikariPoolMXBean().softEvictConnections();
log.info("✅ DataSource credentials updated; idle connections evicted.");
}
});
}
}3. 补充最佳实践配置
-
HikariCP 连接验证增强（防止 stale connection）：
spring: datasource: hikari: connection-test-query: SELECT 1 validation-timeout: 3000 # 禁用自动测试（由 lease 事件驱动更精准） # test-on-borrow 已废弃，改用 validation-timeout + connection-test-query Vault 后端兼容性提示：若使用 Vault 1.10+，建议将
lease-endpoints: Legacy改为lease-endpoints: DatabaseBackend，并确认 Vault database engine 已启用rotate-root权限。日志可观测性：添加
logging.level.org.springframework.cloud.vault=DEBUG可追踪 lease 续订详情。
? 验证是否生效？
部署后观察日志：
- 正常轮换应出现类似
Lease event SecretLeaseCreatedEvent, lease Id ...和? Vault issued new DB credentials； - 错误日志中
password authentication failed应彻底消失； -
hikariDataSource.getHikariPoolMXBean().getTotalConnections()在轮换后短暂下降（因 softEvict），随后恢复。
? 提示：首次启动时，Vault 默认返回
SecretLeaseCreatedEvent（mode=CREATE），但上述代码仅响应ROTATE事件。如需首次也更新，可扩展判断逻辑，但通常CREATE已由初始配置完成，非必需。
通过以上三步，你的 Spring Boot 应用即可实现 PostgreSQL 凭据的全自动、零停机轮换——告别“一天一重启”的运维噩梦。
