> ## 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.

# 疑難排解

> 在 macOS 上以 Docker Desktop 執行 Ayakaleaf Pro 時遇到的問題，以及如何檢查。

### 初始化失敗並顯示 invalid command code

當 `bin/init` 找到的是 macOS 的 BSD sed 時，會回報 `sed: ... invalid command code`。請依照 [1. 下載 Toolkit](https://ayakaleaf-pro.mintlify.site/zh-TW/on-premises/installation/using-docker-compose/macos/1.-download-the-toolkit.md) 將 GNU sed 加入 `PATH`，並檢查 `sed --version`。

失敗的初始化可能會在 `config/` 中留下三個檔案，且其中的 `OVERLEAF_INVITE_TOKEN_SECRET` 為空值。之後再次執行 `bin/init` 會回報 `Config files already exist`。對於從未啟動過的新安裝，請將這三個檔案移到備份目錄，然後再次執行 `bin/init`。對於既有的執行個體，請保留其設定與機密，不要為了讓 `bin/init` 再次執行而刪除其檔案。

### MongoDB 不斷重新啟動

讀取 MongoDB 記錄與 Docker VM 的核心版本：

```bash theme={null}
bin/docker-compose logs --tail=100 mongo
docker info --format '{{.KernelVersion}}'
```

若記錄中提到 Linux 核心不相容問題，請依照[檢查 Docker VM 的 Linux 核心](https://ayakaleaf-pro.mintlify.site/zh-TW/on-premises/installation/using-docker-compose/macos/5.-personalizing-your-instance.md#check-the-docker-vms-linux-kernel)操作，然後再次執行 `bin/up -d`。單憑結束代碼 `137` 並不能證明 MongoDB 記憶體不足：請檢查容器狀態與記錄。關於 Docker Desktop 上較舊的 MongoDB 問題，另請參閱[疑難排解](https://ayakaleaf-pro.mintlify.site/zh-TW/on-premises/support/troubleshooting.md)。

### 無法連線至 Docker daemon

啟動 Docker Desktop 並檢查所選的 Docker context，請參閱 [0. 設定 Docker Desktop](https://ayakaleaf-pro.mintlify.site/zh-TW/on-premises/installation/using-docker-compose/macos/0.-setup-docker-desktop.md)。若 `docker info` 可以運作，但編譯無法連上 Docker，請檢查 `config/overleaf.rc` 中的 socket 設定，並讀取 `clsi` 記錄。Mac 上的 Docker CLI 能正常運作，並不代表應用程式的 socket 掛載是正確的。

### 頁面可以開啟，但編譯失敗

檢查 TeX Live 映像檔是否存在於本機，且與 Docker 引擎的架構相符：

```bash theme={null}
docker image inspect ghcr.io/ayaka-notes/texlive-full:2026.1 \
  --format '{{.Os}}/{{.Architecture}}'
bin/logs -f clsi
```

在 Apple silicon 上，映像檔應為 `linux/arm64`。請檢查 `SERVER_PRO` 與 `SIBLING_CONTAINERS_ENABLED` 是否都為 `true`，然後使用 `bin/up -d` 套用變更。若記錄回報缺少編譯目錄，請檢查 Docker Desktop 的檔案共用與 `OVERLEAF_DATA_PATH` 的位置。請勿為了掩蓋掛載失敗而關閉沙箱編譯。

### Not a directory，或缺少 bind mount

覆寫設定所掛載的主機檔案可能已被刪除，或者 Docker 可能在該檔案應存在的位置建立了一個目錄。請檢查主機上的來源路徑，以及該掛載預期的是檔案還是目錄。在重新建立容器之前，請先還原設定檔。安裝在 `/tmp` 底下的執行個體，可能會在 macOS 移除暫存檔案後遇到此問題。

### 連接埠或容器名稱衝突

若連接埠 `8080` 已被使用，請在 `config/overleaf.rc` 中選擇其他連接埠，將 `OVERLEAF_SITE_URL` 設為相符的值，然後再次執行 `bin/up -d`。

Toolkit 會為其容器指定固定名稱，例如 `sharelatex`、`mongo` 與 `redis`。僅變更 `PROJECT_NAME` 並不能讓兩個 Toolkit 安裝彼此獨立。啟動第二個執行個體之前，請檢查 `docker ps -a`，並在 Compose 覆寫設定中使用其他容器名稱、其他連接埠以及獨立的資料目錄。請勿為了解決名稱衝突而移除既有部署的容器或資料。

### 執行個體在一段時間後無法連線

Mac 可能進入了睡眠，或 Docker Desktop 已被結束。請參閱[保持執行個體可用](https://ayakaleaf-pro.mintlify.site/zh-TW/on-premises/installation/using-docker-compose/macos/6.-post-installation-tasks.md#keep-the-instance-available)。

### `bin/doctor` 表示這不是 Linux，或要求登入 Quay

在 macOS 上使用公開映像檔時，這兩個警告都是預期中的，請參閱 [2. 熟悉 Toolkit](https://ayakaleaf-pro.mintlify.site/zh-TW/on-premises/installation/using-docker-compose/macos/2.-familiarize-yourself-with-the-toolkit.md)。請改為檢查映像檔拉取、服務狀態與編譯結果，且不要忽略報告中的其他錯誤。


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