跳到主要内容

Linux 版 ONLYOFFICE 文档故障排除

联系支持团队之前：收集诊断信息​

如果您遇到的问题未在下文中提及，请在联系 ONLYOFFICE 支持团队之前收集以下信息：

  • 日志目录：/var/log/onlyoffice/documentserver/
  • 软件包版本：dpkg -l | grep onlyoffice（Debian/Ubuntu）或 rpm -qa | grep onlyoffice（CentOS）
  • 操作系统版本：cat /etc/os-release

编译问题​

问： 我克隆了代码，但只找到空文件夹，没有源代码。

答： 该存储库包含子模块。建议执行以下命令克隆存储库：

git clone --recursive https://github.com/ONLYOFFICE/DocumentServer.git

如果您使用以下命令克隆了存储库：

git clone https://github.com/ONLYOFFICE/DocumentServer.git

可以按以下方式更新子模块：

  1. 进入 DocumentServer 目录：

    cd DocumentServer

  2. 运行以下命令：

    git submodule update --init --recursive

使用问题​

问： 停止 ONLYOFFICE 文档时发生了数据丢失。如何防止数据丢失？

答： 由于运行机制的特点，ONLYOFFICE 文档只有在所有编辑过文档的用户都关闭该文档后才会保存它。为避免数据丢失，在应用程序更新、服务器重启等需要停止 ONLYOFFICE 文档的情况下，您必须强制断开 ONLYOFFICE 文档用户的连接。为此，请在安装了 ONLYOFFICE 文档的服务器上执行以下脚本：

sudo documentserver-prepare4shutdown.sh
备注

执行该脚本可能需要较长时间（最多 5 分钟），因为它会等待所有用户断开连接。

问： 我添加了自定义界面主题或更新了编辑器语言文件（更正了一些翻译），但服务器仍然显示以前的值，而不是正确的值。如何同时为所有用户重置缓存？

答： 请按照以下步骤重置缓存：

找到 /etc/nginx/includes/ds-docservice.conf 和 /etc/nginx/includes/ds-spellchecker.conf 文件。其中应有构建日期和时间值。将这些值更改为其他值（任何值都可以，但关键是所有位置的值必须相同），然后重启 NGINX：

sudo service nginx reload

缓存应已为所有服务器用户重置。

问： ONLYOFFICE 文档服务无法启动。我该怎么办？

答： 检查服务状态并查看任何错误输出：

sudo systemctl status ds-docservice
sudo systemctl status ds-converter

如果任一服务已停止，请尝试重启：

sudo systemctl restart ds-docservice

常见原因包括：

  • 内存不足（建议至少 4 GB 内存）。
  • 端口 80 已被其他应用程序占用。使用 sudo ss -tlnp | grep :80 找出冲突的进程并将其停止，或重新配置 ONLYOFFICE 文档以使用其他端口。
  • 查看日志以获取更具体的错误信息：/var/log/onlyoffice/documentserver/

问： 将 ONLYOFFICE 文档与我的平台集成后，JWT 身份验证失败。如何解决？

答： 确认 ONLYOFFICE 文档中配置的 JWT 密钥与平台连接器设置中配置的密钥完全一致。还要检查 JWT 标头名称是否一致（默认为 "Authorization"）。要查看当前密钥，请直接读取配置文件：

cat /etc/onlyoffice/documentserver/local.json

查找 services.CoAuthoring.secret.session.string 处的值。常见错误：

  • 密钥值的开头或结尾有空格。
  • 使用默认的随机密钥，而没有设置自定义密钥。

问： 文档转换失败（例如，打开 DOC、XLS 或 PPT 文件时显示错误）。我该怎么办？

答： 检查转换器日志中的错误：

cat /var/log/onlyoffice/documentserver/converter/out.log

常见原因包括磁盘空间不足和缺少字体。

问： ONLYOFFICE 文档占用大量内存。这正常吗？

答： 内存使用量随打开的文档数和并发用户数而增加。对于有几十个活跃用户的服务器，2–4 GB 的内存使用量是正常的。如果内存使用量异常高，请检查 /var/lib/onlyoffice/documentserver/App_Data/cache/files/forgotten/ 中是否有卡住或被遗忘的文档。

企业版和开发者版问题​

问： 我看到 "License expired"（许可证已过期）警告。我该怎么办？

答： 您的 license.lic 文件已过期。请联系 sales@onlyoffice.com 续订许可证。收到新文件后，替换数据目录中旧的 license.lic 文件并重启 ONLYOFFICE 文档。

问： 我无法访问管理面板。我该怎么办？

答： 如果您尚未设置管理面板，请按照管理面板设置指南进行操作。如果您忘记了管理员密码，请从 runtime.json 中删除 passwordHash 条目并重启，系统将生成新的引导代码。