故障排除

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

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

如果日志中提到了 Linux 内核不兼容问题，请按照检查 Docker 虚拟机的 Linux 内核操作，然后再次运行 bin/up -d。仅凭退出代码 137 并不能证明 MongoDB 内存不足：请检查容器状态和日志。有关 Docker Desktop 上一个较早的 MongoDB 问题，另请参阅故障排除。

​

无法连接到 Docker 守护进程

启动 Docker Desktop 并检查所选的 Docker 上下文，请参阅 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 芯片上，镜像应为 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 已退出。请参阅保持实例可用。

​

bin/doctor 提示这不是 Linux，或要求登录 Quay

在 macOS 上使用公开镜像时，这两个警告都是正常的，请参阅 2. 熟悉 Toolkit。请改为检查镜像拉取、服务状态和编译结果，不要忽略报告中的其他错误。