开头我一直觉得OnlyOffice 这套东西在国内的讨论度其实被严重低估了。很多人一提到在线编辑第一反应就是 Office Online Server、Collabora Online 或者 WPS 的集成方案但真到自己动手部署、接入业务系统的时候才发现里面坑多到能写一本书。OnlyOffice 的好处在于它社区版免费、部署轻量、API 开放而且和 Spring Boot 这类后端框架配合起来能实现非常完整的文档管理 在线预览 协同编辑闭环。这篇文章写给谁两类人。第一类是公司里接了在线编辑需求、但之前没接触过 OnlyOffice 的后端开发你需要知道怎么最快把它跑起来并且让 Java 后端跟它对接上。第二类是已经部署过 OnlyOffice、但经常被文档存储、回调地址、权限控制、多人协同这些问题折腾的同学你可以从这篇文章里拿到一些我踩坑换来的实战结论。我把整个过程拆成两大部分部署篇和开发篇。部署篇讲 Docker 方式快速搭建、配置文件的坑、服务之间连通性的判断开发篇讲 Spring Boot 如何对接 OnlyOffice 的 API、如何管理文档存储、如何处理回调通知、如何做权限控制和版本管理。最后单独放一节常见问题都是我在实际项目中反复遇到过、并且最终解决了的问题。如果你正打算在自己项目里集成 OnlyOffice这篇文章可以直接当参考手册用。1. 部署篇先用 Docker 把 OnlyOffice 跑起来1.1 为什么推荐 Docker 方式部署OnlyOffice 官方提供了多种部署方式Windows 下的安装包、Linux 下的 DEB/RPM 包、以及 Docker 镜像。如果是在生产环境长期使用我更推荐 Docker。原因有三点。第一OnlyOffice 依赖的组件比较多。它内部包含文档服务DocumentServer、转换服务、协同编辑引擎等如果手动安装需要自己处理 PostgreSQL、RabbitMQ、Redis、Nginx 等一系列依赖。社区版虽然打包成了安装包但一旦出问题日志分散在各个服务里排查起来非常痛苦。Docker 方式把这些依赖全部封装在一个容器里你只需要关心 80 端口和持久化目录。第二升级方便。OnlyOffice 的版本迭代不算慢安全更新和功能更新交替出现。Docker 部署升级时只需要拉取新镜像、重建容器配置和数据目录可以完整保留。手动安装的话升级脚本有时候会覆盖你自定义的配置这点很烦。第三环境隔离彻底。OnlyOffice 对系统库的依赖比较挑剔尤其是字体渲染这一块。如果你在一台已经装了其他办公软件或者定制过字体库的机器上安装很容易出现预览时中文乱码、PDF 转换后字体缺失的问题。容器化之后它自带一套完整的字体环境不受宿主系统影响能少掉一大半的兼容性麻烦。我遇到过不止一次在 CentOS 上手动安装 OnlyOffice启动一切正常但文档转换出来的 PDF 中文全是方块。后来全部改用 Docker 部署再也没出现这个问题。1.2 Docker 部署完整步骤部署之前先确认你的服务器配置。OnlyOffice 对内存的要求是真实的不是随便写写——如果只是测试2GB 内存勉强能跑但并发编辑两三个文档时就会开始卡。生产环境建议 4GB 起步如果你们公司会把 Word、PPT、Excel 大文件频繁做预览转换8GB 更稳。CPU 双核起步编码转换和文档渲染时 CPU 占用会瞬间拉高。先创建持久化目录mkdir -p /opt/onlyoffice/data mkdir -p /opt/onlyoffice/logs mkdir -p /opt/onlyoffice/lib mkdir -p /opt/onlyoffice/db然后直接跑官方镜像docker run -i -t -d -p 80:80 \ --restartalways \ -v /opt/onlyoffice/data:/var/www/onlyoffice/Data \ -v /opt/onlyoffice/logs:/var/log/onlyoffice \ -v /opt/onlyoffice/lib:/var/lib/onlyoffice \ -v /opt/onlyoffice/db:/var/lib/postgresql \ onlyoffice/documentserver:8.2这里有个关键点/var/lib/postgresql这个目录是 OnlyOffice 内部 PostgreSQL 的数据目录必须做持久化。否则容器一删你所有文档的历史版本、协同编辑状态、用户注释全部丢失。这个目录丢了比丢 Data 目录还严重。启动之后先别急着去浏览器访问。等容器日志稳定下来docker logs -f onlyoffice/documentserver看到类似Server started或者 Nginx worker 初始化完成的日志后再访问http://你的服务器IP/welcome/。如果能看到欢迎页面说明部署成功。欢迎页面里一般会有一个测试编辑器可以先用它验证文档创建、保存、转换这几个基础功能是否正常。1.3 配置文件里的几个关键调整OnlyOffice 的配置文件叫local.json路径在容器内的/etc/onlyoffice/documentserver/local.json。这个文件在官方文档里描述不多但实际使用中你能碰到的大部分问题都跟它有关。我重点说三个配置项。第一是storage相关配置。默认情况下OnlyOffice 把文档内容缓存在容器内部如果你没有配置外部存储文档在编辑过程中的临时文件会一直存在容器里。容器重启后这些缓存会清空但你通过 API 传入的文档本身不在 OnlyOffice 这边所以在对接 Spring Boot 时这个问题通常不会暴露。不过如果你用了 OnlyOffice 自带的示例项目它会把文档存到 Data 目录那个目录如果没做持久化重启就丢文件。第二是 JWT 密钥配置。这个我放到开发篇详细讲但部署时你要先打开这个功能。在local.json里找到services.CoAuthoring.token.enable和services.CoAuthoring.token.inbox把它们设成true然后指定一个secret。这个密钥相当于是你的 Spring Boot 后端和 OnlyOffice 之间通信的暗号后面开发时回调验证、API 请求签名全靠它。第三是跨域配置。如果你的 Spring Boot 前端和后端不在同一个域名下或者前端页面和后端接口存在跨域请求需要在local.json里找到services.CoAuthoring.server相关配置确认request-filtering-agent允许的域名范围。默认配置一般只会放行 localhost实际项目中要改成你的前端域名。改完配置文件记得重启容器docker restart onlyoffice/documentserver注意OnlyOffice 容器启动时会先做数据库迁移和初始化重启之后需要等 10~20 秒才能完全可用。别刚重启完就去请求接口容易碰到连接拒绝。2. Spring Boot 接入前的准备工作2.1 前后端交互架构梳理在写代码之前一定要先把架构理清楚。OnlyOffice 的前端编辑器是 JS 组件它运行在你的浏览器里Spring Boot 是你的后端服务负责提供文档列表、权限控制、文件读写OnlyOffice 服务端负责承载编辑器、文档转换和协同编辑。这三者之间的关系是这样的用户打开你前端页面上的编辑按钮前端向 Spring Boot 请求一个编辑凭证也就是 OnlyOffice 的配置对象Spring Boot 根据自己的业务逻辑生成这个配置返回给前端。前端拿到配置后加载 OnlyOffice 的编辑器 JS把配置传给编辑器。编辑器根据配置里的document.url去 OnlyOffice 服务端拉取文档内容用户开始编辑。编辑过程中的保存动作由 OnlyOffice 服务端通过回调地址通知你的 Spring Boot。这里最关键的一点是Spring Boot 不是直接把文件内容传给 OnlyOffice 的它传的是一个可访问的 URL。OnlyOffice 服务端需要能够直接访问到这个 URL去下载文档。很多新手在这里卡住明明前端能访问到文件但 OnlyOffice 报错下载文档失败就是因为 OnlyOffice 容器访问不到那个 URL。如果你的文件存在 MinIO 或者本地磁盘但 OnlyOffice 部署在另一台服务器上你需要确保这个 URL 是 OnlyOffice 能访问到的内网或公网地址而不是localhost或127.0.0.1。2.2 Maven 依赖和基础配置Spring Boot 集成 OnlyOffice 官方没有提供 SDK但社区里有不少封装好的库比如onlyoffice-java-integration。不过在真实项目里我不太建议直接引入这种封装库因为 OnlyOffice 的 API 本身不复杂自己封装反而更可控而且不会因为库的版本滞后导致配置格式对不上。你需要的基础依赖就是 Spring Boot Web 和 HTTP 客户端。我用的是Spring Boot 2.7.x搭配OkHttp做服务端到 OnlyOffice 的请求。如果是新项目用 Spring Boot 3.x 也完全没问题接口逻辑一样的。在你的application.yml里加上 OnlyOffice 相关配置onlyoffice: server: url: http://192.168.1.100:80/ # OnlyOffice 服务地址 jwt: secret: your-strong-secret-key algorithm: HS256 header: Authorization callback: url: http://192.168.1.50:8080/api/onlyoffice/callback # Spring Boot 回调地址这个server.url是 OnlyOffice 服务对外提供编辑器和转换服务的地址。如果你的前端和后端部署在同一台机器这里写成内网 IP 也可以但如果前端在公网前端浏览器需要能访问到这个地址去加载编辑器脚本所以内网 IP 会导致前端加载失败。稳妥做法是用一个公司域名或者公网 IP然后在 Nginx 或防火墙层面限制访问来源。2.3 文件存储方案选择OnlyOffice 本身不管你的业务文件它只负责编辑时加载、保存时回调。所以你在 Spring Boot 侧需要自己决定文件存哪里。根据项目规模我给出三种方案。方案一本地磁盘。最简单适合内部系统、用户量不大、单机部署的场景。文件路径可以按业务 ID 组织比如/data/files/{userId}/{fileId}.docx。优点是实现快、好排查缺点是分布式部署时文件不共享多台机器不能同时处理同一个文件。方案二MinIO。这是我最推荐的方案适合大多数中小型项目和云上部署。MinIO 兼容 S3 协议Spring Boot 集成非常方便而且 OnlyOffice 可以直连 MinIO 的预签名 URL 下载文件。你的文件存取逻辑和 OnlyOffice 回调逻辑可以完全解耦即使以后换对象存储厂商也不用改业务代码。方案三数据库 BLOB。只适合小文件、低频访问的场景。文档大了之后数据库压力大而且生成临时 URL 给 OnlyOffice 下载也不方便不推荐除非你有强一致性的合规要求。MinIO 模式下的典型操作流程是用户上传文件时Spring Boot 把文件写入 MinIO用户点击编辑时Spring Boot 生成一个带签名的临时 URL传给 OnlyOffice用户在编辑器里保存时OnlyOffice 回调 Spring BootSpring Boot 再从 OnlyOffice 服务器拉取更新后的文件写回 MinIO。3. 核心接口开发编辑、保存、转换一条龙3.1 生成编辑器配置对象前端加载 OnlyOffice 编辑器时需要拿到一个配置对象。这个对象的结构是官方固定格式的我用一个方法统一生成public MapString, Object buildEditorConfig(String fileId, String userName) { MapString, Object config new HashMap(); config.put(document, buildDocumentConfig(fileId)); config.put(editorConfig, buildEditorConfig(userName)); config.put(token, generateJwtToken(...)); return config; }里面的document部分要包含fileType文件扩展名比如 docx、xlsx、pptxurlOnlyOffice 可以访问到的文件下载地址title文档名称注意必须带扩展名editorConfig部分要包含mode可以是edit或viewcallbackUrlOnlyOffice 保存文档后回调的地址user当前编辑用户的信息包括id、namelang编辑器界面语言中文填zh-CNcustomization自定义项比如隐藏右栏、关闭页眉页脚提醒等这里我强调三个容易被忽略的细节。第一document.url必须是 OnlyOffice 服务端能够访问到的地址。如果 Spring Boot 和 OnlyOffice 在同一台服务器可以用http://127.0.0.1:8080/...如果不在同一台必须用内网 IP 或公网地址。实在不确定的时候可以登录 OnlyOffice 容器内用curl试一下这个 URL 是否能访问docker exec -it onlyoffice/documentserver curl -I http://你的SpringBoot地址/api/onlyoffice/file/123.docx第二editorConfig.mode为edit时user.id不能为空而且同一个文档多人同时编辑时每个用户都要有唯一的id否则 OnlyOffice 会把不同用户当成同一个人协同光标和权限会错乱。第三callbackUrl必须是公网可访问或者 OnlyOffice 服务能直接访问到的地址。这里最容易踩的坑是本地测试时 Spring Boot 地址是localhost:8080前端能访问没问题但 OnlyOffice 是容器它访问不到你宿主机的localhost。本地调试需要让 OnlyOffice 容器能访问宿主机端口要用host.docker.internal或者宿主机局域网 IP。3.2 回调接口的完整实现OnlyOffice 在文档保存、关闭、协同操作等时机会向callbackUrl发送 POST 请求。这个接口是整个集成中最核心的部分没有之一。请求体是一个 JSON里面有几个重要字段status回调状态码1表示文档已保存2表示文档已关闭3表示有用户正在编辑4表示编辑出错6表示正在保存url保存后新文档的下载地址仅在status1时才有key文档的唯一标识是你生成配置时传过去的users当前正在编辑的用户 ID 列表我的回调处理逻辑一般是这样的PostMapping(/api/onlyoffice/callback) public ResponseEntityVoid callback(RequestBody OnlyOfficeCallback body) { // 1. 验证 JWT防止伪造回调 if (!jwtUtils.validate(body.getToken())) { return ResponseEntity.status(HttpStatus.FORBIDDEN).build(); } // 2. 根据 key 找到业务文件 FileMeta meta fileMetaService.getByKey(body.getKey()); // 3. 如果状态为已保存下载新文件并替换旧文件 if (body.getStatus() 1) { byte[] content httpClient.download(body.getUrl()); fileStorageService.save(meta.getFileId(), content); } // 4. 返回空 JSON 对象注意是 {}不是空字符串 return ResponseEntity.ok().body(null); }这个接口的返回值很关键。OnlyOffice 期望收到的是内容为{}的 JSON 响应如果你返回空字符串或者纯文本它会认为回调失败然后不停重试。重试次数多了之后编辑器端会出现保存失败的提示。还有一个状态码容易忽略status6表示正在保存这个状态不需要你做任何处理但如果你在代码里没判断就直接下载url可能会拿到不完整的文件因为此时保存还没结束。所以要等status1再处理文件更新。3.3 文档访问接口的幂等处理前面提到document.url是 Spring Boot 提供的一个下载接口。这个接口不用复杂但必须考虑并发和权限。文件下载接口要注意一个细节OnlyOffice 编辑器加载文档时会发起一次 GET 请求文档转换服务可能也会发起一次请求如果多人同时打开同一份文档这个接口会被反复调用。每次调用都去对象存储拉文件开销不小。我一般会给这个接口加一层本地缓存文件内容在短时间内不变的话直接返回缓存字节。还有一个更重要的问题不要用业务接口的原始文件路径暴露给 OnlyOffice。你最好生成一个临时授权链接比如带一个 5 分钟过期的签名参数OnlyOffice 拿到这个 URL 后才能下载过期后返回 403。这样做的目的是防止用户把文档下载地址分享出去绕过你的权限控制。具体实现可以用 Spring Boot 的HandlerInterceptor或者简单的 Token 校验。我在项目里用的方式是生成配置时在 URL 里拼一个?tokenxxx这个 token 是 JWT 加密的文件 ID 加过期时间下载接口先验证 token再决定返回文件还是拒绝。既安全又不会给 Spring Security 增加额外负担。3.4 手动转换功能预览 PDF、提取文本OnlyOffice 除了在线编辑还提供了文档转换 API。这个功能在我们的系统里用来做两件事一是把文档转成 PDF 供用户预览二是把文档转成图片或者文本用于内容检索。转换请求发到 OnlyOffice 的/ConvertService.ashx接口需要带以下参数filetype源文件类型url源文件下载地址outputtype目标类型比如 pdfkey用于标识转换任务的唯一字符串如果你开启了 JWTConvertService.ashx的请求头里也要带签名。这个接口是同步慢接口大文件可能需要几秒到几十秒所以在 Spring Boot 里调用时一定要设置超时时间建议 60 秒以上并且最好放到异步线程池里执行避免阻塞用户请求。我实测下来的经验是转换 10MB 以内的 Word 文档通常在 3~5 秒内能完成如果是几十页带大量图片的 PPT可能要等十几秒。转换结果会返回一个url这个 URL 是 OnlyOffice 临时生成的默认在一段时间后失效。你需要立刻下载保存到自己的存储里不要存这个临时 URL。4. JWT、权限与多租户场景的实战细节4.1 OnlyOffice JWT 到底验证哪些东西OnlyOffice 的 JWT 机制很多同学一开始容易搞混。你要区分两种 JWT一种是你自己业务系统里生成的 JWT用来登录你的 Spring Boot另一种是OnlyOffice 回调或 API 请求时携带的 JWT用来验证请求来源是合法的 OnlyOffice 服务。在 Spring Boot 集成 OnlyOffice 时涉及两类敏感请求必须让 OnlyOffice 带上 JWT第一类是前端调用你的后端获取编辑配置时你的后端返回的配置对象里会包含一个token。编辑器和 OnlyOffice 服务交互时会携带这个 tokenOnlyOffice 服务端会验证它。第二类是 OnlyOffice 回调你的 Spring Boot 接口时会在请求头带一个Authorization: Bearer xxx。你的回调接口必须验证这个 JWT确保请求确实来自你的 OnlyOffice 服务。因为这个回调接口是公网可访问的如果不验证任何人都能伪造一个文档已保存的通知你的文件就会被恶意覆盖。我在项目里用jjwt库处理 JWT 的生成和解析配置里的secret和 OnlyOfficelocal.json里的secret必须完全一致。注意区分OnlyOffice 8.2 可能有多个 JWT secret 配置项包括inbox、outbox、session等你只需要确保回调验证用的 secret 和 OnlyOffice 发送回调时用的 secret 一致。如果你部署时改了local.json但忘了同步到 Spring Boot 配置你会遇到一个非常诡异的现象前端能正常打开编辑器但保存文档时永远失败日志里全是 JWT 校验错误。4.2 权限控制的三种粒度在线编辑系统的权限控制和普通文件系统的权限差不多但有一个独有的问题只读权限下用户仍然可以发起协同会话只是不能保存。我在项目中把权限分为三种粒度第一种是功能权限控制用户能不能看到在线编辑按钮。这个在 Spring Boot 的接口层做判断就行用户在点击编辑前你的后端检查他是否有该文件的编辑权限没有就直接拒绝生成编辑配置。第二种是文档操作权限控制用户打开编辑器后能做什么。通过在editorConfig里的mode字段设置edit或view实现。view模式下编辑器是只读的没有编辑工具栏也没有保存按钮。对于只读用户document.permissions里很多高级功能会被禁用但要注意mode为view时你不能设置document.url指向一个可写的后端接口因为用户一旦通过某些手段绕过还是能直接访问到文件内容。严格来说只读预览应该由 Spring Boot 生成一个临时只读 URL而不是说只在编辑器层面禁止编辑。第三种是保存权限。这个权限最终由回调接口把关如果当前用户没有保存权限即使 OnlyOffice 发起了保存回调你的后端也不能把新内容写回原文件。但这里有个问题OnlyOffice 的回调里users字段能告诉你谁在编辑但你能不能轻易判断操作者是谁实际测试下来这个字段格式在不同的 OnlyOffice 版本里略有差异可能是一个数组也可能为空。所以更稳妥的做法是在生成编辑配置时根据当前用户保存一个会话记录包含key、用户、文件 ID、是否有保存权限回调时查这个会话再决定是否执行文件替换。4.3 多租户隔离下的 key 策略OnlyOffice 的key字段是用来标识同一个文档的。只有当key相同的时候OnlyOffice 才会把打开同一文档的不同用户视为在同一协同会话中。如果key不同即使 URL 指向同一个文件OnlyOffice 也会当成完全不同的文档来对待各改各的最后以最后一次保存为准。所以在多租户或者多业务线的系统里key的策略特别重要。我的做法是key tenantId : fileId : version。版本号加进去是为了处理一种特殊情况用户 A 在编辑旧版本用户 B 已经保存了新版本如果他们两个的key相同OnlyOffice 会非常困惑。加上版本号后不同版本的文档被视为不同文档避免协同状态错乱。另外key的长度不能太长。OnlyOffice 对key有长度限制实测超过 128 字符会导致请求异常。你用租户 ID 加文件 ID 加版本号正常不会超但如果你图省事把整个文件路径塞进去就有可能触发这个限制。5. 常见问题与排查技巧实录5.1 编辑器一直加载不出来这个问题的出现频率实在太高了而且大部分时候不是代码问题而是地址问题。先记住一个排查顺序。第一步直接在浏览器访问 OnlyOffice 服务地址下的/welcome/看看服务本身是否正常。如果不正常检查 Docker 状态和日志。第二步打开配置对象返回的document.url看能不能直接下载文件。如果下载不了OnlyOffice 编辑器就会一直转圈。第三步打开editorConfig里的callbackUrl确认它能被 OnlyOffice 容器访问。测试方法是我前面讲的进容器里 curl 一下。如果这三步都通过编辑器还加载不出来多半是前端 JS 资源加载失败。用浏览器开发者工具看 Network 面板找到 OnlyOffice 编辑器脚本的请求如果返回 404 或者 403检查你的 Nginx 是否把对应路径反代到 OnlyOffice 容器了。5.2 保存失败回调接口报 404回调查 404 的常见原因有三个接口路径写错了、Spring Boot 的 Context Path 没考虑进去、回调地址被网关拦截了。接口路径这个不用多说但第二个原因很隐蔽。很多 Spring Boot 项目会配置server.servlet.context-path/api这种情况下你的接口实际地址不是/api/onlyoffice/callback而是/api/api/onlyoffice/callback。OnlyOffice 的callbackUrl是你自己写的所以不存在自动拼接需要你仔细核对。网关拦截的情况更常见。如果公司的 Spring Boot 服务部署在 Nginx 后面Nginx 可能只放行了某些路径到后端。回调请求的 Content-Type 是 JSON请求体比较大别让网关把 body 吞掉了。另外注意 OnlyOffice 回调用的是 POST 方法如果是云厂商的负载均衡确认没把 POST 禁用。5.3 文档中文字体乱码这个问题主要出现在文档转换场景预览 PDF 或者转图片时中文全部变成方块。原因是 OnlyOffice 容器内没有安装中文字体或者字体配置丢失。Docker 部署的情况下解决方式是在宿主机准备一个字体目录挂载进容器mkdir -p /opt/onlyoffice/fonts cp /usr/share/fonts/你的中文字体.ttf /opt/onlyoffice/fonts/然后重新创建容器增加一个挂载参数-v /opt/onlyoffice/fonts:/usr/share/fonts/truetype/custom挂载完成后进容器刷新字体缓存docker exec -it onlyoffice/documentserver fc-cache -f -v然后重启容器。实测这个办法对 Windows 的宋体、黑体、微软雅黑都有效。有一个坑是你复制字体时要注意文件权限OnlyOffice 容器内的进程如果没有读权限还是会乱码。挂载目录权限设置为 755 比较稳妥。5.4 协同编辑时光标不同步、内容互相覆盖打开同一文档的人如果看到的不是对方的实时操作或者保存的内容覆盖了别人的修改十有八九是key或者user.id的问题。key不一致是最常见的原因。生成配置时同一个文件必须使用同一个key而且这个key不能包含随机字符。我发现网上有些代码喜欢在key后面加时间戳每次请求都生成一个不同的值然后协同功能完全失效。如果你确实需要在配置中加入版本信息要保证多人打开时拿到的是同一个版本号。user.id的问题则更隐蔽。用户信息必须稳定同一个用户在不同时间、不同设备上打开文档user.id要一致。如果你前端传的是随机 UUID每次刷新页面都变OnlyOffice 会认为刷新前后是两个不同的人协同会话会不断重建光标不同步、权限判断错误接踵而至。5.5 OnlyOffice 容器日志怎么看OnlyOffice 的日志很分散但关键信息其实集中在两个地方。第一个是主日志流用docker logs直接看里面会有 Nginx 和文档服务的大部分报错。第二个是文档转换和协同编辑的详细日志在容器内的/var/log/onlyoffice/documentserver/目录。常见的问题比如文档下载失败JWT 验证失败回调超时都能在这些日志里找到源头。排查时建议先把日志按时间过滤一下只看你复现问题的那段时间不然日志量太大翻半天找不到重点。我在排查回调问题时最喜欢的做法是在回调接口里加一行日志打印收到的原始请求头和请求体。因为 OnlyOffice 版本不同回调的 JSON 格式会有细微差异打印出来后一眼就能看出字段名是status还是statusCode是url还是fileUrl。网上很多教程基于旧版本写照抄容易踩版本差异的坑。6. 几个容易被忽视的工程化问题6.1 回调接口必须做幂等和去重我在真实项目里遇到过这样的情况用户保存文档时网络抖动OnlyOffice 重试了三次回调我的接口没有做幂等处理同一个文件被旧版本覆盖了三次最终文档内容回到了用户保存前的状态。回调的幂等策略应该基于key status 时间来判断。收到status1的保存回调时检查当前文件的最新版本是否已经比回调里的版本新。最简单的方式是在文件元信息里维护一个lastSavedKey每次保存时比较如果回调里的key不等于当前文件对应的key直接返回成功但不做文件替换避免旧版本的异步回调整体覆盖新版本。6.2 文件锁和并发编辑的取舍OnlyOffice 号称支持多人协同编辑但协同编辑只能解决同时对同一文档做小范围修改的问题。如果两个用户同时在系统里编辑同一个文档又都在本地先改了五十处再保存最终结果必然是一方的修改被覆盖。业务层面要区分两种场景实时协同编辑场景类似在线文档和独占编辑场景类似传统文件编辑。对于后者我建议在 Spring Boot 层面做文件锁。比如用户点击编辑时在后端记录一个编辑锁Other 用户再打开同一文件时提示文件已在编辑中编辑完成或会话超时后释放锁。OnlyOffice 协同功能开启后大部分人以为不需要锁了但实际业务中很多文档并不适合多人实时改锁依然是保底方案。6.3 文档历史版本管理怎么实现很多系统希望保留文档的每次保存记录OnlyOffice 本身不做业务层面的版本管理但回调机制给了你足够的信息。我的做法是回调status1时从url下载新文件后不直接覆盖原来的文件而是以版本号为后缀另存一份。同时在数据库里记录一份版本记录包含操作人、操作时间、文件大小、版本号。用户点查看历史版本时前端拿到版本列表点击某个版本Spring Boot 生成一个对应版本的 OnlyOffice 预览配置用view模式打开。这里有一个体验上的关键点预览历史版本时document.title里的文件名要带上版本号否则用户在编辑器里看到的是同一个名字容易混淆到底在预览哪个版本。7. 后续可扩展的方向集成完之后你会发现 OnlyOffice 的 API 还有一些额外能力值得利用。比如文档对比功能可以传入两个版本的 URLOnlyOffice 会返回一个标记了差异的新文档再比如表单填写功能可以做简单的流程审批表单还有水印功能在预览或编辑模式下给文档加上动态水印限制截屏泄露。我在项目里最常用的是文档对比功能。用户想看看同事对合同改了什么不需要逐字去对直接在系统里点版本对比后端调用 OnlyOffice 的对比接口生成一份带修订痕迹的文档放进预览窗口。虽然是简单调用但业务上很受欢迎。另外如果你打算把在线编辑能力开放给外部客户需要考虑给 OnlyOffice 服务加访问限制。不要直接把 80 端口暴露到公网最好放到内网由 Nginx 按域名转发到 OnlyOffice再在 Nginx 层做 IP 白名单。编辑器脚本和下载请求可以走公网但管理和转换接口不要裸奔。最后提醒一句OnlyOffice 社区版的用户数是有限制的不涉及到强制断连但高并发时性能衰减明显。如果你们公司文档在线编辑的日活预计超过几百人建议优先考虑商业授权或者用集群方案不要在单机容器里死磕。毕竟在线编辑最怕的不是功能不够而是关键时刻服务挂掉所有人的工作成果都握在服务端手里。我自己从第一次部署 OnlyOffice 到现在最大的体会就是这个系统并不复杂但它的坑几乎全部集中在网络连通性和配置一致性这两个点上。只要你在部署时把 Docker 持久化和 JWT 配置做对了开发时把回调和下载 URL 的可见范围理清了后面基本就是一马平川。希望这篇文章能让你少走点弯路有问题欢迎在评论里一起讨论。