compose-anything/src/jodconverter/README.zh.md

OfficeConverter（JODConverter）

English | 中文

此服务部署 OfficeConverter，一个基于 JODConverter 和 LibreOffice 的现代 REST API 文档转换服务。它自动进行文档转换，支持多种格式包括 Word、PDF、Excel、PowerPoint 等。officeconverter 项目是 jodconverter-samples-rest 的扩展和积极维护的版本。

服务

• officeconverter：具有集成 LibreOffice 实例的 REST API 文档转换服务。

环境变量

变量名	描述	默认值
OFFICECONVERTER_VERSION	OfficeConverter 镜像版本	latest
OFFICECONVERTER_PORT_OVERRIDE	主机端口映射（映射到端口 8000）	8000
CONVERTER_LIBREOFFICE_INSTANCES	并行 LibreOffice 实例数	2
CONVERTER_QUEUE_SIZE	最大转换队列大小	1000
JAVA_OPTS	Java 堆内存配置	-Xmx1024m
TZ	时区	UTC

请根据您的使用情况修改 .env 文件。

卷

• officeconverter_config：用于存储 OfficeConverter 配置的卷，位于 /etc/app。

使用方法

1. 启动服务：

   docker compose up -d
   

2. OfficeConverter REST API 将在 http://localhost:8000（或您配置的端口）上可用。

3. 在 http://localhost:8000/ready 检查服务就绪状态

文档转换

基本转换

使用 REST API 转换文档：

curl -X POST http://localhost:8000/conversion?format=pdf \
  -F "file=@input.docx" \
  -o output.pdf

REST 端点

• POST /conversion?format=<format> - 将文档转换为指定格式
  • 查询参数：format - 输出格式（例如 pdf、html、docx、xlsx）
  • 表单参数：file - 待转换文件
• GET /ready - 健康检查端点

支持的格式

OfficeConverter 支持各种文档格式之间的转换，包括：

• 文档：DOCX、DOC、ODT、RTF、TXT、DOTX
• 电子表格：XLSX、XLS、ODS、CSV、XLTX
• 演示文稿：PPTX、PPT、ODP
• PDF 和 HTML 转换

可以通过编辑 src/resources/document-formats.json 添加其他格式。

配置

LibreOffice 实例

控制 LibreOffice 实例数量以实现并行文档处理：

CONVERTER_LIBREOFFICE_INSTANCES=4

更多实例允许更高的并发性，但会消耗更多内存。

内存配置

根据您的转换负载调整 Java 堆内存：

JAVA_OPTS=-Xmx2048m

自定义配置

挂载自定义 application.yml 文件以进行高级配置：

# /etc/app/application.yml
converter:
  libreoffice-instances: 4
  queue:
    max-size: 2000

资源限制

• CPU：限制为 2 核，预留 0.5 核
• 内存：限制为 2 GB，预留 512 MB

资源限制可以根据您的转换工作负载在 docker-compose.yaml 中调整。

健康检查

该服务包括一个健康检查，验证 /ready 端点。在 30 秒的成功健康检查后，容器将被视为健康。

高级使用

带选项的转换

某些转换支持其他参数。查看 OfficeConverter 文档了解高级选项。

监控

查看日志以监视转换活动：

docker compose logs -f officeconverter

性能调优

对于高容量转换工作负载，请考虑：

• 将 CONVERTER_LIBREOFFICE_INSTANCES 增加到 4-8
• 增加 JAVA_OPTS 内存限制
• 增加 CONVERTER_QUEUE_SIZE 以支持更多待处理作业

故障排除

服务未就绪

检查服务是否已完全初始化：

curl http://localhost:8000/ready

如果未就绪，检查日志：

docker compose logs officeconverter

内存问题

如果转换因内存错误而失败，请增加 Java 堆：

JAVA_OPTS=-Xmx2048m

并增加 docker-compose.yaml 中的内存限制。

转换失败

检查服务日志以获取详细错误消息：

docker compose logs officeconverter | grep -i error

有关更多信息，请访问 OfficeConverter GitHub 仓库。