常见问题

打开文档提示「下载失败」

• 启动参数需要按照启动编辑服务 设置环境变量 ALLOW_PRIVATE_IP_ADDRESS=true
• 开档时传递的文件地址是需要在容器内部下载并转换的，所以一定要保证地址在容器内可正常下载
• 不能使用 127.0.0.1 或 localhost 一类的域名或地址访问服务，容器内会请求到自己内部
• 如果是使用了 https 协议的地址，一定要保证证书是正式的而不是自己颁发的，否则也可能失败
• 如果是CDN回源，要保证访问协议与回源协议一致

总之下载失败时可以查看容器日志，内部会清晰的告诉你为什么失败。

文档可编辑，保存提示「无法保存」

• 检查浏览器控制台是否有报错。
• 检查容器日志，是否保存回调接口实现存在问题。

提示「安全令牌格式不正确」

文档服务默认开启了 jwt 认证，你如果执意开启，可参考官方文档 签名，并注意 token 过期时间相关配置。

如果非必要，建议按以下操作

• 启动容器时，使用环境变量关闭认证 JWT_ENABLED=false
• 打开文档时将 token 留空

以上两条需要同时达到才可以解决此问题。

授权不生效

中文增强版使用授权文件进行高级版授权。如发现不生效，可以从以下方面排查：

• 查看容器日志，如果提示 License does not exist 说明授权文件不存在，请仔细核对文件位置
• 如果提示 License parsing failed 说明文件内容已经被破坏无法解析
• 如果提示 License is illegal 说明机器码不匹配或已经过期，此时授权已失效
• 核对机器码是否变动 查询机器码，可能由于启动容器时没有使用特权模式或没有正确挂载目录 启动编辑服务
• 宿主机硬件信息是否发生变化。机器码依赖宿主机硬件信息（主板/CPU/网卡），有时候云服务器某些配置操作也会导致信息变化。请使用硬件信息稳定的宿主机服务器。
• 不支持 Docker Desktop 或类似环境，请使用 Linux 宿主机服务器，或者尝试使用 Linux 虚拟机，但不保证稳定性。

如何部署 https

不建议在 文档服务内部部署证书开启 https。相对合理的做法是在最前端的出口服务器（nginx 一类）上部署证书并做反向代理

部署 https 后发现存在部分 http 请求

此种情况大部分出现在你做了 30x 跳转，或者你配置的 https CDN 回源的是 http 地址。CDN 上回源地址需要和源站地址一样，否则内部检测 https 协议会失败，从而返回了 http 的下载地址

如何子目录部署

中文增强版已经适配子目录部署，具体见 子目录部署。

无法复制，控制台提示没有 copy 权限

文档服务在开档时使用参数 document.permissions.copy 配置控制是否允许复制。请仔细核对你的集成参数。

部分第三方系统集成 文档服务时没有传递 copy 权限，也有可能会导致权限不符合预期。请尽量显示传递权限字段。

另外，文档服务的默认逻辑是快捷键读写的是系统剪切板内容，鼠标右键读写的是内部剪切板内容，需要注意操作习惯。

再次打开文档提示版本已更新

先来看基本的流程

• document.key 就相当于你正在编辑的文件内容的版本号，新开文档时设置 key0 对应版本v0，即初始版本
• 编辑服务会下载原始文档 example.docx 转换为中间格式 Editor.bin，浏览器会加载此中间文件，做解析渲染
• 不同的终端使用同一个key0进入，会进入协同编辑状态，此时大家修改的是 Editor.bin 文件。此时 callback 接口会收到 status=1 的回调通知
• 在开启强制保存并手动保存，或者所有终端退出编辑时，编辑服务会在一段时间（0 至几秒钟）之后，生成类似 key0_1234 的版本目录 ，并在其中生成 changes.zip 和 output.docx，然后触发 status=6 或者status=2 的回调。详细回调报文见 Callback handler
• 在 status=2 （所有人退出编辑）时需要在回调接口中下载最新的 output.docx 并覆盖原始文档 example.docx，同时将记录的版本号升级，以便下一轮编辑使用
• 注意下一轮重新打开并编辑需要使用不同的 key，如 key1 对应新的原始文档，否则会直接打开已经存在的缓存文件
• 以上缓存文件都保存在 /var/lib/onlyoffice/documentserver/App_Data 下，可自行验证

所以出现版本更新提示，是因为当前编辑器的 document.key 与服务器内部记录的文件版本（内容 hash）不一致。可能原因是:

• 文件变了但 key 没变
• key 变了但文件没变
• 多人用不同 key
• 存储的延迟或缓存导致文件内容变化

严格按照基本流程实现，就不会存在此问题。至于版本号，你可以自己用数据库在外部存储维护文档的版本号变化。

部署服务需要什么样的硬件

具体参见官方文档 根据并发活跃用户数量的硬件要求。但性能同样受文档大小影响，建议实际使用时将硬件性能放大 1 倍。

打开文档时弹出了“选择TXT选项”窗口

• 文件扩展名错误（最常见）。例如：合同.docx 被改成了 合同.txt，或者上传时文件名丢失 ONLYOFFICE 无法识别格式，于是按 TXT 打开。
• 服务端返回了错误的文件名。例如下载接口 Content-Disposition: attachment; filename=test.txt，但实际内容是 application/vnd.openxmlformats-officedocument.wordprocessingml.document。ONLYOFFICE 会根据文件名判断类型。
• OnlyOffice Config 中 fileType 配置错误

new DocsAPI.DocEditor("placeholder", {
    document: {
        fileType: "txt",
        url: ".../test.docx"
    }
})

• 下载 URL 返回的不是文档，而是返回了 json 或者 html 错误页面。
• 文档损坏。DOCX 本质是 ZIP unzip test.docx，如果解压失败 End-of-central-directory signature not found 说明文件已损坏。ONLYOFFICE 可能退化为文本解析。