LibreOffice REST API

如果你在做“文档在线预览”“Office 转 PDF”“批量格式转换”，libreoffice-rest-api 是一个很直接的方案。

它把 LibreOffice 转换能力封装成 REST API，同时把鉴权、异步任务、格式白名单、健康检查和指标接口都准备好了。

项目地址：https://github.com/funnyzak/libreoffice-rest-api

这个项目解决了什么

传统 LibreOffice 转换常见问题有三类：

• 冷启动慢，单次调用成本高
• 接口不统一，业务接入麻烦
• 线上治理能力弱（鉴权、限流、监控、日志）

libreoffice-rest-api 的做法是：

• 提供 CLI/UNO 双模式，UNO 通过常驻实例降低启动开销
• 同时支持 同步与异步 两条调用路径
• 内置 任务管理与下载接口，便于业务解耦
• 补齐 安全、观测、运维 所需基础能力

核心能力一览

项目能力可以按这几类理解：

• 转换能力：覆盖文档、表格、演示和部分图片格式
• 调用模式：同步直接拿结果，异步走任务轮询
• 合并能力：支持多文件合并为 PDF
• 输入方式：支持文件上传和 URL 拉取
• 安全防护：API Key、MIME/扩展名白名单、文件大小限制、魔数检测
• 可观测性：/health、/metrics、结构化日志
• 运维友好：Swagger 文档自动生成，配置支持环境变量覆盖

如果你目标是尽快做出稳定的文档转换服务，第一阶段基本够用。

安装与启动

常见安装方式有四种：

• 脚本安装：适合快速部署和升级
• Homebrew 安装：macOS 更省事
• Docker 部署：容器环境最方便
• 源码编译：适合做二次开发

快速上手流程：

1
2
3
4

make init-config
export LIBREOFFICE_REST_API_AUTH_API_KEYS=your-api-key
make build && make run
curl http://localhost:30231/health

默认监听 0.0.0.0:30231。启动后可以访问 /swagger/index.html 看接口文档。

API 设计思路

接口围绕“任务生命周期”组织：

• POST /api/v1/convert：提交转换任务（sync/async）
• POST /api/v1/merge：提交合并任务（输出 PDF）
• GET /api/v1/tasks/:id：查询任务状态
• GET /api/v1/files/:id/download：下载结果文件

这套设计的好处是：

• 可按场景切换同步/异步
• 长任务容易追踪，也方便重试和告警
• 下载链路独立，后续接 CDN 或网关策略更轻松

另外，同步模式支持 binary=false 返回 JSON 元数据，不一定非要返回文件流。

配置与安全建议

配置机制很简单：

• 配置文件：config.yaml（通常由 config.yaml.example 复制）
• 环境变量前缀：LIBREOFFICE_REST_API_

比如：

• server.port → LIBREOFFICE_REST_API_SERVER_PORT
• auth.api_keys → LIBREOFFICE_REST_API_AUTH_API_KEYS
• download.require_auth → LIBREOFFICE_REST_API_DOWNLOAD_REQUIRE_AUTH

优先关注这些参数：

• worker.concurrency：并发吞吐
• converter.timeout_seconds：单任务超时
• storage.max_file_mb：单文件体积上限
• converter.mode 与 converter.uno.pool_size：性能和稳定性平衡

安全建议：

• API Key 走环境变量，禁止硬编码
• 打开 metrics.require_auth 与 swagger.require_auth
• 严格收敛 allowed_mime_types 与 allowed_extensions
• 在反向代理层强制 HTTPS

部署时要先盯的点

实战里建议先检查这几件事：

• 字体：安装中文字体，避免乱码
• 磁盘：storage 和日志目录尽量放到性能更好的盘
• 清理：结合 storage.retention_hours 做生命周期回收
• 监控：接入 /metrics，关注失败率、超时率、队列积压
• 容量：按 CPU 核数和流量峰值调 worker.concurrency

如果不确定默认模式，先在压测环境分别测 CLI 和 UNO，再决定线上配置。

小结

libreoffice-rest-api 的价值不只是“能转格式”，而是“转换能力可控、可观测、可扩展”。

下一步可以先做两件事：

• 用 Docker Compose 在测试环境跑通端到端转换链路
• 结合真实文档类型，收敛输入格式白名单和超时策略