SpringBoot与LibreOffice整合及Docker化部署实践

1. 项目概述

在文档处理类项目中，LibreOffice作为开源办公套件常被用于格式转换、文档渲染等场景。SpringBoot应用与LibreOffice的整合主要面临两个核心问题：一是本地部署时需处理JVM与LibreOffice进程的交互，二是分布式环境下如何实现远程调用。本文将详解两种整合方式，并给出Docker化部署方案。

LibreOffice的soffice进程支持headless模式运行，这为后台文档处理提供了基础。SpringBoot通过JODConverter库与之交互时，本质上是在操作UNO（Universal Network Objects）接口。UNO是LibreOffice的组件模型，允许外部程序通过管道或socket连接控制办公套件。

重要提示：LibreOffice 7.0+版本对UNO接口的稳定性有显著提升，建议优先选用新版本。实测中发现6.x版本在长时间运行后容易出现内存泄漏。

2. 本地整合方案

2.1 环境准备

首先需要确保服务器已安装LibreOffice：

bash复制# Ubuntu/Debian
sudo apt install libreoffice-common libreoffice-java-common

# CentOS/RHEL 
sudo yum install libreoffice-headless

验证安装是否成功：

bash复制soffice --version
# 预期输出类似：LibreOffice 7.4.3.2 40(Build:2)

2.2 SpringBoot集成JODConverter

在pom.xml中添加依赖：

xml复制<dependency>
    <groupId>org.jodconverter</groupId>
    <artifactId>jodconverter-spring-boot-starter</artifactId>
    <version>4.4.6</version>
</dependency>

配置application.yml：

yaml复制jodconverter:
  local:
    enabled: true
    office-home: /usr/lib/libreoffice  # 根据实际路径调整
    port-numbers: 2002,2003,2004  # 建议配置多个端口用于负载均衡
    max-tasks-per-process: 100  # 单个进程最大任务数

2.3 核心代码实现

文档转换服务类示例：

java复制@Service
public class DocumentConverter {
    @Autowired
    private LocalOfficeManager officeManager;

    public void convert(File input, File output, DocumentFormat format) {
        try (OfficeManager manager = LocalOfficeManager.builder()
            .portNumbers(2002)
            .officeHome("/usr/lib/libreoffice")
            .build()) {
            
            manager.start();
            Converter converter = LocalConverter.builder()
                .officeManager(manager)
                .build();
            
            converter.convert(input).to(output).as(format).execute();
        }
    }
}

踩坑记录：LibreOffice进程启动耗时约10-15秒，建议在应用启动时预加载OfficeManager，避免首次请求响应延迟。

3. 远程整合方案

3.1 搭建LibreOffice服务端

在独立服务器上启动soffice服务：

bash复制soffice --headless --accept="socket,host=0.0.0.0,port=8100;urp;" \
--nofirststartwizard --nologo --nodefault

关键参数说明：

• --accept：指定UNO监听地址
• --nofirststartwizard：跳过首次启动向导
• urp：使用UNO远程协议

3.2 SpringBoot客户端配置

调整application.yml：

yaml复制jodconverter:
  remote:
    enabled: true
    url: http://office-server:8100

远程调用示例代码：

java复制@Bean
public OfficeManager officeManager() {
    return RemoteOfficeManager.builder()
        .url("http://office-server:8100")
        .poolSize(5)  # 连接池大小
        .build();
}

3.3 负载均衡方案

当需要处理高并发文档转换时，可采用多节点部署：

1. 使用Nginx做TCP负载均衡：

nginx复制stream {
    upstream office_cluster {
        server office1:8100;
        server office2:8100;
        server office3:8100;
    }
    
    server {
        listen 8100;
        proxy_pass office_cluster;
    }
}

2. SpringBoot配置连接池：

java复制@Bean
public OfficeManager officeManager() {
    return RemoteOfficeManager.builder()
        .url("http://nginx-host:8100")
        .poolSize(20)
        .connectTimeout(Duration.ofSeconds(30))
        .build();
}

4. Docker化部署方案

4.1 单体容器部署

Dockerfile示例：

dockerfile复制FROM ubuntu:22.04

# 安装LibreOffice
RUN apt-get update && \
    apt-get install -y libreoffice-common libreoffice-java-common && \
    rm -rf /var/lib/apt/lists/*

# 安装JDK和SpringBoot应用
COPY target/app.jar /app.jar
ENTRYPOINT ["java","-jar","/app.jar"]

启动命令需要同时运行soffice：

bash复制docker run -d \
  --name office-app \
  -p 8080:8080 \
  -v /tmp:/tmp \
  office-image \
  bash -c "soffice --headless --accept='socket,host=0.0.0.0,port=2002;urp;' & java -jar /app.jar"

4.2 多容器协同部署

使用docker-compose.yml：

yaml复制version: '3'
services:
  app:
    image: springboot-app
    ports:
      - "8080:8080"
    depends_on:
      - libreoffice
    environment:
      JODCONVERTER_REMOTE_URL: "http://libreoffice:8100"
  
  libreoffice:
    image: libreoffice/headless:7.4
    command: >
      soffice --headless --accept="socket,host=0.0.0.0,port=8100;urp;"
      --nofirststartwizard --nologo --nodefault
    volumes:
      - /tmp:/tmp

4.3 性能优化配置

在docker-compose中限制资源：

yaml复制libreoffice:
  deploy:
    resources:
      limits:
        cpus: '2'
        memory: 2G
      reservations:
        memory: 1G

经验值：每个LibreOffice进程约需要1GB内存，CPU核心数影响转换速度。实测中2核2GB配置可支持10并发文档转换。

5. 常见问题排查

5.1 连接失败问题

错误现象：

code复制org.jodconverter.core.office.OfficeException: Could not establish connection

排查步骤：

1. 验证LibreOffice进程是否运行：

   bash复制ps aux | grep soffice
   

2. 检查端口监听：

   bash复制netstat -tulnp | grep 8100
   

3. 测试网络连通性：

   bash复制telnet office-host 8100
   

5.2 文档转换超时

调整超时参数：

java复制@Bean
public OfficeManager officeManager() {
    return RemoteOfficeManager.builder()
        .url("http://office-host:8100")
        .taskExecutionTimeout(Duration.ofMinutes(5))  # 单任务超时
        .connectTimeout(Duration.ofSeconds(30))  # 连接超时
        .build();
}

5.3 字体缺失处理

在Docker容器中安装字体：

dockerfile复制RUN mkdir -p /usr/share/fonts/custom && \
    apt-get install -y fonts-wqy-zenhei fonts-wqy-microhei

或挂载主机字体目录：

yaml复制volumes:
  - /usr/share/fonts:/usr/share/fonts

6. 高级应用场景

6.1 集群动态扩展

结合Kubernetes的HPA实现自动扩缩容：

yaml复制apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: libreoffice-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: libreoffice
  minReplicas: 2
  maxReplicas: 10
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 70

6.2 文档预览服务实现

结合PDF.js构建完整方案：

java复制public ResponseEntity<Resource> preview(Path docPath) {
    // 转换为PDF
    File pdfFile = converter.convert(docPath.toFile(), Format.PDF);
    
    // 使用PDF.js渲染
    return ResponseEntity.ok()
        .header("Content-Type", "application/pdf")
        .body(new InputStreamResource(Files.newInputStream(pdfFile.toPath())));
}

6.3 性能监控指标

通过Micrometer暴露指标：

java复制@Bean
public OfficeManager officeManager(MeterRegistry registry) {
    return RemoteOfficeManager.builder()
        .url("http://office-host:8100")
        .meterRegistry(registry)  # 集成监控
        .build();
}

关键监控指标包括：

• jodconverter.tasks.active：活跃任务数
• jodconverter.tasks.duration：任务耗时
• jodconverter.connections.active：活跃连接数