在若依前后端分離項目中集成 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 實現文檔轉換與縮略圖生成功能，豐富系統的文檔管理能力。
