完整教程：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？

• 定义：
  document.key 是文档会话的唯一标识符（string 类型）。

• 用途：

  1. 确保不同文件之间不会混淆。
  2. 在同一文件被修改后，可以区分新旧版本。
  3. 作为协同编辑的“房间号”，保证多个用户能进入同一个协作会话。

---

3️⃣ document.key 的使用规则

1. 唯一性
   每一个正在编辑的文件都必须有一个唯一的 key。如果多个文件使用相同的 key，DocumentServer 会误判它们是同一个协作房间。

2. 版本变化
   当文件内容发生更新（比如被替换、覆盖上传），必须生成一个新的 key，否则用户可能仍然看到旧版本，编辑器会产生“文件版本已更改。 将重新加载页面”的提示。

3. 长度限制
   key 最长 128 个字符，通常建议用 文件 ID + 时间戳/版本号 来保证唯一性。

---

4️⃣ 示例配置

一个典型的 JSON 配置（由业务系统传给 DocumentServer）如下：

{
"document": {
"fileType": "docx",
"key": "file12345-v2",
"title": "示例文档.docx",
"url": "https://yourdomain.com/files/12345.docx"
},
"editorConfig": {
"callbackUrl": "https://yourdomain.com/onlyoffice/callback",
"user": {
"id": "u001",
"name": "Alice"
}
}
}

• key: "file12345-v2"
  表示这是 ID=12345 的文件的第 2 个版本。
• 当该文档被再次覆盖更新时（callback回调保存文档），可以生成 file12345-v3 作为新的 key。

---

5️⃣ 协同编辑与 document.key 的关系

• 多人实时编辑
  所有使用相同 document.key 的会话会被 DocumentServer 归为同一组，进入相同的协同编辑房间。

• 避免数据冲突
  如果文件已被替换（例如新版本上传），必须更新 document.key，否则旧用户的编辑内容可能会覆盖新版本。

• 缓存与同步
  DocumentServer 会缓存部分文档内容。如果 key 不变，它会认为还是同一个文件，从而继续复用缓存。换了 key，才会重新拉取最新内容。

---

6️⃣ 最佳实践

1. 使用 文件 ID + 文件更新时间 生成 key

   document_key = f"{file_id}-{last_modified_timestamp}"

   确保不同版本的 key 不会冲突。

2. 避免使用纯随机值
   否则同一个文件每次打开都会被识别为不同的文档，导致无法协同。

3. 保证跨用户一致
   所有用户在同一时间段打开同一个文档时，必须拿到完全一致的 document.key。

---

总结

• document.key 是 OnlyOffice 协同编辑的核心参数，本质上是 协作房间的唯一 ID。
• 同一份文件 → 相同 key → 用户进入同一个协同编辑会话。
• 新版本文件 → 新 key → 避免版本冲突与缓存问题。

正确管理 document.key，就能让 OnlyOffice 协同编辑更加稳定可靠。