> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 故障排除

<Info>
  如果你使用的是较早的版本，请在路径名中使用 `sharelatex` 代替 `overleaf`。
</Info>

<Accordion title="在 NFS 文件系统上运行 Overleaf">
  在 Overleaf 容器中挂载 NFS 文件系统在技术上是可行的，但不推荐这样做，因为它可能导致各种性能错误。

  编译时常见的一个错误是：

  ```text theme={null}
  EBUSY: resource busy or locked, unlink '/var/lib/overleaf/data/compiles/62f3d57bef7cf9005c364e75-62f3d57bef7cf9005c364e7a/.nfs573663533034825247625441'
  ```

  我们尤其不建议将基于 NFS 的文件系统用于临时数据，例如存放编译数据的目录。对于以下目录，我们建议使用本地临时磁盘，最好是本地 SSD。

  对于基于 `docker-compose` 的部署，我们建议直接覆盖来自 NFS 的绑定挂载，这样可以避免修改应用中的路径。下面是一个 `docker-compose` 配置片段示例，其中使用了挂载在 `/scratch` 的临时磁盘：

  ```yaml title="docker-compose excerpt" theme={null}
  services:
    sharelatex:
      environment:
        SANDBOXED_COMPILES_HOST_DIR: /scratch/compiles/
      volumes:
        - nfs:/var/lib/overleaf/data
        - /scratch/cache/:/var/lib/overleaf/data/cache
        - /scratch/compiles/:/var/lib/overleaf/data/compiles
        - /scratch/output/:/var/lib/overleaf/data/output
        - /scratch/tmp/:/var/lib/overleaf/tmp
  ```

  更新后无需将任何现有文件从 NFS 迁移到新位置。LaTeX 编译器会在再次完整编译时重新创建所有文件。

  更多详情请参阅：[https://docs.overleaf.com/on-premises/support/troubleshooting#running-overleaf-with-an-nfs-filesystem](https://docs.overleaf.com/on-premises/support/troubleshooting#running-overleaf-with-an-nfs-filesystem)
</Accordion>

<Accordion title="在 Windows 或 macOS 上运行 Overleaf 导致 `mongo` 服务无法启动">
  如果你在 Windows 或 macOS 上运行 Overleaf，`mongo` 服务可能无法重新启动，并出现以下错误：

  ```text title="Example error" theme={null}
  Failed to start up WiredTiger under any compatibility version.
  Reason: 1: Operation not permitted
  ```

  为避免此错误，数据需要存储在卷（volume）中，而不是绑定挂载的目录中（更多详情请参阅 `mongo` 镜像文档：[https://github.com/docker-library/docs/blob/master/mongo/content.md#where-to-store-data](https://github.com/docker-library/docs/blob/master/mongo/content.md#where-to-store-data) ）。若要将数据存储在挂载到 MongoDB 和 Redis 容器内的 Docker 卷中，请将以下内容添加到 `config/docker-compose.override.yml`（如果该文件尚不存在，请创建它）：

  ```yaml title="config/docker-compose.override.yml" theme={null}
  volumes:
    mongo-data:
    redis-data:

  services:
    mongo:
      volumes:
        - mongo-data:/data/db

    redis:
      volumes:
        - redis-data:/data
  ```

  更多信息请参阅：[https://docs.overleaf.com/on-premises/support/troubleshooting#running-overleaf-on-windows-or-macos-results-in-the-mongoservice-not-starting](https://docs.overleaf.com/on-premises/support/troubleshooting#running-overleaf-on-windows-or-macos-results-in-the-mongoservice-not-starting)
</Accordion>

<Accordion title="升级到 Redis 6.2 后陷入重启循环">
  使用 `docker logs redis` 命令输出一份日志。

  如果你看到 `Fatal: Can't initialize Background Jobs` 这一行，完整输出大致如下：

  ```text title="Redis log example" theme={null}
  1:M 11 Feb 2024 15:19:22.609 # Server initialized
  1:M 11 Feb 2024 15:19:22.609 # Fatal: Can't initialize Background Jobs.
  1:C 11 Feb 2024 15:19:26.055 # oO0OoO0OoO0Oo Redis is starting oO0OoO0OoO0Oo
  ```

  这可能与当前使用的 Docker 版本有关。更新到 >= 20.10.10 的版本应该可以解决此问题。

  更多信息请参阅 Redis 上游 issue：[https://github.com/redis/redis/issues/12362](https://github.com/redis/redis/issues/12362)

  参考：[https://docs.overleaf.com/on-premises/support/troubleshooting#upgrading-to-redis-6.2-results-in-a-restart-loop](https://docs.overleaf.com/on-premises/support/troubleshooting#upgrading-to-redis-6.2-results-in-a-restart-loop)
</Accordion>

<Accordion title="模板库预览图/缩略图方向不正确">
  偶尔，Server Pro 生成的预览图/缩略图可能方向错误，需要手动干预进行纠正。这些图片存储在 `/var/lib/overleaf/data/template_files/`（>= 5.0.3）和 `/var/lib/sharelatex/data/template_files/`（更早版本）中。

  我们建议在进行任何更改之前备份此文件夹。

  你需要对每个受影响的模板执行以下步骤：

  查找模板 ID：进入你实例的模板库（/templates/all），打开一个受影响的模板，并从 URL 中复制其 ID（例如：[https://your-instance-url/templates/6645d346c224815e9460a695](https://your-instance-url/templates/6645d346c224815e9460a695) ）。运行纠正命令：在 Docker 宿主机上运行以下命令（将模板 ID 替换为你复制的 ID，并视情况更新路径）：docker exec sharelatex /bin/bash -c "mogrify -rotate 90 /var/lib/overleaf/data/template\_files/6645d346c224815e9460a695\_\*\{thumbnail,preview}"

  参考：[https://docs.overleaf.com/on-premises/support/troubleshooting#incorrect-orientation-of-template-gallery-preview-thumbnail-images](https://docs.overleaf.com/on-premises/support/troubleshooting#incorrect-orientation-of-template-gallery-preview-thumbnail-images)
</Accordion>

<Accordion title="请确认你已启用系统调用。对于 pdflatex，即 'pdflatex -shell-escape'。">
  由于所有编译都在同一个 `sharelatex` 容器中进行，Community Edition 默认禁用了 `\write18` 命令；这是更安全的默认设置。

  如果你希望为 pdflatex 启用它，请在项目根目录下创建一个 `latexmkrc` 文件，内容如下：

  ```perl title="latexmkrc" theme={null}
  $pdflatex = 'pdflatex --shell-escape';
  ```

  然后尝试重新编译。

  参考：[https://docs.overleaf.com/on-premises/support/troubleshooting#please-verify-that-you-have-enabled-system-calls.-for-pdflatex-this-is-pdflatex-shell-escape](https://docs.overleaf.com/on-premises/support/troubleshooting#please-verify-that-you-have-enabled-system-calls.-for-pdflatex-this-is-pdflatex-shell-escape)
</Accordion>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.