简介DzzOffice 小胡版 onlyoffice 插件是一款面向 DzzOffice 平台的在线文档处理扩展专门解决在私有化协同办公环境中预览、编辑 Word、Excel、PowerPoint 等 Office 文件的痛点。通过接入 OnlyOffice 文档编辑引擎站点用户无需下载文件即可在浏览器中完成查看与协作编辑适用于企业网盘、知识库、在线协作等场景适合 DzzOffice 管理员和二次开发人员部署使用。整个安装包共 32 个文件压缩后约 34KB以 PHP 核心逻辑、HTM 页面模板、YML 配置及 XML 应用清单等类型为主覆盖主程序入口、管理后台、前端页面、语言包及安装配置等模块结构轻量清晰便于快速集成与适配。目前已有 574 人学习下载说明其在小众插件中有不错的参考价值。资源同时附带完整的许可文件、MD5 校验信息及使用说明文档能够辅助技术人员理解插件调用流程和目录组织方式为基于 DzzOffice 的办公能力扩展提供可复用的实现思路。1. 装DzzOffice小胡版OnlyOffice插件先想清楚要装的是两个组件不少第一次接触DzzOffice小胡版OnlyOffice插件的人会在下载插件包之后直接往后台一丢然后打开在线编辑发现一片白屏下意识觉得是插件坏了。实际上这套东西从来不是“一个插件”就能跑起来的它背后还拖着一个独立的OnlyOffice Document Server文档服务。我当年第一次装也在这个地方栽过跟头插件反复重装了几遍最后才发现是文档服务根本没装。这篇笔记按我后来落地过多次的顺序来写先定环境基线和版本再装Document Server然后把小胡版插件接上去最后把回调链路和协同通道都验证走通。适合正在给DzzOffice加在线编辑能力、被白屏和保存失败折磨的运维和开发者。2. 规划环境基线DzzOffice版本、镜像Tag和端口清单2.1 DzzOffice部署形态决定插件目录怎么放DzzOffice在服务器上的跑法大致有三种整合包一键安装、源码部署到自有PHP环境、以及用别人打包好的容器镜像跑。插件目录的位置和安装方式在这三种形态下不太一样先确认自己属于哪一种再动手放插件文件。部署形态DzzOffice插件目录安装方式注意点整合包一键安装dzzroot/dzz/plugins/需要先确认PHP-FPM运行用户目录权限容易出错源码部署Nginx/ApachePHPMySQLdzzroot/dzz/plugins/可以走后台应用中心上传zip也可以手工放目录容器方式需要进入容器找dzz/plugins容器重启会丢数据插件目录建议挂载到宿主机我大部分场景用的是源码部署Nginx PHP MySQL 的经典组合。小胡版OnlyOffice插件通常不会出现在DzzOffice自带的应用中心里下载下来就是一个zip包所以走“手工放目录 后台扫描安装”这条路最直接。放目录的时候注意一点DzzOffice的应用安装不仅仅是文件落到磁盘还会往应用表里写一条安装记录。只把文件扔进去后台应用列表里不会自动出现必须在应用管理里扫描新应用才会被系统识别。PHP版本这里多说一句。DzzOffice官方对PHP有最低要求但我实际遇到的是另一类问题有些整合包默认装了PHP 7.0跑老版本DzzOffice没问题一旦启用带在线编辑的插件就频繁报函数不存在。小胡版OnlyOffice插件依赖curl扩展和文件操作相关函数建议PHP 7.2以上同时把fileinfo扩展打开否则文件类型识别会出诡异问题。装完这些扩展记得重启PHP-FPM光改php.ini不重启等于没改。2.2 OnlyOffice Document Server版本选择固定Tag别追新OnlyOffice Document Server的Docker镜像Tag从7.x一路出到8.x小胡版插件在接口调用上主要依赖两块加载编辑器用的/web-apps/apps/api/documents/api.js以及保存时回调DzzOffice的/callback接口。这两个接口路径在7.x和8.x之间整体保持兼容但JWT鉴权行为差别很大。镜像系列JWT行为与老插件的兼容情况7.5系列默认关闭可手动开启老插件不传token也能跑但安全性欠缺8.0系列默认开启必须在插件和容器里配置一致的JWT密钥8.2及更新强制开启回调策略有调整部分二次开发版插件会遇见鉴权头识别问题我一般固定使用onlyoffice/documentserver:8.0.1这个Tag不敢用latest。原因很简单latest指向的版本会随官方发布漂移某天容器重建后可能就变成8.2或更高的小版本回调接口行为一变DzzOffice里保存功能就悄悄失效。这类问题通常还不是立即报错而是用户用了一两个小时后才反馈“文档存不进去”排查成本非常高。如果你已经有跑着的旧版7.x容器先确认小胡版插件里有没有关闭JWT的开关。如果没有就按下面第3章的方式手动开启JWT并把密钥填进插件配置两边对齐。相比升级大版本我更推荐先打通JWT链路因为升级Document Server带来的接口变化不可控。2.3 服务器硬件与端口规划给足内存列清端口OnlyOffice Document Server一个容器里打包了Nginx、Node.js、PostgreSQL、RabbitMQ四类组件实际内存占用通常在2.5G到3.5G之间。最低配置建议2核4G但我会直接按4核8G来规划因为一旦多人同时在线编辑内存会往上窜。低配服务器上必须保证有至少4G的swap否则容器启动到一半直接OOM表现出来就是健康检查一直失败日志里全是内存分配报错。端口规划上DzzOffice和Document Server如果共用一台服务器要避免端口互相顶掉。端口用途映射关系80/443DzzOffice站点访问DzzOffice的Nginx占用8001Document Server编辑器页面宿主8001映射容器809875实时协同WebSocket通道宿主9875映射容器98758443Document Server的HTTPS回调可选宿主8443映射容器443注意Document Server容器启动后不会立刻对外可用内部要初始化PostgreSQL数据库和RabbitMQ配置通常需要2到3分钟才能变成healthy状态。别一启动就急着排查问题先等两分钟看健康状态再动手。云服务器还要记得在安全组里放行8001和9875端口不然本机curl是通的外部浏览器访问却一直超时。这个坑特别隐蔽排查半天最后发现是安全组没放行。3. 部署OnlyOffice Document Server一条Docker命令加一个JWT密钥3.1 安装Docker并确认容器运行时可用Document Server最省心的部署方式就是Docker避免在宿主机上手工装PostgreSQL和RabbitMQ再慢慢调依赖。这里以Ubuntu服务器为例常见的Docker安装命令如下apt update apt install -y docker.io systemctl enable --now docker docker versiondocker version能同时输出版本信息说明CLI客户端和Docker守护进程都正常。有些精简系统装了docker.io之后容器服务没自动起来systemctl enable --now docker这一步会把开机自启也一并配置好省得重启服务器后容器没跟着起来。国内服务器拉公有仓库镜像有时候会很慢我一般会在/etc/docker/daemon.json里配置镜像加速源{ registry-mirrors: [https://你的加速源地址] }填好后执行systemctl restart docker重启守护进程再拉镜像。这里注意加速源地址要选你所在网络能正常访问的不同地区可用性差别很大选一个慢的还不如不配。3.2 生成JWT密钥并以单容器方式启动DzzOffice小胡版OnlyOffice插件和Document Server之间通过JWT做身份认证。先随机生成一把密钥openssl rand -base64 32输出的字符串就是后面配置插件时要用到的JWT密钥别用一段简单字母代替。启动容器时用环境变量把密钥传进去docker run -itd --name onlyoffice-docserver \ --restartalways \ -p 8001:80 -p 9875:9875 -p 8443:443 \ -e JWT_ENABLEDtrue \ -e JWT_SECRET粘贴上面生成的密钥 \ -e JWT_HEADERAuthorization \ -e JWT_IN_BODYtrue \ -v /opt/onlyoffice/data:/var/www/onlyoffice/Data \ -v /opt/onlyoffice/logs:/var/log/onlyoffice \ onlyoffice/documentserver:8.0.1这段命令拆开看关键参数JWT_ENABLEDtrue强制开启鉴权8.0系列的默认行为也是开启显式写上免得后续重建容器时行为漂移JWT_SECRET必须和小胡版插件后台填的密钥完全一致一个字符都不能差JWT_IN_BODYtrue允许在POST回调请求体里携带token这个选项在一些插件版本里是硬依赖不开启会报token丢失数据目录挂载到宿主机的/opt/onlyoffice/data防止容器删除重建后历史文档缓存全部丢失。注意-p 8001:80左边是宿主端口右边是容器端口。如果你服务器上80端口已被DzzOffice占用千万不要试图把Document Server也直接映射到80会引发端口冲突导致Nginx起不来。3.3 容器启动后先自检等Health状态变绿启动后我看日志和健康状态的习惯是这样的docker logs --tail 200 onlyoffice-docserver curl http://127.0.0.1:8001/healthcheck/healthcheck接口返回大写的true说明Document Server核心组件已经就绪。如果返回false第一反应不应该是去看容器日志排错而是先确认PostgreSQL初始化完成没有——这个过程耗时最长很多内存不足的场景就卡在这一步。如果等了3分钟以上还是false用docker logs查看最后几十行定位是数据库初始化失败还是RabbitMQ连接异常。还有一个接口也要一并验证curl -I http://127.0.0.1:8001/web-apps/apps/api/documents/api.js这个api.js是之后DzzOffice前端加载编辑器要用的入口文件返回200才是正常的。如果这里返回404说明访问路径不对通常是端口映射或容器内Nginx配置问题。我习惯写一个小的等待循环免去手动反复执行curlfor i in $(seq 1 30); do status$(curl -s http://127.0.0.1:8001/healthcheck) if [ $status true ]; then echo document server is ready break fi sleep 10 done这个循环每10秒探测一次最多等5分钟检测到true就跳出循环。实际使用中低配服务器大概需要2到4分钟才能通过循环方式比人工盯curl要省事。4. 安装小胡版插件并接通回调链路从目录结构到nginx反代4.1 放对插件目录并让DzzOffice识别到新应用拿到小胡版OnlyOffice插件的zip包后我习惯先解压看目录结构而不是直接丢到服务器上cd /tmp unzip onlyoffice-dzz-plugin.zip ls -l解压出来应该是一个以plugin开头的插件目录里面有插件主文件、语言包目录、样式和JS目录。确认结构完整后把它整体放进DzzOffice的插件目录并修正归属和权限cd /www/wwwroot/dzzroot/dzz/plugins cp -r /tmp/plugin_xxx . chown -R www:www plugin_xxx chmod -R 755 plugin_xxx把目录属主改成www是因为Nginx下的PHP-FPM默认用这个用户运行目录权限不对时插件后台配置页会报文件不可写但表面现象可能只是配置保存后没生效非常迷惑。文件放到位后进DzzOffice后台的应用管理执行“扫描新应用”。只有扫描过后系统才会把插件目录注册进应用表DzzOffice的文件列表右键菜单里才会出现“在线编辑”的入口。这个步骤我见过太多人漏掉文件倒是放好了前台就是找不到入口。4.2 后台配置项API地址、JWT密钥和打开模式小胡版插件的配置页主要填以下几项不同版本字段名略有差异但核心参数一致配置项推荐值说明文档服务API地址http://服务器IP或域名:8001/web-apps/apps/api/documents/api.js最后不要带斜杠结尾JWT密钥与容器JWT_SECRET一致漏填或写错会导致编辑器加载失败默认打开模式editview模式只读改edit才是可编辑允许后缀docx,xlsx,pptx按实际使用范围配置移动端预览开启小胡版重点优化过移动端适配文档服务API地址最容易填错的地方是写成http://127.0.0.1:8001。这个地址最终是用户浏览器去加载的如果填了127.0.0.1每个用户打开文档都会去请求他自己的电脑端口结果自然是白屏。这里必须填服务器对外可达的IP或域名。JWT密钥的坑则更隐蔽。DzzOffice插件和Document Server容器各持一份密钥两者不匹配时编辑页可能弹出一个错误提示也可能干脆一直加载不出。因为Document Server收到不含合法token的请求时会拒绝返回编辑器资源浏览器端看到的就是一个空白的编辑器区域。4.3 用nginx反代解决跨域和HTTPS混合内容问题如果DzzOffice跑在HTTPS下而Document Server暴露的是HTTP地址浏览器会直接拦截HTTP资源加载控制台报Mixed Content错误。这个问题的根治方案就是让Document Server和DzzOffice同域名访问在DzzOffice的Nginx站点里加一段反代配置location /onlyoffice/ { proxy_pass http://127.0.0.1:8001/; proxy_set_header Host $host; proxy_set_header X-Forwarded-For $remote_addr; proxy_set_header X-Forwarded-Proto $scheme; }注意proxy_pass末尾的斜杠很关键它会把/onlyoffice/web-apps/...的请求映射到容器的/web-apps/...路径把/onlyoffice这一层前缀剥掉。如果漏掉斜杠请求会变成容器里不存在的/onlyoffice/web-apps/...返回404。仅配置以上对普通预览和编辑足够但实时协同还需要让WebSocket通道也走反代location /onlyoffice/ { proxy_pass http://127.0.0.1:8001/; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_set_header Host $host; }加了Upgrade和Connection这两个头WebSocket握手请求才能穿透Nginx到达Document Server容器。不然编辑器主体能加载出来多人协同的光标和实时保存会全部失效。这段配置生效后插件后台的文档服务API地址就不用再填http://IP:8001了直接填成https://你的DzzOffice域名/onlyoffice/web-apps/apps/api/documents/api.js页面和文档服务同源跨域问题彻底消失。5. 高频问题排查白屏、保存失败和协同失效五类翻车5.1 打开文档一直转圈或白屏现象在DzzOffice里点击在线编辑编辑器区域一直显示加载动画等几分钟还是白屏。原因最常见是文档服务API地址填错或者浏览器跨域拦截了Document Server资源。其次是HTTPS页面加载了HTTP资源被浏览器拦截。解决先按F12打开浏览器开发者工具切到Network面板看api.js这个请求返回多少状态码。如果状态码是200则问题在跨域如果请求根本没发出去地址配置基本跑不掉。改用第4章里nginx同域反代的方式把API地址换成同域名路径白屏问题多数能直接解决。我排查时还会顺手在服务器上curl一下api.js地址排除服务器本身到文档服务链路不通的因素。5.2 编辑页能打开但保存时一直转圈最后失败现象在编辑器里输入内容按CtrlS后保存图标一直转过一会儿提示保存失败刷新后又回到旧版本内容。原因保存路径是Document Server主动回调DzzOffice接口回调地址通常是插件根据DzzOffice站点URL自动拼出来的。如果站点URL填的是localhost或内网不可达地址Document Server容器根本访问不到DzzOffice保存必然失败。另一个高发原因是JWT密钥不一致Document Server回调时携带的token在DzzOffice这边校验不过。解决先进DzzOffice后台确认站点URL是外网可访问的完整地址切忌以localhost结尾。然后在服务器上进入Document Server容器手动探测DzzOffice地址能不能通docker exec onlyoffice-docserver curl -I http://你的DzzOffice站点URL/能返回HTTP状态码说明网络层通。接下来检查插件后台和容器环境变量里的JWT密钥是否逐一字符对得上密钥里如果有/、、这类特殊字符粘贴时容易被截断多核对两遍。最后看Document Server的容器日志docker logs --tail 100 onlyoffice-docserver | grep callback日志里如果出现401或403问题就在JWT密钥如果是连接超时问题在网络链路。5.3 保存成功后文件没更新DzzOffice列表还是旧时间现象编辑器提示保存成功回到DzzOffice文件列表修改时间和文件大小都没变化。原因保存回调虽然返回了成功但DzzOffice侧更新的是缓存数据文件版本记录没刷新。DzzOffice的文档处理流程是先写临时文件再触发逻辑更新文件记录某个环节失败时会出现这种“假成功”。解决检查DzzOffice的runtime/log目录下的错误日志重点看文件写入权限报错。PHP-FPM运行用户对上传目录和临时目录没有写权限时最容易出现此现象。顺手把插件缓存清理一下DzzOffice后台一般有数据缓存清理按钮清完重新保存测试。5.4 中文文件名在编辑器标题栏乱码现象文件内容正常但编辑器顶部标题文件名显示为乱码。原因回调传文件名时没做URL编码或者DzzOffice的数据库连接字符集和页面编码不一致。小胡版插件对中文文件名特别做过一轮修复但还是会有环境触发旧问题。解决首先确认DzzOffice的配置文件里数据库连接字符集是utf8很多旧环境初始装的是gbk。其次检查Nginx出口配置在location块里加上charset utf-8;缺省字符集头。这两个地方都弄完清浏览器缓存重新打开文档标题栏一般就正常了。5.5 多人协同看不到彼此光标现象两个账号同时打开同一份文档互相看不到对方的光标和正在输入的位置。原因实时协同依赖WebSocket通道Document Server的9875端口没放行或nginx反代没配置Upgrade头通道建立失败。容器内RabbitMQ异常也会导致协同消息无法广播。解决先确认宿主机的9875端口有监听ss -lntp | grep 9875如果端口监听正常则检查nginx反代配置里是否带了Upgrade和Connection两个头缺一个都不行。云服务器安全组里9875端口也确认一下放行了没否则外部浏览器连不上。最后看容器日志里RabbitMQ相关报错有异常就docker restart onlyoffice-docserver重启一次重启后等健康检查通过再测试协同。6. 装完怎么验证跑通六步自检清单加一次健康检查环境装完不是能打开编辑页就算完事我给自己定了一套六步自检流程每一步都过了才敢交付给别人用第一步用DzzOffice上传或新建一份测试文档.docx文件名故意带中文。第二步在文件列表点右键选择在线编辑等待编辑器完全加载确认标题栏显示的中文文件名没有乱码。第三步打开F12看Network面板确认api.js返回200同时找到WebSocket连接记录状态码应该是101 Switching Protocols。第四步在编辑器里输入一段测试内容按CtrlS等到右上角出现保存成功提示。第五步关掉编辑器回到DzzOffice文件列表确认文件的修改时间和大小确实变了。第六步开两个不同账号的浏览器窗口同时打开同一份文档在一个窗口输入字符观察另一个窗口是否出现实时光标和内容同步。这六步里最容易被人跳过的就是第六步。很多人保存单独一份文档没问题就以为协同也正常结果交付后多人一用实时同步是失效的还得回头补配置。验证完功能链路后我还会跑一遍Document Server侧的健康检查curl http://127.0.0.1:8001/healthcheck同时用docker inspect --format {{.State.Health.Status}} onlyoffice-docserver确认容器健康状态是healthy而不是starting。健康检查通过只能说明Document Server内部组件活着不能替代上面前端功能验证两者各管一段。以前交付过一套系统当时只验证到第四步保存成功就收了工。结果用户反馈手机浏览器里打开文档编辑器布局挤成一团按钮点不到后来才确认是移动端适配开关没在插件里打开。还有一次是DzzOffice站点URL填的内网地址保存功能时好时坏第二天用户叫苦我才排查出来。从那以后不管时间多紧我每次装完都强制自己走完这六步尤其是跨账号协同和带中文文件名这两步一次都不省。希望帮到你。本文还有配套的精品资源点击获取
