OnlyOffice 应用实战：企业云盘打开 Word 即编辑，劳动合同范本也能在线改、自动留痕

🌐 演示地址：http://ruoyioffice.com | 📦 源码1·GitHub：ruoyi-office | 📦 源码2·GitCode：ruoyi-office | 📦 源码3·Gitee：ruoyi-office | 💬 微信：17156169080（备注「RuoYi Office」）

HR 把《企业通用劳动合同模板.docx》丢进云盘共享文件夹，同事却只能下载→本地改→再上传「V2 最终版」。OnlyOffice 接入企业系统后，目标体验应是：点开即编辑、编辑过程像 Word、关掉也不白改、历史可回看。 本文按 RuoYi Office 企业云盘真实路径写「应用实战」——不重复讲 Docker 怎么起容器，而讲从业务入口到回存留痕怎么跑通。

▲ 应用链路：云盘打开 → 签发 config → 在线编辑 / forcesave → 回调写版本；底部「已保存」不等于业务已落库

引言：应用实战要解决什么？

集成文关心「服务能不能起来」；应用文关心「员工敢不敢用」。现场反馈最多的四类问题：

RuoYi Office 的用法可以概括成一句话：云盘管「可协同的文件资产」；合同模块管「正式套打成稿」。 劳动合同「空白范本」放云盘在线改完全合理；员工入职后的正式合同正文，仍建议走合同中心。

一、场景：云盘里的劳动合同范本

典型路径：

1. 行政/HR 将 企业通用劳动合同模板.docx 上传到企业云盘「人事/模板」目录
2. 设置组织分享（至少「可在线编辑」）
3. 同事在列表点 在线编辑 → 新标签打开 /oa/cloud/file-editor?id=…&editable=1
4. 浏览器内出现完整 OnlyOffice 功能区（字体、样式、协作、保护等）
5. 顶栏可开 历史记录；关页前系统会尽量强制回存

▲ 实机：独立编辑页内嵌 OnlyOffice，打开《企业通用劳动合同模板》，页脚显示「所有更改已保存」——下文会解释它和业务落库的差别

▲ 入口在云盘列表：预览走 editable=0，在线编辑走 editable=1

二、一次点击背后的四步（应用视角）

列表「在线编辑」  → window.open 独立编辑页（长时编辑不堵主界面）    → GET /oa/file/onlyoffice/config  （documentKey + 双 JWT + callbackUrl）      → Document Server 用 download token 拉文件        → 用户编辑；每约 90s / 开历史前 / 关页 → forcesave          → POST callback（status=2 关闭保存 / status=6 强制保存）            → 写对象存储 + 更新主表 URL + createVersion(AUTOSAVE)

对应后端能力集中在 OaFileOnlyOfficeServiceImpl：buildEditorConfig、forceSave、handleCallback。

▲ 分享权限决定能不能进 edit：只有「可在线编辑」及以上，才会签发可写权限

三、实战关键点（相对「装好能打开」）

3.1 独立编辑页，而不是弹窗 iframe

长文档（合同动辄十几页）适合整页工作台。路由 /oa/cloud/file-editor 隐藏菜单、独立标签；关闭时先 forcesave / 销毁编辑器，再关窗口，降低「关标签=白改」概率。

3.2 「所有更改已保存」≠ 业务版本已生成

编辑器页脚的已保存，多半表示内容进了 Document Server 缓存。业务库 oa_file_version 要等：

• status=2
  ：会话正常关闭保存
• status=6
  ：forcesave 强制保存

因此产品上要做：定时 forcesave、开历史前先 forcesave、关页触发回存。否则用户截图「已保存」来投诉，你却查不到版本行。

3.3 双 JWT：下载一条、回调一条

Document Server 拉文件、回调业务时都不带登录 Cookie。实现上：

• download token
  ：签在 document.url，临时拉取私有存储文件
• callback token
  ：带上 fileId / userId / tenantId / editable，回存时恢复租户，避免版本落到 tenant_id=0

// 回调必须带租户，否则版本列表「写了却查不到」callbackToken 含 tenantId、bizId、editable、userId …callbackUrl = base + "/admin-api/oa/file/onlyoffice/callback?token=" + callbackToken;customization.forcesave = true; // 允许命令服务强制保存

3.4 历史记录：只读预览 + 恢复即新版本

顶栏「历史记录」打开抽屉后：

• 带 versionId 打开 → 只读，禁止 callback 写回
• 恢复某一版 → 下载旧内容重新上传新 URL → 再 createVersion(RESTORE)，中间历史不断

这和「把指针拨回旧版」不同，审计更干净（详见云盘版本专文）。

3.5 云盘范本 vs 合同正式稿

应用落地时先问清：这份劳动合同是「大家改范本」，还是「某人入职成稿」——入口选错，权限与归档都会拧巴。

四、最小配置清单（能跑起来）

# application.yml 片段（根节点以工程配置为准）onlyoffice:  enabled: true  server-url: https://your-ds-host   # Document Server  jwt-secret: your-secret            # 与 DS 一致  callback-base-url: https://your-api-host  # DS 能访问到的业务地址

还要确认：

1. DS 能访问 callback-base-url（容器网络最常踩坑）
2. 业务能访问 server-url（前端加载 api.js）
3. 文件扩展名在白名单（docx/xlsx/pptx 等；PDF 通常仅预览）

更细的 Docker / JWT / documentKey 设计见《OnlyOffice 集成实战》《云盘协同编辑》两篇；本文只保证「应用路径正确」。

五、推荐体验路径

在线演示：http://ruoyioffice.com/web/（账号 admin / admin123）

1. OA → 企业云盘
   ：上传或打开一份 docx（如劳动合同范本）。
2. 点 在线编辑，确认新标签出现 OnlyOffice，可改文字、看页脚保存状态。
3. 点 历史记录，再改一版后刷新，确认版本递增。
4. 用只读分享账号打开同一文件，确认只能预览不能改。
5. （对照）合同中心打开正式合同正文，感受另一条业务链路。

源码仓库：GitHub | GitCode | Gitee

常见问题（FAQ）

为什么关浏览器标签会丢修改？

若未触发 forcesave / status=2，内容可能只在 DS 缓存。应依赖关页钩子 + 定时 forcesave，并教育用户「页脚已保存≠业务版本」。

能否多人同时改同一份范本？

OnlyOffice 支持协同会话；前提是同一 documentKey 策略正确、网络与 DS 资源够用。高冲突文档建议拆副本或加锁流程。

PDF 能在线编辑吗？

一般白名单仅预览。编辑请用 docx 等可写格式。

和微信里常见「OnlyOffice 从零部署」文有何不同？

部署文解决「装上」；本文解决「云盘业务怎么用、怎么不丢稿、范本和正式合同怎么分工」。两者互补。

私有 MinIO 文件 DS 拉不到怎么办？

不要把桶直接暴露给 DS；用带 download token 的业务中转下载（本系统默认路径）。

结语

OnlyOffice 应用实战的及格线，不是 iframe 里出现编辑器，而是：打开路径清晰、权限控得住、关页不丢稿、历史可追溯、业务边界清楚（云盘范本 vs 合同成稿）。 RuoYi Office 用独立编辑页 + 四端点 + 版本表，把「像 Word 一样改」嵌进 OA 云盘——劳动合同模板只是其中一个高频场景。

你们现在合同/制度是下载上传，还是已经在线改？有没有踩过「显示已保存其实没落库」？欢迎评论区交流。

💡 想要体验 RuoYi Office 的强大功能？

🌐 在线演示：http://ruoyioffice.com/web/（账号 admin / admin123）

📦 源码仓库：GitHub | GitCode | Gitee

💬 技术咨询：添加微信 17156169080，备注「RuoYi Office」

⭐ 如果觉得不错，请给个 Star 支持一下！