在若依前后端分离项目中集成 ONLYOFFICE 以实现在线预览、编辑和协作功能-CSDN博客

本文链接：https://blog.csdn.net/wykqh/article/details/147629200

在若依前后端分离项目中集成 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:8000
        download: http://your-domain/api/onlyoffice/download
        callback: http://your-domain/api/onlyoffice/callback
        secret: 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 实现文档转换与缩略图生成功能，丰富系统的文档管理能力。