Stirling-PDF项目升级与自定义配置保留指南

核心问题场景

在基于Java的文档处理工具Stirling-PDF的部署过程中，用户常遇到版本升级时自定义配置丢失的问题。典型表现为：

1. 界面语言选项重置（如手动精简后的语言列表恢复默认）
2. 功能模块可见性异常（如PDF转换功能消失）
3. 前端HTML模板修改被覆盖

技术原理剖析

Stirling-PDF采用Spring Boot框架打包为可执行JAR，其配置存储机制具有以下特点：

• 持久化配置：通过application.yml/properties文件存储的配置会自动保留（如服务端口、文件存储路径等）
• 静态资源：前端模板文件（如languages.html）被打包进JAR的resources目录，升级时会被全新替换
• 功能开关：部分功能可见性受版本特性开关控制，不同版本可能存在差异

完整升级方案

标准升级流程

1. 停止运行中的服务

   systemctl stop stirling-pdf
   

2. 备份现有配置

   cp /opt/Stirling-PDF/application.yml /backup/stirling-config-$(date +%F).yml
   

3. 替换JAR文件

   mv Stirling-PDF-new.jar /opt/Stirling-PDF/Stirling-PDF.jar
   

4. 重启服务

   systemctl start stirling-pdf
   

自定义配置保留方案

针对不同类型的自定义需求，需采用不同策略：

前端模板保留

1. 解压原始JAR获取模板

   unzip Stirling-PDF.jar -d jar_contents
   

2. 提取需修改的模板文件（如languages.html）
3. 新建外部模板目录

   mkdir -p /etc/Stirling-PDF/templates/fragments/
   

4. 将修改后的模板置于Spring Boot外部化配置路径下，系统会优先加载外部文件

功能模块控制

1. 通过application.yml配置特性开关

   features:
     pdf-conversion: true
     ocr-processing: false
   

2. 或使用运行时参数

   java -jar Stirling-PDF.jar --features.pdf-conversion=true
   

版本兼容性处理

当出现跨版本功能差异时，建议：

1. 查阅版本变更日志确认特性调整
2. 进行分阶段升级（如0.36.6→0.38.0→0.39.0）
3. 对新版本进行测试环境验证

最佳实践建议

1. 建立配置版本库，记录所有自定义修改
2. 使用Docker部署时可挂载配置卷实现持久化
3. 重要升级前使用数据库备份工具（如针对H2数据库）

通过以上方法，可确保Stirling-PDF在版本迭代过程中既获得新特性，又保持生产环境的配置稳定性。对于企业级部署，建议建立完整的CI/CD流程来自动化这些维护操作。