1. 项目背景与需求分析在企业级应用开发中文档格式转换是常见的业务需求特别是Word/Excel到PDF的转换场景。LibreOffice作为开源办公套件其内置的文档转换引擎具有较好的兼容性和稳定性。Spring Boot作为Java生态的主流框架与LibreOffice的整合能有效解决以下痛点格式兼容性问题商业办公软件转换API存在版权和费用问题转换质量需求需要保持原始文档的排版、样式和图表完整性部署灵活性既要支持开发环境本地调试又要适应生产环境的容器化部署2. 本地整合方案实现2.1 环境准备与依赖配置首先在Linux服务器安装LibreOffice# Ubuntu/Debian sudo apt install libreoffice-common libreoffice-writer # CentOS/RHEL sudo yum install libreoffice-headlessSpring Boot项目需添加以下Maven依赖dependency groupIdorg.jodconverter/groupId artifactIdjodconverter-spring-boot-starter/artifactId version4.4.6/version /dependency dependency groupIdorg.jodconverter/groupId artifactIdjodconverter-local/artifactId version4.4.6/version /dependency2.2 关键配置参数详解application.yml配置示例jodconverter: local: enabled: true office-home: /usr/lib/libreoffice # Linux默认安装路径 portNumbers: 2002,2003,2004 # 建议配置3个端口实现连接池 maxTasksPerProcess: 100 task-execution-timeout: 300000 # 5分钟超时 task-queue-timeout: 60000 # 1分钟队列等待重要提示Windows环境下路径需使用双反斜杠如D:\\Program Files\\LibreOffice2.3 核心转换代码实现文档转换服务类示例Service public class DocumentConversionService { Autowired private DocumentConverter converter; public void convertToPdf(File inputFile, File outputFile) { converter.convert(inputFile) .to(outputFile) .as(DefaultDocumentFormatRegistry.PDF) .execute(); } public InputStream convertToPdf(InputStream input) throws IOException { ByteArrayOutputStream output new ByteArrayOutputStream(); converter.convert(input) .as(DefaultDocumentFormatRegistry.DOCX) .to(output) .as(DefaultDocumentFormatRegistry.PDF) .execute(); return new ByteArrayInputStream(output.toByteArray()); } }3. 远程服务整合方案3.1 独立服务部署在文档转换服务器上启动LibreOffice服务soffice --headless --nologo --nofirststartwizard \ --acceptsocket,host0.0.0.0,port8100;urp; \ --nodefault --norestore Spring Boot配置调整jodconverter: remote: enabled: true url: http://doc-server:8100 # 注意必须包含http协议 connect-timeout: 10000 socket-timeout: 3000003.2 Docker化部署方案推荐使用官方提供的REST服务镜像docker run -d -p 8100:8100 \ -v /usr/share/fonts:/usr/share/fonts \ ghcr.io/jodconverter/jodconverter-examples:rest自定义配置文件示例application.propertiesjodconverter.local.port-numbers2002,2003 jodconverter.local.working-dir/tmp spring.servlet.multipart.max-file-size50MB server.port81004. Docker复合部署实践4.1 多阶段构建方案优化后的Dockerfile示例# 基础镜像阶段 FROM alpine:3.14 as libreoffice RUN apk add --no-cache libreoffice ttf-dejavu # 最终镜像阶段 FROM openjdk:11-jre COPY --fromlibreoffice /usr/lib/libreoffice /usr/lib/libreoffice COPY --fromlibreoffice /usr/share/fonts /usr/share/fonts COPY target/app.jar /app.jar ENV LIBREOFFICE_HOME/usr/lib/libreoffice ENV PATH$PATH:$LIBREOFFICE_HOME/program ENTRYPOINT [java,-jar,/app.jar]4.2 性能优化建议连接池配置建议portNumbers配置3-5个端口字体处理必须挂载中文字体目录VOLUME [/usr/share/fonts]资源限制为容器设置合理的CPU和内存限制docker run -m 2g --cpus 2 ...5. 常见问题排查指南5.1 转换超时问题现象OfficeException: Remote conversion failed检查LibreOffice进程是否存活增加task-execution-timeout配置值检查服务器负载情况5.2 中文乱码问题解决方案确保系统安装中文字体apt install fonts-wqy-zenhei在Docker中挂载字体目录-v /usr/share/fonts:/usr/share/fonts5.3 样式错乱问题Excel转PDF样式异常使用LibreOffice 7.0版本检查文档是否使用非标准字体尝试先转换为ODF格式再转PDF6. 性能对比与方案选型方案类型转换耗时(平均)部署复杂度适用场景本地整合1-3秒中等开发环境、小型应用远程服务2-5秒较高生产环境、微服务架构Docker复合部署3-6秒高容器化环境、独立服务实际测试数据100页Word文档本地模式2.8秒远程调用3.5秒含网络传输Docker部署4.2秒经验建议对于文档转换频率高的场景推荐采用远程服务方案便于横向扩展和独立升级