企业官网建设流程全解析

简介：DzzOffice 小胡版 onlyoffice 插件是一款面向 DzzOffice 平台的在线文档处理扩展，主要解决站内 Word、Excel、PowerPoint 等办公文件的预览与编辑需求。利用 OnlyOffice 文档编辑工具，用户无需下载本地软件即可在浏览器中完成常用办公操作，适用于企业、教育机构及个人站长搭建协作办公环境。插件包共 32 个文件，包含 13 个 PHP 脚本、11 个 HTML 页面、3 个 YML 配置文件，以及许可证、应用清单和校验文件等，整体仅 34KB，结构轻量、易于集成。文件中既有插件主功能代码，也有前后端界面模板、多语言包和安装清单，方便二次开发与定制。目前已有 574 人学习下载。对需要提升 DzzOffice 文档处理能力或希望了解插件开发流程的站点管理员与开发者，这份资源提供了完整的基础代码和部署说明，能够帮助快速上线在线预览与编辑功能并规避常见安装问题。

1. DzzOffice 小胡版 OnlyOffice 插件：一个能把在线编辑彻底换成 OnlyOffice 的救急包

做私有云盘或协同办公的时候，DzzOffice 自带的文档预览只能看不能改，真正要在线编辑得自己挂外部编辑器。官方插件倒是能用，但版本适配经常翻车，加上配置文档写得含糊，很多人在部署阶段就卡住了。小胡版 OnlyOffice 插件就是有人把官方插件重写了一遍，修复了几个关键 bug，把配置流程简化成三步以内，装上就能调用 OnlyOffice Document Server 实现多人协同编辑。适合正在用 DzzOffice 做私有化办公、又不想被官方插件版本捆绑的开发者。这篇笔记我把安装、配置、排错和调优路径完整走一遍，照着做基本能一次跑通。

2. 接入原理与选型：先搞清 DzzOffice 怎么和 OnlyOffice 握手

2.1 DzzOffice 的插件机制：它不是直接调文档服务的

DzzOffice 本身是一个 PHP 编写的协同办公框架，用户文件都放在自己的存储里。当你在某个目录点开 Word 文档时，DzzOffice 会先判断当前用户有没有打开权限，然后根据文件扩展名去匹配已经启用的编辑器插件。这个匹配过程不是简单的 URL 跳转，而是由插件提供一个回调入口，把文件流和用户 token 一起交给外部编辑器，编辑完成后外部编辑器再通过回调把改好的文件吐回来。

所以 OnlyOffice 插件的本质，就是一个适配器。它要完成四件事：第一，把 DzzOffice 用户体系映射成 OnlyOffice 的 JWT 身份；第二，把文档以 OnlyOffice 能访问的 URL 形式传给 Document Server；第三，定义保存回传的接口，接收 OnlyOffice 的编辑结果；第四，把编辑后的文件版本更新回 DzzOffice。这四件事只要有一件没理顺，就会出现“能打开但保存无效”或者“多人同时编辑内容互相覆盖”的问题。

官方插件其实也是这套逻辑，但它在第一和第三件上的实现比较糙。比如 token 生成用的是旧版加密方式，跟新版 OnlyOffice 的密钥校验不一致，就会出现“打开即失败”。小胡版最核心的改动就是把 token 那套逻辑同步到了 OnlyOffice 7.2+ 的规范，同时把保存回写的临时文件处理改成先落盘再移动，降低因并发写入造成文件损坏的概率。

2.2 选型对比：自己对接 API 还是直接用这个改版插件

如果你对 PHP 和 OnlyOffice API 都熟，完全可以自己写一个 DzzOffice 扩展，原理不复杂，就是上面说的四步。但自己写的成本在细节：DzzOffice 的文件表、权限表结构你得读源码，OnlyOffice 的文档回调签名验签你得逐字段测，还要处理大文档的转码超时、临时文件的清理、跨域 iframe 的 cookie 问题。这些坑每一个都能耗掉一整天，我见过某实验室的人折腾了半个多月才把只读器跑通。

小胡版插件的好处是它把这些都已经踩过一遍了。我拆过它的代码，里面处理了一个很细的问题：如果 DzzOffice 开启了域名绑定，用户访问用的是二级域名，内部下载文件的 URL 还是 localhost，OnlyOffice 在服务器端去拉取文档时就会因为 127.0.0.1 不通而失败。它把下载 URL 强制替换成了对外可访问的域名，这个处理官方版一直没有修。

选型上，只要你有 OnlyOffice Document Server（哪怕是社区版），并且 DzzOffice 版本在 1.6 以上，小胡版基本都兼容。唯一要注意的是不能把它和官方插件同时启用，两个插件都向 DzzOffice 注册了同一种文件扩展名的打开方式，会冲突，表现在界面上就是点击文档时偶尔弹出两个编辑选项，选谁都可能在回调时串数据。建议把一个插件禁用干净，再启用另一个。

2.3 小胡版插件改动的核心参数

我对照了官方版和这个改版的配置项，发现它少了很多需要自己猜的字段。官方版经常要求填一堆回调 URL、请求头、密钥前缀，小胡版把这些收敛成了三个关键参数：OnlyOffice 服务地址、服务密钥（secret）、文件下载地址的覆盖域名。后面两个如果留空，它也会从 DzzOffice 的系统配置里自动读取，极大地减少配错的概率。

不过保留空也意味着你要理解它的默认行为。服务密钥如果留空，插件会用 DzzOffice 系统配置里存的 crypto 密钥做降级处理，这时候 OnlyOffice 的 JWT 校验必须关闭，否则验签不通过。而如果你的 OnlyOffice 是 Docker 部署，默认 JWT 是开着的，所以生产环境建议还是把密钥显式写好，两边保持一致，别偷懒。

3. 部署实操：把 DzzOffice 小胡版 OnlyOffice 插件跑起来

3.1 环境准备与版本搭配

在装插件前，先确认服务器上的环境能满足最低要求。DzzOffice 跑在 PHP 上，建议 PHP 7.4 以上，否则 openssl 扩展处理 JWT 签名时可能因为算法支持不全而失败。OnlyOffice Document Server 作为独立服务，最好单独跑在一台 4G 内存以上机器上，社区版默认会接管 80 端口，如果和 DzzOffice 在同一台机器，记住把 DzzOffice 的 Nginx 端口改成 8080 之类的错开。

我一般会用 Docker Compose 来部署 OnlyOffice，因为它自带依赖，升级时也方便。下面这个配置可以作为初始模板，其中JWT_SECRET是你自己生成的随机字符串，后面插件里要填完全相同的值：

version: '3' services: onlyoffice-docs: image: onlyoffice/documentserver:7.4.2 container_name: onlyoffice-docs ports: - "80:80" environment: - JWT_ENABLED=true - JWT_SECRET=your_random_secret_here - JWT_HEADER=Authorization volumes: - onlyoffice_data:/var/www/onlyoffice/Data - onlyoffice_logs:/var/log/onlyoffice restart: unless-stopped volumes: onlyoffice_data: onlyoffice_logs:

这段配置里，JWT_SECRET是确保 DzzOffice 发给 OnlyOffice 的请求带合法签名，如果两边密钥不一致，你等到的不是友好报错，而是网络请求直接 401。JWT_HEADER默认是Authorization，小胡版插件也是读这个头，不需要额外改。容器启动后会持有自己的数据卷，即使重新创建容器，已编辑过的文档缓存和字体库也不会丢。

验证 OnlyOffice 自己是否正常，可以访问http://你的服务器地址/healthcheck，如果返回true，说明文档服务已经就绪。如果这一步都过不了，后面插件全白搭，先排查端口、防火墙和 Docker 网络。

3.2 插件安装与启用

把插件包下载下来后，先解压，确认目录结构里有plug.onlyoffice之类的文件夹，里面至少包含app.php、controller和config三个目录。将整个文件夹上传到 DzzOffice 的system/plug/目录下，注意不是system/plug/插件名/，而是plug/plug.onlyoffice/这样的分层。

上传完成后，进入 DzzOffice 后台管理，找到应用市场或本地插件列表，扫描本地插件就能看到 OnlyOffice 的条目。点击安装，如果 DzzOffice 提示插件权限不足，检查目录所有者是否和 Web 服务用户一致，常见的是 www 用户，用这种命令统一改一下：

chown -R www:www /var/www/dzz/system/plug/plug.onlyoffice/

安装成功后，不要急着在后台启用。先打开插件配置文件config.php，里面有一行$enable_default = false;，这是为了安全，防止刚装上就被所有用户调用。你把它改成true后保存，再回后台的插件管理里点击启用。注意一定不要直接删掉配置行，否则 PHP 会报 undefined constant 错误，整个插件入口崩溃。

启用成功后，在 DzzOffice 的“用户中心”或“全局设置”里会新增一个“OnlyOffice 设置”的面板。如果没有出现，多半是缓存没刷新，到后台“系统工具”里清一下缓存即可。

3.3 配置服务地址、密钥与文件访问域名

后端设置面板里最要紧的四个字段分别是：OnlyOffice 服务 API 地址、JWT 密钥、文件下载回写地址、覆盖域名。第一个地址填写你能从外部访问到的根地址，比如https://doc.example.com，不要带斜杠。JWT 密钥就是刚才 Docker Compose 里的your_random_secret_here，得一字不差。

文件下载回写地址一般填 DzzOffice 的对外地址，比如https://dzz.example.com，这是拿来拼接文档下载 URL 用的。如果你开启了 HTTPS 反向代理，需要确保这个地址能通过 HTTPS 访问到 DzzOffice 的index.php?mod=plug&plug=onlyoffice&act=download这个路径。小胡版在下载文件名处理上做了 URL 编码，中文文件名不会乱码，但前提是 DzzOffice 的伪静态规则没把路径吃掉。

覆盖域名这一个字段是用来替换自动检测出来的内部 IP 的。比如你在内网部署，插件检测到http://172.17.0.1:80这种地址，OnlyOffice 服务器根本不能通过 Docker 网段访问，这时你就把这个字段改成https://dzz.example.com，它会把 download 链接里的 host 强制替换。这个值建议始终填写，不要依赖自动检测。

写完保存后，到插件目录下找到logs目录，没有就新建一个并赋予写权限。然后到 DzzOffice 里随便点开一个 Word 文档，注意如果没报错，但日志里没有记录，说明插件没有完整走下载流程，可能是在文件校验阶段直接返回了。

3.4 验证成功的关键检查点

打开文档后，浏览器地址栏会指向https://doc.example.com/access/开头的路径，同时网络请求里有一个documentServerUrl的参数。这个参数的值会经过 base64 编码，里面包含了文档 ID 和用户 ID。截取这段值解出来看，如果文档 ID 是0，说明 DzzOffice 有权访问的文档对象没取到，多半是回调接口里没有正确传递文件主键。

更直接的验证方式是做一次编辑并保存。在 OnlyOffice 编辑器里改一行文字，点击保存后，DzzOffice 的文件表mtime应该会更新，同时文件大小发生变化。如果保存后新文件变成 0 字节，去查看 DzzOffice 的错误日志，大概率是临时目录权限不够，把data/tmp的可写权限加上即可。

我习惯在验证时先把 OnlyOffice 容器的日志打开，用docker logs -f onlyoffice-docs盯着。每次打开文档和保存操作都会产生若干请求，如果你看到JWT validation failed，说明密钥不一致或 head 名不对；如果看到File download timeout，则是 DzzOffice 到 OnlyOffice 的下载链路超时，需要检查反向代理的超时配置。

4. 避坑记录：三个最容易让人半路放弃的问题

4.1 现象：在线打开文档一直转圈，控制台报 401 Unauthorized

打开文档时加载条一直停在 30% 左右，F12 里能看到请求 OnlyOffice API 时返回 401。这个问题最常见的出错点不是 DzzOffice，而是你填的 JWT 密钥和 OnlyOffice 服务本身的密钥不一致。另一个隐蔽原因是 OnlyOffice 容器里的JWT_ENABLED=true开启了校验，但插件配置里的密钥包含空格或换行，复制粘贴的时候带进去了。

原因：DzzOffice 在向 OnlyOffice 请求 token 时，用的是配置里的密钥去签名，OnlyOffice 用同一个密钥验签。只要有一边多一个空格，签名就失效。

解决：在 DzzOffice 后台把 JWT 密钥框里的内容手动全选删除，重新输入一次，不要直接从 Docker Compose 文件里复制，因为那里可能有不可见字符。然后到 OnlyOffice 容器里执行docker exec -it onlyoffice-docs env | grep JWT确认实际环境变量里的值和输入的一模一样，包括长度和内容。如果还没有解决，临时把JWT_ENABLED设为false再试一次，排除插件签名逻辑的问题。

4.2 现象：保存后文档在 DzzOffice 里预览变得异常，或文件内容少了段落

第一次编辑保存后，再次打开发现文件大小变小，用 Word 打开里面丢失了图片或表格。查看 DzzOffice 日志，发现回写逻辑里用的是临时文件的 MD5 做版本比对，但临时文件被脚本定期清理掉了，导致回写时读取到的是空的文件流。

原因：OnlyOffice 保存回传时，DzzOffice 会先把下载下来的新内容写到data/tmp的随机目录，然后再移动回正式存储目录。如果 tmp 清理任务设置的间隔很短（比如每分钟），而大文档的转码和回传花了十几秒，临时文件就可能被删掉。小胡版虽然增加了先落盘再移动的步骤，但如果落盘的目录本身不持久，依然会踩坑。

解决：把data/tmp挂载到独立的磁盘分区，或者把缓存目录改到/tmp/cache并用任务计划保证至少 10 分钟后再清理。其次，在插件的配置里把“保存后删除源临时文件”这个选项关闭，让回调结束后由 OnlyOffice 自己清理会话文件，而不是 DzzOffice 提前介入。

4.3 现象：多人同时编辑同一份文档，后保存的人把前人的修改覆盖了

明明两人都在编辑同一个 docx，A 改了第 2 页，B 改了第 6 页，B 先点保存，A 后点保存，结果 A 的保存把 B 的内容全冲掉了。这个问题看起来是 OnlyOffice 的版本合并机制没有生效，实际上是小胡版插件在回写时关闭了 OnlyOffice 的冲突检测。

原因：OnlyOffice 有两种保存模式：低版本兼容模式和严格模式。DzzOffice 在回调时带了一个status参数，如果插件没有把旧的版本号传递给 OnlyOffice，它就无法判断当前文档是否被他人修改，于是直接覆盖。小胡版在默认配置里为了追求保存速度，把forcesave设成了false，这一项本身没问题，但 DzzOffice 的文件表里缺少版本字段，导致 OnlyOffice 找不到要合并的基版本。

解决：在 DzzOffice 后台启用文件版本管理（多版本切换），确保每次保存前插件能读取到当前的版本 ID。然后检查插件的callback.php文件里是否强制设置了if (status == 2) { $versionsync = true; }。如果找不到，把这个逻辑手动补上：保存回写前先从 DzzOffice 文件表查最新版本，再把该版本号作为old_version参数传给 OnlyOffice。这样多人编辑时，后保存的人会收到一个“文档已修改，是否加载新版本”的提示，而不是盲目覆盖。

5. 进阶调整：把保存超时、大文档和反向代理再优化一轮

5.1 大文档打开时的转码超时

默认情况下，OnlyOffice 容忍的文档下载和转码时间是 120 秒。如果你经常打开 50 MB 以上的 PPT，到 100 秒左右就会主动断开。此时在 Document Server 的容器配置里调大DownloadTimeout参数，Docker 环境需要修改/etc/onlyoffice/documentserver/default.json里的services.CoAuthoring.autoAssembly.conversionTimeout，建议改到 600。

5.2 Nginx 反向代理加一层缓冲

对外只暴露一个 443 端口时，用 Nginx 把请求分发给 DzzOffice 和 OnlyOffice。注意为 OnlyOffice 的/web-apps和/files路径单独配置proxy_request_buffering off，否则大文件下载时 Nginx 会先把整个文件缓冲到本地再转发，拖慢重文档的加载。我一般会在location ^~ /files/这一段加上proxy_buffering off;，实测打开 80 MB 的演示文稿能快三分之一。

5.3 每当你改完配置文件，强制走一遍这个流程

改完 Docker Compose 的环境变量后，不要只 restart 容器，很多镜像更新环境变量并不会重写内部的配置文件，必须删掉容器重建，也就是docker compose down && docker compose up -d。然后把 DzzOffice 的缓存清干净，再用一个测试账号打开文档并保存。从那以后，我每次部署这类插件都会强制走一遍：先看 OnlyOffice 健康检查，再盯容器日志，最后在 DzzOffice 实际点一次文档。这个习惯帮我避开了至少三次版本升级导致的配置漂移问题。希望这份拆解能让你在集成 DzzOffice 和 OnlyOffice 时少走几个弯，插件拿下来按顺序配置，基本能一次跑通。

本文还有配套的精品资源，点击获取