> For the complete documentation index, see [llms.txt](https://ayakaleaf-pro.ayaka.space/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ayakaleaf-pro.ayaka.space/on-premises/zh-cn/zhi-chi/troubleshooting.md).

# 故障排除

{% 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:
    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
```

{% 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
volumes:
  mongo-data:
  redis-data:

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

  redis:
    volumes:
      - 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` 命令输出一份日志副本。

如果您看到以下行 `致命错误：无法初始化后台作业`，完整输出大致如下：

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

```
1:M 11 Feb 2024 15:19:22.609 # Server initialized
1:M 11 Feb 2024 15:19:22.609 # 致命错误：无法初始化后台作业。
1:C 11 Feb 2024 15:19:26.055 # oO0OoO0OoO0Oo Redis 正在启动 oO0OoO0OoO0Oo
```

{% endcode %}

这可能与当前使用的 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 替换为您复制的那个，并在适当时更新路径）：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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.