去年做的一个后台管理系统里业务方提了个很硬的需求直接在网页里打开数据库里的Word/Excel/PPT改完一键保存回服务器不要下载到本地再上传。一开始我想着用富文本编辑器糊弄过去结果领导拿着排版带图片表格的合同文档一比直接把我否了。后来调研了一圈锁定了一套完整度最高的开源方案——SpringBoot后端 ONLYOFFICE在线编辑。折腾了两周把文档服务器部署、JWT鉴权、SpringBoot签名签发、回调落库整条链路抻通了。这篇就把整个整合过程、原理和踩过的坑一次性写清楚给同样被在线编辑折磨的开发做个参考。1. 先把在线编辑这件事的底层逻辑理顺1.1 ONLYOFFICE是什么和传统预览方案差在哪ONLYOFFICE是一套开源的Office文档处理方案由服务端和前端编辑器两部分组成。服务端叫ONLYOFFICE Docs老版本叫Document Server负责文档格式解析、渲染、协同编辑、格式转换这些重活前端编辑器则是一套现成的JS组件通过iframe嵌进你自己的页面里。用户看到的编辑界面跟微软Office高度相似基本不需要培训。很多项目以前是怎么做的要么用浏览器自带的PDF预览要么接微软的Office Online嵌入要么用纯前端的富文本编辑器。这几个方案各有各的硬伤我整理成一张表方案优点硬伤PDF/图片预览实现简单只能看不能改需求直接不满足微软Office Online兼容性极好必须公网可访问国内网络和域名受限私有化部署基本没戏富文本编辑器轻量灵活Word排版还原度差复杂文档直接崩排版Excel/PPT完全做不到ONLYOFFICE格式还原度高、支持协同、可私有化需要单独部署一套服务配置和鉴权上手门槛偏高和SpringBoot整合之后ONLYOFFICE解决的是网页里的Office交互这部分而你自己的SpringBoot系统仍然管理文件存储、用户权限、业务逻辑、回调落库。一句话文档服务器不存你的业务数据它只是读你的文件、给用户编辑、再把你保存的结果还给你。1.2 一条编辑请求的完整链路搞懂ONLYOFFICE的整个工作链路后面调接口才不会懵。一次完整的在线编辑流程大概是这样的用户点击编辑 - 浏览器请求你的SpringBoot后端获取editor配置和JWT token - 前端加载文档服务器上的api.js用config初始化编辑器 - 编辑器以iframe形式渲染在页面上 - 文档服务器根据config里的document.url主动去你的后端下载原始文件 - 用户开始编辑 - 用户点保存/关闭文档服务器把新文档临时存起来 - 文档服务器调用config里的callbackUrl通知你的后端文档改好了 - 你的后端拿着回调里给的临时url下载新文档覆盖旧文件这里最关键的一点是ONLYOFFICE的文档服务器是被设计成无状态的它不负责管理你的文件生命周期。文件始终在你的SpringBoot后端手里文档服务器只是临时拉走、处理完再送回来。这种设计的好处很明显——文档服务器可以随便横向扩展重启业务数据不会丢。所以整条链路上有三个视角要分清楚很多人卡就卡在这里浏览器视角需要能访问你的业务页面也需要能访问文档服务器的前端资源api.js、编辑器页面。文档服务器视角需要能访问你的后端提供的document.url下载原始文件和callbackUrl保存回调。后端视角需要能访问文档服务器回调时给的临时下载地址。这三个视角任何一个不通编辑器就会各种奇怪的白屏、转圈、保存失败。后面排查部分我会专门展开讲。2. 环境准备DocumentServer部署和配置里的暗坑2.1 Docker一键部署但少做了三件事会很难受部署ONLYOFFICE Docs最省事的方式是Docker一条命令就能跑起来docker run -d \ --name onlyoffice-documentserver \ -p 80:80 \ -v onlyoffice_data:/var/www/onlyoffice/Data \ -e JWT_ENABLEDtrue \ -e JWT_SECRETQ0k3hFzL9pTrXw7yVb5mNd8sGu2aRc4e \ onlyoffice/documentserver:latest看着简单对吧但有几个点不提前处理后面全是坑。第一JWT_SECRET必须显式设置。这是我踩过最深的坑。如果环境变量里不写JWT_SECRET容器每次启动都会生成一个随机密钥而且对外不可见。你前一天调试好的前端和后端token第二天容器一重启全部验签失败。所以你一定要用-e JWT_SECRETxxxxx固定住这个密钥并且SpringBoot里配置的密钥和它完全一致。第二密钥长度必须足够。ONLYOFFICE用的是HS256签名算法密钥至少32字节。你要是图省事写个secret文档服务器那边校验直接报错签出来的token死活验不过去。第三大数据量文件要调Nginx的body size。ONLYOFFICE容器里自带Nginx默认的client_max_body_size很小上传大文件时会有问题。建议加上环境变量-e NGINX_CLIENT_MAX_BODY_SIZE100m另外提一句ONLYOFFICE文档服务器本身资源占用不低里面自带了nginx、postgresql、redis启动后就是好几个进程。低配的1核2G机器跑起来会很卡至少给2核4G并发编辑人数多的话建议再往上加。启动后可以用http://你的服务器地址/healthcheck确认服务状态页面返回true就说明在正常运行。2.2 JWT鉴权编辑器、文档服务器、后端三方如何互认ONLYOFFICE的鉴权机制是很多第一次接触的人搞不明白的地方。简单说它用JWT做三方互认但和一般系统登录态的JWT用途完全不一样这里签的不是用户身份而是编辑器配置和回调内容没被别人篡改。后端生成编辑器配置config之后需要对整个config做一次HS256签名把签出来的token塞进config的token字段。前端拿到这个带token的config去初始化编辑器编辑器会把token传给文档服务器文档服务器验签通过才允许打开文档。保存回调时也是一个道理。文档服务器回调你的SpringBoot接口时会在HTTP请求头里带Authorization: Bearer token这个token就是对回调JSON做的签名。你的后端收到回调后必须用同一个JWT_SECRET去验签验签通过才允许执行文件覆盖操作防止有人伪造回调请求把任意内容写入你的文件存储。用jjwt库实现的话生成token的核心代码如下SecretKey key Keys.hmacShaKeyFor(props.getJwtSecret().getBytes(StandardCharsets.UTF_8)); String token Jwts.builder() .setHeaderParam(typ, JWT) .setPayload(JSON.toJSONString(config)) .signWith(key, SignatureAlgorithm.HS256) .compact();这里有个容易被忽略的细节JWT的payload是整个config的JSON字符串不是某个单独的字段。验证回调时解析出来的Claims对象里直接就是status、url、key这些字段因为jjwt会把payload的JSON展开成Claims。也就是说Claims claims Jwts.parserBuilder() .setSigningKey(key) .build() .parseClaimsJws(callbackToken) .getBody(); int status claims.get(status, Integer.class);不用再套一层去取字段直接按顶层键取值就行。2.3 网络可达性为什么localhost能打开但编辑器白屏很多人在本地调试时喜欢把SpringBoot的document.url写成http://localhost:8080/xxx结果浏览器打开页面正常编辑器却一直白屏转圈。原因是localhost这个地址在文档服务器的视角里根本不存在。文档服务器跑在Docker容器里它去访问localhost时访问的是容器自己而不是你本机的SpringBoot进程。这跟浏览器是完全不同的视角。所以配置document.url和callbackUrl时一定不能用localhost/127.0.0.1要用局域网IP或者域名。如果文档服务器和SpringBoot都在同一台物理机上Docker容器要访问宿主机服务可以用宿主机局域网IP。依赖host.docker.internal这种写法只在Mac/Windows的Docker Desktop里好用Linux服务器上经常没有这个域名映射最稳妥的方案就是直接用内网IP。比如SpringBoot跑在192.168.1.20文档服务器跑在192.168.1.10那么document.urlhttp://192.168.1.20:8080/onlyoffice/stream?fileId1callbackUrlhttp://192.168.1.20:8080/onlyoffice/callback在联调之前先把这三个地址在对应的视角里用curl验证一遍能省下大量的排查时间。具体怎么验我放在第5章讲。3. SpringBoot后端从令牌签发到回调落库3.1 配置项与依赖先定好骨架后端要做的事情无非四件给前端返回编辑器配置、给文档服务器提供文件下载接口、接收文档服务器的保存回调、把新文件落盘/落库。先定好pom依赖和配置结构。pom里加jjwt依赖用0.11.x或者更新的版本。有人还拿网上老教程用0.9.1在Java 11以后的版本上运行会遇到缺javax.xml.bind的坑SpringBoot版本一高就报NoClassDefFoundError白折腾半天dependency groupIdio.jsonwebtoken/groupId artifactIdjjwt-api/artifactId version0.11.5/version /dependency dependency groupIdio.jsonwebtoken/groupId artifactIdjjwt-impl/artifactId version0.11.5/version scoperuntime/scope /dependency dependency groupIdio.jsonwebtoken/groupId artifactIdjjwt-jackson/artifactId version0.11.5/version scoperuntime/scope /dependency配置类用ConfigurationProperties统一管理Data Component ConfigurationProperties(prefix onlyoffice) public class OnlyOfficeProperties { /** 文档服务器地址如 http://192.168.1.10:80 */ private String docServiceUrl; /** 与onlyoffice容器内JWT_SECRET保持一致 */ private String jwtSecret; /** 业务系统对外可访问地址用来拼接document.url和callbackUrl */ private String publicBaseUrl; /** 文件存储目录 */ private String storageDir ./data/files; }对应的application.ymlonlyoffice: doc-service-url: http://192.168.1.10:80 jwt-secret: Q0k3hFzL9pTrXw7yVb5mNd8sGu2aRc4e public-base-url: http://192.168.1.20:8080 storage-dir: ./data/filespublic-base-url这一项就是上章说的SpringBoot对外可达地址必须按真实部署环境填。3.2 生成编辑器配置和token的Service核心方法作用是根据文件的ID查出文件信息拼出config签名返回给前端。这一步相当于整个在线编辑的入场券。public MapString, Object buildEditorConfig(Long fileId) throws IOException { FileRecord file fileMapper.selectById(fileId); if (file null) { throw new IllegalArgumentException(文件不存在); } String fileExt FilenameUtils.getExtension(file.getFileName()).toLowerCase(); MapString, Object document new HashMap(); document.put(title, file.getFileName()); document.put(url, props.getPublicBaseUrl() /onlyoffice/stream?fileId fileId); document.put(fileType, fileExt); document.put(key, buildFileKey(file)); MapString, Object editorConfig new HashMap(); editorConfig.put(callbackUrl, props.getPublicBaseUrl() /onlyoffice/callback); editorConfig.put(lang, zh-CN); editorConfig.put(mode, edit); MapString, Object config new HashMap(); config.put(documentType, detectDocumentType(fileExt)); config.put(document, document); config.put(editorConfig, editorConfig); String token Jwts.builder() .setHeaderParam(typ, JWT) .setPayload(JSON.toJSONString(config)) .signWith(Keys.hmacShaKeyFor(props.getJwtSecret().getBytes(StandardCharsets.UTF_8)), SignatureAlgorithm.HS256) .compact(); config.put(token, token); return config; }documentType根据扩展名决定word类文档传textexcel传spreadsheetppt传presentation这个字段不写对的话编辑器可能打不开对应的格式。这里我特别想展开讲的是key这个字段。ONLYOFFICE用它来标识文档的唯一版本规则是内容变化后key必须跟着变化。很多教程只说key是文档的唯一标识没提内容变了key要变结果做出来的功能是——第一次打开能编辑能保存保存完了再打开编辑器显示的还是老内容。因为你用了同一个key文档服务器会从缓存里给你拉旧文档。我的做法是给文件记录加一个版本字段每次保存成功后版本号1key就拼上版本号和时间戳private String buildFileKey(FileRecord file) { return String.format(%d-%d-%d, file.getId(), file.getVersion(), file.getUpdateTime().getTime()); }这样保证每次编辑内容变化后key都不相同。3.3 回调接口状态码就是保存流程的心电图ONLYOFFICE保存时状态码是整套回调逻辑的核心。直接给一张表看清楚状态码的含义和应对逻辑status含义后端建议处理1用户关闭编辑器且文档已保存如果回调里带url拉取新文件覆盖旧文件2文档保存完成拉取url、覆盖文件、版本号13打开/保存文档出错记录日志做告警6用户正在编辑暂无操作忽略7用户手动触发强制保存CtrlS拉取url、覆盖文件回调接口要在SpringBoot里允许最大的请求体大小因为ONLYOFFICE在某些版本下会把changeshistory这类大段JSON也塞进回调body里。实现时先验签再取状态码再做文件覆盖PostMapping(/onlyoffice/callback) public MapString, Object callback( RequestHeader(value Authorization, required false) String authorization, RequestBody(required false) String body) { String token null; if (authorization ! null authorization.startsWith(Bearer )) { token authorization.substring(7); } else if (StringUtils.hasText(body)) { JSONObject raw JSON.parseObject(body); token raw.getString(token); } if (!StringUtils.hasText(token)) { return Collections.singletonMap(error, 1); } Claims claims verifyJwt(token); int status claims.get(status, Integer.class); if (status 1 || status 2 || status 7) { String downloadUrl claims.get(url, String.class); if (StringUtils.hasText(downloadUrl)) { Long fileId Long.valueOf(claims.get(key, String.class).split(-)[0]); saveEditedFile(downloadUrl, fileId); } } return Collections.singletonMap(error, 0); }saveEditedFile的实现就是下载文档服务器提供的临时下载地址把字节流覆盖到本地存储private void saveEditedFile(String downloadUrl, Long fileId) throws IOException { FileRecord file fileMapper.selectById(fileId); Path targetPath Paths.get(props.getStorageDir(), file.getId() . file.getExt()); try (InputStream in new URL(downloadUrl).openStream()) { Files.copy(in, targetPath, StandardCopyOption.REPLACE_EXISTING); } file.setVersion(file.getVersion() 1); file.setUpdateTime(new Date()); fileMapper.updateById(file); }这里要注意文档服务器给的临时下载地址有时效性回调收到后要尽快拉取别做异步延时任务否则容易拉的时候已经过期了。3.4 文件流出接口文档服务器怎么拿到原始文件既然文档服务器要根据document.url来下载原始文件后端就必须提供一个不要求登录鉴权的文件流接口或者至少对文档服务器放行。这个接口返回原始文件的字节流注意Content-Type不用纠结用application/octet-stream即可ONLYOFFICE会根据config里的fileType去做解析。GetMapping(/onlyoffice/stream) public ResponseEntityResource stream(RequestParam Long fileId) throws IOException { FileRecord file fileMapper.selectById(fileId); Path path Paths.get(props.getStorageDir(), file.getId() . file.getExt()); Resource resource new FileSystemResource(path); return ResponseEntity.ok() .contentType(MediaType.APPLICATION_OCTET_STREAM) .body(resource); }接口不用做文件扩展名校验交给文档服务器处理。但建议加一层简单的请求来源校验至少不要让这个接口裸奔在公网上不然任何人都能遍历fileId下载文件。可以加白名单IP、加一个单独的静态token或者放在内网网段里。4. 前端接入把编辑器嵌进自己的页面4.1 原生方式接入搞懂初始化参数前端接入是非常轻量的一件事只要引入文档服务器的api.js然后调用new DocsAPI.DocEditor就能把编辑器渲染到页面上。先看不依赖框架的原生写法!DOCTYPE html html head meta charsetUTF-8/ title在线编辑/title /head body div ideditor styleheight: 100vh;/div !-- 从文档服务器加载api.js -- script srchttp://192.168.1.10/web-apps/apps/api/documents/api.js/script script fetch(/onlyoffice/config?fileId1) .then(res res.json()) .then(config { new DocsAPI.DocEditor(editor, config); }); /script /body /htmlapi.js是ONLYOFFICE编辑器组件的入口文件它会自动往页面里塞iframe。DocEditor的第一个参数是iframe渲染占位的div id第二个参数就是后端返回的完整config。文档服务器的资源路径是固定的http://文档服务器地址/web-apps/apps/api/documents/api.js整个接入过程前端其实不需要理解ONLYOFFICE内部复杂的WebSocket协同逻辑它已经把协同、自动保存这些事都封装好了。你只需要保证后端返回的config正确以及api.js能加载到剩下就是开着编辑器让它自己跑。4.2 Vue3里的接入细节组件生命周期要处理好到了Vue3里接入逻辑需要处理组件的生命周期销毁问题。很多人直接在组件里写个onMounted就去初始化编辑器结果切路由时iframe没有被正确回收页面就崩了。示范一下Vue3的写法template div idonlyoffice-container styleheight: 100%; width: 100%/div /template script setup import { onMounted, onBeforeUnmount } from vue; const props defineProps({ fileId: { type: Number, required: true } }); let docEditor null; async function loadEditor() { // 动态加载api.js避免路由切换重复执行script导致报错 if (!window.DocsAPI) { await new Promise((resolve, reject) { const script document.createElement(script); script.src http://192.168.1.10/web-apps/apps/api/documents/api.js; script.onload resolve; script.onerror reject; document.head.appendChild(script); }); } const res await fetch(/onlyoffice/config?fileId${props.fileId}); const config await res.json(); docEditor new window.DocsAPI.DocEditor(onlyoffice-container, config); } onMounted(loadEditor); onBeforeUnmount(() { if (docEditor window.DocsAPI) { docEditor.destroyEditor(); docEditor null; } }); /script有两个细节想提醒。一是api.js别放在script标签里静态加载尤其在单页应用里页面切来切去很容易重复执行导致初始化报错。动态加载并缓存window.DocsAPI最稳妥。二是组件销毁时必须调用destroyEditor()不然编辑器内部的WebSocket连接和事件监听会残留长时间切换页面后页面会越来越卡。如果你的系统只有查看权限还要把editorConfig.mode设置成view或者让后端在buildEditorConfig里根据当前用户权限动态决定mode是edit还是view只读场景就不给编辑按钮。5. 实战中会遇到的高频问题与排查路径5.1 编辑器一直转圈问题优先级排查编辑器一直转圈是集成时出现概率最高的问题我在联调阶段遇到无数次。不要慌按优先级逐层排查第一步浏览器F12打开Network面板看api.js能不能加载。如果看到请求都发不出去说明浏览器访问不了文档服务器。先检查文档服务器地址是否可从浏览器所在网络访问ping不通就去解决网络策略。第二步看编辑器的iframe请求是否返回200。如果iframe加载了但里面白屏多半是文档服务器渲染阶段出了问题直接看文档服务器日志docker logs -f onlyoffice-documentserver第三步在SpringBoot的访问日志里看有没有/onlyoffice/stream请求进来。如果后端日志完全没有这个请求说明文档服务器根本访问不到document.url。最常见的原因是document.url用了localhost/内网不通地址。这时候直接在文档服务器容器里curl一下验证docker exec -it onlyoffice-documentserver curl http://192.168.1.20:8080/onlyoffice/stream?fileId1容器里能curl通编辑器就大概率能正常打开curl不通就回去改public-base-url。第四步确认config里的token字段是否正常生成。如果文档服务器的日志里出现Invalid token或JWT verification failed之类的字样检查一下SpringBoot里的jwt-secret和容器里的JWT_SECRET是否完全一致字符大小写、空格都要对齐。5.2 保存回调报签名不通过或者调用404保存时最容易翻车的有两类问题。一类是回调签名校验不过。注意ONLYOFFICE回调请求的Authorization头格式是Bearer token有些封装好的客户端会把整个header值原样传给你你可能要在后端把Bearer前缀剥掉。另外验签用的库版本要一致别在SpringBoot里用一套JWT库、又自己手动拼了另一套算法密钥字符集也要统一用UTF-8。另一类是回调接口根本调不通。你本地开发时回调地址写着http://localhost:8080/onlyoffice/callback文档服务器容器访问不到或者你在SpringBoot里加了拦截器把回调请求拦下来要求登录态导致返回401。ONLYOFFICE要求回调接口返回{error:0}且HTTP状态码是200任何中间环节的跳转、拦截、权限校验都可能让回调功亏一篑。建议这个接口独立配置放行规则不经过Shiro/Spring Security的登录过滤链。5.3 保存后看到的还是老内容key的刷新策略这个问题我第3章提过但因为它太典型了值得单独拿出来说。症状是第一次打开文档编辑、保存都正常关闭再打开文档还是老样子你保存的内容跟消失了似的。看ONLYOFFICE官方文档对key的解释文档服务器会用key做缓存相同key的文档在一定时间内不会重新拉取。你把key写成固定值比如就传文件ID文档服务器就认为这是同一个文档的同一版本直接把缓存里的老内容给你了。正确的做法是key要能反映文档内容是否变化。我用的方案是把文件ID、版本号、更新时间拼在一起。版本号在每次保存回调成功后自增这样每次打开编辑器拿到的key都不相同强制文档服务器重新加载最新文档。还有个衍生问题如果用户在编辑器里还没保存但你已经给他返回了一个新key的config会不会冲突ONLYOFFICE的推荐做法是如果文档还在编辑会话中不要换key等回调保存成功后再让前端用新config重新初始化。这个顺序一定要理清。6. 进阶扩展把在线编辑变成真正的生产力6.1 对接MinIO做文件持久化落地到生产环境一般不会把文件存本地磁盘而是接对象存储。ONLYOFFICE和MinIO对接的思路很清晰document.url指向MinIO的预签名下载地址回调保存时把新文件上传回MinIO。MinIO的预签名URL要注意有效期设置给的太短文档服务器处理慢一点就过期了。我习惯给10分钟足够编辑器打开文档。同时ONLYOFFICE回调时临时下载地址也是有时效的后端收到回调后要立刻下载别把任务丢到消息队列里慢慢处理。调用MinIO的工具类网上很多核心就两个操作生成预签名URL和上传文件。这里不展开写配置了只想提醒一点——MinIO存储桶的访问策略不要设成public预签名URL已经足够ONLYOFFICE使用了设成public等于把文档裸奔在公网上。6.2 历史版本和批注的获取思路很多同学问能不能拿到ONLYOFFICE的批注“能不能看历史修改记录”。这两个诉求都指向同一件事版本历史。ONLYOFFICE在保存回调的body里会带history、changesurl等字段changesurl是修改记录变更列表的下载地址。如果你要做一个历史版本功能可以在回调保存时把这个changesurl下载下来存库之后在页面上展示修改历史。批注和修订的数据本质上是在编辑会话期间由文档服务器维护的你要是想彻底落到自己的业务表里常用的做法是解析docx文件里的comment xml这个工作量比较大如果没有硬性要求不如直接依赖ONLYOFFICE自带的版本历史界面来得实在。另外有个参数叫assemblyFormatAsOrigin如果你发现ONLYOFFICE保存后的文档格式和老文件对不上比如docx变成odt需要把它配成true让文档服务器以原始格式保存。这个参数在config的editorConfig里配置。6.3 安全与资源规划建议最后聊两句生产环境的事情。ONLYOFFICE文档服务器因为是私有化部署所有流量都走你的网络安全上比公有云方案好一些但该做的防护一样不能少document.url和流接口不要裸奔加IP白名单或者内部Token校验。回调接口返回数据最好也做校验确认key对应的文件ID在你系统里真实存在。容器建议单独划一个网段只开放必要的端口ONLYOFFICE默认的80端口不要直接映射到公网。定期备份onlyoffice_data卷的数据虽然文档正文在你手里但一些临时缓存和历史记录还是在这套卷里的。我用ONLYOFFICE跑了小半年最大的体会是这个项目的文档服务器和SpringBoot的耦合点并不多——后端只需要写好config生成、文件下载、回调保存三个接口前端套一层api.js剩下复杂的格式转换、协同编辑全交给ONLYOFFICE处理。但恰恰是这三个接口里的细节JWT密钥一致性、key的版本策略、三端网络可达性决定了整体能不能跑得顺。希望这篇把链路讲清楚的文章能帮你少走几步弯路。
SpringBoot整合ONLYOFFICE实现Word/Excel/PPT在线编辑实战
去年做的一个后台管理系统里业务方提了个很硬的需求直接在网页里打开数据库里的Word/Excel/PPT改完一键保存回服务器不要下载到本地再上传。一开始我想着用富文本编辑器糊弄过去结果领导拿着排版带图片表格的合同文档一比直接把我否了。后来调研了一圈锁定了一套完整度最高的开源方案——SpringBoot后端 ONLYOFFICE在线编辑。折腾了两周把文档服务器部署、JWT鉴权、SpringBoot签名签发、回调落库整条链路抻通了。这篇就把整个整合过程、原理和踩过的坑一次性写清楚给同样被在线编辑折磨的开发做个参考。1. 先把在线编辑这件事的底层逻辑理顺1.1 ONLYOFFICE是什么和传统预览方案差在哪ONLYOFFICE是一套开源的Office文档处理方案由服务端和前端编辑器两部分组成。服务端叫ONLYOFFICE Docs老版本叫Document Server负责文档格式解析、渲染、协同编辑、格式转换这些重活前端编辑器则是一套现成的JS组件通过iframe嵌进你自己的页面里。用户看到的编辑界面跟微软Office高度相似基本不需要培训。很多项目以前是怎么做的要么用浏览器自带的PDF预览要么接微软的Office Online嵌入要么用纯前端的富文本编辑器。这几个方案各有各的硬伤我整理成一张表方案优点硬伤PDF/图片预览实现简单只能看不能改需求直接不满足微软Office Online兼容性极好必须公网可访问国内网络和域名受限私有化部署基本没戏富文本编辑器轻量灵活Word排版还原度差复杂文档直接崩排版Excel/PPT完全做不到ONLYOFFICE格式还原度高、支持协同、可私有化需要单独部署一套服务配置和鉴权上手门槛偏高和SpringBoot整合之后ONLYOFFICE解决的是网页里的Office交互这部分而你自己的SpringBoot系统仍然管理文件存储、用户权限、业务逻辑、回调落库。一句话文档服务器不存你的业务数据它只是读你的文件、给用户编辑、再把你保存的结果还给你。1.2 一条编辑请求的完整链路搞懂ONLYOFFICE的整个工作链路后面调接口才不会懵。一次完整的在线编辑流程大概是这样的用户点击编辑 - 浏览器请求你的SpringBoot后端获取editor配置和JWT token - 前端加载文档服务器上的api.js用config初始化编辑器 - 编辑器以iframe形式渲染在页面上 - 文档服务器根据config里的document.url主动去你的后端下载原始文件 - 用户开始编辑 - 用户点保存/关闭文档服务器把新文档临时存起来 - 文档服务器调用config里的callbackUrl通知你的后端文档改好了 - 你的后端拿着回调里给的临时url下载新文档覆盖旧文件这里最关键的一点是ONLYOFFICE的文档服务器是被设计成无状态的它不负责管理你的文件生命周期。文件始终在你的SpringBoot后端手里文档服务器只是临时拉走、处理完再送回来。这种设计的好处很明显——文档服务器可以随便横向扩展重启业务数据不会丢。所以整条链路上有三个视角要分清楚很多人卡就卡在这里浏览器视角需要能访问你的业务页面也需要能访问文档服务器的前端资源api.js、编辑器页面。文档服务器视角需要能访问你的后端提供的document.url下载原始文件和callbackUrl保存回调。后端视角需要能访问文档服务器回调时给的临时下载地址。这三个视角任何一个不通编辑器就会各种奇怪的白屏、转圈、保存失败。后面排查部分我会专门展开讲。2. 环境准备DocumentServer部署和配置里的暗坑2.1 Docker一键部署但少做了三件事会很难受部署ONLYOFFICE Docs最省事的方式是Docker一条命令就能跑起来docker run -d \ --name onlyoffice-documentserver \ -p 80:80 \ -v onlyoffice_data:/var/www/onlyoffice/Data \ -e JWT_ENABLEDtrue \ -e JWT_SECRETQ0k3hFzL9pTrXw7yVb5mNd8sGu2aRc4e \ onlyoffice/documentserver:latest看着简单对吧但有几个点不提前处理后面全是坑。第一JWT_SECRET必须显式设置。这是我踩过最深的坑。如果环境变量里不写JWT_SECRET容器每次启动都会生成一个随机密钥而且对外不可见。你前一天调试好的前端和后端token第二天容器一重启全部验签失败。所以你一定要用-e JWT_SECRETxxxxx固定住这个密钥并且SpringBoot里配置的密钥和它完全一致。第二密钥长度必须足够。ONLYOFFICE用的是HS256签名算法密钥至少32字节。你要是图省事写个secret文档服务器那边校验直接报错签出来的token死活验不过去。第三大数据量文件要调Nginx的body size。ONLYOFFICE容器里自带Nginx默认的client_max_body_size很小上传大文件时会有问题。建议加上环境变量-e NGINX_CLIENT_MAX_BODY_SIZE100m另外提一句ONLYOFFICE文档服务器本身资源占用不低里面自带了nginx、postgresql、redis启动后就是好几个进程。低配的1核2G机器跑起来会很卡至少给2核4G并发编辑人数多的话建议再往上加。启动后可以用http://你的服务器地址/healthcheck确认服务状态页面返回true就说明在正常运行。2.2 JWT鉴权编辑器、文档服务器、后端三方如何互认ONLYOFFICE的鉴权机制是很多第一次接触的人搞不明白的地方。简单说它用JWT做三方互认但和一般系统登录态的JWT用途完全不一样这里签的不是用户身份而是编辑器配置和回调内容没被别人篡改。后端生成编辑器配置config之后需要对整个config做一次HS256签名把签出来的token塞进config的token字段。前端拿到这个带token的config去初始化编辑器编辑器会把token传给文档服务器文档服务器验签通过才允许打开文档。保存回调时也是一个道理。文档服务器回调你的SpringBoot接口时会在HTTP请求头里带Authorization: Bearer token这个token就是对回调JSON做的签名。你的后端收到回调后必须用同一个JWT_SECRET去验签验签通过才允许执行文件覆盖操作防止有人伪造回调请求把任意内容写入你的文件存储。用jjwt库实现的话生成token的核心代码如下SecretKey key Keys.hmacShaKeyFor(props.getJwtSecret().getBytes(StandardCharsets.UTF_8)); String token Jwts.builder() .setHeaderParam(typ, JWT) .setPayload(JSON.toJSONString(config)) .signWith(key, SignatureAlgorithm.HS256) .compact();这里有个容易被忽略的细节JWT的payload是整个config的JSON字符串不是某个单独的字段。验证回调时解析出来的Claims对象里直接就是status、url、key这些字段因为jjwt会把payload的JSON展开成Claims。也就是说Claims claims Jwts.parserBuilder() .setSigningKey(key) .build() .parseClaimsJws(callbackToken) .getBody(); int status claims.get(status, Integer.class);不用再套一层去取字段直接按顶层键取值就行。2.3 网络可达性为什么localhost能打开但编辑器白屏很多人在本地调试时喜欢把SpringBoot的document.url写成http://localhost:8080/xxx结果浏览器打开页面正常编辑器却一直白屏转圈。原因是localhost这个地址在文档服务器的视角里根本不存在。文档服务器跑在Docker容器里它去访问localhost时访问的是容器自己而不是你本机的SpringBoot进程。这跟浏览器是完全不同的视角。所以配置document.url和callbackUrl时一定不能用localhost/127.0.0.1要用局域网IP或者域名。如果文档服务器和SpringBoot都在同一台物理机上Docker容器要访问宿主机服务可以用宿主机局域网IP。依赖host.docker.internal这种写法只在Mac/Windows的Docker Desktop里好用Linux服务器上经常没有这个域名映射最稳妥的方案就是直接用内网IP。比如SpringBoot跑在192.168.1.20文档服务器跑在192.168.1.10那么document.urlhttp://192.168.1.20:8080/onlyoffice/stream?fileId1callbackUrlhttp://192.168.1.20:8080/onlyoffice/callback在联调之前先把这三个地址在对应的视角里用curl验证一遍能省下大量的排查时间。具体怎么验我放在第5章讲。3. SpringBoot后端从令牌签发到回调落库3.1 配置项与依赖先定好骨架后端要做的事情无非四件给前端返回编辑器配置、给文档服务器提供文件下载接口、接收文档服务器的保存回调、把新文件落盘/落库。先定好pom依赖和配置结构。pom里加jjwt依赖用0.11.x或者更新的版本。有人还拿网上老教程用0.9.1在Java 11以后的版本上运行会遇到缺javax.xml.bind的坑SpringBoot版本一高就报NoClassDefFoundError白折腾半天dependency groupIdio.jsonwebtoken/groupId artifactIdjjwt-api/artifactId version0.11.5/version /dependency dependency groupIdio.jsonwebtoken/groupId artifactIdjjwt-impl/artifactId version0.11.5/version scoperuntime/scope /dependency dependency groupIdio.jsonwebtoken/groupId artifactIdjjwt-jackson/artifactId version0.11.5/version scoperuntime/scope /dependency配置类用ConfigurationProperties统一管理Data Component ConfigurationProperties(prefix onlyoffice) public class OnlyOfficeProperties { /** 文档服务器地址如 http://192.168.1.10:80 */ private String docServiceUrl; /** 与onlyoffice容器内JWT_SECRET保持一致 */ private String jwtSecret; /** 业务系统对外可访问地址用来拼接document.url和callbackUrl */ private String publicBaseUrl; /** 文件存储目录 */ private String storageDir ./data/files; }对应的application.ymlonlyoffice: doc-service-url: http://192.168.1.10:80 jwt-secret: Q0k3hFzL9pTrXw7yVb5mNd8sGu2aRc4e public-base-url: http://192.168.1.20:8080 storage-dir: ./data/filespublic-base-url这一项就是上章说的SpringBoot对外可达地址必须按真实部署环境填。3.2 生成编辑器配置和token的Service核心方法作用是根据文件的ID查出文件信息拼出config签名返回给前端。这一步相当于整个在线编辑的入场券。public MapString, Object buildEditorConfig(Long fileId) throws IOException { FileRecord file fileMapper.selectById(fileId); if (file null) { throw new IllegalArgumentException(文件不存在); } String fileExt FilenameUtils.getExtension(file.getFileName()).toLowerCase(); MapString, Object document new HashMap(); document.put(title, file.getFileName()); document.put(url, props.getPublicBaseUrl() /onlyoffice/stream?fileId fileId); document.put(fileType, fileExt); document.put(key, buildFileKey(file)); MapString, Object editorConfig new HashMap(); editorConfig.put(callbackUrl, props.getPublicBaseUrl() /onlyoffice/callback); editorConfig.put(lang, zh-CN); editorConfig.put(mode, edit); MapString, Object config new HashMap(); config.put(documentType, detectDocumentType(fileExt)); config.put(document, document); config.put(editorConfig, editorConfig); String token Jwts.builder() .setHeaderParam(typ, JWT) .setPayload(JSON.toJSONString(config)) .signWith(Keys.hmacShaKeyFor(props.getJwtSecret().getBytes(StandardCharsets.UTF_8)), SignatureAlgorithm.HS256) .compact(); config.put(token, token); return config; }documentType根据扩展名决定word类文档传textexcel传spreadsheetppt传presentation这个字段不写对的话编辑器可能打不开对应的格式。这里我特别想展开讲的是key这个字段。ONLYOFFICE用它来标识文档的唯一版本规则是内容变化后key必须跟着变化。很多教程只说key是文档的唯一标识没提内容变了key要变结果做出来的功能是——第一次打开能编辑能保存保存完了再打开编辑器显示的还是老内容。因为你用了同一个key文档服务器会从缓存里给你拉旧文档。我的做法是给文件记录加一个版本字段每次保存成功后版本号1key就拼上版本号和时间戳private String buildFileKey(FileRecord file) { return String.format(%d-%d-%d, file.getId(), file.getVersion(), file.getUpdateTime().getTime()); }这样保证每次编辑内容变化后key都不相同。3.3 回调接口状态码就是保存流程的心电图ONLYOFFICE保存时状态码是整套回调逻辑的核心。直接给一张表看清楚状态码的含义和应对逻辑status含义后端建议处理1用户关闭编辑器且文档已保存如果回调里带url拉取新文件覆盖旧文件2文档保存完成拉取url、覆盖文件、版本号13打开/保存文档出错记录日志做告警6用户正在编辑暂无操作忽略7用户手动触发强制保存CtrlS拉取url、覆盖文件回调接口要在SpringBoot里允许最大的请求体大小因为ONLYOFFICE在某些版本下会把changeshistory这类大段JSON也塞进回调body里。实现时先验签再取状态码再做文件覆盖PostMapping(/onlyoffice/callback) public MapString, Object callback( RequestHeader(value Authorization, required false) String authorization, RequestBody(required false) String body) { String token null; if (authorization ! null authorization.startsWith(Bearer )) { token authorization.substring(7); } else if (StringUtils.hasText(body)) { JSONObject raw JSON.parseObject(body); token raw.getString(token); } if (!StringUtils.hasText(token)) { return Collections.singletonMap(error, 1); } Claims claims verifyJwt(token); int status claims.get(status, Integer.class); if (status 1 || status 2 || status 7) { String downloadUrl claims.get(url, String.class); if (StringUtils.hasText(downloadUrl)) { Long fileId Long.valueOf(claims.get(key, String.class).split(-)[0]); saveEditedFile(downloadUrl, fileId); } } return Collections.singletonMap(error, 0); }saveEditedFile的实现就是下载文档服务器提供的临时下载地址把字节流覆盖到本地存储private void saveEditedFile(String downloadUrl, Long fileId) throws IOException { FileRecord file fileMapper.selectById(fileId); Path targetPath Paths.get(props.getStorageDir(), file.getId() . file.getExt()); try (InputStream in new URL(downloadUrl).openStream()) { Files.copy(in, targetPath, StandardCopyOption.REPLACE_EXISTING); } file.setVersion(file.getVersion() 1); file.setUpdateTime(new Date()); fileMapper.updateById(file); }这里要注意文档服务器给的临时下载地址有时效性回调收到后要尽快拉取别做异步延时任务否则容易拉的时候已经过期了。3.4 文件流出接口文档服务器怎么拿到原始文件既然文档服务器要根据document.url来下载原始文件后端就必须提供一个不要求登录鉴权的文件流接口或者至少对文档服务器放行。这个接口返回原始文件的字节流注意Content-Type不用纠结用application/octet-stream即可ONLYOFFICE会根据config里的fileType去做解析。GetMapping(/onlyoffice/stream) public ResponseEntityResource stream(RequestParam Long fileId) throws IOException { FileRecord file fileMapper.selectById(fileId); Path path Paths.get(props.getStorageDir(), file.getId() . file.getExt()); Resource resource new FileSystemResource(path); return ResponseEntity.ok() .contentType(MediaType.APPLICATION_OCTET_STREAM) .body(resource); }接口不用做文件扩展名校验交给文档服务器处理。但建议加一层简单的请求来源校验至少不要让这个接口裸奔在公网上不然任何人都能遍历fileId下载文件。可以加白名单IP、加一个单独的静态token或者放在内网网段里。4. 前端接入把编辑器嵌进自己的页面4.1 原生方式接入搞懂初始化参数前端接入是非常轻量的一件事只要引入文档服务器的api.js然后调用new DocsAPI.DocEditor就能把编辑器渲染到页面上。先看不依赖框架的原生写法!DOCTYPE html html head meta charsetUTF-8/ title在线编辑/title /head body div ideditor styleheight: 100vh;/div !-- 从文档服务器加载api.js -- script srchttp://192.168.1.10/web-apps/apps/api/documents/api.js/script script fetch(/onlyoffice/config?fileId1) .then(res res.json()) .then(config { new DocsAPI.DocEditor(editor, config); }); /script /body /htmlapi.js是ONLYOFFICE编辑器组件的入口文件它会自动往页面里塞iframe。DocEditor的第一个参数是iframe渲染占位的div id第二个参数就是后端返回的完整config。文档服务器的资源路径是固定的http://文档服务器地址/web-apps/apps/api/documents/api.js整个接入过程前端其实不需要理解ONLYOFFICE内部复杂的WebSocket协同逻辑它已经把协同、自动保存这些事都封装好了。你只需要保证后端返回的config正确以及api.js能加载到剩下就是开着编辑器让它自己跑。4.2 Vue3里的接入细节组件生命周期要处理好到了Vue3里接入逻辑需要处理组件的生命周期销毁问题。很多人直接在组件里写个onMounted就去初始化编辑器结果切路由时iframe没有被正确回收页面就崩了。示范一下Vue3的写法template div idonlyoffice-container styleheight: 100%; width: 100%/div /template script setup import { onMounted, onBeforeUnmount } from vue; const props defineProps({ fileId: { type: Number, required: true } }); let docEditor null; async function loadEditor() { // 动态加载api.js避免路由切换重复执行script导致报错 if (!window.DocsAPI) { await new Promise((resolve, reject) { const script document.createElement(script); script.src http://192.168.1.10/web-apps/apps/api/documents/api.js; script.onload resolve; script.onerror reject; document.head.appendChild(script); }); } const res await fetch(/onlyoffice/config?fileId${props.fileId}); const config await res.json(); docEditor new window.DocsAPI.DocEditor(onlyoffice-container, config); } onMounted(loadEditor); onBeforeUnmount(() { if (docEditor window.DocsAPI) { docEditor.destroyEditor(); docEditor null; } }); /script有两个细节想提醒。一是api.js别放在script标签里静态加载尤其在单页应用里页面切来切去很容易重复执行导致初始化报错。动态加载并缓存window.DocsAPI最稳妥。二是组件销毁时必须调用destroyEditor()不然编辑器内部的WebSocket连接和事件监听会残留长时间切换页面后页面会越来越卡。如果你的系统只有查看权限还要把editorConfig.mode设置成view或者让后端在buildEditorConfig里根据当前用户权限动态决定mode是edit还是view只读场景就不给编辑按钮。5. 实战中会遇到的高频问题与排查路径5.1 编辑器一直转圈问题优先级排查编辑器一直转圈是集成时出现概率最高的问题我在联调阶段遇到无数次。不要慌按优先级逐层排查第一步浏览器F12打开Network面板看api.js能不能加载。如果看到请求都发不出去说明浏览器访问不了文档服务器。先检查文档服务器地址是否可从浏览器所在网络访问ping不通就去解决网络策略。第二步看编辑器的iframe请求是否返回200。如果iframe加载了但里面白屏多半是文档服务器渲染阶段出了问题直接看文档服务器日志docker logs -f onlyoffice-documentserver第三步在SpringBoot的访问日志里看有没有/onlyoffice/stream请求进来。如果后端日志完全没有这个请求说明文档服务器根本访问不到document.url。最常见的原因是document.url用了localhost/内网不通地址。这时候直接在文档服务器容器里curl一下验证docker exec -it onlyoffice-documentserver curl http://192.168.1.20:8080/onlyoffice/stream?fileId1容器里能curl通编辑器就大概率能正常打开curl不通就回去改public-base-url。第四步确认config里的token字段是否正常生成。如果文档服务器的日志里出现Invalid token或JWT verification failed之类的字样检查一下SpringBoot里的jwt-secret和容器里的JWT_SECRET是否完全一致字符大小写、空格都要对齐。5.2 保存回调报签名不通过或者调用404保存时最容易翻车的有两类问题。一类是回调签名校验不过。注意ONLYOFFICE回调请求的Authorization头格式是Bearer token有些封装好的客户端会把整个header值原样传给你你可能要在后端把Bearer前缀剥掉。另外验签用的库版本要一致别在SpringBoot里用一套JWT库、又自己手动拼了另一套算法密钥字符集也要统一用UTF-8。另一类是回调接口根本调不通。你本地开发时回调地址写着http://localhost:8080/onlyoffice/callback文档服务器容器访问不到或者你在SpringBoot里加了拦截器把回调请求拦下来要求登录态导致返回401。ONLYOFFICE要求回调接口返回{error:0}且HTTP状态码是200任何中间环节的跳转、拦截、权限校验都可能让回调功亏一篑。建议这个接口独立配置放行规则不经过Shiro/Spring Security的登录过滤链。5.3 保存后看到的还是老内容key的刷新策略这个问题我第3章提过但因为它太典型了值得单独拿出来说。症状是第一次打开文档编辑、保存都正常关闭再打开文档还是老样子你保存的内容跟消失了似的。看ONLYOFFICE官方文档对key的解释文档服务器会用key做缓存相同key的文档在一定时间内不会重新拉取。你把key写成固定值比如就传文件ID文档服务器就认为这是同一个文档的同一版本直接把缓存里的老内容给你了。正确的做法是key要能反映文档内容是否变化。我用的方案是把文件ID、版本号、更新时间拼在一起。版本号在每次保存回调成功后自增这样每次打开编辑器拿到的key都不相同强制文档服务器重新加载最新文档。还有个衍生问题如果用户在编辑器里还没保存但你已经给他返回了一个新key的config会不会冲突ONLYOFFICE的推荐做法是如果文档还在编辑会话中不要换key等回调保存成功后再让前端用新config重新初始化。这个顺序一定要理清。6. 进阶扩展把在线编辑变成真正的生产力6.1 对接MinIO做文件持久化落地到生产环境一般不会把文件存本地磁盘而是接对象存储。ONLYOFFICE和MinIO对接的思路很清晰document.url指向MinIO的预签名下载地址回调保存时把新文件上传回MinIO。MinIO的预签名URL要注意有效期设置给的太短文档服务器处理慢一点就过期了。我习惯给10分钟足够编辑器打开文档。同时ONLYOFFICE回调时临时下载地址也是有时效的后端收到回调后要立刻下载别把任务丢到消息队列里慢慢处理。调用MinIO的工具类网上很多核心就两个操作生成预签名URL和上传文件。这里不展开写配置了只想提醒一点——MinIO存储桶的访问策略不要设成public预签名URL已经足够ONLYOFFICE使用了设成public等于把文档裸奔在公网上。6.2 历史版本和批注的获取思路很多同学问能不能拿到ONLYOFFICE的批注“能不能看历史修改记录”。这两个诉求都指向同一件事版本历史。ONLYOFFICE在保存回调的body里会带history、changesurl等字段changesurl是修改记录变更列表的下载地址。如果你要做一个历史版本功能可以在回调保存时把这个changesurl下载下来存库之后在页面上展示修改历史。批注和修订的数据本质上是在编辑会话期间由文档服务器维护的你要是想彻底落到自己的业务表里常用的做法是解析docx文件里的comment xml这个工作量比较大如果没有硬性要求不如直接依赖ONLYOFFICE自带的版本历史界面来得实在。另外有个参数叫assemblyFormatAsOrigin如果你发现ONLYOFFICE保存后的文档格式和老文件对不上比如docx变成odt需要把它配成true让文档服务器以原始格式保存。这个参数在config的editorConfig里配置。6.3 安全与资源规划建议最后聊两句生产环境的事情。ONLYOFFICE文档服务器因为是私有化部署所有流量都走你的网络安全上比公有云方案好一些但该做的防护一样不能少document.url和流接口不要裸奔加IP白名单或者内部Token校验。回调接口返回数据最好也做校验确认key对应的文件ID在你系统里真实存在。容器建议单独划一个网段只开放必要的端口ONLYOFFICE默认的80端口不要直接映射到公网。定期备份onlyoffice_data卷的数据虽然文档正文在你手里但一些临时缓存和历史记录还是在这套卷里的。我用ONLYOFFICE跑了小半年最大的体会是这个项目的文档服务器和SpringBoot的耦合点并不多——后端只需要写好config生成、文件下载、回调保存三个接口前端套一层api.js剩下复杂的格式转换、协同编辑全交给ONLYOFFICE处理。但恰恰是这三个接口里的细节JWT密钥一致性、key的版本策略、三端网络可达性决定了整体能不能跑得顺。希望这篇把链路讲清楚的文章能帮你少走几步弯路。
