> For the complete documentation index, see [llms.txt](https://overleaf-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://overleaf-pro.ayaka.space/on-premises/zh-tw/zhi-yuan/troubleshooting.md).

# 疑難排解

{% hint style="info" %}
如果您使用的是較早版本，請使用 `sharelatex` 而不是 `Overleaf` 於路徑名稱中。
{% endhint %}

<details>

<summary>在 NFS 檔案系統上執行 Overleaf</summary>

在 Overleaf 容器中掛載 NFS 檔案系統在技術上是可行的，但不建議這麼做，且可能導致不同類型的效能錯誤。

一個編譯過程常見的錯誤是：

```
EBUSY: resource busy or locked, unlink '/var/lib/overleaf/data/compiles/62f3d57bef7cf9005c364e75-62f3d57bef7cf9005c364e7a/.nfs573663533034825247625441'
```

特別是我們不建議將 NFS 支援的檔案系統用於暫存資料，例如用於編譯資料的目錄。我們建議在下列目錄使用本機暫存磁碟，最好是本機 SSD。

適用於 `docker-compose` 為基礎的設定，我們建議直接覆寫來自 NFS 的 bind mount，這樣可避免變更應用程式中的路徑。以下是一個 `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 %}

為避免此錯誤，資料需要儲存在 volume 中，而不是 bind mounted 目錄中（詳見 `mongo` 映像文件說明以獲得更多詳細資訊：<https://github.com/docker-library/docs/blob/master/mongo/content.md#where-to-store-data）。要將資料儲存在掛載於> MongoDB 和 Redis 容器內的 Docker volumes 中，請將以下內容加入 `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` 命令輸出一份日誌副本。

如果您看到以下這一行 `Fatal: Can't initialize Background Jobs`，完整輸出大致如下：

{% code title="Redis 日誌範例" %}

```
1:M 11 Feb 2024 15:19:22.609 # 伺服器已初始化
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 替換為您複製的 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://overleaf-pro.ayaka.space/on-premises/zh-tw/zhi-yuan/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.