升级Camunda 7.20与SpringBoot 3.x后遇History Time To Live非空错误

问题现象 #

升级Camunda到7.20版本、SpringBoot到3.x版本后，启动报错：

History Time To Live cannot be null | resource Orchestration.bpmn

工作区内找不到Orchestration.bpmn文件，且此前从未在BPMN文件中配置过History Time To Live。完整堆栈跟踪：

Caused by: org.camunda.bpm.engine.ParseException: ENGINE-09005 Could not parse BPMN process. Errors:
* History Time To Live cannot be null: History Time To Live cannot be null | resource Orchestration.bpmn | line 3 | column 56
        at org.camunda.bpm.engine.impl.util.EngineUtilLogger.exceptionDuringParsing(EngineUtilLogger.java:66)
        at org.camunda.bpm.engine.impl.util.xml.Parse.throwExceptionForErrors(Parse.java:240)
        at org.camunda.bpm.engine.impl.bpmn.parser.BpmnParse.execute(BpmnParse.java:354)
        at org.camunda.bpm.engine.impl.bpmn.deployer.BpmnDeployer.transformDefinitions(BpmnDeployer.java:105)
        at org.camunda.bpm.engine.impl.AbstractDefinitionDeployer.transformResource(AbstractDefinitionDeployer.java:99)
        at org.camunda.bpm.engine.impl.AbstractDefinitionDeployer.parseDefinitionResources(AbstractDefinitionDeployer.java:74)
        at org.camunda.bpm.engine.impl.AbstractDefinitionDeployer.deploy(AbstractDefinitionDeployer.java:64)
        at org.camunda.bpm.engine.impl.persistence.deploy.cache.CacheDeployer$1.call(CacheDeployer.java:54)
        at org.camunda.bpm.engine.impl.persistence.deploy.cache.CacheDeployer$1.call(CacheDeployer.java:51)
        at org.camunda.bpm.engine.impl.interceptor.CommandContext.runWithoutAuthorization(CommandContext.java:559)
        at org.camunda.bpm.engine.impl.interceptor.CommandContext.runWithoutAuthorization(CommandContext.java:547)
        at org.camunda.bpm.engine.impl.persistence.deploy.cache.CacheDeployer.deploy(CacheDeployer.java:51)
        at org.camunda.bpm.engine.impl.persistence.deploy.cache.DeploymentCache.deploy(DeploymentCache.java:71)
        at org.camunda.bpm.engine.impl.persistence.entity.DeploymentManager.insertDeployment(DeploymentManager.java:64)
        at org.camunda.bpm.engine.impl.cmd.DeployCmd.deploy(DeployCmd.java:258)
        at org.camunda.bpm.engine.impl.cmd.DeployCmd.lambda$doExecute$0(DeployCmd.java:155)
        at org.camunda.bpm.engine.impl.interceptor.CommandContext.runWithoutAuthorization(CommandContext.java:559)
        at org.camunda.bpm.engine.impl.interceptor.CommandContext.runWithoutAuthorization(CommandContext.java:547)
        at org.camunda.bpm.engine.impl.cmd.DeployCmd.doExecute(DeployCmd.java:141)
        at org.camunda.bpm.engine.impl.cmd.DeployCmd.execute(DeployCmd.java:101)
        at org.camunda.bpm.engine.impl.cmd.DeployCmd.execute(DeployCmd.java:81)
        at org.camunda.bpm.engine.impl.interceptor.CommandExecutorImpl.execute(CommandExecutorImpl.java:28)
        at org.camunda.bpm.engine.impl.interceptor.CommandContextInterceptor.execute(CommandContextInterceptor.java:110)
        at org.camunda.bpm.engine.spring.SpringTransactionInterceptor.lambda$execute$0(SpringTransactionInterceptor.java:71)
        at org.springframework.transaction.support.TransactionTemplate.execute(TransactionTemplate.java:140)
        at org.camunda.bpm.engine.spring.SpringTransactionInterceptor.execute(SpringTransactionInterceptor.java:71)
        at org.camunda.bpm.engine.impl.interceptor.ProcessApplicationContextInterceptor.execute(ProcessApplicationContextInterceptor.java:70)
        at org.camunda.bpm.engine.impl.interceptor.CommandCounterInterceptor.execute(CommandCounterInterceptor.java:35)
        at org.camunda.bpm.engine.impl.interceptor.LogInterceptor.execute(LogInterceptor.java:33)
        at org.camunda.bpm.engine.impl.interceptor.ExceptionCodeInterceptor.execute(ExceptionCodeInterceptor.java:55)
        at org.camunda.bpm.engine.impl.RepositoryServiceImpl.deployWithResult(RepositoryServiceImpl.java:104)
        at org.camunda.bpm.engine.impl.repository.DeploymentBuilderImpl.deployWithResult(DeploymentBuilderImpl.java:270)
        at org.camunda.bpm.engine.impl.repository.DeploymentBuilderImpl.deploy(DeploymentBuilderImpl.java:266)
        at org.camunda.bpm.engine.spring.SpringTransactionsProcessEngineConfiguration.autoDeployResources(SpringTransactionsProcessEngineConfiguration.java:156)
        at org.camunda.bpm.engine.spring.SpringTransactionsProcessEngineConfiguration.buildProcessEngine(SpringTransactionsProcessEngineConfiguration.java:67)
        at org.camunda.bpm.engine.spring.ProcessEngineFactoryBean.getObject(ProcessEngineFactoryBean.java:55)
        at org.camunda.bpm.engine.spring.ProcessEngineFactoryBean.getObject(ProcessEngineFactoryBean.java:34)
        at org.springframework.beans.factory.support.FactoryBeanRegistrySupport.doGetObjectFromFactoryBean(FactoryBeanRegistrySupport.java:148)

解决方案 #

1. 定位Orchestration.bpmn的来源 #

Camunda默认会自动部署classpath下所有BPMN文件，该文件可能存在于：

• 项目依赖的第三方jar包中
• 本地构建缓存（如target/或build/目录）
• 之前部署残留的数据库记录

可以通过以下方式查找：

• 用IDE全局搜索整个项目（包括依赖库）
• 执行命令搜索文件系统：

  # Linux/macOS
  find . -name "Orchestration.bpmn"
  # Windows PowerShell
  Get-ChildItem -Path . -Filter "Orchestration.bpmn" -Recurse
  

2. 设置全局History Time To Live默认值 #

Camunda 7.20强化了History TTL的校验，若单个流程未配置，可通过全局配置指定默认值，避免null错误。在application.yml或application.properties中添加：

camunda.bpm:
  history-level: full # 根据业务需求选择合适的历史级别
  history-time-to-live: 30 # 历史数据保留天数，可自定义

3. 清理部署缓存与旧记录 #

• 清理项目构建目录（target/或build/），重新构建项目
• 清空Camunda数据库中的部署相关表：ACT_RE_DEPLOYMENT、ACT_RE_PROCDEF、ACT_RE_CASE_DEF等（注意备份数据）
• 临时关闭自动部署，验证问题是否消失：

  camunda.bpm:
    auto-deployment-enabled: false
  

4. 限制自动部署的资源路径 #

自定义Camunda自动加载的BPMN文件路径，避免加载无关文件：

camunda.bpm:
  deployment-resource-patterns:
    - classpath*:your-processes-dir/*.bpmn # 指定你自己的流程文件目录

内容的提问来源于stack exchange，提问作者Shubham Shekhar