WSL(Linux용 Windows 하위 시스템) 통합¶

WSL을 사용하면 Windows에서 직접 전체 Linux 환경을 실행할 수 있습니다. 일단 설정되면 STT 셸 통합은 Linux Bash 또는 Zsh 가이드와 동일하게 작동합니다. 즉, 셸 기능 자체에 Windows별 적응이 필요하지 않습니다.

권장 대상: Linux 터미널에 익숙하거나 개발 작업을 위해 이미 WSL을 설치한 Windows 사용자. WSL은 가장 충실한 환경과 최소한의 호환성 손상을 제공합니다.

전제 조건¶

WSL 설치(일회성 설정)¶

PowerShell 또는 CMD를 관리자 권한으로 열고 다음을 실행합니다.

wsl --install

기본적으로 Ubuntu와 함께 WSL2를 설치합니다. 메시지가 나타나면 컴퓨터를 다시 시작하세요.

특정 배포판을 설치하려면:

wsl --install -d Ubuntu-24.04
# or
wsl --install -d Debian

사용 가능한 모든 배포판을 나열합니다.

wsl --list --online

WSL 버전 확인¶

wsl --list --verbose

‘VERSION’ 열에 ‘2’가 표시되는지 확인하세요. ‘1’이 표시되면 다음을 사용하여 업그레이드하세요.

wsl --set-version <DistroName> 2

WSL 내부의 셸 통합¶

WSL이 실행되면 Linux 터미널을 열고 원하는 셸에 대한 Linux 셸 가이드를 따르세요.

쉘	가이드
Bash(WSL 기본값)	bash-integration.md
Zsh	zsh-integration.md
물고기	fish-integration.md
크쉬	ksh-integration.md
POSIX sh / 대시	posix-sh-integration.md

Bash를 사용한 기본 Ubuntu/Debian WSL 설정의 경우 빠른 경로는 다음과 같습니다.

nano ~/.bashrc
# Paste the function block from bash-integration.md
source ~/.bashrc

WSL 관련 고려 사항¶

WSL에서 Windows 파일에 액세스¶

Windows 드라이브는 /mnt/에 마운트됩니다:

/mnt/c/   # → C:\
/mnt/d/   # → D:\

프로젝트가 Windows 파일 시스템(예: C:\Projects\stt)에 있는 경우 SL5NET_AURA_PROJECT_ROOT를 다음으로 설정하세요.

export SL5NET_AURA_PROJECT_ROOT="/mnt/c/Projects/stt"

이 줄을 ~/.bashrc(또는 쉘에 해당하는 항목) s() 함수 위에 추가하세요.

성능 팁: 최고의 I/O 성능을 위해서는 프로젝트 파일을 /mnt/c/...가 아닌 WSL 파일 시스템(예: ~/projects/stt)에 보관하세요. WSL과 Windows 간의 파일 시스템 간 액세스는 상당히 느립니다.

WSL 내부의 Python 가상 환경¶

WSL 내에서 표준 Linux 가상 환경을 만들고 사용합니다.

cd "$SL5NET_AURA_PROJECT_ROOT"
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

함수($SL5NET_AURA_PROJECT_ROOT/.venv/bin/python3)의 PY_EXEC 경로는 있는 그대로 올바르게 작동합니다.

Windows 터미널에서 `s` 실행¶

Windows Terminal는 Windows에서 WSL을 사용하는 데 권장되는 방법입니다. 각 WSL 배포에 대해 여러 탭, 창 및 프로필을 지원합니다. Microsoft Store에서 설치하거나 다음을 통해 설치하세요.

winget install Microsoft.WindowsTerminal

가장 원활한 환경을 위해 Windows 터미널 설정에서 WSL 배포를 기본 프로필로 설정하세요.

Docker 온디맨드(Linux)¶

시스템 리소스를 절약하려면 백그라운드에서 지속적으로 실행되는 대신 필요할 때만(예: Aura가 Trino 데이터베이스를 요청할 때) Docker가 시작되도록 구성할 수 있습니다.

지속적인 백그라운드 서비스를 비활성화하고 대신 “소켓 활성화”를 활성화하려면 다음 명령을 실행하십시오.

sudo systemctl disable docker.service
sudo systemctl enable docker.socket
sudo systemctl start docker.socket

업데이트가 안전하도록 만드세요(Linux Arch/Manjaro 사용자): 패키지 업데이트로 인해 소켓 구성이 재설정되는 경우가 있습니다. 이를 방지하려면 영구 로컬 재정의를 만드세요.

sudo systemctl edit docker.socket

다음 줄이 있고 주석 처리가 해제되었는지 확인한 후(# 제거) 저장하고 종료합니다.

[Install]
WantedBy=sockets.target

WSL 내부의 Docker 및 Kiwix¶

Kiwix 도우미 스크립트(kiwix-docker-start-if-not-running.sh)에는 Docker가 필요합니다. Windows용 Docker Desktop을 설치하고 WSL 2 통합을 활성화합니다.

Docker Desktop를 다운로드하고 설치합니다.
Docker Desktop → 설정 → 리소스 → WSL 통합에서 WSL 배포를 활성화합니다.
WSL 내부를 확인합니다.
```
docker --version
```

Windows에서 WSL`s` 함수 호출(선택 사항)¶

WSL 터미널을 열지 않고 Windows CMD 또는 PowerShell 창에서 s 바로 가기를 호출하려면 다음과 같이 래핑하면 됩니다.

# PowerShell wrapper
function s { wsl bash -i -c "s $args" }

:: CMD wrapper — save as s.bat on your PATH
@echo off
wsl bash -i -c "s %*"

-i 플래그는 대화형 셸을 로드하여 ~/.bashrc(및 s 함수)가 자동으로 제공되도록 합니다.

특징¶

완전한 Linux 호환성: 모든 Unix 도구(timeout, pgrep, mktemp, grep)는 기본적으로 작동하므로 해결 방법이 필요하지 않습니다.
동적 경로: 셸 구성에 설정된 SL5NET_AURA_PROJECT_ROOT 변수를 통해 프로젝트 루트를 자동으로 찾습니다.
자동 재시작: 백엔드가 다운되면 ‘start_service’ 및 로컬 Wikipedia 서비스를 실행하려고 시도합니다(Docker가 실행 중이어야 함).
스마트 타임아웃: 먼저 빠른 2초 응답을 시도한 다음 70초 심층 처리 모드로 돌아갑니다.