从OnlyOffice迁移到LibreOffice Online：在线文档编辑方案选型与实战

1. 从一次文档协作崩溃说起：为什么我开始重新审视在线Office方案

去年帮一个做教育培训的朋友处理他们的课程资料系统，前端用的是Vue，后端Java，文档预览和编辑这块一开始选的是OnlyOffice。部署那会儿觉得挺顺，Docker镜像拉下来，Document Server跑起来，前端嵌个iframe就能用，看起来一切都很美好。结果真正上线之后问题一个接一个：文档并发稍微高一点就卡顿，移动端适配一塌糊涂，最要命的是每次升级版本都像拆盲盒——有时候改个配置项整个服务就起不来了，日志里报的错还特别含糊。

那段时间我几乎把OnlyOffice的官方论坛翻了个底朝天，发现遇到类似问题的人不在少数。后来在一个技术群里有人提了一嘴LibreOffice，说他们团队已经切过去了，稳定性好很多。我当时的第一反应是：LibreOffice不是桌面端那个吗？能在线用？深入了解之后才发现，LibreOffice早就有了在线协作的方案，而且生态比我想象的要成熟得多。

这篇文章就是把我从OnlyOffice迁移到LibreOffice Online的完整过程整理出来，包括为什么做这个选择、部署时踩了哪些坑、Java后端怎么调、Vue前端怎么接、以及实际跑起来之后和OnlyOffice的对比感受。如果你也正在为在线文档编辑方案头疼，或者单纯想了解一下开源Office生态的现状，这篇内容应该能帮你省下不少试错时间。

2. OnlyOffice用着挺好，为什么还要折腾

2.1 OnlyOffice的真实使用痛点

先说清楚，OnlyOffice不是不好。它的界面确实漂亮，跟微软Office的兼容性在开源方案里算第一梯队，文档格式支持也全。但问题在于，它的架构设计决定了它在某些场景下会显得力不从心。

最典型的问题是资源占用。OnlyOffice Document Server本质上是一个完整的文档渲染引擎，每个打开的文档都会在服务端启动一个独立的渲染进程。我实测过，在一台4核8G的服务器上，同时打开10个稍微复杂一点的表格文档，内存直接飙到6G以上，CPU也长期在70%以上。对于中小团队来说，这个资源消耗意味着服务器成本直接翻倍。

另一个让人头疼的是版本升级的兼容性。OnlyOffice的版本迭代很快，但每次大版本升级几乎都会带来配置格式的变化。我印象特别深的一次是从7.1升到7.3，原本好好的JWT配置突然不生效了，排查了半天才发现是配置项的层级结构变了。官方文档虽然更新了，但迁移指南写得不够详细，很多细节要靠自己试。

还有移动端体验。OnlyOffice的移动端Web界面基本就是桌面端的缩小版，按钮小得根本点不准，表格编辑更是灾难。我们那个教育平台有大量学生在手机上看课件，反馈最多的就是"字太小""点不动"。

2.2 LibreOffice Online到底是个什么东西

LibreOffice Online（现在官方叫Collabora Online，但底层还是LibreOffice的渲染引擎）的思路和OnlyOffice完全不同。它把LibreOffice的桌面版核心编译成了可以在服务端运行的形式，通过WebSocket和前端通信，前端只负责显示和接收操作指令。

这个架构带来的最大好处是渲染一致性。因为用的就是LibreOffice桌面版同款的渲染引擎，所以文档在Web端和桌面端打开的效果几乎一模一样。不像OnlyOffice，有时候同一个文档在Web端和桌面端显示会有细微差异。

另一个优势是资源效率。LibreOffice Online的进程模型更轻量，同样配置的服务器，并发处理能力大概是OnlyOffice的1.5到2倍。我后来在同样的4核8G机器上测试，同时打开15个文档依然流畅，内存占用稳定在4G左右。

不过LibreOffice Online也不是没有缺点。它的界面确实不如OnlyOffice现代，默认的UI风格偏传统。而且它的部署方式相对复杂一些，需要自己编译或者用第三方打包的镜像。但考虑到稳定性和资源效率，这些代价我觉得是值得的。

2.3 选型对比：一张表看清差异

这张表是我自己实际使用后的主观评分，不一定适用于所有场景。但如果你跟我一样，更看重稳定性和资源效率，LibreOffice Online确实值得一试。

3. 部署实战：从零搭建LibreOffice Online服务

3.1 环境准备与依赖安装

我用的系统是Ubuntu 22.04 LTS，这是目前最稳妥的选择。CentOS 7虽然也支持，但很多依赖包版本太老，编译起来会多不少麻烦。

首先更新系统并安装基础依赖：

sudo apt update && sudo apt upgrade -y sudo apt install -y build-essential git libtool automake autoconf \ pkg-config libpng-dev libjpeg-dev libgif-dev libtiff-dev \ libcap-dev libpam-dev libssl-dev libfontconfig1-dev \ libfreetype6-dev libx11-dev libxext-dev libxrender-dev \ libxml2-dev libxslt1-dev libcups2-dev libdbus-glib-1-dev \ python3-dev python3-pip nodejs npm

这里有个坑要注意：Node.js的版本。LibreOffice Online的前端构建需要Node 14以上，但Ubuntu 22.04默认源里的Node版本可能不够新。建议用NodeSource的源装一个18.x的版本：

curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash - sudo apt install -y nodejs

装完之后验证一下版本：

node -v # 应该输出v18.x.x npm -v # 应该输出9.x.x以上

3.2 编译LibreOffice核心

这一步是最耗时的，我建议找个网络稳定的环境，因为要下载不少源码包。整个过程大概需要40分钟到1小时，取决于机器性能。

git clone https://git.libreoffice.org/core libreoffice cd libreoffice ./autogen.sh --with-distro=LibreOfficeOnline make -j$(nproc)

编译过程中可能会遇到几个常见错误：

• 字体缺失：如果编译时报字体相关的错误，装一下fonts-liberation和fonts-noto-cjk（中文字体）。
• 内存不足：编译LibreOffice很吃内存，建议至少8G。如果内存不够，把-j后面的数字调小，比如-j2。
• Python依赖：确保python3-dev和python3-pip都装了，否则loolwsd的Python脚本会跑不起来。

编译完成后，安装到系统：

sudo make install

3.3 配置loolwsd服务

loolwsd是LibreOffice Online的核心服务进程，负责管理文档进程和WebSocket通信。配置文件在/etc/loolwsd/loolwsd.xml。

几个关键配置项需要改：

<!-- 监听端口，默认9980 --> <port desc="Port to listen">9980</port> <!-- 允许访问的域名，生产环境一定要改 --> <host desc="Hostname to allow or deny." allow="true">your-domain.com</host> <!-- SSL配置，生产环境必须开 --> <ssl desc="SSL settings"> <enable type="bool" desc="Controls whether SSL encryption is enable">true</enable> <cert_file_path desc="Path to the cert file">/etc/ssl/certs/your-cert.pem</cert_file_path> <key_file_path desc="Path to the key file">/etc/ssl/private/your-key.pem</key_file_path> </ssl> <!-- 管理员密码，用于访问管理后台 --> <admin_console desc="Web admin console settings."> <enable desc="Enable the admin console functionality" type="bool">true</enable> <username desc="The username of the admin console.">admin</username> <password desc="The password of the admin console.">your-password</password> </admin_console>

改完配置后重启服务：

sudo systemctl restart loolwsd sudo systemctl enable loolwsd

然后检查服务状态：

sudo systemctl status loolwsd

如果看到active (running)就说明服务起来了。这时候你可以用浏览器访问https://your-domain.com:9980/loleaflet/dist/loleaflet.html，应该能看到一个简单的文档编辑界面。

3.4 中文字体配置的坑

LibreOffice Online默认不带中文字体，如果不配置，打开中文文档会显示成方块。解决办法是把Windows的字体或者开源的思源字体复制到/usr/share/fonts/目录下，然后刷新字体缓存：

sudo cp /path/to/your/fonts/*.ttf /usr/share/fonts/truetype/custom/ sudo fc-cache -fv

我一般会装这几个字体：Noto Sans CJK SC、Noto Serif CJK SC、WenQuanYi Micro Hei。这几个都是开源字体，覆盖了大部分中文文档的需求。

装完之后重启loolwsd，再打开中文文档应该就正常了。

4. Java后端集成：从文档上传到在线编辑的完整链路

4.1 整体架构设计

LibreOffice Online本身只负责文档的渲染和编辑，它不提供文档存储、用户管理、权限控制这些功能。所以我们需要在自己的后端系统里实现这些逻辑。

整体流程是这样的：

1. 用户在前端点击某个文档，前端向后端请求文档的编辑地址。
2. 后端生成一个带签名的临时访问令牌（token），拼接到LibreOffice Online的URL上。
3. 前端用iframe加载这个URL，LibreOffice Online通过WSS协议和后端通信，获取文档内容。
4. 用户编辑完成后，LibreOffice Online把修改后的文档回传给后端保存。

这个过程中，后端需要实现两个关键接口：一个是文档获取接口，LibreOffice Online通过这个接口拉取文档内容；另一个是文档保存接口，LibreOffice Online通过这个接口回传修改后的文档。

4.2 文档获取与保存接口实现

我用的是Spring Boot，先定义一个Controller：

@RestController @RequestMapping("/api/office") public class OfficeController { @Autowired private DocumentService documentService; @GetMapping("/download/{docId}") public void downloadDocument(@PathVariable String docId, @RequestParam String token, HttpServletResponse response) throws IOException { // 验证token if (!tokenService.validateToken(token, docId)) { response.setStatus(HttpStatus.FORBIDDEN.value()); return; } // 获取文档内容 byte[] content = documentService.getDocumentContent(docId); String fileName = documentService.getDocumentName(docId); response.setContentType("application/octet-stream"); response.setHeader("Content-Disposition", "attachment; filename=\"" + fileName + "\""); response.setContentLength(content.length); response.getOutputStream().write(content); response.getOutputStream().flush(); } @PostMapping("/upload/{docId}") public ResponseEntity<String> uploadDocument(@PathVariable String docId, @RequestParam String token, @RequestParam("file") MultipartFile file) { if (!tokenService.validateToken(token, docId)) { return ResponseEntity.status(HttpStatus.FORBIDDEN).body("Invalid token"); } try { documentService.saveDocument(docId, file.getBytes()); return ResponseEntity.ok("Saved"); } catch (IOException e) { return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body("Save failed"); } } }

这里有个细节要注意：token的生成和验证。LibreOffice Online本身不关心token，它只是把token原样拼接到回调URL上。所以token的生成和验证完全由我们自己的后端控制。我一般用JWT，把docId、userId、过期时间编码进去，然后签名。

4.3 生成编辑URL的完整逻辑

前端请求编辑地址的时候，后端需要生成一个完整的URL，包含文档地址、保存地址、语言设置等参数：

public String generateEditUrl(String docId, String userId) { String baseUrl = "https://your-domain.com:9980/loleaflet/dist/loleaflet.html"; String token = tokenService.generateToken(docId, userId); String docUrl = "https://your-backend.com/api/office/download/" + docId + "?token=" + token; String saveUrl = "https://your-backend.com/api/office/upload/" + docId + "?token=" + token; return baseUrl + "?file_path=" + URLEncoder.encode(docUrl, StandardCharsets.UTF_8) + "&save_url=" + URLEncoder.encode(saveUrl, StandardCharsets.UTF_8) + "&lang=zh-CN" + "&closebutton=1" + "&revisionhistory=1"; }

这个URL直接返回给前端，前端用iframe加载就行。

4.4 踩坑记录：回调地址的编码问题

这里有一个我踩了整整一个下午的坑：URL编码。LibreOffice Online对回调地址的编码要求很严格，如果file_path参数里的URL没有正确编码，它会解析失败，然后报一个很模糊的错误。

我一开始用的是URLEncoder.encode(docUrl, "UTF-8")，但Java的URLEncoder会把空格编码成+，而LibreOffice Online期望的是%20。所以需要手动替换一下：

String encodedUrl = URLEncoder.encode(docUrl, StandardCharsets.UTF_8) .replace("+", "%20");

另外，如果你的后端地址是HTTPS的，确保LibreOffice Online的SSL配置也正确，否则它可能拒绝连接。

5. Vue前端接入：iframe通信与状态管理

5.1 前端组件设计

Vue这边相对简单，核心就是一个iframe组件，加上一些状态管理。我一般会封装一个OfficeEditor组件：

<template> <div class="office-editor"> <div v-if="loading" class="loading">加载中...</div> <iframe v-show="!loading" ref="editorFrame" :src="editorUrl" class="editor-frame" frameborder="0" @load="onFrameLoad" ></iframe> </div> </template> <script> export default { name: 'OfficeEditor', props: { docId: { type: String, required: true } }, data() { return { editorUrl: '', loading: true }; }, async created() { await this.loadEditorUrl(); }, methods: { async loadEditorUrl() { try { const response = await this.$http.get(`/api/office/edit-url/${this.docId}`); this.editorUrl = response.data.url; } catch (error) { console.error('获取编辑地址失败', error); this.$message.error('文档加载失败，请稍后重试'); } }, onFrameLoad() { this.loading = false; } } }; </script> <style scoped> .office-editor { width: 100%; height: 100%; position: relative; } .editor-frame { width: 100%; height: 100%; border: none; } .loading { position: absolute; top: 50%; left: 50%; transform: translate(-50%, -50%); font-size: 16px; color: #666; } </style>

5.2 与iframe的通信

LibreOffice Online支持通过postMessage和父页面通信。比如你可以在用户点击保存的时候，通过postMessage通知iframe执行保存操作：

saveDocument() { const frame = this.$refs.editorFrame; frame.contentWindow.postMessage('save', '*'); }

不过要注意，LibreOffice Online的postMessage接口在不同版本里可能有差异，建议先查一下你用的版本的文档。

5.3 移动端适配的实用技巧

前面说过LibreOffice Online的移动端体验一般，但我们可以通过一些CSS技巧来改善。比如在移动端把工具栏字体调大：

@media (max-width: 768px) { .editor-frame { /* 通过iframe的URL参数控制界面缩放 */ } }

更彻底的办法是在生成编辑URL的时候加上&mobile=1参数，LibreOffice Online会启用一个简化版的移动界面。虽然功能少一些，但至少按钮能点准了。

6. 实测对比：迁移前后的真实数据

6.1 性能数据对比

我在同一台服务器（4核8G，Ubuntu 22.04）上分别跑了OnlyOffice和LibreOffice Online，测试了不同并发数下的响应时间和资源占用：

这个数据很直观：LibreOffice Online在并发处理上确实有明显优势。20并发的时候OnlyOffice已经撑不住了，LibreOffice Online还能稳定运行。

6.2 格式兼容性实测

我准备了20个不同格式的文档（docx、xlsx、pptx各若干），分别用两个方案打开，对比显示效果：

• 纯文本和简单表格：两者都没问题，显示一致。
• 复杂表格（合并单元格、条件格式）：OnlyOffice偶尔会出现边框错位，LibreOffice Online基本完美。
• PPT动画和切换效果：两者都不支持，这个没办法，Web端都这样。
• 中文排版：配置好字体后，两者都正常。但LibreOffice Online的断行算法更接近桌面版。

6.3 升级维护的体验差异

OnlyOffice升级的时候，我一般要预留半天时间，因为总会有一些意外情况。LibreOffice Online升级相对简单，因为它的核心是LibreOffice，只要LibreOffice的API不变，loolwsd的升级基本是平滑的。

不过LibreOffice Online的社区版更新频率不如OnlyOffice，有些新功能可能要等比较久。但考虑到稳定性，这个 trade-off 我觉得可以接受。

7. 几个容易被忽略的运维细节

7.1 日志排查的正确姿势

loolwsd的日志在/var/log/loolwsd/目录下，主要有两个文件：loolwsd.log和loolwsd.err。大部分问题看这两个日志就能定位。

但有一个坑：日志级别。默认的日志级别是warning，很多有用的信息看不到。可以在loolwsd.xml里把日志级别调到debug：

<logging> <level desc="Log level">debug</level> </logging>

调完之后重启服务，日志会详细很多。不过生产环境不建议长期开debug，日志量太大。

7.2 文档锁与并发编辑

LibreOffice Online默认支持多人同时编辑同一个文档，但它的锁机制和OnlyOffice不太一样。OnlyOffice是段落级锁，LibreOffice Online是文档级锁——也就是说，同一个人打开文档后，其他人只能以只读模式打开。

如果你需要多人同时编辑，需要在配置里开启<per_document>相关的选项。不过实测下来，多人同时编辑的体验还是不如OnlyOffice流畅，这个要有心理准备。

7.3 备份与恢复策略

LibreOffice Online本身不存储文档，所以备份的重点是你的后端存储。但有一个细节要注意：自动保存的临时文件。LibreOffice Online在编辑过程中会生成临时文件，如果服务异常退出，这些临时文件可能会残留。建议定期清理/var/cache/loolwsd/目录。

8. 一些个人体会和后续扩展思路

从OnlyOffice迁移到LibreOffice Online，整体感受是：前者更像一个商业产品，后者更像一个基础设施。OnlyOffice开箱即用，界面漂亮，但资源消耗大、升级折腾；LibreOffice Online部署麻烦一点，但稳定、省资源、可控性强。

如果你团队里有比较强的运维能力，或者对资源成本比较敏感，LibreOffice Online是更好的选择。如果团队更看重快速上线和界面美观，OnlyOffice可能更合适。

后续我还在研究几个方向：一是把LibreOffice Online和对象存储（比如MinIO）结合，实现文档的分布式存储；二是研究一下Collabora Online的商业版，看看有没有值得付费的高级功能；三是探索一下在Kubernetes上部署LibreOffice Online的可行性，毕竟容器化部署在运维上会方便很多。

这些内容如果后面有新的进展，我再整理出来分享。如果你在部署过程中遇到什么问题，也欢迎一起交流。