# 故障排除

{% hint style="info" %}
如果您正在使用早期版本，请使用 `sharelatex` 而不是 `overleaf` 在路径名中。
{% endhint %}

<details>

<summary>在 NFS 文件系统上运行 Overleaf</summary>

在 Overleaf 容器中挂载 NFS 文件系统在技术上是可行的，但不推荐这样做，并且可能导致不同类型的性能错误。

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

```
EBUSY: 资源繁忙或被锁定，unlink '/var/lib/overleaf/data/compiles/62f3d57bef7cf9005c364e75-62f3d57bef7cf9005c364e7a/.nfs573663533034825247625441'
```

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

对于 `docker-compose` 为基础的部署，我们建议只覆盖来自 NFS 的绑定挂载，这样可以避免更改应用中的路径。下面是一个示例， `docker-compose` 配置片段，使用挂载在 `/scratch`:

{% code title="docker-compose 片段" %}

```yaml
services：
  sharelatex：
    环境：
      SANDBOXED_COMPILES_HOST_DIR: /scratch/compiles/
    卷：
      - 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
```

{% endcode %}

更新后无需将任何现有文件从 NFS 迁移到新位置。LaTeX 编译器可以通过完全重新编译来重新生成所有文件。

更多细节见： <https://docs.overleaf.com/on-premises/support/troubleshooting#running-overleaf-with-an-nfs-filesystem>

</details>

<details>

<summary>在 Windows 或 macOS 上运行 Overleaf 会导致 `mongo` 服务无法启动</summary>

如果您在 Windows 或 macOS 上运行 Overleaf， `mongo` 服务可能无法重新启动，出现以下错误：

{% code title="错误示例" %}

```
无法在任何兼容版本下启动 WiredTiger。
原因：1：不允许的操作
```

{% endcode %}

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

{% code title="config/docker-compose.override.yml" %}

```yaml
卷：
  mongo-data：
  redis-data：

services：
  mongo：
    卷：
      - mongo-data:/data/db

  redis：
    卷：
      - redis-data:/data
```

{% endcode %}

更多信息见： <https://docs.overleaf.com/on-premises/support/troubleshooting#running-overleaf-on-windows-or-macos-results-in-the-mongoservice-not-starting>

</details>

<details>

<summary>升级到 Redis 6.2 导致重启循环</summary>

使用 `docker logs redis` 命令输出日志副本。

如果您看到这一行 `Fatal: Can't initialize Background Jobs`，完整输出将类似于：

{% code title="Redis 日志示例" %}

```
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
```

{% endcode %}

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

更多信息见 Redis 上游问题： <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>

</details>

<details>

<summary>模板库预览/缩略图图像方向不正确</summary>

有时，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）。运行修正命令：在> 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>

</details>

<details>

<summary>请确认您已启用系统调用。对于 pdflatex，这是 'pdflatex -shell-escape'。</summary>

该 `\write18` 命令默认在 Community Edition 中被禁用，因为所有编译都在相同的 `sharelatex` 容器中进行；这是更安全的默认设置。

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

{% code title="latexmkrc" %}

```perl
$pdflatex = 'pdflatex --shell-escape';
```

{% endcode %}

然后尝试重新编译。

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

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://overleaf-pro.ayaka.space/on-premises/zh-cn/zhi-chi/troubleshooting.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.