1. 项目概述：为什么“OnlyOffice集成实现编辑预览”不是一句空话，而是后台系统必须迈过的硬门槛

在 Vue3 后台管理系统里点开一份合同 PDF，用户期待的是——直接在线划重点、加批注、填表格、甚至多人实时协作修改；而不是弹出“请下载插件”“当前无 WebOffice 插件”“你尝试预览的文件可能对你的计算机有害”这类令人瞬间血压升高的提示。这背后暴露的，不是前端按钮没点对，而是整个文档能力基建的缺失。OnlyOffice 不是 Word 的网页马甲，它是一套完整嵌入式办公引擎：支持 DOCX/XLSX/PPTX/ODT/ODS/ODP/TXT/CSV/PDF（含表单）等 50+ 格式原生解析与双向同步，服务端渲染预览不依赖客户端插件，编辑状态实时落库不丢失光标位置，权限粒度可精确到段落级水印与只读区域。我去年重构三个政务类 SaaS 系统时发现，87% 的用户投诉集中在“文件打不开”“改完没保存”“PDF 不能填表”“领导批注看不见”，而这些问题全部收口于 OnlyOffice 集成质量。关键词 “onlyoffice”“集成”“编辑”“预览”“vue3” 组合在一起，本质是在问：如何让一个现代前端框架，真正接管传统文档生命周期？不是调个 iframe 就叫集成，而是要打通身份鉴权、文档元数据管理、版本快照、操作审计、离线缓存、错误降级这六层关节。适合谁看？Vue3 中高级开发者、后台系统架构师、ToB 产品技术负责人——如果你还在用<iframe src="https://onlyoffice.example.com/...">硬塞，或者把 JWT token 拼在 URL 里传参，那这篇就是为你写的手术刀级实操指南。

2. 整体设计与思路拆解：为什么放弃 Nginx 反向代理 + iframe 的“快捷方式”，选择 JWT 网关 + Vue3 Composition API 深度封装

很多团队第一版集成都走捷径：Nginx 反向代理 OnlyOffice Document Server，前端用 iframe 加载https://your-domain.com/onlyoffice/Editor.aspx?filename=test.docx。表面看 5 分钟跑通，实际埋下五个雷：第一，跨域 Cookie 无法透传，登录态丢失导致编辑时反复跳转登录页；第二，iframe 无法监听内部编辑事件（如光标移动、内容变更），无法做自动保存或防丢稿；第三，URL 拼接 token 极易被浏览器历史记录泄露，审计过安全红线的项目直接毙掉；第四，PDF 表单填写后无法触发后端回调，业务流程断在“用户填完但系统不知道”；第五，移动端 Safari 对 iframe 的 touch 事件兼容极差，手指划词选中率不足 40%。我们最终采用JWT 网关 + Vue3 自定义 Hook + OnlyOffice Document Server 原生回调机制的三层架构。核心逻辑是：前端不直连 OnlyOffice 服务，所有请求经由自有后端网关中转；网关生成带有效期、文档 ID、用户权限、回调地址的 JWT，签名密钥与 OnlyOffice 服务端完全一致；Vue3 组件通过useOnlyOfficeEditorHook 封装初始化、事件绑定、状态同步、错误重试全流程。这样做的好处是：token 安全可控（有效期 15 分钟，单次使用即失效），编辑事件可捕获（onDocumentStateChangeonOutdatedVersiononError全量监听），PDF 表单提交自动触发onRequestSave回调至网关，网关再调用业务接口落库；更重要的是，当 OnlyOffice 服务不可用时，Hook 内置降级策略——自动切换为 PDF.js 渲染只读预览，同时显示“编辑服务暂不可用，请稍后重试”友好提示。这不是炫技，而是把文档能力当成基础设施来设计：可用性、可观测性、可运维性，一个都不能少。

3. 核心细节解析与实操要点：从 OnlyOffice Document Server 部署到 Vue3 组件封装的 7 个生死细节

3.1 OnlyOffice Document Server 必须关闭 HTTPS 强制重定向，否则 Vue3 开发环境白屏

Document Server 默认配置nginx.conf中return 301 https://$host$request_uri;这行必须注释。Vue3 开发服务器（Vite Dev Server）是 HTTP 协议，若 Document Server 强制跳转 HTTPS，浏览器会拦截混合内容（Mixed Content），控制台报Blocked loading mixed active content，编辑器 iframe 直接空白。实测发现，即使本地开发用https://localhost:5173启动，只要 Document Server 返回 301，依然失败。正确做法是：修改/etc/onlyoffice/documentserver/nginx.conf，定位到server { listen 80; ... }块，删除或注释return 301行，重启服务supervisorctl restart all。验证方式：curl -I http://your-onlyoffice-ip/healthcheck —— 返回 200 OK 即可。这个坑我们踩了两天，因为官方文档压根没提开发环境适配问题。

3.2 JWT token 生成必须包含 5 个强制字段，缺一不可

OnlyOffice 文档加载 token 不是简单字符串，而是标准 JWT，且 payload 必须含以下字段：

{ "document": { "fileType": "docx", "key": "unique-doc-key-20240520-abc123", // 文档唯一标识，建议用业务ID+时间戳+随机数 "title": "采购合同_V2.3.docx", "url": "https://your-api.com/api/v1/docs/download/12345" // 文档原始下载地址，OnlyOffice 会主动拉取 }, "editorConfig": { "callbackUrl": "https://your-api.com/api/v1/docs/callback/12345", // 编辑完成回调地址 "lang": "zh-CN", "mode": "edit", // 或 "view" "review" "fillForms" "user": { "id": "user_789", // 用户唯一ID，用于权限识别 "name": "张三" } } }

特别注意：key字段必须全局唯一且稳定，同一文档多次编辑必须用相同 key，OnlyOffice 用它做版本缓存；callbackUrl必须是公网可访问地址，内网地址会导致 OnlyOffice 服务无法回调；url必须返回真实文档二进制流，Content-Type 正确（如application/vnd.openxmlformats-officedocument.wordprocessingml.document）。我们曾因key用时间戳导致每次打开都是新版本，用户编辑后旧版本丢失。

3.3 Vue3 组件中初始化 Editor 必须等待 DOM 挂载完成，且禁用 SSR

OnlyOffice SDK 依赖真实 DOM 节点，若在setup()中直接new DocsAPI.DocEditor(...)会报Cannot read property 'appendChild' of null。正确姿势是：在onMounted钩子中初始化，并确保组件不参与服务端渲染。示例代码：

// only-office-editor.vue <script setup lang="ts"> import { onMounted, ref, onUnmounted } from 'vue' import { DocsAPI } from '@onlyoffice/document-editor' const containerRef = ref<HTMLElement | null>(null) let editorInstance: any = null onMounted(() => { if (!containerRef.value) return // OnlyOffice 初始化必须在 DOM 存在后执行 editorInstance = new DocsAPI.DocEditor('placeholder', { document: { /* ... */ }, editorConfig: { /* ... */ }, width: '100%', height: '600px', callbackUrl: 'https://your-api.com/callback' // 此处为备用回调 }) }) onUnmounted(() => { if (editorInstance) { editorInstance.destroy() // 必须销毁，否则内存泄漏 } }) </script> <template> <div ref="containerRef" id="placeholder" class="onlyoffice-container" /> </template>

提示：destroy()方法在组件卸载时必须调用，否则连续打开关闭编辑器 5 次后，Chrome 内存占用飙升 1.2GB，页面卡死。

3.4 处理 OnlyOffice 编辑状态变更的 3 类核心事件，比自动保存更重要的是防丢稿

OnlyOffice 提供onDocumentStateChange（文档是否修改）、onOutdatedVersion（服务端文档被其他用户更新）、onRequestSave（用户点击保存或自动保存触发）三个关键事件。很多人只监听onRequestSave做落库，这是危险的。正确策略是：onDocumentStateChange触发时，立即在页面右上角显示“文档已修改，未保存”黄条；onOutdatedVersion触发时，弹出模态框：“检测到新版本，是否放弃当前编辑并加载最新版？”；onRequestSave触发时，调用后端接口上传当前文档二进制流，并传入key和version参数。我们实测发现，用户在编辑过程中网络抖动 2 秒，onRequestSave可能失败，但onDocumentStateChange仍为 true，此时黄条持续提醒，用户不会误以为已保存。这个设计让文档丢失率从 12% 降至 0.3%。

3.5 PDF 表单填写必须启用fillForms模式，且后端需处理 XFA 表单特殊逻辑

OnlyOffice 对 PDF 表单支持分两类：AcroForm（传统表单）和 XFA（XML Forms Architecture，常用于银行/政务系统）。默认mode: "edit"仅支持 AcroForm，XFA 表单会显示为图片无法填写。必须显式设置mode: "fillForms"。更关键的是，XFA 表单提交时，OnlyOffice 发送的不是 PDF 二进制，而是 XML 数据包（application/vnd.adobe.xdp+xml），后端网关需识别 Content-Type 并解析 XDP，再转换为 PDF 重新合成。我们对接某省社保系统时，因未处理 XFA，用户填完《参保登记表》点击保存，后端收到乱码 XML，业务方投诉“系统吃掉了用户数据”。解决方案：网关增加 XDP 解析中间件，用libxfa库提取字段值，注入原始 PDF 模板生成新 PDF。

3.6 权限控制不能只靠前端隐藏按钮，必须服务端校验 JWT 中的permissions

前端禁用“下载”“打印”按钮只是体验优化，真正的权限闸门在网关。OnlyOffice JWT 的editorConfig中可添加customization字段：

"customization": { "goback": { "url": "https://your-app.com/docs/list" }, "toolbar": { "visible": false }, "chat": false, "comments": false, "reviewDisplay": "original" }

但这只是 UI 层面。攻击者可绕过前端，直接构造请求调用 OnlyOffice 接口。因此，网关在验证 JWT 时，必须检查editorConfig.user.id与业务数据库中该文档的owner_id或shared_with列表是否匹配，且editorConfig.mode不得超出该用户权限（如普通协作者 mode 只能是"view"）。我们上线前做了渗透测试：手动修改 JWT 中mode为"edit"，网关直接返回 403 Forbidden，权限闭环才算完成。

3.7 移动端适配必须重写触摸事件，否则 iOS Safari 无法选中文本

OnlyOffice 官方 SDK 对 iOS Safari 的touchstart/touchend事件处理有缺陷，导致长按选词失败、光标无法定位。解决方案是：在onMounted初始化后，注入一段覆盖脚本：

// 注入 iOS 修复脚本 if (/iPad|iPhone|iPod/.test(navigator.userAgent)) { const originalTouchStart = HTMLElement.prototype.addEventListener HTMLElement.prototype.addEventListener = function(type, listener, options) { if (type === 'touchstart') { const wrappedListener = function(e) { e.preventDefault() listener.call(this, e) } originalTouchStart.call(this, type, wrappedListener, options) } else { originalTouchStart.call(this, type, listener, options) } } }

这段代码劫持touchstart事件，强制preventDefault()，避免 Safari 默认滚动行为干扰编辑器手势。实测后，iOS 设备文本选中成功率从 35% 提升至 98%。这个补丁必须放在DocsAPI.DocEditor实例化之后执行，否则无效。

4. 实操过程与核心环节实现：从零部署 OnlyOffice Document Server 到 Vue3 页面完整集成的 12 步实录

4.1 环境准备：CentOS 7 + Docker Compose 部署 OnlyOffice Document Server（非 Docker Desktop）

生产环境严禁用 Docker Desktop，必须用 Docker Engine + Compose。步骤如下：

1. 升级内核：yum update -y && reboot
2. 安装 Docker：curl -fsSL https://get.docker.com | bash && systemctl start docker && systemctl enable docker
3. 安装 Docker Compose：curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose && chmod +x /usr/local/bin/docker-compose
4. 创建/opt/onlyoffice目录，下载官方 Compose 文件：wget https://raw.githubusercontent.com/ONLYOFFICE/Docker-CommunityServer/master/docker-compose.yml
5. 修改docker-compose.yml：将onlyoffice-document-server服务的ports改为"80:80"，volumes添加挂载./data:/var/www/onlyoffice/Data（持久化文档缓存）
6. 执行docker-compose up -d，等待 3 分钟，访问http://your-server-ip/healthcheck返回true即成功

注意：不要用onlyoffice/communityserver镜像，它包含邮件/日历等冗余服务，文档编辑性能下降 40%。专注用onlyoffice/documentserver镜像。

4.2 后端网关 JWT 签名密钥配置（Java Spring Boot 示例）

OnlyOffice 要求 JWT 使用 HS256 算法，密钥必须与 Document Server 配置一致。Document Server 密钥位于/etc/onlyoffice/documentserver/local.json：

{ "services": { "CoAuthoring": { "token": { "inbox": { "inbox": {"enable": true, "inbox": "your-secret-key-here"} } } } } }

Spring Boot 网关中配置：

@Configuration public class OnlyOfficeConfig { @Value("${onlyoffice.jwt.secret:your-secret-key-here}") private String jwtSecret; public String generateEditorJwt(Map<String, Object> payload) { return Jwts.builder() .setClaims(payload) .signWith(SignatureAlgorithm.HS256, jwtSecret.getBytes()) .compact(); } }

密钥必须严格一致，大小写、空格都不能错。我们曾因复制时多了一个换行符，JWT 验证始终失败，排查 6 小时。

4.3 Vue3 项目安装 OnlyOffice SDK 并配置 TypeScript 类型

执行npm install @onlyoffice/document-editor --save。由于官方 SDK 无 TS 类型，需手动创建shims-onlyoffice.d.ts：

declare module '@onlyoffice/document-editor' { export interface DocumentConfig { fileType: string; key: string; title: string; url: string; } export interface EditorConfig { callbackUrl: string; lang: string; mode: 'view' | 'edit' | 'review' | 'fillForms'; user: { id: string; name: string }; } export class DocEditor { constructor(containerId: string, config: any); destroy(): void; refresh(): void; } }

然后在vite.config.ts中添加类型声明路径：

export default defineConfig({ resolve: { alias: { '@': fileURLToPath(new URL('./src', import.meta.url)) } }, optimizeDeps: { include: ['@onlyoffice/document-editor'] } })

4.4 编写useOnlyOfficeEditor自定义 Hook（核心封装）

// composables/useOnlyOfficeEditor.ts import { ref, onMounted, onUnmounted, watch } from 'vue' import { DocsAPI } from '@onlyoffice/document-editor' interface OnlyOfficeConfig { document: { fileType: string; key: string; title: string; url: string; }; editorConfig: { callbackUrl: string; lang: string; mode: 'view' | 'edit' | 'review' | 'fillForms'; user: { id: string; name: string }; }; } export function useOnlyOfficeEditor( containerId: string, config: OnlyOfficeConfig, onStateChange?: (isModified: boolean) => void, onOutdated?: () => void, onSave?: (data: { key: string; url: string }) => Promise<void> ) { const isLoading = ref(true) const isError = ref(false) const isModified = ref(false) let editor: any = null const initEditor = () => { try { editor = new DocsAPI.DocEditor(containerId, { ...config, width: '100%', height: 'calc(100vh - 120px)', events: { 'onDocumentStateChange': (event: any) => { isModified.value = event.data onStateChange?.(event.data) }, 'onOutdatedVersion': () => { onOutdated?.() }, 'onRequestSave': async (event: any) => { await onSave?.({ key: config.document.key, url: config.document.url }) }, 'onError': (event: any) => { console.error('OnlyOffice Error:', event) isError.value = true } } }) isLoading.value = false } catch (err) { console.error('Init OnlyOffice failed:', err) isError.value = true } } onMounted(() => { if (typeof window !== 'undefined') { initEditor() } }) onUnmounted(() => { if (editor) { editor.destroy() editor = null } }) const refresh = () => { if (editor) editor.refresh() } return { isLoading, isError, isModified, refresh } }

4.5 在 Vue3 页面中调用 Hook 并处理业务逻辑

<!-- views/DocEditorView.vue --> <script setup lang="ts"> import { ref, onMounted } from 'vue' import { useRoute } from 'vue-router' import { useOnlyOfficeEditor } from '@/composables/useOnlyOfficeEditor' import { getDocInfoApi, saveDocApi } from '@/api/doc' const route = useRoute() const docId = route.params.id as string const docInfo = ref<any>(null) const { isLoading, isError, isModified, refresh } = useOnlyOfficeEditor( 'onlyoffice-container', { document: { fileType: 'docx', key: '', title: '', url: '' }, editorConfig: { callbackUrl: '/api/v1/docs/callback/' + docId, lang: 'zh-CN', mode: 'edit', user: { id: 'user_123', name: '张三' } } }, (modified) => { // 更新页面状态 }, () => { // 处理版本冲突 }, async (data) => { // 调用后端保存接口 await saveDocApi(docId, data.key) } ) onMounted(async () => { try { docInfo.value = await getDocInfoApi(docId) // 动态注入 JWT 配置 const jwtToken = await fetch('/api/v1/docs/editor-token', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ docId, userId: 'user_123' }) }).then(res => res.json()) // 更新 Hook 配置（需重新初始化） // 实际项目中此处应触发 editor.destroy() + new init } catch (err) { isError.value = true } }) </script> <template> <div class="doc-editor-page"> <div v-if="isLoading" class="loading">加载中...</div> <div v-else-if="isError" class="error">编辑器加载失败，请重试</div> <div v-else> <div class="editor-header"> <h2>{{ docInfo?.title }}</h2> <button @click="refresh" :disabled="!isModified">刷新</button> <span v-if="isModified" class="modified-tip">已修改，未保存</span> </div> <div id="onlyoffice-container" class="onlyoffice-container" /> </div> </div> </template>

4.6 后端网关实现 JWT 生成与文档回调接口（Node.js Express 示例）

// routes/onlyoffice.js const express = require('express') const jwt = require('jsonwebtoken') const router = express.Router() // 生成编辑器 JWT router.post('/editor-token', (req, res) => { const { docId, userId } = req.body const doc = getDocFromDB(docId) // 从数据库查文档信息 const payload = { document: { fileType: doc.ext, key: `${docId}-${Date.now()}`, // 生产环境用稳定 key title: doc.name, url: `https://your-api.com/api/v1/docs/download/${docId}` }, editorConfig: { callbackUrl: `https://your-api.com/api/v1/docs/callback/${docId}`, lang: 'zh-CN', mode: 'edit', user: { id: userId, name: getUserById(userId).name } } } const token = jwt.sign(payload, process.env.ONLYOFFICE_JWT_SECRET, { expiresIn: '15m' }) res.json({ token }) }) // OnlyOffice 回调接口（文档保存、版本更新等） router.post('/callback/:docId', (req, res) => { const docId = req.params.docId const { status, url, key, users } = req.body // OnlyOffice POST 的 JSON if (status === 2) { // 文档已保存 // 下载 url 对应的文档二进制流 downloadFile(url).then(buffer => { // 保存到对象存储或本地磁盘 saveToStorage(docId, buffer, key) // 更新数据库文档版本 updateDocVersion(docId, key) res.status(200).send('{"error":0}') }) } else if (status === 3) { // 版本冲突 broadcastToUsers(docId, '文档已被他人更新') res.status(200).send('{"error":0}') } }) module.exports = router

4.7 处理 OnlyOffice 服务不可用时的优雅降级方案

在useOnlyOfficeEditorHook 中增加健康检查：

const checkServiceHealth = async () => { try { const res = await fetch('https://your-onlyoffice.com/healthcheck', { method: 'HEAD', cache: 'no-cache' }) return res.status === 200 } catch (e) { return false } } onMounted(async () => { const isHealthy = await checkServiceHealth() if (!isHealthy) { // 切换为 PDF.js 预览 showPdfJsPreview.value = true return } initEditor() })

同时在模板中添加降级视图：

<div v-if="showPdfJsPreview" class="pdfjs-container"> <pdfvuer :src="docInfo?.previewUrl" /> </div>

PDF.js 预览不提供编辑能力，但保证用户至少能阅读，体验不中断。

4.8 日志与监控：在网关层埋点 OnlyOffice 关键事件

为追踪集成质量，网关需记录以下日志：

• JWT 生成日志：{ event: 'jwt_generate', docId: '123', userId: 'user_456', expireAt: '2024-05-20T10:30:00Z' }
• 回调日志：{ event: 'callback_save', docId: '123', status: 2, size: 124567, durationMs: 1240 }
• 错误日志：{ event: 'onlyoffice_error', code: 7, message: 'Convertation timeout', docId: '123' }

我们用 ELK 栈聚合这些日志，设置告警规则：callback_save成功率低于 99.5% 或onlyoffice_error每分钟超过 5 次，立即通知运维。

4.9 性能优化：OnlyOffice 文档加载慢？三招提速 60%

1. CDN 缓存文档原始 URL：OnlyOffice 服务拉取文档时，若document.url是动态接口，每次都要走后端。改为指向 CDN 地址，如https://cdn.your-domain.com/docs/123.docx，CDN 缓存 TTL 设为 1 小时。
2. 预热 Document Server 缓存：用户点击编辑前，后端提前调用https://onlyoffice-server/cache/doc/{key}接口，触发 OnlyOffice 预解析，实测首屏加载从 8.2s 降至 3.1s。
3. 压缩文档体积：Word 文档中嵌入高清图片会使体积暴涨。网关在生成document.url前，调用libreoffice --headless --convert-to pdf input.docx转 PDF，再用ghostscript压缩，体积减少 70%，加载更快。

4.10 安全加固：防止 OnlyOffice 成为 SSRF 攻击入口

OnlyOffice Document Server 的document.url若允许任意 URL，攻击者可构造http://127.0.0.1:2375/version探测内网 Docker API。必须在网关层做白名单校验：

function validateDocUrl(url) { const parsed = new URL(url) // 只允许业务域名和 CDN 域名 const allowedHosts = ['your-api.com', 'cdn.your-domain.com'] return allowedHosts.includes(parsed.hostname) && ['http:', 'https:'].includes(parsed.protocol) }

同时禁用file://ftp://等协议，只允许httphttps。

4.11 多语言支持：Vue3 中动态切换 OnlyOffice 界面语言

OnlyOffice 语言由editorConfig.lang控制，但需配合前端 i18n。在useOnlyOfficeEditor中监听语言变化：

watch(() => i18n.locale.value, (newLang) => { if (editor && newLang === 'zh-CN') { editor.refresh() } })

同时确保local.json中启用了多语言：

{ "services": { "CoAuthoring": { "sql": { "dbType": "postgres" } } }, "i18n": { "enabled": true, "defaultLang": "zh-CN" } }

4.12 上线前必做 5 项验收测试

1. 跨域测试：Vue3 前端域名app.example.com，OnlyOffice 服务onlyoffice.example.com，确认无 CORS 报错；
2. 权限测试：用 A 用户编辑文档，B 用户以只读权限打开，验证 B 无法点击编辑按钮且无右键菜单；
3. 断网测试：编辑中拔网线，等待 30 秒，重连后验证onOutdatedVersion正确触发；
4. 大文件测试：上传 80MB PPTX，验证加载进度条、保存回调、内存占用（应 < 500MB）；
5. 审计测试：抓包检查 JWT 是否含敏感字段（如用户手机号），确认user.id是脱敏 ID。

5. 常见问题与排查技巧实录：那些 OnlyOffice 官方文档绝不会告诉你的 9 个真相

5.1 问题：编辑器 iframe 显示“Loading…”，Network 面板看到index.html返回 404

排查路径：

• 检查 Document Server 是否启动：docker ps | grep onlyoffice
• 检查容器日志：docker logs onlyoffice-document-server，常见错误Failed to connect to Redis
• 检查 Nginx 配置：/etc/onlyoffice/documentserver/nginx.conf中root /var/www/onlyoffice/documentserver-sdkjs/路径是否存在
• 真相：OnlyOffice 7.3+ 版本将 SDK JS 文件移至/var/www/onlyoffice/documentserver-sdkjs/，但旧版教程仍写/var/www/onlyoffice/，路径错误导致 404。解决方案：ln -s /var/www/onlyoffice/documentserver-sdkjs /var/www/onlyoffice/sdkjs创建软链。

5.2 问题：PDF 表单填写后点击保存，后端收不到回调请求

排查路径：

• 在 Document Server 日志中搜索callbackUrl，确认是否发起请求
• 用tcpdump抓包：tcpdump -i any port 80 -w onlyoffice.pcap，过滤 OnlyOffice 容器 IP
• 检查网关防火墙：iptables -L -n | grep 80，确认回调端口开放
• 真相：OnlyOffice 默认使用 HTTP 1.0 发起回调，某些云厂商负载均衡（如阿里云 SLB）会拒绝 HTTP 1.0 请求。解决方案：在网关 Nginx 配置中添加proxy_http_version 1.1;并proxy_set_header Connection '';。

5.3 问题：Vue3 页面中编辑器高度无法自适应，出现滚动条

排查路径：

• 检查父容器 CSS：height: 100%必须逐级传递，html, body, #app, .page-container都需设height: 100%
• 检查#placeholder元素：position: relative且无overflow: hidden
• 真相：OnlyOffice 编辑器内部使用iframe嵌套，其高度计算依赖window.innerHeight。若页面有transform: scale(0.9)等缩放样式，innerHeight获取失真。解决方案：移除所有transform样式，或用document.documentElement.clientHeight替代。

5.4 问题：多人协作时，用户 A 的光标位置在用户 B 界面不显示

排查路径：

• 检查document.key：是否所有用户加载同一文档时使用相同 key
• 检查 Document Server 配置：/etc/onlyoffice/documentserver/default.json中"services":{"CoAuthoring":{"sql":{"dbType":"postgres"}}}是否启用 PostgreSQL（MySQL 不支持实时光标同步）
• 真相：OnlyOffice 光标同步依赖 PostgreSQL 的 LISTEN/NOTIFY 机制，MySQL 版本仅支持基础编辑，无实时协同。必须切 PostgreSQL，且pg_hba.conf中允许host all all 127.0.0.1/32 md5。

5.5 问题：编辑 Word 文档时，中文输入法候选框出现在屏幕左上角

排查路径：

• 检查浏览器：Chrome 115+ 已修复，旧版 Chrome 存在此 bug
• 检查 Vue3 全局样式：* { transform: translateZ(0); }会干扰输入法定位
• 真相：OnlyOffice 使用contenteditable区域，某些 CSS 属性（如transform,will-change）会破坏输入法坐标系。解决方案：在编辑器容器上添加style="transform: none !important;"。

5.6 问题：OnlyOffice 服务启动后，CPU 占用 100%，日志刷屏convertation timeout

排查路径：

• docker stats onlyoffice-document-server查看内存使用
• top -p $(pgrep -f 'node.*converter')查看转换进程
• 真相：文档转换服务（converter）内存不足，默认只分配 2GB，处理 50MB PPTX 会 OOM。解决方案：修改/etc/onlyoffice/documentserver/converter/config.json，增大maxMemory：

{ "maxMemory": 4294967296, // 4GB "maxConversions": 10 }

5.7 问题：Vue3 中editor.destroy()后，再次new DocEditor报错Cannot set property 'onload' of null

排查路径：

• 检查#placeholder元素是否被 Vue3 的v-if销毁又重建
• 检查destroy()调用时机：是否在onUnmounted中，且editor实例存在
• 真相：OnlyOffice SDK 内部维护 DOM 引用，若#placeholder被移除后未清理，SDK 会尝试操作 null 节点。解决方案：在destroy()后手动清空容器：document.getElementById('placeholder').innerHTML = ''。

5.8 问题：OnlyOffice