OnlyOffice预览失败需依次检查服务状态、JWT密钥、私有IP访问权限、混合内容及License文件。执行systemctl命令验证服务运行，curl检测healthcheck端点，校验local.json中JWT密钥一致性，启用default.json中allowPrivateIPAddress，强制HTTPS资源加载，并确认license.lic存在且MD5匹配。
一、检查OnlyOffice服务状态与网络连通性
若OnlyOffice前端显示空白、加载转圈或直接报错“预览失败”，首要确认文档编辑服务是否处于运行状态，且客户端能正常访问其HTTP端点。服务未启动或网络路径中断将导致预览请求根本无法抵达后端处理模块。
1、执行命令检查OnlyOffice核心服务进程是否存活：
systemctl is-active onlyoffice-documentserver
2、验证服务监听端口（默认80或443）是否可被外部访问：
curl -I http://localhost/healthcheck
3、若使用反向代理（如Nginx），确认代理配置中已正确透传WebSocket升级头：
proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade";
4、从浏览器所在机器执行telnet测试目标OnlyOffice服务器IP及端口连通性，排除防火墙或安全组拦截。
二、校验JWT密钥一致性
DzzOffice、O2OA等集成平台与OnlyOffice通信时依赖JWT签名验证身份。密钥不匹配将导致预览请求被服务端拒绝，返回401或空白响应，但前端常无明确提示。
1、在DzzOffice后台管理界面定位OnlyOffice配置项，复制其中的JWT密钥字符串。
2、登录OnlyOffice服务器，打开配置文件：
vi /etc/onlyoffice/documentserver/local.json
3、定位到"token": { "inbox": { "inbox": { "enable": true, "inbox": "密钥值" } } }结构，确认inbox字段值与DzzOffice后台所填完全一致，区分大小写且不可含空格或换行。
4、保存修改后重启服务：
systemctl restart supervisord
三、启用私有IP地址访问权限
当OnlyOffice以Docker方式部署，且DzzOffice或Vue前端运行于同一局域网内私有IP段（如192.168.x.x、10.x.x.x）时，服务默认拒绝来自私有地址的请求，直接触发“下载失败”或白屏。
1、进入OnlyOffice容器：
docker exec -it onlyoffice-documentserver bash
2、编辑默认安全策略文件：
vi /etc/onlyoffice/documentserver/default.json
3、查找"request-filtering-agent"节点，将其中两个布尔值设为true：
"allowPrivateIPAddress": true, "allowMetaIPAddress": true
4、退出容器并重启服务：
docker restart onlyoffice-documentserver
四、修复混合内容（Mixed Content）错误
当宿主系统（如O2OA、Vue2项目）已启用HTTPS，而OnlyOffice服务仍通过HTTP提供资源（如api.js、字体、图标），现代浏览器将主动阻断不安全子资源加载，导致预览界面样式错乱、功能按钮失效或控制台报“Mixed Content”警告。
1、打开浏览器开发者工具（F12），切换至Console标签页，确认是否存在红色Mixed Content报错。
2、检查OnlyOffice服务是否已配置有效HTTPS证书；若未配置，需为其绑定SSL证书并启用443端口。
3、在宿主系统调用OnlyOffice SDK时，确保所有URL参数（如document.url、callbackUrl、editorConfig.type相关资源路径）均使用https://协议前缀。
4、若暂时无法部署HTTPS，可在OnlyOffice Nginx配置中添加Header强制升级：
add_header Content-Security-Policy "upgrade-insecure-requests";
五、验证License文件完整性与有效期
前端持续显示【您的许可证已过期。请更新您的许可证并刷新页面。】即表明License校验失败。该提示不仅影响专业版功能，部分社区版定制部署亦依赖license.lic文件完成初始化校验，缺失或损坏将阻断预览流程。
1、进入OnlyOffice License目录：
cd /var/www/onlyoffice/Data/
2、检查license.lic文件是否存在且非空：
ls -l license.lic && stat -c "%s" license.lic
3、比对文件MD5值是否为预期值：
md5sum license.lic | grep -q "8d289ecbf3c3afcc280fb7971ac120f2"
4、若校验失败，从原始安装包中提取合法license.lic并覆盖：
cp -vf ./informat_next_2.23/onlyoffice/license.lic /var/www/onlyoffice/Data/
5、重启supervisord使License重载生效：
systemctl restart supervisord
