疑難排解

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

​

初始化失敗並顯示 invalid command code

當 bin/init 找到的是 macOS 的 BSD sed 時，會回報 sed: ... invalid command code。請依照 1. 下載 Toolkit 將 GNU sed 加入 PATH，並檢查 sed --version。

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

​

MongoDB 不斷重新啟動

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

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

若記錄中提到 Linux 核心不相容問題，請依照檢查 Docker VM 的 Linux 核心操作，然後再次執行 bin/up -d。單憑結束代碼 137 並不能證明 MongoDB 記憶體不足：請檢查容器狀態與記錄。關於 Docker Desktop 上較舊的 MongoDB 問題，另請參閱疑難排解。

​

無法連線至 Docker daemon

啟動 Docker Desktop 並檢查所選的 Docker context，請參閱 0. 設定 Docker Desktop。若 docker info 可以運作，但編譯無法連上 Docker，請檢查 config/overleaf.rc 中的 socket 設定，並讀取 clsi 記錄。Mac 上的 Docker CLI 能正常運作，並不代表應用程式的 socket 掛載是正確的。

​

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

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

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 已被結束。請參閱保持執行個體可用。

​

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

在 macOS 上使用公開映像檔時，這兩個警告都是預期中的，請參閱 2. 熟悉 Toolkit。請改為檢查映像檔拉取、服務狀態與編譯結果，且不要忽略報告中的其他錯誤。