当前位置：首页 > news >正文

Springboot集成OnlyOffice

news 2025/11/15 11:28:37

一、OnlyOffice 是什么？为什么选择它？

ONLYOFFICE 是一款开源免费的全功能办公套件，核心优势在于文档在线编辑、实时协同与灵活集成能力，完美适配企业级私有化部署需求。它支持 Word、Excel、PPT、PDF 等主流格式的查看与编辑，还提供 AI 辅助编辑（文本生成、翻译、语法检查）、跨平台协作（内置聊天、音视频通话）、三级加密（静态 / 传输 / 端到端）等进阶功能，且拥有完善的中文文档和活跃社区。

相比 OpenOffice、Office Online，OnlyOffice 的核心竞争力体现在：

开源可定制：社区版基于 AGPL 3.0 协议，支持二次开发（如突破 20 人协同限制）；

集成友好：提供全面的 REST API，支持与 40+ 平台无缝对接（Nextcloud、Moodle 等）；

协同高效：支持字符级实时协作，多人编辑无冲突，自带修订记录与评论功能；

生态完善：覆盖桌面端（Windows/Linux/macOS）、移动端（iOS/Android）与网页端，满足全场景需求。

适合场景：企业内部文档协作平台、SaaS 产品嵌入在线编辑功能、私有化办公系统搭建等。

二、Docker 快速部署 OnlyOffice Docs 服务

Docker 是部署 OnlyOffice 最便捷的方式，无需复杂依赖配置，一键启动完整服务（含文档服务器、数据库）。

前提条件

已安装 Docker 与 Docker Compose（推荐 Docker 版本 ≥ 20.10）；

服务器内存 ≥ 2GB（官方建议，否则编辑时可能卡顿）；

开放 80 端口（或自定义端口），确保网络可访问。

部署步骤

1. 拉取官方镜像

OnlyOffice 文档服务器的官方镜像已包含核心依赖，直接拉取即可：

# 拉取最新版 OnlyOffice Docs 镜像

docker pull onlyoffice/documentserver

注意：若 Docker Hub 访问受限，可通过国内镜像源同步（如阿里云镜像仓库），避免自行打包镜像（易出现兼容性问题）。

简化版（无需 MySQL，使用内置 SQLite）：

docker run --name onlyoffice-docs -d -p 8088:80 --restart=always onlyoffice/documentserver

适合测试环境，生产环境建议用 MySQL 保证数据可靠性。

onlyoffice默认开启token,如果不需要token可以加-e JWT_ENABLED=false

4. 验证部署成功

容器启动后（约 1-2 分钟），访问 http://服务器IP:8088，若看到 OnlyOffice 欢迎页面，则部署成功：

常见问题解决

权限不足：若容器启动失败，添加 --privileged=true 参数赋予权限；

端口占用：修改 -p 映射端口（如 8089:80），避免与其他服务冲突；

中文字体缺失：进入容器复制本地中文字体（如 SimHei.ttf）到 /var/www/onlyoffice/documentserver/core-fonts，执行 documentserver-generate-allfonts.sh 刷新缓存。

SpringBoot的集成

在动手写代码前，我们需要先理清集成的核心逻辑，准备好所需环境，避免后续踩坑。

核心原理：OnlyOffice 与 Spring Boot 如何交互？

OnlyOffice 的集成本质是 “前端渲染 + 后端通信” 的组合：

前端：通过 OnlyOffice 提供的 JavaScript API，在页面中嵌入文档编辑器组件，负责文档的可视化编辑、格式渲染；
后端（Spring Boot）：作为 “中间桥梁”，承担三个关键角色：
1. 提供文档文件的存储（本地 / 云存储）与访问接口（如下载文档的 URL）；
2. 处理 OnlyOffice 的回调通知（如文档编辑完成后，接收 OnlyOffice 返回的编辑结果，更新本地文件）。

简单来说：用户在前端编辑文档时，操作会实时同步到 OnlyOffice 服务端；编辑完成后，OnlyOffice 会通知 Spring Boot 后端，后端再从 OnlyOffice 获取最新文档并保存 —— 整个流程需保证 “文件地址可访问”“接口权限合法”“回调处理可靠”。

步骤 1：配置 OnlyOffice 服务地址

在 application.properties 中配置 OnlyOffice 服务地址和回调接口地址：

# OnlyOffice Document Server 地址（前端加载编辑器用）
onlyoffice.server.url=http://onlyoffice-ip:8080
# 后端回调接口地址（OnlyOffice 保存文档时调用）
onlyoffice.callback.url=http://your-springboot-ip:8081/api/onlyoffice/callback
# 文档存储路径（本地存储示例）
doc.storage.path=/app/documents/

步骤 2：后端核心接口实现

2.1 文档配置接口（给前端返回编辑器参数）

前端加载 OnlyOffice 编辑器时，需要从后端获取文档的配置信息（如文件地址、权限、回调地址等）。

import com.fasterxml.jackson.databind.ObjectMapper;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.web.bind.annotation.*;
import java.util.HashMap;
import java.util.Map;@RestController
@RequestMapping("/api/onlyoffice")
public class OnlyOfficeController {@Value("${onlyoffice.server.url}")private String onlyofficeServerUrl;@Value("${onlyoffice.callback.url}")private String callbackUrl;@Value("${doc.storage.path}")private String docStoragePath;// 文档配置接口：前端请求此接口获取编辑器参数@GetMapping("/config")public Map<String, Object> getDocConfig(@RequestParam String fileName) throws Exception {// 1. 构建文档访问地址（后端提供的文档下载地址）String docUrl = "http://your-springboot-ip:8081/api/doc/download?fileName=" + fileName;// 2. 配置 OnlyOffice 编辑器参数Map<String, Object> config = new HashMap<>();config.put("document", Map.of("fileType", fileName.split("\\.")[1], // 文档类型（如 docx、xlsx）"key", fileName, // 文档唯一标识（建议用文件MD5或UUID）"title", fileName,"url", docUrl // 文档下载地址（OnlyOffice 会从这里拉取文件）));// 3. 配置编辑器权限（是否可编辑）config.put("editorConfig", Map.of("callbackUrl", callbackUrl, // 保存回调地址"user", Map.of("id", "1", "name", "张三"), // 当前用户信息"mode", "edit" // 模式：edit（编辑）/ view（查看）));// 4. 配置 OnlyOffice 服务地址config.put("documentServerUrl", onlyofficeServerUrl);return config;}
}

2.2 文档下载接口（OnlyOffice 拉取文件用）

OnlyOffice 编辑器需要从后端下载文档进行编辑，因此需要提供一个下载接口：

import org.apache.commons.io.FileUtils;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import java.io.File;@RestController
@RequestMapping("/api/doc")
public class DocController {@Value("${doc.storage.path}")private String docStoragePath;// 文档下载接口：OnlyOffice 从这里拉取文件@GetMapping("/download")public ResponseEntity<byte[]> downloadDoc(@RequestParam String fileName) throws Exception {File docFile = new File(docStoragePath + fileName);if (!docFile.exists()) {return new ResponseEntity<>(HttpStatus.NOT_FOUND);}// 设置响应头（指定文件类型）HttpHeaders headers = new HttpHeaders();headers.setContentType(MediaType.APPLICATION_OCTET_STREAM);headers.setContentDispositionFormData("attachment", fileName);return new ResponseEntity<>(FileUtils.readFileToByteArray(docFile), headers, HttpStatus.OK);}
}

2.3 回调接口（OnlyOffice 保存文档时调用）

当用户编辑完成并点击保存后，OnlyOffice 会将编辑后的文档通过回调接口发送到后端，后端需要接收并保存文件。

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import org.apache.commons.io.FileUtils;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;
import java.io.File;
import java.net.URL;@RestController
@RequestMapping("/api/onlyoffice")
public class OnlyOfficeCallbackController {@Value("${doc.storage.path}")private String docStoragePath;private final ObjectMapper objectMapper = new ObjectMapper();// 回调接口：OnlyOffice 保存文档时调用@PostMapping("/callback")public ResponseEntity<String> callback(@RequestBody JsonNode body) throws Exception {// 1. 解析回调参数String status = body.get("status").asText(); // 状态：2 - 已保存，3 - 保存并关闭if (!"2".equals(status) && !"3".equals(status)) return ResponseEntity.ok("{\"error\":0}");String url = body.get("url").asText(); // 编辑后文档的临时URL（OnlyOffice 提供）String fileName = body.get("key").asText(); // 文档唯一标识（与配置中的key一致）// 2. 状态为2或3时，下载并保存文档if ("2".equals(status) || "3".equals(status)) {// 从 OnlyOffice 提供的临时URL下载编辑后的文件File editedFile = new File(docStoragePath + fileName);FileUtils.copyURLToFile(new URL(url), editedFile);}// 3. 必须返回 {"error":0}，否则 OnlyOffice 会认为回调失败并重复调用return ResponseEntity.ok("{\"error\":0}");}
}

步骤 3：前端页面集成 OnlyOffice 编辑器

前端需要引入 OnlyOffice 的 JS 脚本，并通过后端返回的配置信息初始化编辑器。

示例（HTML + JavaScript）：

<!DOCTYPE html>
<html>
<head><meta charset="UTF-8"><title>OnlyOffice 编辑示例</title><!-- 引入 OnlyOffice 编辑器脚本（地址为部署的 Document Server） --><script src="http://onlyoffice-ip:8080/web-apps/apps/api/documents/api.js"></script>
</head>
<body><!-- 编辑器容器 --><div id="onlyofficeEditor" style="width: 100%; height: 800px;"></div><script>// 从后端获取文档配置fetch('http://your-springboot-ip:8081/api/onlyoffice/config?fileName=test.docx').then(response => response.json()).then(config => {// 初始化 OnlyOffice 编辑器new DocsAPI.DocEditor("onlyofficeEditor", config);});</script>
</body>
</html>

查看全文

http://www.dtcms.com/a/610847.html