ARTICLE · 1367099
为什么越来越多人用 OnlyOffice ?
大家好,我是苏三,又跟大家见面了。
前言
做企业项目的小伙伴应该都遇到过这样的需求。
业务部门提需求说:系统需要有在线编辑 Word的功能,客户不想下载下来改完再传回去。
你一想这需求挺正常,然后开始找方案,发现怎么走都不顺。
绕不开的第一件事是私有化部署。
如果客户是国企或者金融机构,数据不能出内网,必须部署在自己的服务器或私有云上。
SaaS 方案第一步就卡死,数据出境这关过不去。
第二件事,业务系统要嵌入文档编辑能力。
不是让用户跳到某个独立平台去改文件,而是在自己的系统里直接打开、编辑、保存,改完还能回到业务流程里接着走。
第三件事,开发成本要可控。
买商业 SDK,按人头收费,五百个用户一年下来够养半个前端团队,预算会上根本没法交代。
自研呢,光把 .docx 在浏览器里渲染得跟 Word 差不多,就够一个小组折腾大半年,更别提协同算法和格式兼容。
三条路都试过,都不太通。
那该怎么办呢?
今天这篇文章就专门跟大家一起聊聊OnlyOffice,它可以帮我们解决这些问题。
二、OnlyOffice 是什么?
OnlyOffice是一个可私有化部署的在线文档编辑引擎,支持 Word、Excel、PPT、PDF 和表单的查看与编辑,通过 API 嵌进你自己的系统。

它不是网盘,也不是要替代你业务系统的协作平台。

你可以把它当成一块“文档编辑能力”的积木。
用户、权限、文件存储、业务流程,还是你自己的系统管,它只负责把那个 .docx 在浏览器里打开、让人改、改完通知你存回去。
版本上分三条线:开源社区版、企业版、开发者版。
三者核心编辑功能基本一致,区别在授权方式和高级功能。
社区版免费,AGPL v.3 协议,适合小团队和测试。
企业版是商业授权,面向企业内部部署,多了管理面板、高级安全配置和技术支持。
开发者版同样商业授权,核心差异是白标——能换掉 Logo、改主题色、把“关于”页面换成你自己的品牌。
三、四个与开发者相关的能力
3.1 API 集成
这是 OnlyOffice 最核心的能力,也是开发者接触它的第一道门。
集成模型不复杂,就三件事:后端生成 config、前端加载编辑器、文档服务回调你的接口保存。
config 机制。
你的后端生成一个 JSON,里面描述这份文档的一切:文件类型、文档地址、权限、用户信息、界面语言、回调地址。这个 JSON 交给前端,前端拿它初始化编辑器。
config 里放什么、不放什么,完全由你控制。官方文档的集成示例里,config 就是编辑器的“说明书”。
前端加载。
你的页面里放一个 div,引入 ONLYOFFICE 的 api.js,然后 new DocsAPI.DocEditor("div-id", config),编辑器就渲染在那个 div 里。
用户看到的是你系统里的一个页面,背后是 ONLYOFFICE 在渲染文档。
回调保存。
用户在编辑器里改完,ONLYOFFICE 在保存时机向你的 callbackUrl 发 POST 请求,body 里带状态码和文档下载地址。
你的后端收到之后,下载新文件、覆盖存储、返回成功。整个闭环就完成了。
50+ 连接器。
官方准备了 50 多个现成连接器,覆盖 Nextcloud、Moodle、Odoo、WordPress、SharePoint 这些常见系统。
如果你的系统正好是其中之一,接起来很快。
但更实用的是另一件事:你可以一个连接器都不用,直接拿 API 从零嵌进自己的业务系统。官方连接器本质上是这套 API 的现成用法示例,看懂一个,自己写就不难。

config 进入、文件被拉取、保存时回调,三步闭环。
3.2 私有化部署
这个能力是很多人第一次试 OnlyOffice 的直接原因。
部署形态。
OnlyOffice 文档支持部署在本地服务器、私有云、完全离线的内网环境。
官方下载页提供 Windows、Linux 安装包,也提供 Docker 镜像。
企业版产品页写得很明确:自托管部署,数据保留在你自己的基础设施内,无第三方数据访问。
Docker 一行跑起来。最快的方式就是 Docker:
docker run -i -t -d -p 8080:80 onlyoffice/documentserver挂载数据目录、配好 JWT,服务就在你机器上跑起来了。
本地、私有云、离线内网,用的都是这套。
为什么这件事重要。
数据在自己手里,金融、医疗、政府这类客户的合规门槛才谈得上满足。
文档、用户数据、审计日志全在你的基础设施里,OnlyOffice 官方碰不到你的数据。
SaaS 方案给不了这个保证,自研又扛不住成本,私有化部署恰好卡在中间那个位置。

文档服务、文件存储、日志全在你自己的基础设施内,官方不接触数据。
3.3 协作能力
协作是内置的,不是外挂插件。
实时编辑。
多人同时打开同一份文档,能看到彼此的光标、选区和在线状态。
协同有两种模式:快速模式实时显示所有人的改动,严格模式锁定段落,让你专注写自己的部分不受干扰。

评论。
选中一段文字加评论,可以 @ 提及协作者。
评论和修订可以并存,适合审阅流程。
版本历史。
编辑器里能查看文档的历史版本,对比差异、回滚到某个版本。

对于需要留痕的业务场景(合同、报告、审批稿),这个能力是刚需。

多个浏览器窗口并排,不同账号编辑同一文档,能看到对方彩色光标和头像。
3.4 白标能力
白标是开发者版的核心差异,也是做 SaaS 的人最在意的一点。
换什么。
通过 editorConfig.customization,可以换掉编辑器界面里的 Logo、深色主题 Logo、点击 Logo 跳转的 URL、关于页面里的公司名称、地址、邮箱等信息。
主题色也能改。
客户看到的是你的品牌,不是“由 OnlyOffice 提供技术支持”。
为什么重要。
做 SaaS 产品卖给客户,品牌一致性是产品体验的一部分。
如果你的产品里突然冒出一个第三方 Logo,客户会问“这是谁”,信任感会打折。
白标能力让 OnlyOffice 变成你产品里“看不见的引擎”。
补充一句:OnlyOffice 支持离线 AI,但不是自托管后开箱就能用的。需要额外部署本地模型、做配置,是另一套工程。
四、实战演示:Spring Boot 接入
流程就四步:Docker 部署、后端生成 config、前端加载编辑器、处理保存回调。
这里先把示例工程的结构交代清楚。
后面的代码都来自 onlyoffice-springboot,项目使用 Spring Boot 3.4.5 和 Java 17,不额外引入 JWT 框架,签名和验签直接用 JDK 的 HmacSHA256 完成:
onlyoffice-springboot/├── config/OnlyOfficeProperties.java├── controller/│ ├── DocumentController.java│ ├── FileController.java│ └── OnlyOfficeController.java├── service/│ ├── DocumentStorageService.java│ ├── FileAccessService.java│ ├── JwtService.java│ └── OnlyOfficeCallbackService.java└── resources/static/ ├── index.html └── editor.html第一步,Docker 部署,带上 JWT 配置。
docker run -i -t -d -p 8080:80 \ -e JWT_ENABLED=true \ -e JWT_SECRET=susantest123456 \ -v /data/onlyoffice/data:/var/www/onlyoffice/Data \ onlyoffice/documentserverJWT_SECRET 记下来,后端生成 config 和校验回调都得用它。
不设或者设个弱密钥,等于把文档服务裸奔在公网上,别这么干。
Docker 跑起来之后,别急着写代码,先花两分钟确认服务是真的就绪了。
先查一下实际容器名或 ID:
docker ps
更严谨一点的做法是在容器内查一下版本信息:
docker exec 3eff4ef3b2b6 curl -s http://127.0.0.1:8000/info/info.json | grep buildVersion正常会返回类似 "buildVersion":"10.0.0" 的输出。
注意别在宿主机上直接 curl 容器的 8000 端口,那个端口没映射出来,查不到是正常的。
最直接的办法是浏览器访问 http://你的服务器IP:8080/welcome/,看到 “ONLYOFFICE Docs Community Edition installed” 的欢迎页,就说明主体服务起来了。

如果页面打不开,先 docker ps 看容器状态是不是 Up,再 docker logs 看有没有报错。
JWT 配置有没有生效,也顺手确认一下:
docker exec 3eff4ef3b2b6 documentserver-jwt-status.sh这个命令会显示当前 JWT 的启用状态和密钥,你拿它跟 docker run 里设的 JWT_SECRET 对一下,一致就说明配置没问题。
后面后端生成 config 和校验回调时用的就是这个密钥,对不上编辑器会白屏报“文档安全令牌格式不正确”。
项目里的配置入口如下,下面是 application.yml 的配置片段:
server: port: ${SERVER_PORT:8081} address: 0.0.0.0onlyoffice: docs-url: ${ONLYOFFICE_DOCS_URL:http://localhost:8080} public-app-url: ${APP_PUBLIC_URL:https://your-app.example.com} jwt-secret: ${ONLYOFFICE_JWT_SECRET:} storage: directory: ${DOCUMENT_STORAGE_DIR:./data/documents}这里要特别提醒一句:docs-url 是浏览器加载 api.js 使用的地址,public-app-url 是 ONLYOFFICE 服务端下载文件和发送回调使用的地址。
本地调试时,public-app-url 不能随手写成 http://localhost:8081。
远程文档服务访问不到你电脑上的 localhost,最后还是会在保存时提示“这份文件无法保存”。
下面是 JwtService 的核心源码片段,负责给 config 和文件下载地址签发 HS256 令牌,同时校验回调请求:
@Servicepublic class JwtService { private static final Base64.Encoder BASE64_URL_ENCODER = Base64.getUrlEncoder().withoutPadding(); private static final Base64.Decoder BASE64_URL_DECODER = Base64.getUrlDecoder(); private static final TypeReference<Map<String, Object>> MAP_TYPE = new TypeReference<>() {}; private final ObjectMapper objectMapper; private final OnlyOfficeProperties properties; public JwtService(ObjectMapper objectMapper, OnlyOfficeProperties properties) { this.objectMapper = objectMapper; this.properties = properties; } public String sign(Map<String, Object> claims) { if (!properties.jwtEnabled()) { throw new IllegalStateException("onlyoffice.jwt-secret 未配置"); } try { Map<String, Object> payload = new LinkedHashMap<>(claims); long now = Instant.now().getEpochSecond(); payload.putIfAbsent("iat", now); payload.putIfAbsent("exp", now + 3600); String header = encodeJson(Map.of("alg", "HS256", "typ", "JWT")); String body = encodeJson(payload); String signingInput = header + "." + body; return signingInput + "." + BASE64_URL_ENCODER.encodeToString(hmac(signingInput)); } catch (Exception exception) { throw new IllegalStateException("生成 JWT 失败", exception); } } public Map<String, Object> verify(String token) { if (!properties.jwtEnabled()) { return Map.of(); } if (token == null || token.isBlank()) { throw new IllegalArgumentException("请求缺少 JWT"); } try { String[] parts = token.split("\\."); if (parts.length != 3) { throw new IllegalArgumentException("JWT 格式错误"); } String signingInput = parts[0] + "." + parts[1]; byte[] expected = hmac(signingInput); byte[] actual = BASE64_URL_DECODER.decode(parts[2]); if (!MessageDigest.isEqual(expected, actual)) { throw new IllegalArgumentException("JWT 签名无效"); } Map<String, Object> claims = objectMapper.readValue( BASE64_URL_DECODER.decode(parts[1]), MAP_TYPE); Number expiresAt = (Number) claims.get("exp"); if (expiresAt != null && expiresAt.longValue() < Instant.now().getEpochSecond()) { throw new IllegalArgumentException("JWT 已过期"); } return claims; } catch (IllegalArgumentException exception) { throw exception; } catch (Exception exception) { throw new IllegalArgumentException("JWT 校验失败", exception); } } private String encodeJson(Map<String, Object> value) throws Exception { return BASE64_URL_ENCODER.encodeToString( objectMapper.writeValueAsBytes(value)); } private byte[] hmac(String input) throws GeneralSecurityException { Mac mac = Mac.getInstance("HmacSHA256"); mac.init(new SecretKeySpec( properties.jwtSecret().getBytes(StandardCharsets.UTF_8), "HmacSHA256")); return mac.doFinal(input.getBytes(StandardCharsets.UTF_8)); }}这段代码里有两个关键点。
第一,比较签名用 MessageDigest.isEqual,没有直接比较普通字符串。
第二,config 和文件下载各自使用独立令牌。config 令牌供 ONLYOFFICE 校验编辑器配置,下载令牌会额外带 fileId 和 purpose,只允许文档服务拉取指定文件。两类权限不混用,后面排查也清楚。
第二步,后端生成 config。
两个地方要留意:document.key 怎么生成,文件怎么访问。
@GetMapping("/config/{fileId}")public Map<String, Object> getConfig(@PathVariable Long fileId) { StoredFile file = fileRepository.mustFind(fileId); // key 用 文件ID + 版本号 String documentKey = file.getId() + "_" + file.getVersion(); Map<String, Object> document = new LinkedHashMap<>(); document.put("fileType", "docx"); document.put("key", documentKey); document.put("title", file.getOriginalName()); // 这个 url 是 ONLYOFFICE 服务端去拉的,不是浏览器 document.put("url", "https://your-app.com/api/files/" + fileId + "/download"); Map<String, Object> editorConfig = new LinkedHashMap<>(); editorConfig.put("callbackUrl", "https://your-app.com/api/office/callback/" + fileId); editorConfig.put("lang", "zh-CN"); editorConfig.put("user", Map.of("id", currentUserId(), "name", currentUserName())); Map<String, Object> config = new LinkedHashMap<>(); config.put("document", document); config.put("editorConfig", editorConfig); config.put("token", jwtSigner.sign(config)); return config;}document.key 用“文件 ID + 版本号”,保存成功后版本号加一,下次打开自然就是新 key。
别拿文件名或者时间戳随手拼,容易出问题。
项目里把上面的 config 生成逻辑补成了下面这样。
下面是 OnlyOfficeController 的核心源码片段,权限、用户、回调和配置签名都在这里收口:
@GetMapping("/config/{id}")public Map<String, Object> config( @PathVariable String id, @RequestParam(defaultValue = "demo-user") String userId, @RequestParam(defaultValue = "演示用户") String userName, @RequestParam(defaultValue = "edit") String mode) { DocumentInfo file = storageService.get(id); String normalizedMode = "view".equalsIgnoreCase(mode) ? "view" : "edit"; Map<String, Object> document = new LinkedHashMap<>(); document.put("fileType", file.fileType()); document.put("key", file.documentKey()); document.put("title", file.name()); document.put("url", fileAccessService.createDownloadUrl(file.id())); document.put("permissions", Map.of( "edit", "edit".equals(normalizedMode), "download", true, "print", true )); Map<String, Object> customization = new LinkedHashMap<>(); customization.put("autosave", true); customization.put("compactHeader", false); customization.put("comments", true); customization.put("feedback", false); customization.put("forcesave", false); customization.put("help", false); customization.put("hideRightMenu", false); Map<String, Object> editorConfig = new LinkedHashMap<>(); editorConfig.put("mode", normalizedMode); editorConfig.put("lang", "zh-CN"); editorConfig.put("callbackUrl", properties.publicUrl( "/api/office/callback/" + file.id())); editorConfig.put("user", Map.of( "id", safeUserValue(userId, "demo-user"), "name", safeUserValue(userName, "演示用户") )); editorConfig.put("customization", customization); editorConfig.put("coEditing", Map.of("mode", "fast", "change", true)); Map<String, Object> config = new LinkedHashMap<>(); config.put("type", "desktop"); config.put("documentType", documentType(file.fileType())); config.put("document", document); config.put("editorConfig", editorConfig); config.put("width", "100%"); config.put("height", "100%"); if (properties.jwtEnabled()) { config.put("token", jwtService.sign(config)); } Map<String, Object> response = new LinkedHashMap<>(config); response.put("docsApiUrl", properties.docsApiUrl()); response.put("documentInfo", file); return response;}private String documentType(String fileType) { return switch (fileType) { case "xls", "xlsx", "csv" -> "cell"; case "ppt", "pptx" -> "slide"; case "pdf" -> "pdf"; default -> "word"; };}这里有一个顺序不能弄反:先把 document 和 editorConfig 填完整,再对整份 config 签名。
签名内容必须与前端实际拿到的配置一致。
文件访问方式这块,url 是 ONLYOFFICE 服务端去请求的,不是浏览器直接请求。
文件如果在内网,得确保文档服务容器能访问到那个地址,不然浏览器能下载、编辑器却一直转圈报下载失败。
项目里没有直接把 /api/files/{id}/download 裸奔出去,而是给文档服务签发一枚 15 分钟有效的下载令牌。
下面是 FileAccessService 的源码实现:
@Servicepublic class FileAccessService { private final JwtService jwtService; private final OnlyOfficeProperties properties; public FileAccessService( JwtService jwtService, OnlyOfficeProperties properties) { this.jwtService = jwtService; this.properties = properties; } public String createDownloadUrl(String documentId) { String path = "/api/files/" + documentId + "/download"; if (!properties.jwtEnabled()) { return properties.publicUrl(path); } Map<String, Object> claims = new LinkedHashMap<>(); claims.put("fileId", documentId); claims.put("purpose", "document-download"); claims.put("iat", Instant.now().getEpochSecond()); claims.put("exp", Instant.now().plusSeconds(900).getEpochSecond()); String token = jwtService.sign(claims); return UriComponentsBuilder.fromUriString(properties.publicUrl(path)) .queryParam("access_token", token) .build(true) .toUriString(); } public void verifyDownload(String documentId, String token) { if (!properties.jwtEnabled()) { return; } Map<String, Object> claims = jwtService.verify(token); if (!documentId.equals(claims.get("fileId")) || !"document-download".equals(claims.get("purpose"))) { throw new IllegalArgumentException("下载令牌与文档不匹配"); } }}文档服务真正拉取文件时,会请求类似下面的地址:
https://your-app.example.com/api/files/welcome-word/download?access_token=eyJ...下载接口先验令牌,再从存储读取文件:
@GetMapping("/{id}/download")public ResponseEntity<byte[]> download( @PathVariable String id, @RequestParam(name = "access_token", required = false) String accessToken) { fileAccessService.verifyDownload(id, accessToken); DocumentInfo document = storageService.get(id); byte[] content = storageService.read(id); HttpHeaders headers = new HttpHeaders(); headers.setContentType(mediaType(document.fileType())); headers.setContentDisposition(ContentDisposition.attachment() .filename(document.name(), StandardCharsets.UTF_8) .build()); headers.setCacheControl(CacheControl.noStore().cachePrivate() .maxAge(Duration.ZERO)); return ResponseEntity.ok().headers(headers).body(content);}不带 access_token 请求这个接口时,项目会直接返回 400。
这样浏览器知道文件 ID,也拿不到文档内容;只有拿到后端签发的短效令牌,文档服务才能完成拉取。
第三步,前端加载编辑器。
<div id="office-editor" style="width:100%; height:100vh;"></div><script src="https://your-docserver/web-apps/apps/api/documents/api.js"></script><script>const config = await fetch(`/api/office/config/${fileId}`).then(r => r.json());new DocsAPI.DocEditor("office-editor", config);</script>项目里没有把 api.js 写死在页面中,而是先请求 config,再从 config 返回的 docsApiUrl 动态加载脚本。
下面是 editor.js 的核心源码片段:
async function startEditor() { const query = new URLSearchParams({ userId, userName, mode }); const response = await fetch( `/api/office/config/${encodeURIComponent(documentId)}?${query}`, { cache: "no-store" } ); const config = await response.json(); if (!response.ok) { throw new Error(config.message || "无法获取编辑器配置"); } await loadDocsApi(config.docsApiUrl); config.events = { onAppReady: () => { loadingPanel.hidden = true; }, onDocumentReady: () => { setStatus("saved", "文档已加载"); }, onDocumentStateChange:event => { const changed = Boolean(event?.data); setStatus( changed ? "changed" : "idle", changed ? "有未保存修改" : "编辑器内已同步" ); }, onError:event => { const code = event?.data?.errorCode ?? "unknown"; const description = event?.data?.errorDescription || "ONLYOFFICE 返回未知错误"; showError(`错误码 ${code}:${description}`); }, onRequestClose: () => { window.location.href = "/"; } }; new DocsAPI.DocEditor("office-editor", config);}function loadDocsApi(url) { return new Promise((resolve, reject) => { const script = document.createElement("script"); script.src = url; script.async = true; script.onload = resolve; script.onerror = () => reject( new Error("无法加载 ONLYOFFICE api.js,请检查文档服务地址。") ); document.head.appendChild(script); });}要注意,onDocumentStateChange(false) 只能说明编辑器内部状态已经同步,不代表 Spring Boot 已经收到 status=2 并把文件落盘。真正的保存结果,还得看服务端回调日志。
第四步,处理保存回调
status=2 或 6 时下载新文件、更新存储、刷新 key。
@PostMapping("/callback/{fileId}")public Map<String, Integer> callback(@PathVariable Long fileId, @RequestBody Map<String, Object> body) { if (!jwtVerifier.verify(body)) return Map.of("error", 1); int status = (int) body.get("status"); if (status == 2 || status == 6) { String downloadUrl = (String) body.get("url"); byte[] newContent = restTemplate.getForObject(downloadUrl, byte[].class); fileStorage.update(fileId, newContent); fileRepository.incrementVersion(fileId); // 刷新 key } return Map.of("error", 0);}上面的代码保留了回调主流程。项目里把“验签、下载、写文件、升版本”拆到了 OnlyOfficeCallbackService 和 DocumentStorageService 中,下面是 OnlyOfficeCallbackService 的核心源码片段:
public Map<String, Integer> receive( String documentId, Map<String, Object> body) { try { Object token = body.get("token"); jwtService.verify(token == null ? null : token.toString()); int status = statusOf(body); log.info("OnlyOffice callback: document={}, status={}, key={}", documentId, status, body.get("key")); if (status == 2 || status == 6) { Object downloadUrl = body.get("url"); if (!(downloadUrl instanceof String url) || url.isBlank()) { throw new IllegalArgumentException( "OnlyOffice 回调缺少保存地址"); } byte[] content = restClient.get() .uri(url) .accept(MediaType.APPLICATION_OCTET_STREAM) .exchange((request, response) -> { if (!response.getStatusCode().is2xxSuccessful()) { throw new IllegalStateException( "下载 OnlyOffice 文件失败: " + response.getStatusCode()); } byte[] bytes = response.getBody() .readNBytes(MAX_DOWNLOAD_BYTES + 1); if (bytes.length > MAX_DOWNLOAD_BYTES) { throw new IllegalArgumentException( "OnlyOffice 文件超过 50 MB"); } return bytes; }); var updated = storageService.updateContent(documentId, content); log.info( "OnlyOffice document saved: document={}, version={}, size={}", documentId, updated.version(), updated.size()); } return Map.of("error", 0); } catch (Exception exception) { log.error( "OnlyOffice callback failed: document={}", documentId, exception); return Map.of("error", 1); }}private int statusOf(Map<String, Object> body) { Object value = body.get("status"); if (value instanceof Number number) { return number.intValue(); } if (value instanceof String text) { return Integer.parseInt(text); } throw new IllegalArgumentException("OnlyOffice 回调缺少 status");}这里的 RestClient 设置了 10 秒连接超时、60 秒读取超时,并限制下载文件最大为 50 MB,避免回调线程被异常地址拖住。
状态码只需要先盯住下面几个:
1 | ||
2 | ||
4 | ||
6 | ||
7 |
最后落盘时,项目没有直接往目标文件里写,而是先写临时文件,再原子替换:
public synchronized DocumentInfo updateContent( String id, byte[] content) { if (content == null || content.length == 0) { throw new IllegalArgumentException("OnlyOffice 返回了空文件"); } DocumentInfo current = get(id); DocumentInfo updated = current.withContent(content.length); try { writeContent(updated, content); documents.put(id, updated); persistMetadata(); return updated; } catch (IOException exception) { throw new IllegalStateException("更新文档内容失败", exception); }}private void writeContent( DocumentInfo document, byte[] content) throws IOException { Path target = contentPath(document); Path temporary = storageDirectory.resolve(document.id() + ".tmp"); Files.write(temporary, content); Files.move( temporary, target, StandardCopyOption.REPLACE_EXISTING, StandardCopyOption.ATOMIC_MOVE );}withContent 会生成新的版本号:
public DocumentInfo withContent(long newSize) { return new DocumentInfo( id, name, fileType, version + 1, newSize, Instant.now() );}下一次打开会使用 id + "_" + version 组成新的 document.key,不会继续复用旧缓存。
踩坑提醒,提前说。
key 不更新,会导致协同错乱。
文件已经变了还用旧 key,用户打开看到缓存旧版本,或者协同状态乱套。
回调不保存,用户会觉得“内容丢了”。
回调返回非零或者超时,ONLYOFFICE 就当保存失败,用户下次打开看到的是改之前的版本。
JWT 不一致,编辑器直接加载失败。
后端配了 JWT,Docker 环境变量没配或者配了别的值,编辑器白屏,报“文档安全令牌格式不正确”。
项目实际运行时效果:

在线编辑 Word文件的效果:

在线编辑 Excel文件的效果:

五、适用场景速查
四个能力和项目实战讲完,落到选型就一个问题:你的场景决定版本。
功能三档差别不大,差的是授权、并发和品牌控制权。
下面这张表格总结了版本选型:
六、写在最后
回头看开头那三个问题:SaaS 数据出不了内网,商业 SDK 按人头收费扛不住,自研的隐性成本又太高。三条路走不通,大家才开始找“第三条路”。
OnlyOffice 给出的答案,是把“文档编辑”这件事从一项服务变成一块可以装进自己系统里的组件。
数据在你自己服务器上,能力通过 API 嵌进你的业务流程,授权按场景选、预算可控。
它不完美——社区版有 AGPL 的约束和并发上限,白标只有开发者版才有,离线 AI 还得自己额外部署模型。但在“私有化、可集成、成本可控”这个坐标系里,它确实把那条堵死的路走通了。
所以文档协作的“第三选择”,不是更便宜的 SaaS,也不是又一个自研轮子。
是数据在自己手里、能力能嵌进自己系统的编辑引擎。
选型时先想清楚两件事:数据要不要留在自己手里,品牌要不要换成自己的。
这两个问题的答案,基本就决定了你该看社区版、企业版还是开发者版。
剩下的,交给 Docker 一行命令和一份 config。
七、获取链接
在线试用:https://www.onlyoffice.com/zh/signup 本地部署:https://www.onlyoffice.com/zh/download 开源地址:https://github.com/ONLYOFFICE/DocumentServer
了解更多:
企业版介绍:https://www.onlyoffice.com/zh/docs-enterprise 开发者版介绍:https://www.onlyoffice.com/zh/for-developers 价格和版本对比:https://www.onlyoffice.com/zh/pricing 帮助中心:https://helpcenter.onlyoffice.com/zh/ API 文档:https://api.onlyoffice.com/zh-CN/














































































