OnlyOffice集成实战：部署、前端集成与回调保存全解析

早在好几年前，我就被一个问题反复问住：“我想在自己系统里加一个能在线编辑文档的编辑器，是选富文本编辑器，还是 OnlyOffice？”我的回答从来都是：你先搞清楚自己处理的是“一段文字”还是“一份文档”。如果你只需要让用户写写通知、填填表单，那用一个成熟的富文本编辑器就够了；但如果你要的是一个能打开 docx、xlsx、pptx，排版接近桌面 Office，还支持多人同时修改、留痕批注的在线编辑环境，OnlyOffice 几乎是开源方案里最均衡的选择。这篇文章我只讲三件事：OnlyOffice 编辑器到底由哪几部分组成、怎么部署它、怎么真正把编辑器实现到自己的业务系统里。我从 Docker 部署、前端集成、回调保存到权限裁剪都用过三四年，下面的内容适合正准备选型、或者已经下载后遇到一堆安装问题的开发者。

1. OnlyOffice 不是一款软件：服务器、编辑器和工作区的边界

1.1 三兄弟分别用来干嘛

OnlyOffice 这个名字底下其实有三套东西，很多人第一次接触就栽在“装错组件”上。

第一套是 OnlyOffice Docs，社区版也经常被直接称为 DocumentServer。它是最核心的服务端组件，提供在线编辑 API、文档转换、协同编辑能力。它本身没有复杂的门户界面，部署完你会看到一个欢迎页和一个自带的示例页。我们做业务集成，说的就是集成这一套。

第二套是 OnlyOffice Workspace，可以理解为“自带文件管理、用户体系、权限、聊天功能的整套协作平台”，类似于自己动手搭一个带私有化部署的在线办公门户。如果你们团队就是想快速搞一个类似 Google Docs 的私有化环境，不考虑和现有 OA 深度集成，Workspace 很合适。但如果你已经有自己的用户系统和文件中心，硬上 Workspace 反而要处理两套账号体系的同步，工作量不比直接集成 Docs 少。

第三套是 OnlyOffice Desktop Editors，也就是桌面客户端。它既可以纯本地使用，也可以连接前面说的 Docs 服务器，在企业内网环境下体验非常接近传统 Office 软件。做系统集成的人经常忽略它，但很多企业实际落地的形态是“网页端给协作场景，桌面端给重度编辑场景”。

我在项目里通常只推荐集成 Docs，因为业务系统的核心诉求是把编辑器嵌进自己的产品里，而不是再造一个 OnlyOffice 门户。

1.2 编辑器、富文本编辑器和编译器，别混为一谈

很多相关热词里同时出现了“编译器”和“编辑器”，这里先做一个明确区分。日常我们说的 Vim、VS Code、文本编辑器，解决的是“怎么写代码、怎么改文件”；编译器解决的是“怎么把源代码变成可运行的程序”。OnlyOffice 属于前者，它是一个文档编辑器，不是编译器，不负责编译任何东西。

网页开发里的富文本编辑器，比如 TinyMCE、CKEditor，和 OnlyOffice 也完全是两种东西。富文本编辑器底层大多基于浏览器自身的 contenteditable 能力，适合拿来处理短文内容，比如评论、公告、邮件；但你要是让它打开一份一百页、满是目录和修订的 docx，它很容易排版紊乱，甚至直接把样式吃光。OnlyOffice 前端用的是基于 canvas 的文档渲染引擎，而不是直接操作 DOM 的文本框，所以它能做到接近桌面 Office 的页面排版还原。

用个生活化类比：富文本编辑器像便利贴，内容好写但撑不起正式排版；OnlyOffice 像一个完整的排版工作台，适合处理合同、方案、报表这类正经文档。所以选型的第一步，其实是判断你们的业务“内容”重不重。

1.3 什么业务真正需要它

我整理了一张选型对照表，方便你对号入座：

一旦确认业务属于“正式文档”场景，才需要继续研究 OnlyOffice 的部署和实现。

2. 部署只做这一件事：把 DocumentServer 跑起来并验证

2.1 下载地址和部署选型建议

OnlyOffice Docs 社区版是免费开源的，官方下载地址在 https://www.onlyoffice.com/download-docs.aspx?from=community。如果你是直接用 Docker，镜像在 https://hub.docker.com/r/onlyoffice/documentserver，桌面版安装包在 GitHub Releases 里也能找到。相关热词里很多人搜“onlyoffice server 下载地址”，很可能是因为官方页面更替过很多次，记忆里的链接变了。我的习惯是认准上面三个入口，不要从第三方站点下旧包。

部署方式我强烈推荐 Docker。原因很简单：OnlyOffice Docs 依赖 PostgreSQL、文档转化服务、协同服务等多个组件，用 apt 安装会把一整套组件都装到系统里，升级和卸载都比较痛苦。Docker 容器本身封装好了所有依赖，挂载卷和日志清晰，回滚也方便。只有一种情况我会考虑 DEB 包，那就是公司已经有严格的服务器基线，不允许上容器，要求直接用 apt 管理。

2.2 Docker 一键起服务

用 Docker 拉最新版并启动，命令很简单：

bash复制docker run -i -t -d \
  -p 80:80 \
  --restart=always \
  --name onlyoffice-docs \
  onlyoffice/documentserver:latest

这里要注意一个细节：-p 80:80 默认把宿主机的 80 端口映射到容器。如果宿主机上已经有 Nginx、Apache 或者其他服务占用了 80 端口，你可以改成 -p 8080:80。但端口一旦改了，后面前端初始化编辑器时，api.js 的地址、回调地址里所有涉及文档服务器 URL 的地方都要跟着改。很多人最开始用 80 端口没问题，后来部署到已有网关的机器上，改成其他端口后一直调不通，就是漏了这块。

启动完成后，用三个地址做最基本的验证：

• http://<服务器IP>/welcome/：能看到 OnlyOffice 版本信息，说明主服务活着。
• http://<服务器IP>/healthcheck：返回 true 说明核心健康检查通过。
• http://<服务器IP>/example：打开官方自带示例页，可以现场打开 docx、xlsx、pptx 试编辑，这是判断服务是否真正可用的最快方法。

2.3 用 apt 安装的另一种路径

不用 Docker 的话，安装思路是这样的：先把 OnlyOffice 官方软件源添加到系统，然后执行更新，再安装 onlyoffice-documentserver 包。官方文档会根据发行版给出当时的 GPG key 和源地址，这些命令在不同版本里会有变化，我建议直接复制官网当时的安装脚本，不要凭记忆写老命令。

装完后服务由 systemd 管理，默认监听 80 端口，日志落在 /var/log/onlyoffice/ 下。这个方式的好处是没有一层容器，排查系统级问题更直接；坏处是升级时容易残留旧配置，PostgreSQL 和文档服务之间偶发连接异常，排查起来比 Docker 容器要多不少步骤。

我在生产环境里已经很少用这套方式，不是因为不能跑，而是容器化之后更容易统一管理和回滚。

2.4 “onlyoffice 安装问题”里面，我踩过最多的五个

相关热词里“onlyoffice安装问题”被搜得非常多，我按出现频率把这几个坑列出来：

1. 80 端口被占：服务起不来，先 sudo netstat -tunlp | grep :80 看谁占了。要么停掉老服务，要么改端口映射，别硬扛。
2. 内存不足导致服务崩溃：DEB 包安装会自带 PostgreSQL 和转换服务，2GB 内存的机器很容易被 OOM killer 干掉进程，现象是打开文档时提示“文档服务不可用”。至少给 4GB，生产建议 8GB 以上。
3. 中文全部变成方块：服务自带字体不包含中文字体，这是官方镜像一直以来的痛点。需要手动装字体：sudo apt install fonts-noto-cjk fonts-noto-cjk-extra，然后 fc-cache -f，再重启文档服务。
4. 打开文档一直转圈：大概率不是文档服务器的问题，而是文档服务器通过文档 URL 去拉取你业务文件时拉不到。后面 3.4 节会展开讲。
5. PostgreSQL 连接失败：Docker 容器内置数据库，一般不用管；DEB 包安装时如果机器上已经跑着 PostgreSQL，端口 5432 冲突就很常见。

安装完成之后，别急着写代码，先把 /example 里的示例文档都打开一遍，确认能加载、能编辑、能保存，再进入下一步集成。

3. 前端集成：从一段 script 到真正能保存文档

3.1 初始化原理：前端只是壳，后端才是大脑

OnlyOffice 编辑器在前端的本质是一段 JavaScript 初始化：页面加载文档服务器上的 api.js，然后调用 DocsAPI.DocEditor 创建一个编辑器实例。但真正决定“打开哪份文档、谁能编辑、保存到哪里”的配置对象，绝不能写死在前端，必须由后端生成并签名。

原因很直接：编辑器配置里包含了文档下载地址、回调地址、用户信息、权限。如果前端随意构造，任何人都可以伪造一个配置，让文档服务器把业务文件当成自己的文件加载，或者把伪造的回调发给后端。开启 JWT 之后，配置对象要由后端使用密钥签名，文档服务器验签通过才接受。

所以整体实现要分三块：

• 文档服务器：负责编辑、转换、协同、保存缓存。
• 业务后端：提供文档下载接口、回调保存接口、配置签名接口。
• 前端页面：加载 api.js，用后端返回的配置初始化编辑器，监听关闭和保存事件。

3.2 一个最小可运行的集成示例

假设文档服务域名是 https://doc.example.com，业务系统域名是 https://app.example.com。前端页面代码大致如下：

html复制<script src="https://doc.example.com/web-apps/apps/api/documents/api.js"></script>
<div id="editor"></div>
<script>
  const config = {
    document: {
      fileType: "docx",
      title: "项目方案.docx",
      url: "https://app.example.com/api/files/1234?token=temp-download-token",
      key: "1234_v3",
      permissions: {
        edit: true,
        comment: true,
        download: false,
        print: false
      }
    },
    documentType: "word",
    editorConfig: {
      mode: "edit",
      lang: "zh-CN",
      callbackUrl: "https://app.example.com/api/files/1234/callback",
      user: {
        id: "u_1001",
        name: "张工"
      }
    }
  };
  const editor = new DocsAPI.DocEditor("editor", config);
</script>

实际项目中这个 config 应该由后端接口返回。如果开了 JWT，后端把整个 config 对象签名，再连同 token 一起给前端，Node.js 写法大概是：

js复制const jwt = require("jsonwebtoken");
const config = { document: {...}, editorConfig: {...} };
const token = jwt.sign(config, process.env.DOC_SERVER_SECRET, {
  algorithm: "HS256",
  expiresIn: "1h"
});
res.json({ ...config, token });

前端把返回对象作为初始化配置传进去即可。这里最容易犯的错误是只给 editorConfig 签名，实际上 OnlyOffice 要求对“整个配置对象”签名。

3.3 保存回调：整个链路真正的闭环

很多人在“点击保存后文档没更新”这个问题上卡很久，原因是没理解 OnlyOffice 的保存机制。OnlyOffice 文档服务器不会把你的文件直接 POST 回业务系统，它只会发一个回调通知，告诉你“新版文件在这里，你自己去下载”。

回调的 JSON 长这样：

json复制{
  "key": "1234_v3",
  "status": 2,
  "url": "https://doc.example.com/cache/files/.../output.docx",
  "user": "u_1001"
}

后端收到回调后要把文件内容保存到自己的存储里，核心逻辑大概是：

js复制app.post("/api/files/1234/callback", async (req, res) => {
  const body = req.body;

  // 此处在实际项目中必须先校验 JWT，防止伪造回调

  if (body.status === 2 || body.status === 6) {
    const stream = await fetch(body.url).then(r => r.body);
    await saveToStorage("file-id-1234", stream);
  }

  res.json({ error: 0 });
});

这里的状态码含义要记牢：

回调接口必须返回 { "error": 0 }，这是 OnlyOffice 约定的成功标志。你返回 { success: true } 它都不认。

3.4 前后端交互里最容易踩的三个坑

第一个是文档下载接口不能带复杂登录态。文档服务器在回调保存、打开文档时，都是服务器到服务器之间的请求，它不会输入账号密码。我的做法是提供带签名的短期临时下载地址，比如 /api/files/1234?sign=xxxx&expires=600，让文档服务器在 10 分钟内可以拉取，过期即失效。

第二个是key 不能随便换，也不能永远不变。key 在 OnlyOffice 里被用来识别同一份文档的不同版本。如果用户编辑过程中后端一直在更新 key，编辑器会频繁重载，直接打断操作；如果 key 始终不变，即使内容更新了，编辑器也可能从缓存里打开旧版本。推荐规则：文档ID_版本号，只有确认内容进入新版本时才递增。

第三个是回调地址必须能被文档服务器访问到。不能写 localhost，不能让回调接口前面挡着一层需要登录态的网关，也不能让 HTTPS/HTTP 协议不一致。只要回调地址文档服务器访问不到，一切保存动作都是纸上谈兵。

4. 使用细节：协同编辑、界面裁剪、权限与水印

4.1 四种编辑器，能力边界要说清楚

OnlyOffice 不止能做 Word 文档，它实际提供 word、cell、slide、pdf 四类编辑器，能力边界不一样，别默认它们都一样：

关于热词里“pdf编辑器”，OnlyOffice 的定位是“PDF 查看和批注工具”，不是 Acrobat 这种“PDF 文字修改工具”。如果你有用户想改 PDF 里的文字，要么把它当图片重新覆盖，要么先转回 Word 编辑再导出 PDF。

4.2 协同编辑和审阅怎么用

只要多个用户打开同一个 key 的文档，OnlyOffice 会自动进入协同模式。你可以在页面上实时看到对方的光标位置、选区和输入内容，体验和 Google Docs 很接近，这也是它区别于普通在线预览的核心价值。

审阅功能在 word 编辑器里做得比较完整。开启审阅之后，所有修改都会变成修订状态，另外的人可以选择接受或拒绝。这个能力对业务系统里的合同审批、制度流转特别有用，可以直接替代原来“下载附件、每个人改一遍、再合并”的老流程。

评论区也支持选中内容添加评论和 @ 用户。不过要注意，OnlyOffice 自带的通知机制有限，评论的实时提醒如果要做进自己的系统，通常需要额外开发轮询任务，去文档服务器那边拉取未读评论数据。

4.3 通过 customization 把编辑器裁剪成自己的组件

很多时候我们并不需要把整个完整工具栏暴露给用户。比如一个审批场景里，用户只应该能批注、修订，不应该能下载原文件，甚至不应该能打印。

通过配置可以做到类似效果：

js复制const config = {
  editorConfig: {
    customization: {
      autosave: true,
      forcesave: true,
      compactHeader: true,
      hideRightMenu: false,
      watermark: {
        text: "内部资料"
      }
    }
  }
};

forcesave: true 会显示强制保存按钮，并在回调里产生一条 status 为 6 的通知。水印是防止截图外泄最实用的手段。这里要提醒一句：前端隐藏下载按钮只能防普通用户，真要在安全要求高的环境里堵住下载，必须把配置里的 permissions.download 设为 false，同时在后端下载接口也做权限控制，双管齐下。

4.4 格式转换不只是“另存为”

OnlyOffice 文档服务器自带一个转换服务接口，可以把 docx、xlsx、pptx 转成 PDF、TXT、HTML 等格式。最常见的用法有两个：

第一个是在线预览 Office 附件。用户上传一个 docx 后，后端调转换接口生成 PDF，前端直接显示 PDF 预览。这样不用在用户电脑上安装 Office，也不用担心浏览器兼容性问题。

第二个是保存后的二次处理。比如合同文档编辑完成后，自动转换一份 PDF 作为不可篡改的盖章版本，或者转成文本喂给全文检索索引。

转换接口是 POST /ConvertService.ashx，参数里需要带上源文件 URL、目标格式、以及 JWT 签名。转换属于 CPU 密集型任务，文件大了之后会明显拉高服务器负载，生产环境不要把它做成同步请求，最好丢到任务队列里慢慢消费。

5. 生产环境兜底：内存、字体、回调与安全

5.1 给文档服务器多少资源才算够

OnlyOffice 官方给的底线是双核 2GB，但这个底线只够一个人轻度编辑。我按自己的实测经验给出一个更实用的建议：

• 5 到 10 人同时在线编辑：4 核 8GB 比较稳。
• 20 到 50 人使用，还经常做 PDF 转换：8 核 16GB。
• 文档转换并发高的话，CPU 比内存更重要，多一点核心收益明显。

容器部署时，我不建议给容器加一个特别严格的 --memory 硬上限，因为当内存用到顶时会被内核直接杀掉，反而引发“文档服务不可用”的连锁反应。更好的做法是用 --cpus 限制 CPU，再通过监控观察实际内存趋势。磁盘方面，容器镜像本身加临时文件加 PostgreSQL 数据，至少准备 30 到 50GB。

5.2 HTTPS、跨域与回调的三角关系

一旦你的业务系统跑在 HTTPS 下，文档服务器也必须走 HTTPS，否则浏览器会因为混合内容拦截加载。用 Nginx 反向代理时，要把 /web-apps、/cache、/coauthoring、/ConvertService.ashx、/docservice 这些路径都代理到文档服务上，并且把代理超时时间调大，因为协同编辑有很多 WebSocket 长连接。

如果前端页面和文档服务器不是同一个域名，跨域问题会非常多。最简单的做法是让它们共用同一个主域，用 Nginx 做路径转发，从源头上把跨域消掉。如果确实做不到同域，再考虑配置 CORS 头，但要注意文档服务器发起的回调并不遵守浏览器 CORS，那是服务端请求，不能只靠前端配置解决。

JWT 是一定要开的。容器环境里通过环境变量设置：

yaml复制environment:
  - JWT_ENABLED=true
  - JWT_SECRET=your-strong-secret
  - JWT_HEADER=Authorization

前面说的前端配置签名，用的就是同一个 JWT_SECRET。回调接口那边，也必须校验请求头里的 JWT 签名，否则一旦回调地址泄露，别人完全可以伪造一条“保存完成”通知，把你的文档覆盖成恶意内容。

5.3 日志定位和升级回滚

Docker 部署时看日志的方式很直接：

bash复制docker logs --tail 100 onlyoffice-docs

一旦编辑器打开失败，我一般按三条线去查：转化服务日志、文档服务日志、协同服务日志。大多数“打开就转圈”的问题，日志里会直接说“源文档 URL 不可达”或者“签名校验失败”，信息量比浏览器端大得多。

升级时先把新镜像拉下来，然后停旧容器、删旧容器、用新镜像起一个新容器。如果有自定义字体、插件、证书，通过挂载卷带入，升级不会丢。大版本升级前一定要看官方发布说明，尤其是 API 字段和 JWT 默认行为的变化，升级后先在测试环境完整跑一遍打开、编辑、回调保存，确认没有问题再切生产。

5.4 几个隐蔽的配置点

• client_max_body_size：如果用户要上传 200MB 的 PPT，Nginx 默认 1MB 就会直接拒绝，这个值要调大。
• 临时文件访问有效期：文档服务器打开文档时去拉源文件，如果签名有效期只给几分钟，而文档很大、转换很慢，就会拉取失败。给个 10 到 20 分钟更稳。
• 时间同步：文档服务器和业务服务器之间时间差太大会导致 JWT 验签失败，两边最好都用 NTP 同步时间。

6. 三年实战下来我总结的隐藏坑与选型建议

6.1 文档 key 的生成规则要先定好

这是我在多个项目里吃过亏的地方。如果拿数据库自增 ID 当 key，用户修改后文档服务器会认为还是同一个文件，打开的都是缓存里的旧状态；反过来，如果每次打开都随机生成 key，用户编辑到一半文档会突然被重载，因为文档服务器认为版本发生了跳变。

稳妥的做法是 文档ID_版本戳，只在文档内容发生明确变化时递增版本。用户只是预览不修改，就不要让版本号变动。如果业务系统里确实需要强制用户看到新内容，用编辑器实例的 refresh() 方法刷新即可，不需要动 key。

6.2 和业务系统打通的正确姿势

用户体系打通，核心是保证 editorConfig.user.id 稳定。这个 id 会跟随修订、评论、历史版本记录，一旦用户对象被删除或 ID 被复用，历史记录就会归错人。

文件存储不要给文档服务器直接暴露内网共享目录。最理想的方式是通过你自己的文件服务给一个带签名的可再生 URL，文档服务器只能拿到临时访问权，权限控制和审计都留在业务层，这样即使文档服务器被攻破，文件库也不会被整个拉走。

6.3 中文场景必须提前处理

中文字体是中文项目绕不开的第一坑。不装 Noto CJK 字体，打开中文文档全是方块，导出的 PDF 更是没法看。在此基础上，还要考虑两个细节：水印里的中文如果没有字体支持，水印会渲染成空；用户使用了某种特殊中文字体而服务器上没有，会自动回退到默认字体，不一定会报错，但是观感可能有变化。

生产环境里我一般会多装“思源黑体”“思源宋体”这类常见中文字体包，尽可能和用户端字体保持一致。

6.4 我的选型建议，以及一个私藏小技巧

如果只是给后台加一个能写富文本的输入框，真的没必要上 OnlyOffice，内存和部署复杂度都是额外负担。但如果你的产品核心是“让用户在线处理正式文档”，OnlyOffice 社区版是目前开源方案里综合最均衡的选择之一。代价是它需要有人维护，至少团队里要有一个懂 Linux、懂基本 API 集成的人。

最后分享一个很实用的小技巧：上线前把用户打开编辑器时的浏览器控制台报错统一收集到日志里。很多问题并不是配置写错，而是用户浏览器版本太老、WebSocket 被企业防火墙掐断、或者内网证书链不全。这些在控制台里一眼就能看到，比在服务端日志里猜半天快得多。OnlyOffice 这个生态不算小，但文档分散、版本更替快，遇上问题最好先定位是“部署层、集成层还是浏览器层”，再动手排查，能省下大量时间。