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

# 문제 해결

> WSL 2에서 Docker Desktop 통합, MongoDB 시작, Windows localhost 접근, Sandboxed Compiles 문제를 진단합니다.

**PowerShell**로 표시되지 않은 한 Toolkit 및 Docker 명령은 **Ubuntu**에서 실행하세요. 실패를 진단하는 동안 구성과 데이터를 유지하세요.

### WSL 또는 Docker에서 가상화를 사용할 수 없다고 보고합니다

WSL 2 백엔드에는 하드웨어 가상화와 **Virtual Machine Platform**이 필요하며, Docker의 대체 Hyper-V 백엔드에서 사용하는 전체 Hyper-V 기능은 필요하지 않습니다. 다음 확인부터 시작하세요.

1. Windows **작업 관리자 → 성능 → CPU**에서 **가상화: 사용**인지 확인하세요. 비활성화되어 있다면 PC 제조업체의 안내에 따라 BIOS/UEFI에서 Intel VT-x/VMX 또는 AMD-V/SVM을 활성화하세요.
2. **관리자 권한 PowerShell**에서 Windows 기능을 확인하세요.

```powershell theme={null}
Get-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform
Get-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux
```

필요한 기능이 비활성화되어 있다면 활성화하고 Windows를 다시 시작한 후 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. 기능과 BIOS 설정이 활성화되어 있는데도 `0x80370102` 오류가 계속되면 **관리자 권한 PowerShell**에서 확인하세요.

```powershell theme={null}
bcdedit /enum | findstr -i hypervisorlaunchtype
```

명시적으로 `Off`로 표시되면 하이퍼바이저 시작을 복원하고 Windows를 다시 시작하세요.

```powershell theme={null}
bcdedit /set hypervisorlaunchtype auto
```

4. Windows 자체가 VM에서 실행 중이라면 외부 하이퍼바이저가 **중첩 가상화**를 노출해야 합니다. Windows 확인란을 켜는 것만으로는 누락된 가상 CPU 기능을 제공할 수 없습니다.

해당 오류에 맞는 [Microsoft의 WSL 오류 0x80370102 복구 가이드](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)와 [Docker의 가상화 문제 해결](https://docs.docker.com/desktop/troubleshoot-and-support/troubleshoot/topics/#docker-desktop-fails-due-to-virtualization-not-working)을 따르세요. 이러한 복구 작업은 Windows 기능이나 부팅 구성을 변경하므로, 진단 결과와 관련된 작업만 실행하세요.

### Docker Desktop에 업데이트가 필요하거나 이미지를 가져올 수 없습니다

**WSL update required**가 표시되면 PowerShell에서 `wsl --update`를 실행하고, 요청이 있으면 Windows를 다시 시작한 다음 Docker Desktop과 Ubuntu를 다시 여세요. Ubuntu 행이 여전히 WSL 1로 표시되면 0단계에 설명된 대로 배포판을 변환하세요.

레지스트리 시간 초과, DNS, 프록시 또는 인증서 오류의 경우 pull 출력에서 정확히 어떤 레지스트리가 실패하는지 확인하세요. 네트워크에 필요하다면 Windows/Docker Desktop 프록시와 인증서 신뢰를 구성하고, TLS 검증을 비활성화하지 마세요. GitHub 복제가 성공했다고 해서 Docker가 `ghcr.io`나 Docker Hub에 접근할 수 있다는 것이 증명되지는 않습니다. [Docker Desktop 프록시 설정](https://docs.docker.com/desktop/settings-and-maintenance/settings/#proxies)을 참조하세요. 연결이 정상화되면 `bin/up -d`를 다시 실행하세요. 구성된 이미지 이름은 일관되게 유지해야 합니다.

### Ubuntu에서 Docker를 사용할 수 없습니다

`docker`를 찾을 수 없다면 Windows에서 Docker Desktop을 열고 **Settings → Resources → WSL Integration**에서 Ubuntu를 활성화한 다음, 변경 사항을 적용하고 Ubuntu를 다시 여세요. **PowerShell**에서 `wsl --list --verbose`로 배포판 이름과 WSL 모드를 확인하세요. WSL 2를 사용해야 합니다.

클라이언트는 있지만 데몬에 접근할 수 없다면 엔진이 시작을 마쳤는지 확인하세요. `docker context ls`와 사용자 지정 `DOCKER_HOST`/`DOCKER_CONTEXT` 설정을 확인하세요. 원격 엔진이나 이전 Ubuntu Engine 소켓은 이 가이드의 로컬 Desktop 설정이 아닙니다. 다른 데몬을 설치하거나 소켓을 누구나 쓸 수 있게 만드는 방식으로 해결하지 마세요.

### MongoDB가 시작되지 않습니다

`bin/up`은 애플리케이션을 시작하기 전에 MongoDB 복제본 세트를 초기화합니다. `Waiting for Mongo...`에서 멈추면 두 번째 **Ubuntu** 터미널에서 데이터베이스를 확인하세요.

```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}}'
```

`mongo`가 없고 출력에 이미지 pull 오류가 표시되면 먼저 레지스트리 접근이나 디스크 공간 문제를 해결하세요. 아직 데이터베이스 시작 단계에 도달하지 않은 것입니다. 원인을 해결한 후 `bin/up -d`를 다시 실행하세요.

| 증상 | 확인할 사항 |
| - | - |
| `OOMKilled=true` | WSL/Docker에서 사용할 수 있는 메모리를 늘리거나 다른 워크로드를 줄인 다음 다시 시도하세요 |
| `No space left on device` | Windows 호스트 저장 공간, Ubuntu의 `df -h`, Docker의 디스크 사용량을 확인하세요. 실제 데이터베이스 데이터를 삭제하지 않고 공간을 확보하세요 |
| `/data/db` 아래의 권한 또는 스토리지 오류 | `MONGO_DATA_PATH`를 Ubuntu의 Linux 파일 시스템에 두세요. 실제 바인드 마운트와 소유권을 확인하고, `chmod -R 777`을 적용하지 마세요 |
| Illegal instruction / CPU 기능 오류 | CPU와 가상화가 사용 중인 MongoDB 버전에 필요한 기능을 노출하는지 확인하세요. 포트를 변경해도 해결되지 않습니다 |
| 기존 데이터의 데이터베이스 형식 / 업그레이드 오류 | 지원되는 [업그레이드 절차](https://ayakaleaf-pro.mintlify.site/ko/on-premises/maintenance/upgrading-your-deployment.md)를 따르세요. 임의의 이전 MongoDB 이미지를 최신 데이터에 연결하지 마세요 |

MongoDB가 실행 중이면 복제본 세트를 확인하세요.

```bash theme={null}
bin/docker-compose exec -T mongo mongosh --quiet --eval 'rs.status().ok'
```

결과는 `1`이어야 합니다. `bin/up -d`가 초기 복제본 세트 설정을 수행하며, 새 배포에서 Compose 서비스를 직접 시작하면 이 Toolkit 단계를 건너뛰게 됩니다.

Docker 엔진이 영향을 받는 커널을 사용하는 경우에만 MongoDB 커널 해결 방법을 적용하세요. MongoDB 로그에 커널 문제가 표시되면 엔진의 실제 커널을 [MongoDB의 프로덕션 노트](https://www.mongodb.com/docs/manual/administration/production-notes/)와 비교하고 필요에 따라 WSL/Docker를 업데이트하세요. 일반적인 시작 문제 해결 방법으로 `data/mongo`를 지우지 마세요.

### Windows에서 localhost를 열 수 없습니다

먼저 Ubuntu에서 테스트하세요.

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

그런 다음 **PowerShell**에서 테스트하세요.

```powershell theme={null}
curl.exe -I http://localhost:8080/launchpad
```

둘 다 실패하면 애플리케이션 로그와 포트 구성을 확인하세요. Windows에서만 실패한다면 포트 8080을 사용하는 다른 Windows 프로세스, 사용자 지정 WSL 네트워킹 설정, VPN/프록시 규칙 또는 보안 소프트웨어를 확인하세요. 방화벽을 전역적으로 비활성화하지 마세요. 포트를 변경했다면 `OVERLEAF_PORT`, `OVERLEAF_SITE_URL`, 브라우저 URL을 일치시킨 다음 `bin/up -d`를 실행해야 합니다.

### Sandboxed Compiles가 실패합니다

세 가지를 모두 확인하세요. 이미지가 이 Docker 엔진에 존재하는지, 애플리케이션이 엔진 소켓을 사용할 수 있는지, 형제 컨테이너가 컴파일 디렉터리를 마운트할 수 있는지 확인합니다.

```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
```

`config/variables.env`에 구성된 이미지를 사용하세요. `SERVER_PRO=true`, `SIBLING_CONTAINERS_ENABLED=true`, `DOCKER_SOCKET_PATH=/var/run/docker.sock`은 `config/overleaf.rc`에 들어갑니다. 수정한 후에는 `bin/up -d`를 실행하세요. `bin/start`만으로는 컨테이너 환경이 업데이트되지 않습니다.

`No such image` 오류는 Docker가 해당 프로젝트에서 요청한 정확한 이미지를 찾을 수 없다는 뜻입니다. `TEX_LIVE_DOCKER_IMAGE`와 `ALL_TEX_LIVE_DOCKER_IMAGES`를 일관되게 유지하고, 같은 엔진에서 이미지를 가져오고, 프로젝트의 TeX Live 선택을 확인하세요. 기존 프로젝트는 이전 이미지 선택을 유지하고 있을 수 있습니다.

마운트 오류나 빈 `/compile` 디렉터리의 경우 Toolkit이 Ubuntu의 홈 디렉터리 아래에 있고, 같은 배포판에 대해 Docker Desktop의 통합이 활성화되어 있는지 확인하세요. WSL 호스트 경로를 Windows `C:\...` 경로로 바꾸지 마세요. Toolkit은 `OVERLEAF_DATA_PATH`에서 형제 컨테이너 경로를 계산합니다.

**basic**에서 `ctexart.cls`나 글꼴이 없는 것은 패키지/이미지의 한계입니다. 먼저 [6단계](https://ayakaleaf-pro.mintlify.site/ko/on-premises/installation/using-docker-compose/windows/6.-post-installation-tasks.md)의 일반 article을 확인하고, 추가 패키지가 필요한 프로젝트에는 더 완전한 이미지를 사용하세요. 누락된 TeX 패키지를 해결하기 위해 샌드박스를 비활성화하지 마세요.

### 셸 스크립트에서 CRLF 오류가 발생합니다

스크립트는 Ubuntu Bash에서 실행하세요. 구성은 LF 줄 끝으로 수정하세요. `bash\r`이나 `$'\r'`이 언급된 오류는 보통 파일이 Windows CRLF로 변환되었다는 뜻입니다. 로컬 구성 변경 사항은 유지하면서 해당 스크립트를 저장소에서 복원하거나 줄 끝을 변환하세요.

### 재시작 후 컨테이너가 사라집니다

Docker Desktop이 실행 중이고 Ubuntu 통합이 활성화되어 있는지 확인하세요. `docker ps`는 실행 중인 컨테이너만 표시하므로 `docker ps -a`도 확인하세요. 엔진이 설정 시 사용한 것과 다르다면 비어 있는 새 설치를 초기화하지 말고 올바른 컨텍스트로 다시 전환하세요.

컨테이너는 있지만 중지되어 있다면 `bin/start`를 실행하고 로그를 확인하세요. 로그인 시 시작, 재시작 정책, Windows 절전 설정은 [인스턴스 가용성 유지](https://ayakaleaf-pro.mintlify.site/ko/on-premises/installation/using-docker-compose/windows/6.-post-installation-tasks.md#keep-the-instance-available)를 따르세요.


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