RuoYi OnlyOffice 集成

以下指导涵盖了在 RuoYi-Vue 前后端分离框架 中集成 OnlyOffice 的关键步骤，帮助你在已有的 RuoYi 项目中实现在线文档编辑与预览的功能。整体流程主要分为以下几个部分：

1. 部署 OnlyOffice Document Server
2. 配置反向代理（可选）
3. 后端配置：编写获取文档信息的接口
4. 前端配置：嵌入 OnlyOffice 前端 SDK
5. 编写前端页面：使用 OnlyOffice 编辑器
6. 调试与常见问题排查

下面将逐步进行讲解。

---

一、部署 OnlyOffice Document Server

在将 OnlyOffice 集成到 RuoYi 的系统之前，需要先部署好 OnlyOffice Document Server。有以下几种部署方式：

1. Docker 部署

   • 官方镜像：onlyoffice/documentserver
   • 命令示例：

     bash
     docker run -i -t -d -p 8080:80 --name onlyoffice \
       onlyoffice/documentserver

   • 如果需要启用 HTTPS，需自行配置 HTTPS 证书，或者在外层通过 Nginx/Traefik 等进行反向代理。

2. Linux/Windows 手动部署

   • 可从 官方文档 获取对应操作系统的安装包与安装方式。

注意：确保你部署完成后，能够在浏览器中访问到 OnlyOffice Document Server 的 Welcome 页面（例如：http://localhost:8080/）。

---

二、配置反向代理（可选）

如果你的 OnlyOffice Document Server 和 RuoYi 后端分离运行在不同的域名或端口下，尤其在生产环境中，通常会在外层用 Nginx 做反向代理。这样做的目的：

• 提供统一且合法的域名或 HTTPS 访问（避免浏览器跨域问题或安全限制）
• 更好地管理端口、证书及负载均衡等

Nginx 示例

以 onlyoffice.example.com 为例，你可以编写一个简单的 Nginx 配置：

nginx
server {
    listen 80;
    server_name onlyoffice.example.com;
    # 如果需要 HTTPS，需要在此处配置证书listen 443 ssl; 并添加证书配置等

    location / {
        proxy_pass         http://127.0.0.1:8080/;
        proxy_http_version 1.1;
        proxy_set_header   Upgrade $http_upgrade;
        proxy_set_header   Connection "upgrade";
        proxy_set_header   Host $host;
    }
}

完成后，你就可以通过 http://onlyoffice.example.com 来访问 OnlyOffice Document Server。

---

三、后端配置：编写获取文档信息的接口

1. RuoYi-Vue 后端项目结构概览

RuoYi-Vue 的后端是一个基于 Spring Boot 的 Java 项目，大致结构如下：

text
ruoyi
 └─ ruoyi-admin
     └─ src
         └─ main
             └─ java
                 └─ com.ruoyi.web.controller.system  # 业务接口层
                 └─ ...

你可以在对应的业务接口层创建新的 Controller，用于处理 OnlyOffice 相关逻辑，比如：

java
@RestController
@RequestMapping("/system/onlyoffice")
public class OnlyOfficeController {

    /**
     * 获取文档编辑所需要的配置信息
     * @param docId 文档ID，比如数据库中的文件ID
     * @return 用于OnlyOffice编辑器初始化的配置JSON
     */
    @GetMapping("/config")
    public AjaxResult getDocumentConfig(@RequestParam("docId") Long docId) {
        // 1. 根据docId查询数据库，获取文件存储路径、文件名称等信息
        // 2. 生成 OnlyOffice 初始化所需的各种URL，包括：
        //    - 编辑回调URLcallbackUrl（optional）
        //    - 文档下载URL fileUrl
        //    - 是否只读权限等

        // 仅做示例
        String fileUrl = "http://your-file-server/documents/sample.docx";
        String callbackUrl = "http://your-api-server/system/onlyoffice/callback";

        // 构造返回
        Map<String, Object> config = new HashMap<>();
        config.put("fileUrl", fileUrl);
        config.put("callbackUrl", callbackUrl);
        config.put("docTitle", "示例文档");
        // ...还可附带其他自定义信息

        return AjaxResult.success(config);
    }

    /**
     * OnlyOffice 编辑回调接口（可选）
     * 用于接收文档被编辑后的事件，比如自动保存
     */
    @PostMapping("/callback")
    public AjaxResult handleCallback(@RequestBody Map<String, Object> data) {
        // 根据 OnlyOffice 的官方文档，回调数据中会包含 status、url 等信息
        // 你可以根据 status 判断文档是否已编辑结束，然后将 url 指向的最新文档下载到自己服务器保存
        return AjaxResult.success();
    }
}

关键点：

• fileUrl 必须是一个可被 OnlyOffice 访问到的文件地址。
• 如果要保存编辑后的文档，需要配置 callbackUrl，并在回调中取到编辑后的文件地址，然后将其下载或转存到自己的文件系统中。

注意：除了回调实现“文档实时保存”外，也可以在编辑器上点击“保存”时，通过自定义事件与 RuoYi 后端交互。

---

四、前端配置：嵌入 OnlyOffice 前端 SDK

1. 获取 OnlyOffice 前端 SDK

OnlyOffice 的 Web Editor 前端通常通过以下方式引入：

html
<script type="text/javascript" src="https://onlyoffice.example.com/web-apps/apps/api/documents/api.js"></script>

如果你不想直接使用线上版本，也可以将 api.js 放入你自己的静态资源服务器，然后在前端引入。

2. 在 RuoYi-Vue 前端项目中引用

RuoYi-Vue 前端是一个基于 Vue + Vite 或 Vue + Webpack（根据版本不同）的单页面应用（SPA）。通常目录结构如下：

text
ruoyi-ui
 └─ src
     ├─ api         # axios 请求接口定义
     ├─ assets      # 静态资源
     ├─ components  # 公共组件
     ├─ views       # 业务页面
     └─ ...

你可以在需要用到编辑功能的页面（例如 views/onlyoffice/index.vue）中，通过 <script> 或者在公共模板 public/index.html 中引入。

---

五、编写前端页面：使用 OnlyOffice 编辑器

下面给出一个简化的示例，假设在 views/onlyoffice/Editor.vue 中：

html
<template>
  <div class="onlyoffice-editor-page">
    <!-- 用于放置OnlyOffice编辑器的容器 -->
    <div id="placeholder" style="width: 100%; height: 100vh;"></div>
  </div>
</template>

<script setup>
// 1. 从 Vue Router 或参数中获取 docId
import { onMounted } from 'vue'
import { useRoute } from 'vue-router'
import { getConfig } from '@/api/onlyoffice' // 假设封装了后端的接口

const route = useRoute()

onMounted(async () => {
  const docId = route.query.docId
  if (!docId) return

  // 2. 请求后端接口，获取文档的配置信息
  const res = await getConfig({ docId })
  if (res.code === 200) {
    initOnlyOfficeEditor(res.data)
  }
})

// 3. 调用 OnlyOffice 前端SDK，初始化编辑器
function initOnlyOfficeEditor(config) {
  // config 示例
  // {
  //   fileUrl: 'http://your-file-server/documents/sample.docx',
  //   callbackUrl: 'http://your-api-server/system/onlyoffice/callback',
  //   docTitle: '示例文档'
  // }
  window.DocEditor = new DocsAPI.DocEditor('placeholder', {
    width: '100%',
    height: '100%',
    documentType: 'word', // 可根据文件类型自动判断
    document: {
      fileType: 'docx',
      key: new Date().getTime().toString(), // 用于标识文件版本的 key
      title: config.docTitle || '未命名文件',
      url: config.fileUrl,
    },
    editorConfig: {
      callbackUrl: config.callbackUrl,
      mode: 'edit'  // or 'view'
      // 用户信息、语言等也可以在这里设置
    }
  })
}
</script>

<style scoped>
.onlyoffice-editor-page {
  padding: 0;
  margin: 0;
}
</style>

要点说明：

• DocsAPI.DocEditor('placeholder', options) 是官方提供的初始化方法。第一个参数为容器 DOM 的 ID，第二个参数为配置对象。
• documentType 通常可以是 'word' | 'cell' | 'slide'，对应 Word、Excel、PPT。
• document.fileType 必须与 url 中实际文件类型匹配，例如 .docx、.xlsx、.pptx 等。
• document.key 用于区分文档版本，若你想要 OnlyOffice 帮你做历史版本，需要保证每次更新后 key 都变化。
• editorConfig 中包含了大量可选配置项，可以设置语言、多用户协作等。

---

六、调试与常见问题排查

1. 跨域问题
   如果前端 (RuoYi) 和 OnlyOffice Document Server 不同域名/端口，需要在 Nginx 端或后端接口端做好 CORS 配置，或者使用统一域名进行代理。

2. callbackUrl 未被调用

   • 确保你在 editorConfig.callbackUrl 中填写的地址可以被外部访问。
   • 检查 OnlyOffice 的日志，确认是否有报错信息。

3. 编辑器无法加载文档

   • 检查 fileUrl 是否可被 OnlyOffice 服务器访问到。
   • 可能是 document.fileType 与实际文件后缀不一致。

4. 前端报 DocsAPI is not defined

   • 确认引入了 api.js，并且在执行 DocsAPI.DocEditor 前，api.js 已被加载。
   • 可以在 public/index.html 中全局引入，或者在组件中通过 <script src="..."></script> 的方式引入（不建议在 Vue 组件内部 script 标签直接引入外部脚本，最好放在全局或通过 Vite/Webpack 配置引用）。

5. 如何保存编辑后的文档

   • 走 OnlyOffice 的回调流程：在后端 handleCallback 中拿到新的文档地址 url，然后主动下载并覆盖到你的存储位置。
   • 或者在前端通过 OnlyOffice 提供的 JS API “获取文档”并自行上传，但需要额外配置编辑器插件或方法。多数情况下配合后端回调更方便。

---

总结

1. 准备好 OnlyOffice Document Server 运行环境（Docker 或手动安装），确保浏览器可访问。
2. 在 RuoYi 后端 编写接口，提供文档的访问地址和回调地址。
3. 在 RuoYi 前端 引入 OnlyOffice 的前端 SDK，并编写页面组件，初始化编辑器。
4. 处理跨域、回调保存文档、权限控制等细节。

按照以上步骤即可实现 在 RuoYi-Vue 前后端分离项目中集成 OnlyOffice。后续若需要实现更多功能（多用户协作、批注、版本管理等），可深入阅读 OnlyOffice 官方文档 并结合你们的业务逻辑进一步拓展。祝你集成顺利!