找回密码
立即注册
搜索
发回帖 发新帖

6916

积分

0

好友

873

主题
发表于 6 小时前 | 查看: 2| 回复: 0

前言

做企业项目的人,大多接过这样的需求。

业务部门说:系统里要能在线编辑 Word,客户不想先下载、改完再传回去。

这个需求听起来很普通。真开始找方案,会发现每条路都不好走。

第一个绕不开的问题是私有化部署。

国企、金融机构这类客户的数据不能出内网,系统只能部署在客户自己的服务器或私有云上。SaaS 方案在这一步就用不了,数据出境这一关过不去。

第二个问题是文档编辑要嵌进业务系统。

用户不该被带到另一个独立平台去改文件。他们要在自己的系统里打开、编辑、保存,改完还要回到原来的业务流程。

第三个问题是开发成本。

商业 SDK 按人头收费,五百个用户一年的授权费够养半个前端团队,预算会上很难讲清楚。

自研的成本更高。只是让 .docx 在浏览器里渲染得接近 Word,一个小组就要做大半年,协同算法和格式兼容还没算进去。

三条路都试过,都走不通。那还有什么办法?

这篇文章介绍 OnlyOffice,看看它怎么解决这几个问题。

二、OnlyOffice 是什么?

OnlyOffice 是一个可以私有化部署的在线文档编辑引擎。它支持查看和编辑 Word、Excel、PPT、PDF 和表单,并通过 API 嵌进你自己的系统。

ONLYOFFICE 官网中文首页,展示文档、表格、演示文稿编辑器

它不是网盘,也不打算取代你业务系统里的协作平台。

ONLYOFFICE PDF 编辑器、批注与 @ 提及协作界面

可以把它看作一块提供“文档编辑能力”的积木。

用户、权限、文件存储和业务流程仍然由你的系统负责。OnlyOffice 只做三件事:在浏览器里打开 .docx,让用户编辑,改完后通知你把文件存回去。

它有三个版本:开源社区版、企业版和开发者版。

三个版本的核心编辑功能基本相同,区别在授权方式和高级功能。

  • 社区版:免费,采用 AGPL v.3 协议,适合小团队和测试环境。
  • 企业版:商业授权,面向企业内部部署,额外提供管理面板、高级安全配置和技术支持。
  • 开发者版:同样是商业授权,主要区别是支持白标。你可以替换 Logo、修改主题色,把“关于”页面换成自己的品牌。

三、开发者最关心的四项能力

3.1 API 集成

API 集成是 OnlyOffice 最核心的能力,开发者接触它通常也从这里开始。

集成模型分三步:后端生成 config,前端加载编辑器,文档服务回调你的接口完成保存。

config 机制

后端生成一个 JSON,描述这份文档的全部信息,包括文件类型、文档地址、权限、用户信息、界面语言和回调地址。前端拿到这个 JSON 后,用它初始化编辑器。

config 里放哪些字段由你决定。官方文档的集成示例也是这样用的,config 相当于编辑器的“说明书”。

前端加载

在页面里放一个 div,引入 ONLYOFFICE 的 api.js,再执行 new DocsAPI.DocEditor("div-id", config),编辑器就会渲染在这个 div 里。

用户看到的是你系统里的一个页面,文档由 ONLYOFFICE 在背后渲染。

回调保存

用户在编辑器里改完后,ONLYOFFICE 会在保存时向你的 callbackUrl 发送 POST 请求,请求体里带有状态码和新文档的下载地址。

后端收到请求后下载新文件、覆盖存储、返回成功,整个流程就闭环了。

50 多个现成连接器

官方提供了 50 多个现成连接器,覆盖 Nextcloud、Moodle、Odoo、WordPress、SharePoint 等常见系统。如果你的系统正好在其中,接入会很快。

不过更有用的一点是,你完全可以不用连接器,直接调用 API,从零嵌进自己的业务系统。官方连接器本质上就是这套 API 的现成用法示例。看懂一个,自己写一个并不难。

ONLYOFFICE 集成时序图:浏览器、业务后端与文档服务之间的 config、拉取文件与保存回调流程

整个流程是:下发 config,文档服务拉取文件,保存时回调后端。

3.2 私有化部署

很多人第一次试用 OnlyOffice,就是为了私有化部署。

部署形态

OnlyOffice 文档服务可以部署在本地服务器、私有云或完全离线的内网环境。

官方下载页提供 Windows 和 Linux 安装包,也提供 Docker 镜像。

企业版产品页写明了:采用自托管部署,数据保留在你自己的基础设施内,第三方无法访问。

用 Docker 一条命令启动

最快的方式是 Docker:

docker run -i -t -d -p 8080:80 onlyoffice/documentserver

再挂载数据目录、配好 JWT,服务就在你的机器上运行起来了。本地服务器、私有云和离线内网用的都是这一套。

为什么私有化很重要

数据掌握在自己手里,才谈得上满足金融、医疗、政府这类客户的合规要求。

文档、用户数据和审计日志都留在你的基础设施里,OnlyOffice 官方接触不到。

SaaS 方案给不了这种保证,自研的成本又太高,私有化部署正好处在两者之间。

ONLYOFFICE 私有化部署架构图:文档服务、文件存储与审计日志都在自有基础设施内

文档服务、文件存储和日志都在你自己的基础设施内,官方不接触数据。

3.3 协作能力

协作功能是内置的,不需要额外装插件。

实时编辑

多人同时打开同一份文档时,每个人都能看到其他人的光标、选区和在线状态。

协同编辑有两种模式。快速模式会实时显示所有人的改动。严格模式下,你保存之后其他人才能看到你的修改,适合不想被打扰、专心写自己那部分的时候。

ONLYOFFICE 共同编辑模式:快速与严格两种模式切换

评论

选中一段文字就能添加评论,也可以 @ 提及协作者。评论和修订可以同时使用,适合审阅流程。

版本历史

在编辑器里可以查看文档的历史版本,对比差异,或者回滚到某个版本。

ONLYOFFICE 版本历史面板与修订预览

合同、报告、审批稿这类需要留痕的业务场景,离不开版本历史。

多用户通过相同 document.key 协同编辑同一份文档,文档服务负责实时同步、版本历史与评论提及

几个用户的浏览器只要使用同一个 document.key,打开的就是同一份文档。文档服务负责同步光标和改动,并管理版本历史和评论。

3.4 白标能力

白标是开发者版的核心功能,也是做 SaaS 的团队最在意的一项。

能换哪些内容

通过 editorConfig.customization,你可以替换编辑器界面里的 Logo 和深色主题 Logo,修改点击 Logo 后跳转的 URL,以及“关于”页面里的公司名称、地址、邮箱等信息。主题色也可以改。

这样客户看到的是你的品牌,而不是“由 OnlyOffice 提供技术支持”。

为什么重要

把 SaaS 产品卖给客户时,品牌一致也是产品体验的一部分。

产品里突然冒出一个第三方 Logo,客户会问“这是谁家的”,对产品的信任也会打折扣。有了白标能力,OnlyOffice 就成了你产品里“看不见的引擎”。

补充一点:OnlyOffice 支持离线 AI,但自托管部署后并不能直接使用。你还需要部署本地模型并完成配置,这是另一项工程。

四、实战演示:Spring Boot 接入 OnlyOffice

接入分四步: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/documentserver

记下 JWT_SECRET,后端生成 config 和校验回调都要用到它。

如果不设置密钥,或者用了弱密钥,文档服务在公网上就等于没有防护。生产环境不要这样做。

容器启动后先别急着写代码,花两分钟确认服务确实已经就绪。

先查出实际的容器名或 ID:

docker ps

docker ps 输出:onlyoffice/documentserver 容器状态为 healthy,8080 端口已映射

更稳妥的做法是在容器内查询版本信息:

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 installed successfully” 欢迎页,就说明主体服务已经启动。

ONLYOFFICE Docs 10.0.0 社区版安装成功欢迎页

如果页面打不开,先用 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.0

onlyoffice:
  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 令牌,也负责校验回调请求:

@Service
public 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。

不要随手用文件名或时间戳拼 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 签名。

签名的内容必须和前端实际拿到的配置一致。

再说文件访问。config 里的 url 由 ONLYOFFICE 服务端请求,不是浏览器直接请求。

如果文件放在内网,要确保文档服务容器能访问这个地址。否则就会出现浏览器能下载文件,编辑器却一直转圈、提示下载失败的情况。

项目没有把 /api/files/{id}/download 直接对外开放,而是给文档服务签发一个 15 分钟有效的下载令牌。

FileAccessService 的实现如下:

@Service
public 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 type="module">
  const config = await fetch(`/api/office/config/${fileId}`).then(r => r.json());
  new DocsAPI.DocEditor("office-editor", config);
</script>

这个示例在脚本里直接使用了顶层 await,所以第二个 script 标签要加上 type="module"。fileId 需要由页面自行提供。

项目没有把 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 环境变量没有配置,或者配置的值不同,编辑器就会白屏,并提示“文档安全令牌格式不正确”。

运行效果

文档中心首页:

Spring Boot 文档中心首页,展示上传入口和文档版本列表

在线编辑 Word 文件:

ONLYOFFICE 在线编辑 Word,顶部工具栏和文档画布均已正常加载

在线编辑 Excel 文件:

ONLYOFFICE 在线编辑 Excel,项目任务表的条件格式与数据条正常显示

五、版本选型速查

四项能力和实战演示讲完了。真到选型时,问题只有一个:你的场景决定该用哪个版本。

三个版本的功能差别不大,区别在授权方式、并发数和品牌控制权。

场景 推荐版本 关键约束
小团队、测试 社区版 AGPL v.3 有传染性;早期版本有 20 并发上限,从 9.4 版本开始已取消
企业内部部署、保留 OnlyOffice 品牌 企业版 50 并发起;可按年订阅或购买永久许可
提供 SaaS 服务、需要白标 开发者版 支持白标;只能按年订阅
为每位客户单独部署 看品牌需求 需要白标选开发者版,保留品牌选企业版

六、写在最后

再看开头那三个问题:SaaS 的数据出不了内网,商业 SDK 按人头收费承受不起,自研的隐性成本又太高。这三条路都走不通,大家才会去找别的办法。

OnlyOffice 的做法,是把“文档编辑”从一项外部服务变成一个可以装进自己系统的组件。

数据放在你自己的服务器上,编辑能力通过 API 嵌进业务流程,授权按场景选择,预算也能控制。

它也有局限。社区版受 AGPL 协议约束,老版本还有并发上限。白标只有开发者版才有。离线 AI 需要你自己额外部署模型。但如果你的要求是私有化、可集成、成本可控,OnlyOffice 确实能解决这个问题。

所以,文档协作的另一种选择,既不是更便宜的 SaaS,也不是再造一个自研轮子。它是一个数据留在自己手里、能嵌进自己系统的编辑引擎。

选型前先想清楚两件事:数据要不要留在自己手里?品牌要不要换成自己的?

这两个问题的答案,基本决定了你该选社区版、企业版还是开发者版。剩下的工作,就是一条 Docker 命令加一份 config。如果你在接入过程中遇到其他问题,也欢迎到云栈社区和其他开发者交流。

七、相关链接

更多资料:


作者:苏三




上一篇:FlowMQ Kafka 存储方案:降低云上成本与简化集群扩容
下一篇:Magpie 本地网关怎么用?订阅共享与模型路由详解
您需要登录后才可以回帖 登录 | 立即注册

关闭

站长推荐上一条 /1 下一条

手机版|小黑屋|网站地图|云栈社区 ( 苏ICP备2022046150号-2 )

GMT+8, 2026-11-21 15:43 , Processed in 0.109179 second(s), 41 queries , Gzip On.

Powered by Discuz! X3.5

© 2025-2026 云栈社区.

快速回复 返回顶部 返回列表