> ## 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.

# 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:

```powershell theme={null}
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:

```powershell theme={null}
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**:

```powershell theme={null}
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:

```powershell theme={null}
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](https://learn.microsoft.com/en-us/windows/wsl/troubleshooting#error-0x80370102-the-virtual-machine-could-not-be-started-because-a-required-feature-is-not-installed) và [hướng dẫn khắc phục sự cố ảo hóa của Docker](https://docs.docker.com/desktop/troubleshoot-and-support/troubleshoot/topics/#docker-desktop-fails-due-to-virtualization-not-working) 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](https://docs.docker.com/desktop/settings-and-maintenance/settings/#proxies). 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:

```bash theme={null}
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](https://ayakaleaf-pro.mintlify.site/vi/on-premises/maintenance/upgrading-your-deployment.md) đượ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:

```bash theme={null}
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](https://www.mongodb.com/docs/manual/administration/production-notes/) 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:

```bash theme={null}
bin/docker-compose ps
bin/docker-compose port sharelatex 80
curl -I http://localhost:8080/launchpad
```

Sau đó kiểm tra trong **PowerShell**:

```powershell theme={null}
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:

```bash theme={null}
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](https://ayakaleaf-pro.mintlify.site/vi/on-premises/installation/using-docker-compose/windows/6.-post-installation-tasks.md); 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](https://ayakaleaf-pro.mintlify.site/vi/on-premises/installation/using-docker-compose/windows/6.-post-installation-tasks.md#keep-the-instance-available) để biết về khởi động khi đăng nhập, restart policy và thiết lập chế độ ngủ của Windows.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.