常见问题

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

开档时传递的文件地址是需要在容器内部下载并转换的，所以一定要保证地址在容器内可正常下载。

• 不能使用 127.0.0.1 或 localhost 一类的域名或地址，容器内会请求到自己内部
• 如果是使用了 https 协议的地址，一定要保证证书是正式的而不是自己颁发的，否则也可能失败

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

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

onlyoffice documentserver 默认开启了 jwt 认证，你如果执意开启，可参考官方文档 签名。如果非必要，建议按以下操作

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

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

授权不生效

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

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

如何部署 https

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

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

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

如何子目录部署

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

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

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

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

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

先来看基本的流程

• 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
• 此时需要在回调接口中下载最新的 output.docx 并覆盖原始文档 example.docx，以便下一轮编辑使用
• 注意下一轮重新打开并编辑需要使用不同的 key，如 key1 对应新的原始文档，否则会直接打开已经存在的缓存文件
• 以上缓存文件都保存在 /var/lib/onlyoffice/documentserver/App_Data 下，可自行验证

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

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

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