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？