Khắc phục sự cố

Chẩn đoán tích hợp Docker Desktop, khởi động MongoDB, truy cập localhost từ Windows và sandboxed compiles trên WSL 2.

Chạy các lệnh Toolkit và Docker trong Ubuntu trừ khi được đánh dấu PowerShell. Hãy giữ nguyên cấu hình và dữ liệu trong khi chẩn đoán lỗi.

​

WSL hoặc Docker báo rằng ảo hóa không khả dụng

Backend WSL 2 cần ảo hóa phần cứng và Virtual Machine Platform, chứ không phải tính năng Hyper-V đầy đủ được dùng bởi backend Hyper-V thay thế của Docker. Hãy bắt đầu với các bước kiểm tra sau:

1. Trong Task Manager → Performance → CPU của Windows, kiểm tra Virtualization: Enabled. Nếu bị tắt, hãy bật Intel VT-x/VMX hoặc AMD-V/SVM trong BIOS/UEFI theo hướng dẫn của nhà sản xuất máy tính.
2. Trong PowerShell với quyền quản trị viên, kiểm tra các tính năng của Windows:

Get-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform
Get-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux

Nếu các tính năng cần thiết bị tắt, hãy bật chúng và khởi động lại Windows trước khi thử lại WSL:

dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

3. Nếu các tính năng và thiết lập BIOS đã được bật nhưng lỗi 0x80370102 vẫn còn, hãy kiểm tra trong PowerShell với quyền quản trị viên:

bcdedit /enum | findstr -i hypervisorlaunchtype

Nếu nó báo rõ ràng là Off, hãy khôi phục việc khởi động hypervisor và khởi động lại Windows:

bcdedit /set hypervisorlaunchtype auto

4. Nếu chính Windows đang chạy trong một máy ảo, hypervisor bên ngoài phải cung cấp ảo hóa lồng nhau (nested virtualization). Chỉ bật một ô đánh dấu trong Windows không thể bổ sung các tính năng CPU ảo còn thiếu.

Hãy làm theo hướng dẫn sửa lỗi WSL 0x80370102 của Microsoft và hướng dẫn khắc phục sự cố ảo hóa của Docker cho lỗi tương ứng. Các cách sửa này thay đổi tính năng hoặc cấu hình khởi động của Windows; chỉ chạy những cách liên quan đến chẩn đoán của bạn.

​

Docker Desktop cần cập nhật hoặc không thể pull image

Với thông báo WSL update required, hãy chạy wsl --update trong PowerShell, khởi động lại Windows nếu được yêu cầu, sau đó mở lại Docker Desktop và Ubuntu. Nếu hàng Ubuntu vẫn hiển thị WSL 1, hãy chuyển đổi bản phân phối như mô tả ở bước 0.

Với các lỗi hết thời gian chờ registry, DNS, proxy hoặc chứng chỉ, hãy kiểm tra chính xác registry bị lỗi trong đầu ra của lệnh pull. Cấu hình proxy và tin cậy chứng chỉ cho Windows/Docker Desktop nếu mạng của bạn cần; không tắt xác minh TLS. Việc clone thành công từ GitHub không chứng minh rằng Docker có thể truy cập ghcr.io hoặc Docker Hub. Xem thiết lập proxy của Docker Desktop. Khi kết nối đã hoạt động, hãy chạy lại bin/up -d; các tên image đã cấu hình phải được giữ nhất quán.

​

Docker không khả dụng trong Ubuntu

Nếu không tìm thấy docker, hãy mở Docker Desktop trong Windows, bật Ubuntu trong Settings → Resources → WSL Integration, áp dụng thay đổi và mở lại Ubuntu. Kiểm tra tên và chế độ WSL của bản phân phối bằng wsl --list --verbose trong PowerShell. Nó phải dùng WSL 2.

Nếu client tồn tại nhưng không thể kết nối tới daemon, hãy kiểm tra rằng engine đã khởi động xong. Kiểm tra docker context ls và mọi thiết lập DOCKER_HOST/DOCKER_CONTEXT tùy chỉnh; một engine từ xa hoặc một socket Engine cũ trong Ubuntu không phải là thiết lập Desktop cục bộ của hướng dẫn này. Không khắc phục bằng cách cài đặt một daemon khác hoặc cho phép mọi người ghi vào socket.

​

MongoDB không khởi động được

bin/up khởi tạo replica set của MongoDB trước khi khởi động ứng dụng. Nếu nó dừng ở Waiting for Mongo..., hãy kiểm tra cơ sở dữ liệu trong một terminal Ubuntu thứ hai:

cd "$HOME/ayakaleaf-toolkit"
bin/docker-compose ps -a
bin/docker-compose logs --tail=150 mongo
docker inspect mongo --format 'Exit={{.State.ExitCode}} OOM={{.State.OOMKilled}} Error={{.State.Error}}'
docker info --format '{{.KernelVersion}}'

Nếu không có mongo và đầu ra hiển thị lỗi pull image, hãy giải quyết vấn đề truy cập registry hoặc dung lượng ổ đĩa trước; nó chưa đến bước khởi động cơ sở dữ liệu. Khi nguyên nhân đã được khắc phục, hãy chạy lại bin/up -d.

Dấu hiệu	Cần kiểm tra gì
OOMKilled=true	Tăng bộ nhớ khả dụng cho WSL/Docker hoặc giảm các workload khác, sau đó thử lại
No space left on device	Kiểm tra dung lượng lưu trữ của máy chủ Windows, df -h của Ubuntu và mức sử dụng ổ đĩa của Docker; giải phóng dung lượng mà không xóa dữ liệu cơ sở dữ liệu đang hoạt động
Lỗi quyền hoặc lỗi lưu trữ trong /data/db	Giữ MONGO_DATA_PATH trên hệ thống tệp Linux của Ubuntu. Kiểm tra bind mount thực tế và quyền sở hữu; không áp dụng chmod -R 777
Lỗi illegal instruction / tính năng CPU	Kiểm tra rằng CPU và lớp ảo hóa cung cấp các tính năng mà phiên bản MongoDB của bạn yêu cầu; thay đổi cổng sẽ không khắc phục được điều này
Lỗi định dạng cơ sở dữ liệu / nâng cấp với dữ liệu hiện có	Làm theo quy trình nâng cấp được hỗ trợ; không trỏ một image MongoDB cũ hơn bất kỳ vào dữ liệu mới hơn

Khi MongoDB đang chạy, hãy kiểm tra replica set:

bin/docker-compose exec -T mongo mongosh --quiet --eval 'rs.status().ok'

Kết quả phải là 1. bin/up -d thực hiện thiết lập replica set ban đầu; khởi động trực tiếp các dịch vụ Compose trên một bản triển khai mới sẽ bỏ qua bước đó của Toolkit.

Chỉ áp dụng cách khắc phục tạm thời về kernel cho MongoDB nếu Docker engine của bạn dùng một kernel bị ảnh hưởng. Nếu log của MongoDB cho thấy vấn đề về kernel, hãy so sánh kernel thực tế của engine với ghi chú production của MongoDB và cập nhật WSL/Docker cho phù hợp. Không bao giờ xóa data/mongo như một cách khắc phục chung cho lỗi khởi động.

​

Windows không mở được localhost

Trước tiên hãy kiểm tra trong Ubuntu:

bin/docker-compose ps
bin/docker-compose port sharelatex 80
curl -I http://localhost:8080/launchpad

Sau đó kiểm tra trong PowerShell:

curl.exe -I http://localhost:8080/launchpad

Nếu cả hai đều thất bại, hãy kiểm tra log của ứng dụng và cấu hình cổng. Nếu chỉ Windows thất bại, hãy kiểm tra xem có tiến trình Windows nào khác đang dùng cổng 8080 không, các thiết lập mạng WSL tùy chỉnh, quy tắc VPN/proxy hoặc phần mềm bảo mật. Không tắt tường lửa trên toàn hệ thống. Một cổng đã thay đổi cần có OVERLEAF_PORT, OVERLEAF_SITE_URL và URL trình duyệt tương ứng, sau đó chạy bin/up -d.

​

Sandboxed compiles thất bại

Hãy xác minh cả ba yếu tố: image tồn tại trong Docker engine này, ứng dụng có thể dùng socket của engine, và container anh em (sibling container) có thể gắn thư mục biên dịch:

docker image inspect ghcr.io/ayaka-notes/texlive-basic:2026.1 --format '{{.Architecture}} {{.Id}}'
docker inspect sharelatex --format '{{json .Mounts}}'
bin/logs -f clsi

Hãy dùng image đã được cấu hình trong config/variables.env. SERVER_PRO=true, SIBLING_CONTAINERS_ENABLED=true và DOCKER_SOCKET_PATH=/var/run/docker.sock thuộc về config/overleaf.rc. Sau khi chỉnh sửa, hãy chạy bin/up -d; chỉ riêng bin/start không cập nhật môi trường của container.

Lỗi No such image có nghĩa là Docker không thể tìm thấy chính xác image mà dự án đó yêu cầu. Hãy giữ TEX_LIVE_DOCKER_IMAGE và ALL_TEX_LIVE_DOCKER_IMAGES nhất quán, pull image trong cùng engine đó, và kiểm tra lựa chọn TeX Live của dự án. Các dự án hiện có có thể vẫn giữ lựa chọn image cũ hơn.

Với lỗi mount hoặc thư mục /compile trống, hãy xác nhận rằng Toolkit nằm trong thư mục home của Ubuntu và tích hợp của Docker Desktop được bật cho chính bản phân phối đó. Không thay thế đường dẫn host WSL bằng một đường dẫn Windows C:\.... Toolkit tính toán đường dẫn cho sibling container từ OVERLEAF_DATA_PATH.

Việc thiếu ctexart.cls hoặc phông chữ với image basic là giới hạn của gói/image. Trước tiên hãy xác minh bài viết đơn giản từ bước 6; dùng một image đầy đủ hơn cho các dự án cần thêm gói. Không tắt sandbox để khắc phục việc thiếu một gói TeX.

​

Các shell script báo lỗi CRLF

Hãy chạy các script trong Ubuntu Bash. Chỉnh sửa cấu hình với ký tự xuống dòng LF. Các lỗi đề cập đến bash\r hoặc $'\r' thường có nghĩa là các tệp đã bị chuyển sang CRLF của Windows. Hãy khôi phục script bị ảnh hưởng từ kho lưu trữ hoặc chuyển đổi ký tự xuống dòng của nó, đồng thời giữ lại các thay đổi cấu hình cục bộ.

​

Các container biến mất sau khi khởi động lại

Kiểm tra rằng Docker Desktop đang chạy và tích hợp Ubuntu đã được bật. docker ps chỉ hiển thị các container đang chạy; hãy kiểm tra cả docker ps -a. Nếu engine khác với engine đã dùng trong quá trình thiết lập, hãy chuyển về đúng context thay vì khởi tạo một bản cài đặt trống khác.

Với các container vẫn tồn tại nhưng đã dừng, hãy chạy bin/start và kiểm tra log. Làm theo Giữ cho phiên bản luôn khả dụng để biết về khởi động khi đăng nhập, restart policy và thiết lập chế độ ngủ của Windows.