前言

传统OA 系统里往往已经沉淀了合同、审批附件和项目资料，但要改一份 Office 文件，用户仍常要经历“下载—本地编辑—重新上传”。文件离开系统后，版本很容易混乱；原本由 OA 管理的权限、流程和归档，也会在编辑环节出现断点。对已有 OA 而言，真正需要补上的不是另一套文件库，而是能在原有文件与权限边界内完成编辑、保存和回写的能力。

图 1　ONLYOFFICE 官网产品页：Docs 覆盖Word、Excel 、PowerPoint和PDF

基于这个需求，我选择了 ONLYOFFICE Docs 作为编辑组件。它是 ONLYOFFICE 文档产品页所介绍的开源在线办公套件，可在浏览器中处理 Word、Excel、PowerPoint和PDF 等Office文件，并支持实时共同编辑、批注、修订和版本历史。更重要的是，编辑器、文档服务和转换服务可以部署在自有环境中：OA 仍负责账号、文件和权限，ONLYOFFICE Docs 专注完成在线编辑。已有适配平台可通过 连接器 接入；自研 OA 也可通过 开发者版与 Docs API 完成嵌入。本文实测的重点，就是验证这两种路径能否形成“打开—编辑—保存—重开”的完整闭环。

为避免只停留在功能说明，我用 M3 MacBook Pro 和 Docker 搭建了本地环境，分别走连接器和 Docs API 直连两条路径。前者验证已有文件平台接入后的使用体验；后者则在一个简化 OA 页面中验证 Word、Excel 和 PPT 的打开、编辑、保存与重开。

接下来我会从 OA 需要补齐的能力、两条接入路径的差异，以及本地部署后的实际操作体验三部分展开。需要自行评估产品的读者，可先 在线试用；计划在自有环境部署的团队，可从 本地部署下载页 获取安装包与部署入口

一、OA 到底要补什么

以前在 OA 或业务系统里处理 Word，我的动作基本固定：下载一份文件，在本地改完，再上传回去。一个人写东西还好，文件一旦要在同事之间来回传，最后谁改了哪一版很容易说不清。

这次我没有把题目理解成每家公司都要从零开发一套 OA。这里的 OA 可以是自研系统，也可以是私有化部署、再按流程定制过的平台；合同、项目、知识库和文件管理系统，只要它保管用户、文件和权限，都可能有给文档增加在线编辑的需求。

在线编辑也不是把网页编辑器塞进页面就结束。按照 ONLYOFFICE 的官方工作方式，文档管理与存储服务留给集成方，编辑器、编辑服务与转换服务交给 Docs。翻成 OA 的语言就是：OA 继续负责账号、组织、文件、审批与权限；ONLYOFFICE Docs 负责浏览器中的文档、表格和演示文稿编辑；本次三类文件都通过同一套回调机制回传。保存时，Docs 再把最新文件交还给 OA。真正的边界不在有没有编辑按钮，而在谁拥有文件和权限。

环节	OA 或业务系统负责	ONLYOFFICE Docs 负责
打开文件	校验用户，生成文件地址与权限	加载对应编辑器
编辑过程	提供文件存储与业务上下文	编辑、协作、格式转换
保存回传	接收回调，下载新版本，留存记录	按 callbackUrl 通知保存状态

一条从打开到保存的完整数据流是：用户在 OA 点击文件 → OA 校验身份并给出文件 URL、权限、document.key 与 callbackUrl → 浏览器加载 ONLYOFFICE 编辑器 → Docs 读取原文件并提供编辑能力 → 保存时 Docs 回调 OA → OA 拉取新版本并写回自己的文件库。

图 2　OA 接入 ONLYOFFICE Docs 的打开、编辑与保存回传数据流

这个分工也解释了为什么"下载—编辑—上传"会带来问题：版本与权限都留在 OA，编辑却跑到了用户的本地电脑。在线编辑的价值，是让文件的归属不变，只把编辑动作搬进浏览器。

二、先选对接入路径

有现成连接器的系统，先走连接器

如果现有系统已经有成熟的 ONLYOFFICE 连接器，例如 DzzOffice、企业网盘或协作平台，优先从连接器开始最稳。它通常已处理文件列表、用户信息、编辑器配置和回调协议，实施重点从开发编辑器变为检查地址可达性、JWT 和保存回传。这条路适合已经有文件库和账号体系、想先验证在线编辑效果的团队——我的 DzzOffice 实测就属于这一类。

自研 OA 没有连接器，走 Docs API

如果 OA 是自研的，或现成连接器无法满足审批流、档案编号与权限模型等要求，才需要直接集成 Docs API（官方文档）。前端初始化时，OA 需要生成文档类型、文件地址、唯一 key、用户与编辑权限、callbackUrl 和 JWT token，再以这些对象启动 DocsAPI.DocEditor。

这里不应该把它误解成嵌一个 iframe：服务端还要提供能被 Docs 访问的文件地址，并实现 callback 接口。集成方需要自己实现文档管理与存储服务，编辑后的文件才能真正回到 OA。

复用现有协作套件，先判断系统边界

如果团队日常文件、审批和协作都已经在飞书、钉钉或企业微信的原生文档体系内，未必需要再引入一套 Docs 服务；也可以把文件能力交给企业网盘或办公中台。ONLYOFFICE 更适合的场景是：文档必须留在已有 OA 或业务系统里，或者组织希望把编辑服务部署在自己可控的环境中。

路径	开发投入	适合场景	实施重点
连接器接入	低	已有支持平台	地址、JWT、回调验证
Docs API 直连	中到高	自研或深度定制 OA	权限映射、配置生成、回调落库
复用套件或办公中台	低到中	文档入口可迁移或已有中台	评估系统边界与迁移成本

三、编辑器选型：为什么是 ONLYOFFICE Docs

这次的目标是让 OA 中原有的 Office 文件能在浏览器里打开和保存，因此我把 ONLYOFFICE Docs 作为实测对象。它既可以通过连接器接进现有平台，也能把编辑器嵌进自研页面；对需要保留既有文件库、审批号和权限模型的场景，这两条接入方式都比较顺手。

如果团队已经围绕 LibreOffice 或某个特定协作生态运转，也可以评估 Collabora Online；如果需求只是多人记事或 Markdown 协作，轻量文本工具反而更简单。它们之间不是单纯的优劣替代，关键要看三点：要不要 Office 文件的版式、表格与批注，要不要保留原系统内的权限边界，以及文件必须放在哪里。

判断维度	连接器优先	API 直连优先	换用原生协作产品
文件归属	原平台已有文件库	必须留在自研 OA 或业务库	可以迁到新平台
流程耦合	沿用平台现有权限	审批、编号、档案规则很深	流程主要在协作产品中
实施速度	最快，偏配置	需要开发与联调	取决于迁移与培训

四、实测一：DzzOffice 连接器路径

ONLYOFFICE 的 连接器目录将 DzzOffice 列为企业和团队协作的开源办公套件。DzzOffice 本身已有网盘、文件夹、账号与权限，很适合代表“已有文件库和账号体系的系统”来验证连接器路径：用户不必离开原来的文件入口，编辑器只在打开文档时出现。

环境与部署

我的环境是 M3 MacBook Pro、16GB 内存和 Docker Desktop 28.5.1，实际启动了 DzzOffice、MariaDB、Redis 与 ONLYOFFICE Docs 9.3.0.1，DzzOffice 侧安装应用市场的 ONLYOFFICE 插件 V2.1.2。Document Server 从 7.1 起支持 ARM64；部署前可先阅读 官方 ARM64 Docker 安装说明，并从 ONLYOFFICE Document Server 镜像页确认标签。本文本机使用的 DzzOffice 容器镜像来自 xiaohu2023/dzzoffice；它用于本地联调，生产环境应固定可追溯的镜像版本或摘要。

镜像与命令说明：下文的 Docker Compose 由项目 compose 文件按上述来源拉取镜像。若单独预拉取，请先在镜像页确认版本标签，再执行相应 pull 命令；不要把测试环境的 latest 当作生产版本。

# 首次拉取镜像并启动 DzzOffice、数据库、缓存和 Docs 服务
docker compose pull
docker compose up -d

# 确认四个服务都在运行
docker compose ps

# 检查 ONLYOFFICE Docs 是否已经能够接收请求
curl -I http://localhost:18081/healthcheck

图 3　Docker Desktop 中的本机容器服务已启动

图 4　DzzOffice 与 ONLYOFFICE Docs 的本机连通性验证

图 5　本机启动后的 DzzOffice 安装向导

图 6　DzzOffice 已通过环境检查，而不只是停在 Compose 文件中

启动后，我从 DzzOffice 应用市场安装 ONLYOFFICE 插件。配置页里最关键的不是美观的开关，而是 Document Server API 地址、DzzOffice 文件服务器地址和 JWTSecret——DzzOffice ONLYOFFICE 应用市场页也专门提到了 JWTSecret 与内网地址设置。

踩坑：localhost 的网络视角

我的第一轮配置把 Document Server 地址填成了本机 localhost。浏览器里编辑器可以打开，保存按钮也会变灰；但关闭后重开，ONLYOFFICE 弹出了服务器备份副本提示。

原因出在网络视角不同：浏览器中的 localhost 是我的 Mac，DzzOffice 容器里的 localhost 却是容器自己。Docs 要把最新文件交回 DzzOffice 时，回调端从错误地址拿不到文件。把 Document Server 地址改成浏览器与容器都能访问的局域网地址后，回调恢复正常。

这个坑正好暴露了集成时最核心的工作：callbackUrl 必须是集成方提供的绝对地址，编辑服务会通过 POST 通知状态。官方 callback 处理说明中列出的状态 2 表示文档已准备保存，状态 6 表示当前状态已被强制保存，回调中会带可下载的新文件地址；存储服务处理后需要返回 {“error”:0}。

对自研 OA 来说，回调接口至少要做四件事：校验请求与文档 key 的归属、下载新版本、以原文件或新版本号写回存储、记录保存结果。DzzOffice 例子虽然由插件完成了这部分，但网络地址配置失败时，仍然会在同一个保存闭环上出问题。

保存闭环验证

我在 DzzOffice 网盘新建了空白 Word 文档。点开后，页面仍在 DzzOffice 的文件环境里，文档主体则变成 ONLYOFFICE 编辑器；中文菜单、开始和插入等工具栏可以直接使用。

图 7　写入测试内容后，状态栏显示所有更改已保存

我写入测试文字、保存、关闭编辑页，等待回调请求结束，再从 DzzOffice 网盘打开同一份文件：保存的文字仍然在，也没有再出现备份副本提示。

图 8　重新打开同一份 Word 文件后，仍可读到保存内容

这个结果证明了最基础、也最容易被忽略的一点：编辑器能打开不等于集成成功，保存后能回到原系统才算闭环。

五、实测二：最小自研 OA 直连 Docs API

为了不把 API 部分写成纯资料整理，我又做了一个最小自研 OA 页面。它不依赖 DzzOffice：页面自己提供文件接口、根据当前文件生成编辑器配置，并在回调接口里把编辑后的文件写回 OA 文件服务。截图中的"星河 OA"只是本地演示界面，不代表一个产品。

五项不能省的能力

能力	自研 OA 需要提供什么	为什么不能省
文件读取	Docs 可访问的临时或受控文件 URL	编辑服务需要下载原文件
编辑器配置	文件 key、类型、用户、权限、callbackUrl	决定打开哪份文件、谁能编辑
权限映射	将 OA 的查看、编辑、下载等权限映射到编辑器配置	不能因接入编辑器绕过 OA 权限
保存回调	接收状态 2 / 6，取回并写入新文件	否则编辑结果不会回到 OA
JWT	用统一密钥签发并校验配置	防止配置被篡改或未授权调用

核心配置

官方 配置说明把 document、editorConfig 和 token 作为启动编辑器的核心部分，权限、文档 URL、用户与 callbackUrl 都在这里传入。下面是我本地配置接口的精简结构，密钥不写入前端：

const config = {
  documentType: 'word',
  document: {
    fileType: 'docx',
    key, // 每次文档变更后必须更新
    url: oaFileUrl, // Docs 可访问的文件地址
    permissions: { edit: true, download: true }
  },
  editorConfig: {
    user: { id, name },
    callbackUrl: oaCallbackUrl,
    customization: { forcesave: true }
  }
};

config.token = signWithJwt(config); // 密钥只留在服务端

保存—重开闭环验证

页面加载后，左侧仍是 OA 的文件信息和权限说明，右侧由 ONLYOFFICE Docs 渲染 Word 编辑器。这里的关键不是页面长得像不像 OA，而是配置中的文档 URL 和 callbackUrl 都由 OA 自己控制。

图 9　最小自研 OA 通过 Docs API 加载 Word 编辑器

我在编辑区补写一行标记内容后点击保存。因为配置开启了强制保存，Docs 向本地 callback 发出 status 6；OA 回调服务下载该地址返回的新文件、写回自己的文件路径，并按协议返回 error: 0。

图 10　点击保存后，页面显示已收到 status 6 并写回 OA 文件服务

随后我刷新页面，让 OA 再次依据已写回文件生成新的 document.key 并打开。编辑区中的 API-SAVE-OK 标记仍然存在，页面也显示了关闭编辑会话后收到的 status 2 回调。这个"保存—重开"过程证明了 API 直连路径至少在 Word 场景已形成闭环。

图 11　刷新后重新打开，保存标记仍在，OA 收到 status 2 回调

Excel 与 PPT 的保存回传

Excel 部分，我在最小 OA 中打开 XLSX 项目进度表，将单元格 D5 修改为“Excel-SAVE-OK”，点击保存。页面显示 ONLYOFFICE 已完成保存，OA 收到 status 6 并将新版文件写回自己的文件服务。

图 12　Excel 写入标记后，OA 收到 status 6 并完成文件回写

刷新页面后，OA 根据写回后的文件重新生成 document.key；“Excel-SAVE-OK”仍保留在单元格中，同时页面显示关闭会话后的 status 2。这证明表格不是只在浏览器里改了显示，而是已回到 OA 文件服务。

图 13　刷新重开 XLSX 后，Excel-SAVE-OK 标记保留并收到 status 2

PPT 部分，我打开一份由 OA 文件服务提供的单页 PPTX，在正文文本框新增“PPT-SAVE-OK”，再执行保存。演示文稿编辑器正常加载，保存完成后 OA 同样收到 status 6。

图 14　PPT 写入 PPT-SAVE-OK 后，编辑器显示所有更改已保存

刷新并重新打开后，新增的 PPT-SAVE-OK 仍在幻灯片内，OA 页面记录到 status 2 回调。到这里，Word、Excel、PPT 三类常见 Office 文件均完成基础编辑与回传闭环；但复杂模板、动画、宏、公式兼容性不在本轮结论内。

图 15　刷新重开 PPTX 后，PPT-SAVE-OK 标记仍在，OA 已完成回传

两个容易忽略的细节

• document.key 不是任意固定字符串。官方编辑常见问题提醒：每次文档变更后应生成新 key，否则编辑服务可能从缓存取旧文件。我的演示页按文件更新时间生成 key，生产系统则应使用文件版本号或内容版本。

• Office 类型不该只盯着 Word。ONLYOFFICE Docs 的配置可声明 word、cell、slide、pdf 与 diagram 等文档类型，对应常见的文档、表格和演示文稿。为避免只凭产品说明下结论，我随后用同一套最小 OA 的文件接口、权限配置与 callback，分别跑了 XLSX 和 PPTX 的“打开—编辑—保存—重开”闭环。

六、深入体验：拿“项目周报资料包”跑一遍

为避免体验部分停留在概念描述，我重新拉起本地 Docker 环境，把验证换成一个更接近日常工作的“项目 A / 周报资料包”：其中有第 33 周产品迭代周报、交付台账和周会评审材料。三份文件均由同一个 OA 文件服务提供，编辑器只负责在页面内打开，文件归属、权限和保存回传仍留在 OA。

**周报 Word：**我从“项目 A / 周报资料包”打开《第 33 周产品迭代周报》，页面左侧仍显示文件归属、可编辑权限和周报流转信息；正文在右侧直接进入编辑状态。补写编辑记录并点击保存后，外层 OA 页面显示已收到 status 6，说明这次保存已从编辑器回传并写回 OA 文件服务。

图 16　项目周报在 OA 页面内完成编辑并回传，外层状态显示 status 6

交付台账 Excel：同一入口换成《项目 A 交付台账》后，编辑界面仍保留表格特有的列、单元格和工作表结构。对项目管理场景而言，这一点很实在：文件不会因为切到在线编辑就失去“工作项—负责人—风险等级—下周动作”的可读性，更新动作可继续在原来的项目上下文中完成。

图 17　项目交付台账在同一 OA 周报资料包中打开，表格结构与文件元信息同时可见

周会 PPT：我再打开《周会评审材料》，在正文中补充评审结论后保存。PPT 编辑器保留了缩略图、文本框和放映入口，保存完成时，OA 同样显示 status 6。也就是说，Word、Excel 与 PPT 不是三套不同的文件流程，而是同一套权限、文件地址和 callback 配置下的三种编辑器形态。

图 18　周会评审材料保存后，OA 收到 status 6 并写回新版 PPTX

这一轮最直接的感受不是“网页里多了 Office”，而是资料包没有离开 OA。连接器适合已有成熟文件库、希望快速加上在线打开能力的团队；若审批、档案编号或项目上下文已深度定制，Docs API 直连能让编辑器嵌在原业务页面中。无论选哪条路径，用户看到的都是同一个连续动作：从 OA 打开、在浏览器中编辑、由 OA 接住保存结果。

七、权限与安全：让编辑器消费权限，而不是创造权限

在 OA 场景里，编辑器应该消费权限，而不是创造权限。我的最小页面把"可编辑、可下载"明确写进 document.permissions；实际项目则应由 OA 在每次打开时根据部门、角色、流程状态和文件密级生成这份权限。已进入审批锁定状态的文件，可以只给查看或批注，不能因为嵌入编辑器就绕过流程。

关注点	建议由 OA 实施	这次验证的边界
身份与权限	服务端生成用户、编辑/下载/打印权限	最小页面传入演示用户与编辑权限
保存回写	校验 document.key、记录版本和操作者	收到 status 2 / 6 后写回本地文件
网络边界	HTTPS、固定域名、回调访问控制	本机 Docker 网络联调，不等同生产配置
审批关联	按流程节点控制编辑、锁定与归档	未接入真实审批流

JWT 的作用也要摆正：它用于给编辑器配置加签，避免重要参数被替换；但它不能代替 OA 自己的登录鉴权、文件访问审计和审批规则。对于回调地址，生产上还应限制来源、核验文档归属，并避免把任意 URL 当作可下载地址。

八、实测结论

两条路径已形成完整证据链：连接器路径跑通 Word 的保存闭环；Docs API 直连路径跑通 Word、Excel 与 PPT 的“打开—编辑—保存—重开”。实测结果与上线建议如下：

维度	本次已验证	上线建议
功能	Word、Excel、PPT 的打开、编辑、保存、重开	按典型业务模板与协作方式设定验收标准
网络	浏览器与容器可达、回调成功	固定域名、HTTPS、反向代理与故障恢复
安全	JWT 已配置，权限仍由原系统管理	回调鉴权、地址白名单、审计日志与备份
运维	Docker 服务已运行	监控、容量评估、升级与回滚演练

给准备落地的团队一个建议：先摸清现有 OA 的使用人数、最常见的三类文档，以及这些文档的主要访问方式。已有文件库与账号体系、希望快速验证效果的，可优先选连接器接入；审批、编号、档案和权限模型已深度定制的，自研 OA 更适合通过 Docs API 保持文件与权限仍由原系统掌控。上线时，再将并发容量、协作权限与典型业务模板纳入自身的验收标准。

这次实测让我更确定：给 OA 增加 Office 在线编辑并不是装个插件那么简单，但也不必从零制造一个办公套件。已有连接器时，重点是把网络、JWT 与保存回传做实；自研 OA 需要直连 API 时，重点是文件、权限和回调闭环。

除了编辑，ONLYOFFICE 文档还提供实时共同编辑、批注、修订和版本历史等协作能力；对已有平台，可通过 现成连接器 或 开发者版与 Docs API 接入。学校若希望先低成本验证，可先 在线试用；如需把文档、账号和权限留在校内环境，可前往 本地部署下载页 评估自托管方案。教育优惠与免费方案以 2026 开学季官方说明 为准。

DzzOffice 加 ONLYOFFICE 证明了连接器路径能跑通：一份 Word 可以从系统网盘进入浏览器编辑，再回到原来的文件位置。对于已有文件与权限体系的团队，这是成本低、验证快的起点；当流程和权限更复杂时，再以同一套原理把 Docs API 接进自研系统，才是更稳的扩展方式。