> ## 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-CN/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 虚拟机的内核版本：

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

如果日志中提到了 Linux 内核不兼容问题，请按照[检查 Docker 虚拟机的 Linux 内核](https://ayakaleaf-pro.mintlify.site/zh-CN/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-CN/on-premises/support/troubleshooting.md)。

### 无法连接到 Docker 守护进程

启动 Docker Desktop 并检查所选的 Docker 上下文，请参阅 [0. 安装 Docker Desktop](https://ayakaleaf-pro.mintlify.site/zh-CN/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 芯片上，镜像应为 `linux/arm64`。检查 `SERVER_PRO` 和 `SIBLING_CONTAINERS_ENABLED` 是否都为 `true`，然后使用 `bin/up -d` 应用更改。如果日志报告缺少编译目录，请检查 Docker Desktop 的文件共享设置以及 `OVERLEAF_DATA_PATH` 的位置。不要通过关闭沙盒编译来掩盖挂载失败。

### Not a directory，或缺少绑定挂载

覆盖配置所挂载的主机文件可能已被删除，或者 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-CN/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-CN/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.