Khắc phục sự cố

Các vấn đề gặp phải khi chạy Ayakaleaf Pro bằng Docker Desktop trên macOS, và cách kiểm tra chúng.

​

Khởi tạo thất bại với lỗi invalid command code

bin/init báo sed: ... invalid command code khi nó gặp BSD sed của macOS. Hãy đưa GNU sed vào PATH như trong 1. Tải xuống Toolkit và kiểm tra sed --version.

Một lần khởi tạo thất bại có thể để lại cả ba tệp trong config/ với OVERLEAF_INVITE_TOKEN_SECRET trống. Khi chạy lại bin/init, nó sẽ báo Config files already exist. Đối với một bản cài đặt mới chưa từng khởi động, hãy di chuyển ba tệp đó vào một thư mục sao lưu và chạy lại bin/init. Đối với một phiên bản hiện có, hãy giữ cấu hình và các secret của nó, và không xóa các tệp của nó chỉ để bin/init chạy lại được.

​

MongoDB liên tục khởi động lại

Đọc log của MongoDB và phiên bản kernel của máy ảo Docker:

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

Nếu log đề cập đến sự không tương thích của kernel Linux, hãy làm theo Kiểm tra kernel Linux của máy ảo Docker và chạy lại bin/up -d. Chỉ riêng mã thoát 137 không chứng minh rằng MongoDB đã hết bộ nhớ: hãy kiểm tra trạng thái container và log. Đối với một vấn đề MongoDB cũ hơn trên Docker Desktop, xem thêm Khắc phục sự cố.

​

Không thể kết nối tới Docker daemon

Khởi động Docker Desktop và kiểm tra Docker context đang được chọn, xem 0. Cài đặt Docker Desktop. Nếu docker info hoạt động nhưng các lần biên dịch không thể kết nối tới Docker, hãy kiểm tra các thiết lập socket trong config/overleaf.rc và đọc log của clsi. Một Docker CLI hoạt động trên máy Mac không chứng minh rằng socket mount của ứng dụng là chính xác.

​

Trang mở được nhưng biên dịch thất bại

Kiểm tra rằng TeX Live image tồn tại cục bộ và khớp với kiến trúc của Docker engine:

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

Trên Apple silicon, image phải là linux/arm64. Kiểm tra rằng SERVER_PRO và SIBLING_CONTAINERS_ENABLED đều là true, sau đó áp dụng các thay đổi bằng bin/up -d. Nếu log báo thiếu thư mục biên dịch, hãy kiểm tra phần chia sẻ tệp của Docker Desktop và vị trí OVERLEAF_DATA_PATH. Không tắt sandboxed compiles để che giấu một lỗi mount.

​

Not a directory, hoặc thiếu một bind mount

Một tệp trên máy chủ host mà một override gắn vào có thể đã bị xóa, hoặc Docker có thể đã tạo một thư mục tại vị trí lẽ ra là tệp. Hãy kiểm tra đường dẫn nguồn trên máy chủ host, và xem mount đó cần một tệp hay một thư mục. Khôi phục tệp cấu hình trước khi bạn tạo lại container. Một bản cài đặt trong /tmp có thể gặp phải tình trạng này sau khi macOS xóa các tệp tạm thời.

​

Xung đột cổng hoặc tên container

Nếu cổng 8080 đang được sử dụng, hãy chọn một cổng khác trong config/overleaf.rc, đặt OVERLEAF_SITE_URL cho khớp và chạy lại bin/up -d.

Toolkit đặt cho các container của nó những tên cố định như sharelatex, mongo và redis. Chỉ thay đổi PROJECT_NAME không làm cho hai bản cài đặt Toolkit độc lập với nhau. Trước khi bạn khởi động một phiên bản thứ hai, hãy kiểm tra docker ps -a, và dùng các tên container khác trong một Compose override, một cổng khác và các thư mục dữ liệu riêng biệt. Không xóa các container hoặc dữ liệu của một bản triển khai hiện có để giải quyết xung đột tên.

​

Phiên bản không thể truy cập được sau một thời gian

Có thể máy Mac đã chuyển sang chế độ ngủ, hoặc Docker Desktop đã bị thoát. Xem Giữ cho phiên bản luôn khả dụng.

​

bin/doctor báo đây không phải Linux, hoặc yêu cầu đăng nhập Quay

Cả hai cảnh báo đều là điều bình thường trên macOS với image công khai, xem 2. Làm quen với Toolkit. Thay vào đó, hãy kiểm tra việc pull image, trạng thái dịch vụ và kết quả biên dịch, và không bỏ qua các lỗi khác trong báo cáo.