在若依前后端分离项目中集成 ONLYOFFICE 以实现在线预览、编辑和协作功能
在若依前后端分离项目中集成 ONLYOFFICE 以实现在线预览、编辑和协作功能
概述
ONLYOFFICE 是一款开源的在线文档编辑套件，可实现文档预览、编辑、协作与转换等功能，可通过 Docker 部署 DocumentServer 服务，并通过 HTTP API 或 WOPI 接口与第三方系统集成。在 RuoYi 前后端分离项目（RuoYi-Vue）中集成 ONLYOFFICE，可使系统具备高效的在线文档处理能力，并保持与现有微服务架构的无缝衔接。
前置准备
环境要求
- Linux 服务器，推荐 CentOS 7+ / Ubuntu 20.04+。
- Docker 与 Docker-Compose 已安装并配置正常运行。
- RuoYi-Vue 前端和 Spring Boot 后端项目已能正常启动并通过 JWT 进行用户认证。
部署 OnlyOffice DocumentServer
-
拉取并启动官方镜像
docker pull onlyoffice/documentserver docker run -i -t -d -p 8000:80 --name onlyoffice-documentserver onlyoffice/documentserver该命令可快速完成 OnlyOffice 文档服务的部署，并将服务映射至主机 8000 端口。
-
高可用/集群部署（可选）
如需更高可用性，可参考官方 docker-compose 示例进行集群化部署。
DocumentServer 配置
开放私有网络地址访问
默认情况下，DocumentServer 会拒绝访问私有 IP，需要修改配置以允许内网地址：
docker exec -it onlyoffice-documentserver /bin/bash
cd /etc/onlyoffice/documentserver
nano default.json
在 "request-filtering-agent" 节点下添加：
"request-filtering-agent": {"allowPrivateIPAddress": true,"allowMetaIPAddress": true
},
保存后重启容器即可生效。
启用 JWT 验证（可选）
若需在 OnlyOffice 与后端之间使用 JWT 签名验证，可在容器环境变量或 default.json 中配置：
JWT_ENABLED=true
JWT_SECRET=your_secret
JWT_HEADER=Authorization
JWT_IN_BODY=true
启用后，OnlyOffice 将通过 JWT 校验编辑请求，有效提升安全性。
后端集成 (RuoYi Spring Boot)
引入依赖
在 ruoyi-admin 或后端主工程的 pom.xml 中加入 OnlyOffice SDK 依赖：
<dependency><groupId>com.gitee.onlyoffice</groupId><artifactId>onlyoffice-sdk</artifactId><version>1.1.0</version>
</dependency>
（示例座标，仅供参考；也可自行封装 HTTP 客户端）。
配置 application.yml
file:online:preview:onlyoffice:domain: http://localhost:8000download: http://your-domain/api/onlyoffice/downloadcallback: http://your-domain/api/onlyoffice/callbacksecret: your_jwt_secret # 若启用 JWT
统一管理 OnlyOffice 服务地址、文档下载和回调接口。
实现 OnlyOffice 服务 API 封装
在后端创建 OnlyOfficeService，封装读取上述配置，生成编辑器所需的 DocumentConfig 对象（包括 fileType、documentKey、token 等字段）。可参考 Lucy-OnlyOffice 项目源码以及相关开源示例，快速上手 OnlyOffice SDK 的基本调用。
回调接口实现
在 OnlyOfficeController 中添加回调接口，用于接收编辑后的文件写回请求：
@PostMapping("/onlyoffice/callback")
public ResponseEntity<?> callback(@RequestBody CallbackRequest request) {// 通过 request.getUrl() 下载编辑后的文档并替换原存储return ResponseEntity.ok(Map.of("error", 0));
}
注意处理并发写入及异常重试，确保文件完整性与数据一致性。
前端集成 (RuoYi-Vue)
安装依赖
在 ruoyi-ui 根目录执行：
npm install @onlyoffice/document-editor-vue --save
# 如遇 peer 依赖冲突，可加 --legacy-peer-deps
即可引入 OnlyOffice 的 Vue 编辑组件。
新增编辑页面与路由
-
在
src/views/document下新建OnlyOfficeEditor.vue。 -
在
src/router/index.js中添加路由：{path: '/document/edit/:id',name: 'OnlyOfficeEditor',component: () => import('@/views/document/OnlyOfficeEditor.vue'),meta: { title: '文档协作编辑', noCache: true } } -
在侧边栏菜单中新增“文档编辑”导航入口。
编写 OnlyOffice 编辑组件
在 OnlyOfficeEditor.vue 中：
<template><DocumentEditor :config="config" />
</template>
<script>
import { DocumentEditor } from '@onlyoffice/document-editor-vue';
export default {components: { DocumentEditor },data() { return { config: {} }; },async created() {const res = await this.$axios.get(`/api/onlyoffice/config/${this.$route.params.id}`);this.config = res.data;}
}
</script>
组件将自动渲染在线编辑器，并内置协作与保存逻辑。
测试与优化
多人协作测试
- 不同账户登录系统，打开同一文档，验证实时光标与内容同步。
- 测试段落锁定与全体锁定模式，确保多人协作稳定性。
文件存储方案
建议结合 MinIO 对象存储管理文档文件，以减轻本地磁盘压力并提升可扩展性，可参考相关教程。
总结与建议
通过上述步骤，您即可在 RuoYi 前后端分离项目中无缝集成 ONLYOFFICE，实现文档的在线预览、编辑与多人协作。建议在生产环境中开启 HTTPS、JWT 验证与日志监控，并结合 CDN 缓存编辑器静态资源，以进一步提升安全性与性能。未来可考虑结合 Lucy-OnlyOffice 实现文档转换与缩略图生成功能，丰富系统的文档管理能力。