OnlyOffice 协同编辑与 document.key 的关系详解

🔑 OnlyOffice 协同编辑与 document.key 的关系详解

在使用 OnlyOffice DocumentServer 进行协同编辑时，很多人都会接触到一个关键参数：document.key。它常常出现在我们集成 OnlyOffice 与业务系统（如 Nextcloud、Odoo、自建系统）的 JSON 配置中。那么，这个 document.key 到底有什么作用？ 它和协同编辑的稳定性、安全性又有什么关系？为什么会出现“文件版本已更改。 将重新加载页面”的错误提示？本文来系统讲解。

1️⃣ 协同编辑的基本原理

OnlyOffice 的协同编辑流程大致如下：

1. 用户请求文档：业务系统（如网盘、OA）生成一个配置 JSON 并传递给 DocumentServer。
2. DocumentServer 渲染文档：根据 JSON 中的参数（文件地址、权限、用户信息等），启动一个文档编辑会话。
3. WebSocket 通讯：多个用户在浏览器中通过 WebSocket 与 DocumentServer 保持连接，实时同步编辑操作。
4. 回调保存：编辑完成后，DocumentServer 会通过回调 URL 将最终文件保存回业务系统。

在这个过程中，DocumentServer 必须要有一种机制来识别 同一个文档的不同编辑会话，否则就无法判断哪些用户属于同一个协同房间。这就是 document.key 的作用。

2️⃣ 什么是 document.key？