简介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 还是 localhostOnlyOffice 在服务器端去拉取文档时就会因为 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_ENABLEDtrue - JWT_SECRETyour_random_secret_here - JWT_HEADERAuthorization 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?modplugplugonlyofficeactdownload这个路径。小胡版在下载文件名处理上做了 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_ENABLEDtrue开启了校验但插件配置里的密钥包含空格或换行复制粘贴的时候带进去了。原因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 现象多人同时编辑同一份文档后保存的人把前人的修改覆盖了明明两人都在编辑同一个 docxA 改了第 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 时少走几个弯插件拿下来按顺序配置基本能一次跑通。本文还有配套的精品资源点击获取
