Dzzoffice 搭好了OnlyOffice 也装了结果点开文档就是打不开报错一个接一个。这是我最近帮朋友排查一套内部协同平台时遇到的情况前后折腾了好几天把能踩的坑基本都踩了一遍。这篇文章把这次的报错排查流程完整记录下来从架构思路到具体问题再到工具命令都做了整理。如果你也在做 Dzzoffice 和 OnlyOffice 的对接或者只是单纯想把 OnlyOffice 文档服务器跑稳这篇内容应该能帮你省下不少时间。先说下这套东西是干嘛的。Dzzoffice 是国内团队维护的一款开源协同办公套件相当于一个把网盘、文档、表格、通讯录、任务管理整合到一起的企业门户它本身不做在线编辑而是通过插件形式把在线编辑能力交给 OnlyOffice。OnlyOffice 文档服务器是另外一套独立部署的服务负责文档解析、在线渲染、协同编辑和保存。Dzzoffice 做的事情就是把用户点开的文档交给 OnlyOffice 去编辑再在保存时把文件拿回来放回自己的存储里。很多人在部署完以后遇到的第一个问题就是明明两边都装了文档就是打不开或者打开了保存不了。排查这种问题如果脑子里没有一个清晰的链路图很容易修了 A 坏了 B最后开始怀疑文档服务器是不是装坏了。1. 先认清两条服务链路排查才不会走弯路1.1 Dzzoffice与OnlyOffice各自扮演什么角色Dzzoffice 本质上是一个门户层它负责用户管理、文件存储、权限控制和页面集成。它把文件存在自己的目录结构里但在线编辑时会把文件内容交给 OnlyOffice 文档服务器去处理。OnlyOffice 文档服务器也叫 Document Server则是真正干活的组件。它启动后一般监听 80 端口对外提供几个关键服务文档转换、在线编辑、协同通信。浏览器打开时其实加载的是 OnlyOffice 文档服务器上的前端编辑器页面Dzzoffice 这边只是嵌入了这个页面的 iframe。所以很多问题发生在浏览器和 OnlyOffice 之间跟 Dzzoffice 本身没多大关系。明确这一点很重要因为这意味着排错时要分成三层来看浏览器前端、OnlyOffice 文档服务、Dzzoffice 业务后端。1.2 一次文档打开背后的完整请求链路用户点击文档到看到编辑器中间大概发生了这样几步用户访问 Dzzoffice 页面点击某个文档。Dzzoffice 后端校验权限生成一个唯一的文档 key。Dzzoffice 页面拼接 OnlyOffice 编辑器的 URL通常是http://你的文档服务器地址/web-apps/apps/api/documents/api.js。浏览器请求这个 api.js拿到 OnlyOffice 前端的加载脚本。前端加载完成后向 OnlyOffice 文档服务器发起 document 请求请求里包含文档 URL、key、权限和 JWT 令牌。OnlyOffice 文档服务器收到请求后向 Dzzoffice 提供的文档地址拉取文件内容。编辑器渲染完成用户开始编辑。用户保存时OnlyOffice 文档服务器通过回调地址通知 Dzzoffice“文件已保存”并把编辑后的文件内容推送过去。这里面最容易出问题的就是第 5 步和第 8 步。第 5 步出问题编辑器打不开或者报“文档安全令牌”相关错误第 8 步出问题保存失败或者保存后版本不一致。1.3 把报错分成四类缩小排查范围我后来给自己定了一个分类方法遇到任何报错先把问题归类再去翻对应的日志和配置。大致分四类第一类页面加载类报错。表现为浏览器打开文档时白屏、404、api.js 无法访问、证书错误等问题基本在前端访问链路。第二类鉴权类报错。表现为有报错提示“文档安全令牌的格式不正确”、401、403 等问题基本在 JWT 密钥配置不一致。第三类保存回调类报错。表现为文档保存不上、保存超时、版本被覆盖、提示“文件版本已更改该页面将被重新加载”等问题通常在回调链路。第四类偶发异常类报错。表现为多人同时编辑时状态错乱、文档锁死、偶尔能打开偶尔报错问题可能在 WebSocket、缓存或并发处理上。这个方法不一定完美但能让你在收到一个报错时不用东翻西翻直接按类别去查对应的配置和日志。2. 排查必备日志位置、配置清单和验证命令2.1 三类日志定位问题各管一段排查 OnlyOffice 问题不能只盯着一个地方看日志至少要同时看三处。第一处是 OnlyOffice 文档服务器自己的日志。以 Docker 部署为例进入容器后可以在/var/log/onlyoffice/documentserver/目录下看到日志文件。docservice是核心服务负责文档转换和编辑请求converter负责格式转换webapi负责接口请求。不同日志对应不同问题但实际操作中我一般先看docservice下有没有 output 信息和错误信息比如 JWT 校验失败、JSON 解析失败、某个地址访问不了等都会在这边留有记录。第二处是 Dzzoffice 业务侧的日志。因为 Dzzoffice 是 PHP 程序日志一般在 Web 服务器Nginx 或 Apache的 access log 和 error log 里PHP-FPM 的错误日志也会有帮助。特别是在排查回调问题时如果 Dzzoffice 的接口返回了 500就得去这里看。第三处是浏览器开发者工具。打开不起效的文档页面时按 F12 切到 Network 面板看 document 请求的响应状态和响应内容切到 Console 面板看有没有 JS 报错。千万不要忽略这一步因为有些问题其实在浏览器端就已经暴露出来了只是报错提示被 Dzzoffice 的界面挡住了。2.2 改配置之前先核对这份最小清单在动手改任何配置之前先把下面这几项核对一遍能避免 80% 的低级错误OnlyOffice 文档服务器的地址Dzzoffice 端填写时不能带上末尾的斜杠比如填写http://192.168.1.100而不是http://192.168.1.100/。有些版本里这一字之差就会导致拼接 URL 异常。Dzzoffice 端填写的 OnlyOffice 地址必须是浏览器能够直接访问的地址。如果你的 Dzzoffice 是通过域名访问那 OnlyOffice 也尽量用同一个域名避免浏览器因为混合内容HTTPS 页面加载 HTTP 资源直接拦截。JWT 密钥是否一致。OnlyOffice 文档服务器和 Dzzoffice 端的 OnlyOffice 插件配置里都有一个密钥字段两个值必须完全一样。注意空格、大小写、编码都不要有差异。文档服务器的回调地址是否可以被 OnlyOffice 访问。这一条最容易被忽略因为浏览器能打开 OnlyOffice 不代表 OnlyOffice 服务器能反过来访问 Dzzoffice。尤其当你用内网 IP 访问 Dzzoffice 的时候要确认 OnlyOffice 所在机器能 ping 通并访问那个 IP。2.3 用curl快速验证文档服务是否真正可用有时候界面上一堆报错看着很吓人其实根因就是文档服务器没起来。我最常用的验证手段是用 curl 直接探测几个关键地址。探测 api.js 是否可访问curl -I http://你的文档服务器地址/web-apps/apps/api/documents/api.js正常情况会返回 200并且响应头里有Content-Type: text/javascript。如果返回 404 或者连接失败说明你的文档服务器地址、端口或者路径有问题先解决这个问题再看其他。验证健康状态较新的 OnlyOffice 版本提供专门的健康检查接口curl http://你的文档服务器地址/healthcheck返回true表示文档服务基本正常。如果访问不了说明服务本身没起来或者 Nginx、防火墙把这路径拦掉了。验证 Dzzoffice 和 OnlyOffice 之间能不能互相访问用一个最简单的办法在 OnlyOffice 所在的机器上执行curl -I http://你的Dzzoffice地址能返回 200说明回调链路是通的。如果这一步都不通后面保存报错基本不用查其他的先把网络打通再说。3. 高频报错逐个拆解与解决方案3.1 api.js无法访问浏览器编辑器白屏现象在 Dzzoffice 里点击文档后弹出来的编辑区域一直是空白加载不出编辑器界面。F12 里能看到请求api.js这个资源失败报 404、超时或者连接被拒绝。这个问题的根源十有八九是浏览器访问不到 OnlyOffice 文档服务器的这个资源路径。具体来说分几种情况。第一种OnlyOffice 服务没起来。Docker 部署时执行docker ps看看onlyoffice/documentserver容器是不是 running 状态。如果容器起来了但文档服务异常看容器日志docker logs onlyoffice-document-server --tail 100看到报错按报错处理常见的比如数据库没起来、内存不足导致目录服务崩溃等。第二种地址或端口配错了。Dzzoffice 后台配置 OnlyOffice 地址时填的是http://192.168.1.100:8080但 OnlyOffice 实际监听的是 80 端口那浏览器访问http://192.168.1.100:8080/web-apps/apps/api/documents/api.js自然访问不到。这里尤其要提醒一种情况Windows 上安装 OnlyOffice 时安装程序默认监听 80但很多人的 80 端口已经被其他 Web 服务占了比如 IIS、Apache 或某个奇怪的软件。Win11 下我遇到过 80 端口被系统打印服务或 Hyper-V 保留端口占用的场景很隐蔽不仔细查根本想不到。Windows 下可以用这个命令查 80 端口占用netstat -ano | findstr :80查到占用进程的 PID 后再去任务管理器里确认是谁停掉或者给 OnlyOffice 换端口。换端口后记得同步修改 Dzzoffice 后台的地址还要检查防火墙是否放行新端口。第三种防火墙拦截。只开了 80 端口的入站规则但 OnlyOffice 换了端口以后没加新规则或者服务器在云上安全组策略只放行了特定端口。这种情况在 Windows 和 Linux 上都可能出现处理方式是开放对应端口或者干脆让 OnlyOffice 保持默认 80 端口把其他占用 80 的服务挪走。第四种HTTPS 混合内容拦截。Dzzoffice 本身用了 HTTPS 域名访问但 OnlyOffice 地址填的是 HTTP。浏览器出于安全策略会拦截 HTTP 资源但报错往往不是很明显控制台会提示 Mixed Content。解决办法是 OnlyOffice 也配上 HTTPS或者让 Dzzoffice 先统一走 HTTP内网测试环境再排其他问题。实际的长期方案还是把 OnlyOffice 和 Dzzoffice 放到同一个域名体系下统一 HTTPS。第五种Nginx 反向代理配置有问题。如果 OnlyOffice 文档服务器是通过 Nginx 反代出去的那 Nginx 配置里必须把/web-apps、/docxs、/coauthoring等路径代理到 OnlyOffice 实际服务端口。很多人只代理了根路径/但 OnlyOffice 的一堆子路径没有配全结果 api.js 能访问内部的其他请求却一直报错。最简单稳妥的做法是直接代理整个域名的根路径到 OnlyOffice再配合 location 规则处理静态资源和 WebSocket。3.2 文档安全令牌的格式不正确JWT密钥不一致现象打开文档时编辑器页面弹出一行中文提示“文档安全令牌的格式不正确”。浏览器控制台配合日志能看到大概是 invalid token 或者 security token 格式不对的信息。这个报错在 OnlyOffice 7.2 以后版本出现的频率非常高因为从那个版本开始文档服务器对 JWT 令牌的校验变严格了而且默认就会生成一个随机密钥。Dzzoffice 端如果配置了 OnlyOffice 插件但没有正确填写文档服务器生成的密钥就会导致双方校验对不上直接报这个错。排查方向就一个核对 Dzzoffice 和 OnlyOffice 两边的 JWT 密钥是否一致。OnlyOffice 文档服务器如果是 Docker 部署可以在启动 Docker 时用环境变量设置密钥docker run -d \ -p 80:80 \ -e JWT_ENABLEDtrue \ -e JWT_SECRETmy_super_secret_key_123 \ --name onlyoffice-document-server \ onlyoffice/documentserver如果是之前已经启动过的容器或者用的是安装包直接安装那就需要找到文档服务器的本地配置文件local.json查看services.CoAuthoring.secret和services.CoAuthoring.token.enable两个配置项。Debian 安装包的位置通常在/etc/onlyoffice/documentserver/local.jsonDocker 容器内也会有一份默认配置建议用docker exec进去看看。Dzzoffice 后台的 OnlyOffice 插件设置里一般有一个“密钥”或“Secret”的输入框。把 OnlyOffice 侧配置的 JWT_SECRET 完整复制过来。这里我吃过大亏密钥复制的时候多了个空格表面上看不出来实际一比对就是不一样导致怎么配置都报同样的错。另外要注意OnlyOffice 不同版本对 JWT 密钥有长度要求太短的密钥会被拒绝。建议直接生成一个 32 位以上的随机字符串避免踩这个边界问题。生成方法很随意openssl rand -base64 32配置改完后重启 OnlyOffice 文档服务器让配置生效。Docker 方式是docker restart onlyoffice-document-server。重启后再测试打开文档正常情况下这个报错就消失了。如果重启后还是报同样的错那要检查一下是不是有多个配置文件在同时生效。遇到过一种情况是老版本升级上来的 OnlyOffice 保留了旧的 local.json同时又有新的环境变量覆盖两边加密算法不一致。这时候最好的办法是打开 local.json 把 secret 字段的值直接复制出来再填到 Dzzoffice 那边两边用同一个来源基本不会错。3.3 文件版本已更改该页面将被重新加载现象用户编辑完文档后保存然后再打开同一份文档有时候甚至不关闭页面浏览器弹出一个提示“文件版本已更改该页面将被重新加载”。点确定后页面刷新之前编辑的内容不知道还在不在。这个提示的本质是 OnlyOffice 检测到当前文档的版本标识发生了变化。文档版本号一般由 key 来标识Dzzoffice 每次把同一份文档交给 OnlyOffice 时key 必须是一致的。如果同一个 key 对应的文档内容变化了OnlyOffice 就会认为文档被外部修改当前打开的编辑器版本已经过期于是强制刷新页面。这个报错常见于两种场景。第一种是用户开了多个标签页编辑同一份文档或者上一个编辑窗口没有正常关闭旧会话还占用着文档的编辑锁。当你再次打开时新的编辑会话发现文档已经被另一个会话保存过版本自然不一致。解决办法是关闭所有相关标签页等几秒让锁释放再重新打开文档。如果问题反复出现需要检查 Dzzoffice 后台是否配置了“单一编辑锁定”之类的功能或者是否允许同一文档被多个窗口同时编辑。第二种是 Dzzoffice 在保存文档后重新生成了 key或者保存时把文档内容重写了一遍比如从临时文件覆盖到正式文件导致文件内容虽然一样但底层文件的修改时间变了OnlyOffice 判断版本变化。这种情况需要去 Dzzoffice 的代码或插件配置里看 key 生成的规则。正常的做法是同一个文档路径对应同一个稳定 key不要每次生成随机 key。第三种情况是回调保存机制出了问题。OnlyOffice 保存文档时会把结果通过回调地址告诉 Dzzoffice。Dzzoffice 在收到回调后如果返回给 OnlyOffice 的状态码不是 200OnlyOffice 会认为保存失败但用户端已经触发了刷新逻辑结果就是弹出版本变化提示。排查方法是看 OnlyOffice 文档服务器的日志看保存回调有没有成功。同时看 Dzzoffice 这边 Nginx 的 access log看有没有来自 OnlyOffice 的 POST 请求以及返回的状态码。实际项目里我还遇到一个很隐蔽的问题Dzzoffice 的保存回调地址用的是内网 IP但 OnlyOffice 是通过公网域名访问 Dzzoffice 的。OnlyOffice 服务器在公网环境下无法解析或访问内网 IP回调一直失败用户那边就反复出现版本刷新提示。解决方法是把 Dzzoffice 的可访问地址配置成 OnlyOffice 能访问到的地址并在 Dzzoffice 后台做地址白名单校验时把这个地址加进去。3.4 编辑器一直转圈或加载一半卡住现象文档倒是能打开了编辑器也出现了但是一直转圈或者等很久才出来。有些文档打开后是空白编辑器工具栏有内容区域不渲染。这类问题排查起来相对麻烦因为不是“无法访问”而是“访问链路有一部分不通”。最常见的原因是 WebSocket 没有连通。OnlyOffice 的协同编辑功能依赖 WebSocket 连接用于同步光标位置、编辑内容、协同状态等。如果浏览器和文档服务器之间的 WebSocket 连接建立不起来前端会反复重连表现出来的就是一直加载或者在协同编辑时各种诡异。Docker 部署时默认会监听 80 端口WebSocket 走的是/coauthoring/路径。如果前面套了 Nginx 反向代理必须要对 WebSocket 升级请求做特殊处理。Nginx 里至少要加这些配置location /coauthoring/ { proxy_pass http://onlyoffice_backend; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_set_header Host $host; }如果少了Upgrade请求头WebSocket 就会握手失败前端会不断重连表现就是编辑器加载不出来或者协同状态异常。还有一种可能是时间不同步。OnlyOffice 服务器和浏览器所在机器如果系统时间偏差太大会导致 JWT 过期或者握手校验失败。特别是内网环境里有人手动调过系统时间TLS 校验或者令牌有效期就会出问题。解决方法是把服务器时间改成自动同步并确认 OnlyOffice 所在机器的时区和你预期的一致。另外如果只有某些特定浏览器打不开其他浏览器正常尤其在 Windows 环境要检查浏览器的安全策略、代理设置和兼容模式。OnlyOffice 编辑器对浏览器内核有要求老版本的 IE 内核基本是打不开的。建议优先用最新版 Chrome 或 Edge 测试定位。热词里有“onlyoffice 查看文档显示 文档安全令牌的格式不正确”“win11 安装 api.js 无法访问”这类问题多数都和浏览器缓存或本地代理有关。遇到玄学报错先换无痕窗口再试往往就有新发现。3.5 保存失败、保存后内容丢失或版本冲突现象文档编辑过程中一切正常点击保存后没有反应或者提示保存失败。有的更严重用户以为保存成功了关闭页面后再次打开发现内容还是旧的。保存这一环牵扯到 OnlyOffice 和 Dzzoffice 两边的配合流程上比打开文档复杂。OnlyOffice 不会把编辑后的文件直接覆盖到原位置而是先保存到自己的临时存储然后通过回调接口把文件数据 POST 给 Dzzoffice由 Dzzoffice 负责写回正式存储。所以排查保存问题核心是确认回调是否成功。具体步骤第一步看 OnlyOffice 文档服务器的日志找到对应文档 key 的保存记录看有没有向回调地址发出请求。如果没有发起请求说明 OnlyOffice 侧保存没触发可能是文档服务异常或者保存方式配置不对。第二步看 Dzzoffice 的 Nginx 访问日志检查有没有来自 OnlyOffice 的 POST 请求以及请求是否返回 200。如果请求到了但返回 500问题在 Dzzoffice 后端要看 PHP 日志或应用日志。如果请求压根没到那就是网络隔离或地址不通的问题。第三步确认回调地址配置。Dzzoffice 在向 OnlyOffice 发起打开文档请求时会在请求参数里带上一个回调用地址。有些版本里这个地址是自动生成的基于 Dzzoffice 后台配置的站点域名。如果站点域名配置的是http://localhost或内网 IP而 OnlyOffice 拿到的回调地址访问不了那保存就会失败。解决办法是去修改 Dzzoffice 的站点访问地址配置确保对外使用的域名和内网访问域名保持一致或者至少在 OnlyOffice 所在的服务器上能够解析。第四步检查磁盘权限和存储目录。有些 Dzzoffice 安装到 Docker 里文件存储目录没有做持久化映射容器一重启已经保存的文件全没了。Dzzoffice 的安装文档里会说明存储路径实际部署时一定要把文件存储目录挂载到宿主机否则遇到升级或重启哭都来不及。存储冲突这块再补充一点。如果企业里既有 Dzzoffice又有 Nextcloud 之类的云盘同时接同一个 OnlyOffice也要注意不同系统对同一文档的保存策略不一样。热词里提到的 openeuler 25.09 Docker 部署 Nextcloud 34 加 OnlyOffice 9.4.0 加 PostgreSQL 16 那一套其实就是多种存储和协同服务堆在一起。一旦其中某一层的回调配置没对上就会连环报错。这种场景下我建议先单独验证每个系统和 OnlyOffice 的直连是否正常再组合起来测试否则多系统叠加时很难分清问题出在谁身上。4. 不同集成方式下的避坑要点4.1 Dzzoffice原生集成的配置细节Dzzoffice 官方网站和应用市场里提供了 OnlyOffice 的集成应用安装后在后台设置里一般需要配置两个核心参数文档服务地址和密钥。文档服务地址我前面说过不要带末尾斜杠。密钥则要来源于 OnlyOffice 文档服务器的配置。很多人在 Dzzoffice 后台看到密钥输入框以为随便填一个就行结果填了以后一直报“文档安全令牌”错误。正确的操作流程是先确认 OnlyOffice 文档服务器上配置的 JWT 密钥是什么。在 Dzzoffice 后台填入这个密钥。保存配置后清理浏览器缓存重新打开文档。如果 Dzzoffice 后台没有密钥输入框或者在应用设置里找不到 OnlyOffice 的配置入口那可能是你安装的 Dzzoffice 版本太老或者 OnlyOffice 集成应用没有正确安装。解决办法是去 Dzzoffice 应用市场检查应用版本或者手动更新 OnlyOffice 连接器文件。有个细节是新版本 OnlyOffice 文档服务器默认开启 JWT 之后Dzzoffice 老版本连接器是不带 JWT 签发的两边一个签发一个校验肯定对不上。这种情况要么升级 Dzzoffice 连接器要么在 OnlyOffice 文档服务器里暂时关闭 JWT 校验不推荐仅测试时用。生产环境务必保持 JWT 开启。4.2 自研Java系统集成OnlyOffice的注意项热词里有一批是“springboot 集成 onlyoffice”“java 进行 onlyoffice 在线编辑文书”之类的。说明不少人是在自研系统里做集成而不是用 Dzzoffice 这种现成套件。SpringBoot 集成 OnlyOffice核心要做的事情有两件一是签发包含文档信息的 JWT二是实现 OnlyOffice 的回调接口。JWT 签发时要注意OnlyOffice 的文档配置config会被加密成一个 token然后作为参数传给前端。生成 token 时密钥必须和 OnlyOffice 文档服务器的 secret 一致。实践中常见错误是本地配置里写了一个 secretNacos 配置中心里又写了另一个发布的时候没注意结果测试环境好的线上一直报错。回调接口实现时有几个注意点。OnlyOffice 发送回调请求时会带一个status字段不同值代表不同状态。保存完成后 status 为 2需要返回{error:0}。有些系统在保存完成后没有做文件写回只是返回了一个正常响应结果 OnlyOffice 以为保存成功了其实文件内容根本没更新。所以回调接口里务必要实现完整的文件写入逻辑并用事务保证数据一致性。另外OnlyOffice 回调请求中会包含一个 JWT 令牌服务端在接收回调时应当先校验令牌确认请求来自可信的 OnlyOffice 文档服务器而不是任意伪造请求。这既是安全问题也能避免一些误触发的情况。4.3 Vue3前端嵌入OnlyOffice的常见问题Vue3 项目嵌入 OnlyOffice 通常是通过 iframe 加载 api.js 后动态生成编辑器实例。这块容易出现问题的地方主要在加载顺序和生命周期管理上。Vue3 的组件生命周期和 OnlyOffice 的初始化事件做不好配合时会出现编辑器已经创建但页面 DOM 还没渲染完或者页面销毁后 OnlyOffice 的事件还挂在那里导致内存泄漏。比较稳妥的做法是在 mounted 里先加载 api.js加载完成后再调用new DocsAPI.DocEditor()组件卸载时销毁编辑器实例。另一个常见问题是前后端连接时的跨域。Vite 开发环境下前端项目跑在http://localhost:5173OnlyOffice 文档服务器跑在另一个端口跨域请求会被浏览器拦截。解决方法是配置 Vite 的 proxy把/web-apps、/coauthoring等路径代理到文档服务器地址。Vue3 项目里嵌入 OnlyOffice 时JWT 令牌的值也要注意时效。有些系统在点击文档时动态获取 token但如果文档编辑器打开时间很长超过 token 有效期保存时就会报“令牌不正确”。需要合理设置 token 过期时间或者在前端检测到错误时重新获取令牌并刷新编辑器配置。这种做法在 Dzzoffice 里也有类似场景Dzzoffice 的集成插件会自己处理令牌签发但换成自研前端时就完全要自己掌控了。4.4 不使用Docker部署OnlyOffice容易踩什么坑虽然官方推荐 Docker 部署但不是所有企业都允许用 Docker尤其内网环境对容器技术管控比较严的时候只能用安装包直接装。OnlyOffice 文档服务器的 Debian 包安装时要装不少依赖PostgreSQL、RabbitMQ、Nginx 等并且版本要和 OnlyOffice 要求的版本匹配。版本对不上装到一半会报依赖错误。我遇到过一次 PostgreSQL 版本不满足要求只能先卸载再重装指定版本过程比较痛苦。安装之后Nginx 的配置也需要手动检查。安装包自带一份默认 Nginx 配置一般会放到/etc/nginx/sites-available/onlyoffice-documentserver并且软链到 sites-enabled。如果你的服务器上 Nginx 默认站点占用了 80 端口或者有其他站点配置冲突那就可能导致 OnlyOffice 首页能访问但实际加载不正常。Windows 上不建议生产环境使用 OnlyOffice 文档服务器官方对 Linux 的支持完善得多。Windows 安装更多用于本地开发测试。Windows 上最容易遇见的问题就是端口占用和防火墙前面说到的 win11 场景很典型。如果你坚持要在非 Docker 环境安装 OnlyOffice务必记录好所有安装步骤和版本号。升级时先备份数据库和配置然后在测试环境完整走一遍升级流程再上生产。Docker 版本升级时用官方镜像更新通常很方便但裸机安装版升级往往就没那么顺利了。5. 配置加固与版本升级的长效机制5.1 JWT密钥管理一次改对不再反复JWT 密钥不应该经常换但也不应该一年到头不换。合理的做法是把它当成数据库密码一样管理存放在配置中心或者环境变量里不写死在代码中。统一密钥的方式有几种。如果你的环境里只有一套 OnlyOffice 文档服务器那么所有对接方Dzzoffice、自研系统、其他云盘都用同一个 secret配置简单直接。如果你有多个环境开发、测试、生产每个环境单独一套密钥使用时按环境切换不要所有环境共用。更换密钥的流程也要注意顺序。先改 OnlyOffice 文档服务器配置并重启再依次更新所有下游对接方的密钥配置最后清掉浏览器缓存重新测试。顺序反了会导致部分系统在密钥切换期间出现“安全令牌格式不正确”的报错。实际业务中文档服务器上的 local.json 里还有token.enable配置。建议保持开启并在开启状态下禁止任何人关闭 JWT 校验来“暂时解决”鉴权问题。JWT 对 OnlyOffice 集成来说不仅是安全屏障也是判断请求来源合法性的重要依据。关了它问题可能会变少但风险会成倍增加。5.2 反向代理、HTTPS和WebSocket必须一起处理企业里很少有人直接暴露文件服务端口一般都会在前面加一层 Nginx 反向代理。做反代的配置时除了常规的 proxy_pass还要特别注意 WebSocket 代理和静态资源路径。这套代理配置如果草草写完最常见的现象就是页面能打开但协同功能异常或出现连接断开重连。这个我在 3.4 节里说过了核心是把Upgrade和Connection请求头透传过去。这一点看似基础但配置错的人不在少数。HTTPS 又是另一个容易出问题的点。OnlyOffice 文档服务器和 Dzzoffice 之间如果有一侧走 HTTPS另一侧走 HTTP就会出现混合内容拦截或者回调地址不一致的情况。比如 Dzzoffice 网站是 HTTPS但填的 OnlyOffice 地址是 HTTP编辑器页面会加载不出来。反过来OnlyOffice 通过回调访问 Dzzoffice 时如果 Dzzoffice 是 HTTP但配置里写成了 HTTPS 地址回调就会失败。所以最好一开始就统一Dzzoffice 和 OnlyOffice 都走 HTTPS域名在同一个主域下回调用内网专用域名或 IP。如果暂时不具备全部 HTTPS 条件至少保证浏览器访问的所有资源都是同协议回调用内网 HTTP 地址单独配置。这样既不影响浏览器加载也能保证 OnlyOffice 到 Dzzoffice 的回调链路稳定。5.3 版本升级与缓存清理的标准动作OnlyOffice 文档服务器版本更新较快每次升级前最好看一下官方发布说明因为某些大版本会变更配置项导致旧配置失效。升级前备份是必须的。如果是 Docker 部署备份容器配置记录下端口映射、环境变量、挂载卷。升级时拉取新镜像用同样的启动参数重建容器。如果是裸机安装要备份local.json和数据库。这里的数据库指的是 OnlyOffice 用来存文档元数据的 PostgreSQL不是 Dzzoffice 自己的业务库。升级完成后一个容易被忽视的动作是清理浏览器缓存和 OnlyOffice 的前端缓存。OnlyOffice 前端有一部分静态资源会被浏览器缓存在本地版本更新后旧缓存和新接口不兼容会导致初始化失败或者编辑器加载异常。最直接的验证方式是用无痕窗口打开文档测试。如果无痕模式正常普通模式异常那就是缓存问题强制刷新或者清缓存就能解决。容器内部的前端缓存一般不需要手动清理重启容器时会自动重置。但如果遇到页面加载的 JS 还是旧版本可以在宿主机上清一下 related 的缓存目录或者直接用覆盖安装的方式强制刷新。实际运维中我更倾向于重启文档服务器服务后再测试多数缓存相关的问题在服务重启后就会消失。6. 写在最后一次排查一次收获Dzzoffice 加 OnlyOffice 这套组合单看每个产品都不复杂真正考验人的反而是各种配置之间的“对不上”。我在这次排查中最深的体会是不要一上来就怀疑软件有 bug。大部分报错的根因都能归结为密钥不一致、地址填错、回调不通、缓存未清这几类。把排查顺序固化下来先日志后配置先网络后代码很多看起来玄学的问题其实是稳定的逻辑链条。最后分享一个小技巧每次改完配置别急着让用户去测。你先自己用 curl 验证文档服务是否正常再开一个无痕窗口登录 Dzzoffice 打开文档。如果无痕窗口下一切正常那剩下的问题基本都是浏览器缓存或者历史会话导致的状态错乱清理一下就好。小技巧虽然土但在这种多系统协同的场景里真的能帮你把“偶发问题”变成“稳定复现”后面的排查难度会下降一大截。