企业官网建设流程全解析

最近好几个做企业系统的朋友都在问同一件事：Vue项目里怎么把Word文档在页面上展示出来，还得能在线编辑、改完还能保存回去。这个问题看起来简单，真正动手才会发现坑不少——Word本身是带格式的复合文档格式，浏览器不可能直接渲染，在线编辑也不是套个textarea就能糊弄过去的。我最近把一个完整的文档管理需求在Vue项目里从零实现了，包含只读渲染、在线编辑、保存回调全链路，把过程中的方案对比、踩坑经历和最终代码整理成这篇笔记。如果你正在做文档管理系统、OA审批、知识库或者后台文件预览功能，这篇可以直接拿来当参考。

先说结论：纯预览场景我用docx-preview，轻量、快、不依赖后端；需要在线编辑的场景我接入了OnlyOffice Document Server，自部署、开源、数据留在内网。两种方案组合使用，覆盖了“只读查看”到“在线协同编辑”的完整需求。下面我会把每一步的原理、配置、坑位都写清楚，尤其是OnlyOffice的保存回调机制，这是最容易让人卡住的地方。

1. 需求拆解与方案选型

1.1 先分清你的需求是“预览”还是“编辑”

很多人一上来就搜“Vue word渲染”，实际做的需求可能只是“能看就行”，也可能真的要“能改能存”。这两种需求对应的技术方案完全是两码事，所以第一步不是写代码，而是把需求边界划清楚。

我一般会先问三个问题：

• 用户只是查看文档内容，还是要修改文档？
• 修改后是保存为新文件，还是覆盖原文件？
• 文档是内部系统里的私有数据，还是公开文件？

如果是“只看不改”，引入一套完整的在线编辑服务纯属杀鸡用牛刀；如果是“要改要存”，光靠前端渲染组件根本做不到，必须有一个编辑器后端配合。下面这张表是我自己的需求判断速查，遇到新项目直接对照着选型：

1.2 市面主流方案对比

我在选型时把市面上的主流方案都过了一遍，简单说一下各自的定位和优缺点。

docx-preview（npm包）：纯前端解析docx并渲染成HTML，支持分页、表格、图片，使用简单，几行代码就能接入。缺点是只支持新版.docx格式，老式.doc二进制格式无能为力，而且不支持编辑。

mammoth.js：同样是将docx转换为HTML，但它的目标是“干净的语义化HTML”，会丢掉很多Word原始排版信息，比如页码、页眉页脚、复杂表格。适合做正文提取、导入导出场景，不适合追求一比一还原的预览。

OnlyOffice：一个开源在线办公套件，自部署服务端后，前端通过iframe或SDK嵌入编辑器。它本身就是一套完整的编辑器和协同服务，支持docx、xlsx、pptx、pdf等格式。社区版免费，UI和兼容性都不错，是目前自托管方案里最成熟的选择。缺点是部署依赖Docker，初期配置稍微有点门槛。

kkFileView：一个基于Spring Boot的文档预览服务，支持Office、PDF、图片、视频等几十种格式，内部依赖OpenOffice/LibreOffice做转换。优点是格式覆盖面广，缺点是不支持在线编辑，且部署一套Java服务对纯前端项目来说略重。

微软Office Online Server / WPS WebOffice：体验最接近原生Office，但Office Online Server部署极其复杂，需要域环境，WPS开放平台的授权和合规也要评估。对中小型项目来说，如果不是硬性要求，我不会优先选这两条路。

1.3 我最终选型逻辑

我最终确定的是“docx-preview做预览 + OnlyOffice做编辑”的组合，原因很直接：

• 预览场景追求轻量，一个npm包就够，不用为“看一眼文档”去部署一套服务。
• 编辑场景必须保证编辑体验和数据安全，OnlyOffice社区版免费、可自部署、数据不经过第三方，适合企业内网系统。
• 两者都是开源方案，没有授权风险，也不依赖公网服务，部署在客户内网也能跑。

需要提醒的是，OnlyOffice社区版用的是AGPL协议，如果你是把系统对外商业化售卖，需要考虑协议义务；如果是企业内部自用，基本没影响。这个我在后面第6节还会再讲。

2. 文档只读预览：docx-preview集成详解

2.1 为什么先用docx-preview

很多场景下用户其实只是要在页面里打开一个Word附件看看内容，比如审批流里的附件预览、知识库里的文档查看。这种需求如果也调OnlyOffice，每次打开都要加载一个完整的编辑器框架，首屏体验反而不如轻量渲染组件。

docx-preview的原理是在浏览器里把docx包内的XML和资源文件解析出来，转成带样式的DOM节点渲染到容器里。它在浏览器端只做纯解析，不需要后端介入，加载速度很快，特别适合做“列表页点击附件直接预览”这种高频轻量操作。

2.2 安装与三行代码接入

先装包：

npm install docx-preview

然后在Vue组件里这样用：

<template> <div ref="previewRef" class="docx-preview-container"></div> </template> <script setup> import { ref, onMounted } from 'vue' import { renderAsync } from 'docx-preview' const previewRef = ref(null) async function previewDocx(file) { // file 可以是 Blob、ArrayBuffer 或者文件路径 const blob = file instanceof Blob ? file : await fetch(file).then(res => res.blob()) await renderAsync(blob, previewRef.value) } onMounted(() => { // 示例：直接请求后端接口拿文件流 previewDocx('/api/file/123.docx') }) </script>

renderAsync的核心参数就两个：传入的文件数据，和挂载的DOM容器。它返回Promise，页面加载完会开启一个类似Word文档的翻页视图，每页上下带阴影，底部还有页码。我这里没有做额外分页样式，默认效果已经够用。

2.3 预览样式的几个调优点

默认渲染效果虽然能用，但有几个细节通常要单独调。

第一是字体。docx-preview渲染中文文档时，如果系统里没匹配到文档指定的字体，会退回到默认字体，显示效果偏丑。可以在渲染时传入options覆盖默认样式：

await renderAsync(blob, previewRef.value, undefined, { className: 'docx', inWrapper: true, ignoreWidth: false, ignoreHeight: false, ignoreFonts: false, breakPages: true, ignoreLastRenderedPageBreak: false, experimental: false, useBase64URL: true, bodyStyles: ['font-family: "Microsoft YaHei", "PingFang SC", sans-serif; font-size: 14px;'] })

useBase64URL这个参数建议打开，它会把文档内的图片资源转成base64，避免渲染时图片加载不到。breakPages保持默认的true，才能实现Word那种一页一页的视觉效果。

第二是容器高度。组件默认会在容器内生成滚动区域，如果外层div没有固定高度，页面会被拉得很长。我一般会给容器加一个固定的高度：

.docx-preview-container { height: calc(100vh - 180px); overflow: auto; background: #f5f5f5; }

第三是水印和页眉页脚。复杂文档的页眉页脚、批注、域代码没办法保证100%还原，如果业务上对这类内容有硬性要求，老老实实用OnlyOffice预览模式，不要用docx-preview强行撑。

2.4 只读预览的边界与兜底

docx-preview对.docx的兼容性已经不错，但它只支持新版Office开放式XML格式，遇到老式.doc文件会直接报错。解决办法是提前在服务端做格式识别，是.doc就先转成.docx或PDF再返回给前端。

我踩过的一个坑是：用户改完文件后没有关掉Word进程，上传时文件没正常落盘，后端拿到的流是损坏的，前端渲染出来是空的。后来我在后端加了一层文件完整性校验，用POI读一遍文件头，读不了就返回“文件格式损坏”提示，不让这种脏数据继续流入前端。

另外，如果项目已经有OnlyOffice，只读预览可以直接用OnlyOffice的mode: 'view'，加载速度比编辑器模式还快，而且格式兼容性更好。我的经验是：简单的快速预览用docx-preview，对格式还原有高要求就用OnlyOffice的view模式，两个都接上，前端根据文件大小和业务场景动态选择。

3. 在线编辑：OnlyOffice集成实战

3.1 先部署Document Server

OnlyOffice在线编辑的核心是Document Server，也就是文档处理服务。它是独立部署的，Vue项目通过iframe把编辑器嵌到页面里。部署方式很简单，官方提供了Docker镜像：

docker run -d \ -p 8080:80 \ --restart=always \ --name onlyoffice-ds \ -e JWT_SECRET=my-secret-key \ onlyoffice/documentserver:8.2

注意两点：

• 容器内部监听80端口，我映射到宿主机的8080，实际按你的环境调整。
• JWT_SECRET是前后端配置签名用的密钥，不设置的话新版镜像是默认密钥，安全风险很大，生产环境必须自己指定。

等容器启动完，浏览器访问http://你的服务器IP:8080，能看到欢迎页就说明部署成功。OnlyOffice不需要额外配置数据库，默认把文档缓存存在容器内，但这个缓存目录最终要挂载到宿主机，防止容器重建丢数据：

docker run -d \ -p 8080:80 \ --restart=always \ --name onlyoffice-ds \ -v /data/onlyoffice/logs:/var/log/onlyoffice \ -v /data/onlyoffice/data:/var/www/onlyoffice/Data \ -v /data/onlyoffice/cache:/var/lib/onlyoffice \ -e JWT_SECRET=my-secret-key \ onlyoffice/documentserver:8.2

3.2 Vue前端如何嵌入编辑器

接入OnlyOffice有两种常见方式：一种是封装好的Vue组件@onlyoffice/document-editor-vue，另一种是自己写一个承载页面用iframe嵌入。我用的是iframe方案，原因是配置自由度更高，不用额外维护SDK版本，出问题时排查也直观。

先在静态目录放一个承载页document-server.html，这个页面会接收URL参数，然后初始化OnlyOffice编辑器：

<!DOCTYPE html> <html> <head> <meta charset="utf-8"> <title>OnlyOffice Document Editor</title> </head> <body> <div id="placeholder"></div> <script src="http://你的DocumentServer地址/web-apps/apps/api/documents/api.js"></script> <script> const config = JSON.parse(decodeURIComponent(location.hash.substring(1))) new DocsAPI.DocEditor('placeholder', config) </script> </body> </html>

然后在Vue组件里动态创建iframe，把config对象作为hash传进去：

const frameUrl = `/document-server.html#${encodeURIComponent(JSON.stringify(editorConfig))}` const iframe = document.createElement('iframe') iframe.src = frameUrl iframe.style.width = '100%' iframe.style.height = 'calc(100vh - 120px)' iframe.allowFullscreen = true container.appendChild(iframe)

其实理论上iframe的src里可以直接带query参数，但config对象太长，而且URL里塞大量中文和特殊字符容易出错，所以我把config通过hash传递，再用decodeURIComponent解析。这个方案实测下来很稳。

3.3 config配置的关键字段解析

OnlyOffice的config是编辑器能否正常工作的核心，字段不少，但真正关键的就这么几个：

const editorConfig = { document: { fileType: 'docx', key: 'unique-doc-key-20240914', title: '项目需求文档.docx', url: 'http://你的业务后端地址/api/file/download?fileId=123' }, documentType: 'word', height: '100%', width: '100%', editorConfig: { mode: 'edit', lang: 'zh-CN', callbackUrl: 'http://你的业务后端地址/api/onlyoffice/callback', user: { id: 'user-001', name: '张三' }, customization: { autosave: true, forcesave: false, chat: false, compactHeader: false } } }

逐项说明一下：

• document.url：最关键字段。OnlyOffice启动时，会从这个地址拉取原始文档内容。文档服务器必须能访问到这个URL，不能写localhost指向你本地电脑，要写业务后端的公网或内网可访问地址。
• document.key：当前文档的唯一标识，OnlyOffice用它做缓存和协同。同一个文档每次编辑后key不能变，变了OnlyOffice会认为是新文档；但key也不能长时间固定不变，否则团队编辑时缓存会冲突。一般用“文件ID + 版本号”的组合。
• document.fileType：文件扩展名，docx、xlsx、pptx、pdf都支持，要和fileType一致。
• editorConfig.mode：edit是编辑模式，view是只读预览模式。
• editorConfig.callbackUrl：保存回调地址。OnlyOffice在需要保存时会往这个地址发请求，业务后端接收后拉取最新文件并落库。这个地址同样要能被Document Server访问到。
• editorConfig.autosave：是否自动保存，默认true，每10秒左右保存一次。
• editorConfig.forcesave：是否显示“强制保存”按钮。这个后面会专门讲，想用强制保存功能的话这里必须设true。

配置里还包含JWT签名，这个单独说。

3.4 JWT签名与前后端联动

OnlyOffice 7.2以上版本默认开启了JWT签名，Document Server会校验前端传过来的config是否被篡改。也就是说，config对象传到浏览器之前，后端必须拿之前设置的JWT_SECRET对它做HMAC-SHA256签名，在config里生成一个token字段。

Node.js后端生成token的代码示例：

const jwt = require('jsonwebtoken') const JWT_SECRET = 'my-secret-key' function buildEditorConfig(fileInfo, userInfo, mode = 'edit') { const config = { document: { fileType: fileInfo.ext, key: `${fileInfo.id}-${fileInfo.version}`, title: fileInfo.title, url: fileInfo.downloadUrl }, documentType: 'word', editorConfig: { mode, callbackUrl: 'http://业务后端地址/api/onlyoffice/callback', user: { id: userInfo.id, name: userInfo.name } } } const token = jwt.sign(config, JWT_SECRET, { algorithm: 'HS256', expiresIn: '1h' }) config.token = token return config }

前端把这个带token的config传给承载页，OnlyOffice会用部署时的同款密钥验签。只要前后端使用的密钥不一致，编辑器就会直接白屏或报签名错误，这是最常踩的坑之一。

这里有个经验：JWT的密钥一旦在部署时确定了，不要随便改。我遇到过同事改了部署机器的环境变量但没同步给业务后端，结果所有打开编辑器的用户全部报错的情况。建议把密钥放到统一配置中心管理，避免散落各处。

4. 保存链路：改完文档如何真正落库

4.1 先理解OnlyOffice的保存机制

OnlyOffice编辑器和业务系统之间不是直连的，它中间有一层Document Server的缓存。用户在页面上的所有修改都先存在Document Server的临时缓存里，业务后端想拿最终结果，得等Document Server把编辑完成的状态回调给业务后端。

整个保存链路是这么走的：

1. 用户打开OnlyOffice编辑器，Document Server根据document.url拉取原始文档到本地缓存。
2. 用户编辑过程中，修改只存在于Document Server缓存里，业务后端和数据库暂时一无所知。
3. 保存时间到或用户点击保存时，Document Server向callbackUrl发一个HTTP请求，请求体里有status字段和下载地址。
4. 业务后端收到回调，根据下载地址向Document Server发起请求，拉取最新文档二进制流。
5. 业务后端把二进制流写入文件存储，或替换数据库里的原始文件，最后向Document Server返回{"error": 0}表示保存成功。

第5步的返回结果很重要，如果不返回{"error": 0}，Document Server会认为保存失败，会不断重试回调，直到超时。

曾经有个项目上线后出现了诡异现象：用户改完文档，过一会儿看数据库里文件大小变了，但下载打开还是旧内容。查到最后发现是回调接口内存泄漏，进程假死，每次Document Server回调都拿不到响应，于是反复重试，数据库文件被改来改去。后来我把回调接口的下游操作改成异步队列，才彻底解决这个问题。

4.2 三种保存方式怎么选

OnlyOffice的保存行为有三种，理解它们才能设计出符合业务的保存逻辑。

如果你希望在编辑器的工具栏上显示“强制保存”按钮，需要在config里设置：

editorConfig: { customization: { forcesave: true } }

同时，调用Document Server强制保存API时，必须带一个签名过的请求参数，里面包含forcesave: true、key等信息。具体做法是把整个内部请求对象也用JWT签名，放到URL的token参数里。这个流程比较绕，我在第5节问题排查里会给出报错表现和解决办法。

4.3 回调接口实现与幂等处理

回调接口是保存链路里工作量最大的一块。我用Node.js/Express写了一个简化版本：

const express = require('express') const axios = require('axios') const fs = require('fs') const path = require('path') const router = express.Router() // OnlyOffice回调地址 router.post('/api/onlyoffice/callback', async (req, res) => { const body = req.body // status: 1=编辑中 2=已保存 3=保存出错 4=用户关闭 6=正在保存 7=强制保存 const status = body.status if (status === 2 || status === 6 || status === 7) { const downloadUrl = body.url const fileKey = body.key // 从Document Server下载最新文件 const response = await axios.get(downloadUrl, { responseType: 'arraybuffer' }) const buffer = Buffer.from(response.data) // 这里把buffer写入文件系统，实际业务里可以替换MinIO、OSS或数据库 const filePath = path.join(__dirname, `files/${fileKey}.docx`) await fs.promises.writeFile(filePath, buffer) // 返回成功，Document Server收到后会停止重试 res.json({ error: 0 }) } else { // status=1或4时无需保存，直接返回成功 res.json({ error: 0 }) } })

回调幂等性是我特别想强调的一点。Document Server的重试机制和并发回调会导致同一个回调接口被重复调用，所以接口里必须做去重处理。最简单的做法是用fileKey做去重标记，比如在Redis里记录最近处理的key和时间戳，收到重复回调直接返回{ error: 0 }，不再重复写文件。

还有一种情况：用户A和用户B同时打开同一份文档，A先保存，B再保存，最终覆盖的可能是旧数据。OnlyOffice本身有协同编辑机制，同一个key会合并会话，但如果不同用户打开的config里key不一致，就会各存各的，后保存的覆盖先保存的。所以key必须严格按“文件ID+最新版本”生成，不能夹杂用户ID或其他易变字段。

4.4 nginx配置和回调地址注意事项

实际生产环境里，Document Server、业务后端、前端页面可能分布在不同的机器上，nginx层有些参数必须单独调，否则保存回调很容易出问题。

首先是上传大小限制。默认nginx的client_max_body_size是1m，但Word文档动辄几十MB，如果回调流程里涉及文件上传，这个值必须调大或设为0：

server { listen 80; server_name onlyoffice.example.com; client_max_body_size 0; proxy_connect_timeout 600s; proxy_read_timeout 600s; proxy_send_timeout 600s; location / { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }

其次是回调地址的可见性。callbackUrl和document.url都必须是Document Server容器能访问到的地址。如果你的Document Server在服务器A，业务后端在服务器B，那么URL不能写localhost或127.0.0.1，要写服务器B的内网IP或域名。否则OnlyOffice回调时请求发到了自己身上，直接连接失败，文档保存就静默失败了。

最后是HTTPS问题。如果业务后端是HTTPS，但Document Server是HTTP，或者反过来，都会导致OnlyOffice浏览器端报“混合内容”错误。生产环境建议给Document Server也套一层HTTPS（用nginx配置证书就行），保持前后端协议一致。

5. 高频问题与排查实操记录

5.1 “当前浏览器暂不支持office文档在线编辑”

这个提示我在接OnlyOffice时见过太多次了，互联网上也有很多人问。它看着像浏览器兼容性问题，实际上原因可能有好几层：

• Document Server版本太旧，对浏览器内核要求高，升级镜像即可解决。
• Document Server的80端口没有正常暴露，前端加载不到api.js，编辑器初始化失败。可以单独在浏览器访问http://DocumentServer地址/web-apps/apps/api/documents/api.js验证。
• WebSocket连接不通。OnlyOffice会话依赖WebSocket做协同通信，如果nginx没有为WebSocket配置升级请求头，编辑器会在加载过程中挂掉。nginx配置里必须加：

location / { proxy_pass http://127.0.0.1:8080; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; }

排查顺序建议是：先访问api.js确认静态资源正常，再打开浏览器控制台看WebSocket请求，最后看Document Server日志（docker logs onlyoffice-ds）有没有报错。

5.2 强制保存一直403或失败

OnlyOffice从7.2版本起，强制保存必须带签名校验。具体表现是：用户点“强制保存”按钮，状态一直转圈，控制台报error: 403，或者提示has no permission。

原因基本是两种：

• config里没有设置forcesave: true，工具栏压根不显示强制保存按钮，或者显示了但点击无效。
• 强制保存请求里没有带正确的JWT签名。OnlyOffice每次强制保存，都会往callbackUrl发一个status=3的请求，但这个请求和普通自动保存不一样，它内部还包了一个forcesaveURL，Document Server会再去请求这个forcesaveURL。如果这个URL不能被合法访问，会直接失败。

解决方法是，在后端生成签名token时，把强制保存信息内嵌进去。我这里用Node.js示例：

const payload = { forcesave: true, key: 'unique-doc-key', url: 'http://DocumentServer地址/cache/files/xxx.docx' } const token = jwt.sign(payload, JWT_SECRET, { algorithm: 'HS256' }) // 将这个token作为query参数拼到强制保存URL后面 const forcesaveUrl = `http://DocumentServer地址/coauthoring/CommandService.ashx?token=${token}`

这个逻辑刚接触时确实容易绕进去，我的建议是查看OnlyOffice官方Node.js示例（GitHub上有onlyoffice/onlyoffice.github.io仓库），里面有现成的强制保存实现，照着改就行。

5.3 预览时下划线或格式错乱

你要是搜索“word下划线上打字保持下划线不动”，会发现很多人遇到的是Word文档里下划线文本在输入时光标跳位的问题。这个现象在docx-preview渲染时也会出现：因为docx-preview把Word的XML样式转成CSS，下划线样式如果没处理好，显示时文字下面会有条错位的线，或者输入时光标跑到下划线外面。

如果是纯预览场景，没有输入需求，字体和下划线错乱一般是渲染时缺少字体或CSS重置导致的。我给docx-preview容器加过一段兜底样式，效果还不错：

.docx-preview-container u, .docx-preview-container ins { text-decoration: underline; text-underline-offset: 3px; }

如果文档里有很多复杂排版、域代码、上下标，docx-preview确实很难还原到位。这种场景我在第2节说过，换OnlyOffice的view模式最省心。

5.4 中文乱码和字体缺失

中文文档在OnlyOffice里打开乱码，通常是Document Server容器缺少中文字体。默认服务器镜像只有基础字体，遇到宋体、黑体这种Windows常见字体会退化显示。

解决办法是在容器里补装中文字体：

# 进入容器 docker exec -it onlyoffice-ds bash # 安装字体，这里以Ubuntu系为例 apt-get update apt-get install -y fonts-noto-cjk # 清理字体缓存后重启 fc-cache -f exit docker restart onlyoffice-ds

补装字体后，中文显示基本恢复。如果是docx-preview渲染乱码，多半是浏览器本地没有文档指定的字体，直接在bodyStyles里强制定字体族即可。

5.5 大文件渲染慢、白屏

文档超过20MB时，无论是docx-preview还是OnlyOffice，都会明显变卡。OnlyOffice白屏和内存相关，Document Server容器长时间运行不重启，内存占用会逐渐增大。

我处理大文件的方法是：

• 在线预览前，后端先对文档做体积检查，超过阈值直接提示下载，不强行预览。
• Document Server容器配置内存上限，并定时重启，比如每天凌晨低峰期重启一次，防止内存碎片堆积。
• 文档入库时做预处理，把大文件统一转换为PDF再提供预览，原始docx保留给编辑场景。这样“只读预览”不看原文件，编辑时才拉原始文件。

另外，如果你的场景是给RAG/知识库做文档切片，docx文件需要先拆成段落文本再入库。这个预处理规则一般是：读取Word XML里的段落节点，按标题级别切分，表格单独处理，图片忽略或提取单独存储。我用的是cheerio解析docx里的document.xml，效果不错，比直接转文本再暴力分段要准确得多。

5.6 回调保存后文件打不开或损坏

这个问题的根源通常不在OnlyOffice，而在后端处理下载流的姿势不对。一个很经典的错误是用文本模式读取二进制流，或者中间转了一次编码，文件就废了。

我踩过坑之后总结了三点：

• 用axios下载Document Server文件时，必须设置responseType: 'arraybuffer'，保证拿到的是二进制流。
• 写文件时用fs.writeFile，不要走任何字符串转换逻辑。
• 保存到数据库时，如果是MySQL的BLOB字段，用参数化SQL的二进制流方式写入，不要手动拼接base64字符串。

还有一点，OnlyOffice编辑器打开期间，业务后端不要手动去更新这个文件，否则两者会互相覆盖。协同编辑期间文件属于“正在被编辑”状态，任何外部修改都应该排队到用户关闭编辑器后再执行。

6. 实用经验与扩展建议

6.1 老式.doc文件怎么兼容

项目里总会遇到用户上传老式的.doc文件，docx-preview和OnlyOffice对.doc的兼容性都不好。我之前接到一个客户需求，历史文件库里有几万个.doc文件要在线预览，最后采用的方案是服务端统一转换：

• 装一个LibreOffice服务，通过命令将.doc批量转成.docx：libreoffice --headless --convert-to docx 输入.doc --outdir 输出目录
• 转换成功后用新版格式存储，预览、编辑都走docx链路。
• 转换失败的零散文件单独标记，提示用户手动处理。

转换是异步的，放一个后台队列跑，不然几万个文件能把服务拖死。

6.2 版本升级与许可注意

OnlyOffice社区版是免费开源的，但用的是AGPL协议。如果项目只是企业内部用，不对外分发，基本没问题。如果你是在做SaaS服务，把OnlyOffice作为自己产品的一部分对外售卖，那就得买商业授权，否则有法律风险。

版本升级也要谨慎。我遇到过同事直接升级了Document Server大版本，结果旧的config字段在8.x里已经被废弃，编辑页面直接白屏。升级前一定读官方变更日志，先在一台测试机上验证一遍，再上生产。

6.3 常用资源与下一步扩展

如果你想继续深入，推荐几个我会翻的官方资源：

• OnlyOffice GitHub官方文档库（onlyoffice.github.io）提供了几乎所有语言的后端集成示例，包括强制保存、回调、权限控制。
• docx-preview的GitHub仓库里有API文档和示例代码，虽然是英文，但示例很直观。
• OnlyOffice的开发文档里对config每个字段都有说明，遇到不懂的字段直接查。

后续想扩展的方向也很多：加上文件版本管理，把每次保存生成一个历史版本；接入MinIO或者阿里云OSS存文件；用WebSocket做多人光标和在线人数展示。这些都是基于这套架构可以继续深入的模块。

我个人在实际操作中的体会是，这类“编辑器 + 回调”的架构，调试阶段最痛苦的就是两头不透明：编辑器状态变化不直观，回调接口又不方便打断点。建议在OnlyOffice承载页和控制台加一些打印，把每次config生成过程记录下来，回调接口里把status和body.url先落日志再处理业务，这样排查问题效率能高一倍。最后再分享一个细节：OnlyOffice的config里document.url如果经常变，比如每次打开都带随机的签名参数，会导致用户重新打开文档时无法恢复上次的编辑历史。URL签名参数要带，但是要用稳定可重复的值，比如基于文件ID和时间段生成，而不是每次随机生成。这个点我确实踩过坑，值得写进你的实践清单里。