为什么越来越多人用 OnlyOffice?

将 脚本之家 设为“星标⭐”

前言

2026年5月19日，OnlyOffice DocumentServer 9.4.0正式发布。

这次更新有一个标志性的变化——官方社区版从9.4.0开始强制使用轻量模式，不再提供原有的标准模式。

传统的分布式架构，合并成了单进程单体化架构。

这意味着部署一个在线文档编辑服务，从“docker-compose多容器编排”变成了“docker run一键启动”。

今天这篇文章，我就把OnlyOffice为什么越来越多人用的原因，从头到尾给你拆解一遍。

希望对你会有所帮助。

一、OnlyOffice到底是什么？

有些小伙伴可能会说：“OnlyOffice不就是个开源办公套件吗？跟LibreOffice有什么区别？”

区别很大。

LibreOffice是桌面软件，你装在自己电脑上，编辑本地文件。

它的在线版本是Collabora Online，基于LibreOffice核心。

OnlyOffice的核心是DocumentServer——一个独立的在线文档编辑后端服务。你可以把它理解成：在服务器上跑了一个“云端的Office” ，用户通过浏览器访问，文档存在你的服务器上，不经过任何第三方。

用人话说：OnlyOffice是“文档编辑后端服务”，不是完整的网盘或办公套件。

它负责在浏览器里渲染和编辑文档，至于文档存哪里、谁有权限访问、怎么管理文件夹——这些需要你的系统来提供。

二、一张图看懂OnlyOffice的架构

文档管理器和文档存储服务由集成商提供——可以是OnlyOffice DocSpace，也可以是你自己服务器上的实现。DocumentServer负责文档编辑、转换、命令和构建服务。

三、底层原理

document.key——整个协同编辑的“身份证”。

这是理解OnlyOffice最关键的一点。

很多开发者第一次接触OnlyOffice时会以为：浏览器直接编辑服务器上的Word文件。实际上不是。

真实的流程是：

浏览器编辑的是ONLYOFFICE内部缓存中的协同编辑文件（Editor.bin） ，而不是原始Word文件。

document.key是当前文档内容版本的唯一身份标识。

它不是文件ID，是当前协同编辑版本ID。

它决定了五件事：多个用户是否进入同一个协同会话、是否复用已有的Editor.bin文件、是否认为文件已经变化、是否重新下载原始文件、是否属于同一个编辑版本。

完整的编辑生命周期：

第一次打开文档（key = key0）→ 原始Word文件被下载 → 转换为Editor.bin缓存在/var/lib/onlyoffice/documentserver/App_Data中。

多人进入协同编辑 → 使用同一个key0 → 进入同一个协同编辑会话，大家编辑的是Editor.bin。

编辑过程中 → 所有修改都在缓存中，原始Word文件可能完全没有变化。

真正生成新Word文件的时机是所有人退出编辑或强制保存之后，此时生成output.docx，callback收到status = 2或6。

为什么会出现“内容丢失”？

很多系统收到回调后没有下载output.docx，仍然保留旧的原始文件。

下次重新打开时，ONLYOFFICE下载的仍然是旧文件。

实际上不是内容丢失，而是根本没有保存新的output.docx。

四、Java集成OnlyOffice

4.1 部署DocumentServer

docker run -i -t -d -p 8080:80 --restart=always \  -e JWT_ENABLED=true \  -e JWT_SECRET='your-secret-key' \  onlyoffice/documentserver:9.4.0

访问 http://localhost:8080 验证是否成功。

4.2 Spring Boot后端：生成编辑器配置

@RestControllerpublicclassDocumentController{@Value("${onlyoffice.docserver.url}")private String docServerUrl;@Value("${onlyoffice.callback.url}")private String callbackUrl;@GetMapping("/edit/{docId}")public String editDocument(@PathVariable String docId, Model model){        Document doc = documentService.findById(docId);// 构建编辑器配置        Map<String, Object> config = Map.of("document", Map.of("fileType", doc.getExtension(),"key", doc.getVersionKey(),  // 关键！每次内容变化要换key"title", doc.getName(),"url", doc.getDownloadUrl()            ),"editorConfig", Map.of("callbackUrl", callbackUrl,"mode", "edit","user", Map.of("id", "1", "name", "老张")            )        );        model.addAttribute("config", config);        model.addAttribute("docServerUrl", docServerUrl);return"editor";    }}

关键点：key每次文档内容变化后必须更新，否则OnlyOffice会认为文件没变，继续用缓存的Editor.bin。

4.3 处理保存回调

OnlyOffice在文档保存时会回调你的服务：

@PostMapping("/callback")@ResponseBodypublic String handleCallback(@RequestBody Map<String, Object> data){// 状态2或6表示文档已准备好保存if ("2".equals(data.get("status")) || "6".equals(data.get("status"))) {        String downloadUrl = (String) ((Map) data.get("url")).get("url");// 下载并保存文档        saveDocument(downloadUrl, (String) data.get("key"));// 更新版本key，让下次打开时重新加载        documentService.updateVersionKey((String) data.get("key"));    }return"{\"error\":0}";}

4.4 前端页面

<scriptsrc="http://docserver-url/web-apps/apps/api/documents/api.js"></script><divid="editor"></div><script>const docEditor = new DocsAPI.DocEditor("editor", {document: { fileType: "docx", key: "key0", title: "demo.docx", url: "..." },editorConfig: { callbackUrl: "http://your-server/callback", mode: "edit" },width: "100%", height: "100%"    });</script>

五、轻量模式

这是9.4版本最重要的变化。

传统标准模式依赖Nginx + PostgreSQL + RabbitMQ + 多Node进程协同，部署时需要处理服务依赖顺序、健康检查、MQ异常恢复。对中小企业私有化部署、Docker单容器/NAS/群晖/ARM低配机器、POC验证场景来说，这些依赖过于沉重。

轻量模式将原本依赖消息队列和数据库的分布式架构，合并为单进程单体化架构。

状态全部内存化，无需额外数据库维护；单机文件状态管理，不再依赖RabbitMQ。

启动轻量模式只需要在环境变量中加上：

docker run -itd -p 8080:80 \  -e MEMORY_MODE=true \  onlyoffice/documentserver:9.4.0

轻量模式特别适合中小企业/小团队文档协作、POC验证与开发测试、NAS/Docker单容器部署、ARM低配机器、离线内网环境。

如果你的业务需要集群、高可用、横向扩展，仍然建议使用标准模式。

六、各项对比

核心差异可以概括为三句话：

• OnlyOffice给的是“Microsoft格式兼容性” ——如果你团队主要用.docx和.xlsx，OnlyOffice的round-trip fidelity最强
• Collabora给的是“轻量+ODF生态” ——如果你用户主要用ODF格式，Collabora的空闲内存只有1GB左右
• Microsoft 365给的是“原生体验” ——如果不需要私有化部署，微软云端仍是最省心的选择

七、优缺点

优点

1. Microsoft格式兼容性最强自研OOXML引擎，对.docx、.xlsx、.pptx的round-trip fidelity在开源方案中最好。界面和交互方式与Microsoft Office非常接近，迁移成本低。

2. 轻量模式部署极简9.4版本起社区版强制轻量模式，单进程架构，docker run一键启动。对2C4G的小机器和NAS环境非常友好。

3. 原生在线协作实时多人协同编辑、版本历史、评论批注、更改追踪。协同模式支持Fast和Strict两种。

4. 安全功能全内置JWT双重校验、HTTPS强制、回调防伪造、字段脱敏。不需要额外付费购买安全模块。

5. 生态丰富构建了40多个连接器和50多个插件，可以嵌入Nextcloud、ownCloud、Seafile、Odoo、Moodle等系统，也兼容Office 365和SharePoint。

6. 官方社区版免费社区版采用AGPL v3协议，核心编辑功能完整。9.4版本取消了20个并发连接限制。

缺点

1. 资源占用比Collabora高空闲内存约2GB，而Collabora只有约1GB。对于2GB以下内存的VPS，OnlyOffice可能跑不起来。

2. 非OOXML格式兼容性一般OnlyOffice主要优化了OOXML格式。如果你处理大量ODF或旧版.doc文件，可能不如Collabora。

3. document.key机制容易踩坑很多开发者第一次接触时会把document.key当成文件ID，导致协同会话错乱、版本冲突、内容看似“丢失”。理解这个机制需要时间。

4. 社区版不支持集群轻量模式只适合单机小规模部署。需要高可用和横向扩展时，必须使用企业版。

八、适用场景

九、写在最后

回到最初的问题：为什么越来越多人用OnlyOffice？

答案不复杂——因为它把“在线文档编辑”这件事，从“买授权”变成了“自己部署”。

商业文档SDK按年收费、按并发收费、多人协同要升级旗舰版。

而OnlyOffice把核心编辑能力开源出来，你用Docker就能跑，数据在自己服务器上，不经过任何第三方。

更关键的是，9.4版本把部署复杂度砍了一大截。

过去部署OnlyOffice要处理PostgreSQL、RabbitMQ、多Node进程，很多人卡在环境配置上就放弃了。

现在轻量模式单进程架构，docker run -e MEMORY_MODE=true一条命令就能启动。

document.key机制是最大的坑，也是最大的价值。

理解它需要时间，但理解之后你会发现，这套机制让协同编辑、版本管理、缓存复用都变得优雅。

当然，OnlyOffice不是银弹。

资源占用比Collabora高、社区版不支持集群、非OOXML格式兼容性一般。

但对于企业OA集成、私有化文档协作、Microsoft格式为主的团队来说，它已经是一个非常成熟的选项。

十、参考资源

• OnlyOffice官网：https://www.onlyoffice.com
• DocumentServer GitHub：https://github.com/ONLYOFFICE/DocumentServer
• API文档：https://api.onlyoffice.com
• Docker镜像：onlyoffice/documentserver:9.4.0