Docker on Windows: deploy, run, and un-break은(는) 무엇을 하나요?
이 스킬은 Windows 11 데스크탑(중국 본토 네트워크 환경)에서 Docker Compose 앱을 무인으로, 재부팅에도 살아남는 방식으로 배포하면서 얻은 고생 끝에 얻은 운영 지식입니다. 아래의 오류 메시지는 난해해 보이고 해결책은 직관적이지 않습니다. 그래서 기록해 둔 것입니다. 추측보다 이 기록을 우선 참조하세요. 각각의 해결법은 실제 디버깅 시간을 소모한 것들입니다.
여기에는 특정 앱에 국한된 내용은 없습니다. 실행 예시는 Python/FastAPI + pgvector 스택이었지만, 함정(Docker Desktop 소켓, 네트워크 차단, 자동 시작, PowerShell 인코딩)은 Windows의 모든 Dockerized 프로젝트에 적용됩니다.
먼저, 행동하기 전에 방향 잡기
어떤 참조 파일이 필요한지 결정하는 간단한 확인 항목입니다:
- Docker가 실행 중인가?
docker version(클라이언트+서버),docker compose ps. 서버 오류는 보통 Docker Desktop이 시작 중에 크래시 났음을 의미합니다 →crash-recovery.md. - WSL2 백엔드가 정상인가?
wsl -l -v— 배포판(예:docker-desktop)이Running상태여야 합니다. - 중국 본토 네트워크인가? Pull/다운로드가 타임아웃되거나 TLS 실패하면, 네트워크가 차단 중이라고 가정하고 재시도에 시간 낭비하지 말고
china-network.md로 이동하세요. - 아무도 안 볼 때 재부팅을 견뎌야 하나? 이것은 하나의 설정이 아니라 전체 체인입니다 →
unattended-operation.md.
증상 → 참조 문서
| 증상 | 참조 문서 |
|---|---|
Docker Desktop이 시작되지 않거나, 크래시 루프가 발생하거나, 로그에 Inference manager / Secrets Engine / listening on unix://… / the file cannot be accessed by the system / syntax is incorrect 메시지가 나타남 | references/crash-recovery.md |
docker pull이 EOF/TLS handshake timeout; 빌드 중 pip/apt 실패; wsl --install이 멈춤; winget 0x8a15000f; HuggingFace/모델 다운로드가 차단된 호스트로 302 리디렉션 | references/china-network.md |
| 사람 없이 재부팅 후 실행되어야 함 (자동 로그인, 자동 시작, 잠금 화면, 재시작 정책). 또는 "로그인했을 때는 작동했는데 부팅 후에는 안 됨" | references/unattended-operation.md |
.ps1 파일이 비ASCII 문자를 깨뜨리거나, Missing closing '}' 오류와 함께 죽거나, 자신의 프로세스를 종료시키거나, 모든 네이티브 명령이 무서운 빨간색 텍스트를 뿜어냄 | references/windows-scripting.md |
| 새 Windows 머신에 배포, DB 볼륨 복원, 또는 "코드를 편집했는데 컨테이너가 변경되지 않았어요" | references/deploy-workflow.md |
일반화 가능한 원칙 (참조 문서를 열지 않더라도 훑어보세요)
-
Docker Desktop의 최악의 Windows 오류는 설정 오류가 아니라 고아 AF_UNIX 소켓입니다. 강제 종료(크래시/강제 종료/전원 손실)는
%LOCALAPPDATA%\Docker\run\과%LOCALAPPDATA%\docker-secrets-engine\아래에 삭제할 수 없는 재분석 지점 소켓 파일을 남깁니다. Docker는 다음 시작 시 이를 제거하고 재생성하려고 시도하다가 크래시 루프에 빠집니다. 이 파일들을 삭제할 수 없습니다 (Remove-Item/.NETDelete모두 실패) — 하지만 상위 디렉터리 이름을 바꿀 수는 있습니다 (접근 오류를 우회하는 메타데이터 작업). 이름을 바꾸면 Docker가 깨끗하게 재구축됩니다.EnableInference/EnableDockerAI를 토글한다고 고쳐지지 않습니다.crash-recovery.md를 참조하세요. -
중국 본토 네트워크에서는 직접 연결보다 미러를 먼저 사용하세요. Docker Hub,
winget, 온라인wsl --install,deb.debian.org, HuggingFace 대형 가중치는 차단되거나 불안정합니다. 레지스트리 미러, Tsinghua pip/apt, 오프라인 WSL MSI, 모델 가중치용 ModelScope가 신뢰할 수 있는 경로입니다.desktop.docker.com과 GitHub 릴리스는 직접 연결됩니다.china-network.md를 참조하세요. -
Windows 자동 로그인 상태에서
HKCU\...\Run자동 시작 항목은 조용히 실행되지 않습니다. 대신 로그온 시 트리거되는 작업 스케줄러 작업을 사용하세요. 이것이 무인 설정에서 가장 큰 함정입니다.unattended-operation.md를 참조하세요. -
.ps1파일은 ASCII 문자만 사용하여 작성하세요. PowerShell 5.1은 BOM 없는 UTF-8 파일을 GBK로 읽습니다. 비ASCII 문자(예: 중국어 주석)는 중괄호 매칭을 망가뜨려 →Missing closing '}'오류가 발생하여 스크립트가 로그도 남기지 않고 즉시 종료됩니다. 스크립트는 순수 ASCII로 유지하고 로그는 영어로 남기세요.windows-scripting.md를 참조하세요. -
마운트된 코드 = 재시작, 재구축 불필요.
docker-compose.yml이 소스를 바인드 마운트하는 경우 (./:/app), 코드 수정은docker compose restart <서비스>만으로 적용됩니다. 이미지 재구축은 필요하지 않습니다. 종속성/Dockerfile이 변경될 때만 재구축하세요. 논리 변경 사항은 실제 스케줄이 실행되기 전에 임시로docker compose exec <서비스> python …으로 드라이런하여 검증하세요. 이렇게 하면 라이브 출력 채널에 스팸을 보내는 방식으로 테스트하는 일이 없습니다.deploy-workflow.md를 참조하세요. -
단일 쓰기 제약 조건을 존중하세요. 앱이 스케줄에 따라 외부 채널에 푸시하는 경우, 한 번에 하나의 머신만 스케줄러를 실행해야 합니다. 두 개의 복사본은 중복 전송을 의미합니다. 새 머신을 시작하기 전에 이전 머신을 내리세요 (
docker compose down). -
Claude는 조용히 관리자 권한을 얻을 수 없습니다. 상승 권한이 필요한 모든 시스템 변경 사항은 UAC 프롬프트를 통해 사람이 확인해야 합니다 (
Start-Process -Verb RunAs가 이를 트리거합니다). 이러한 단계는 명확하게 "需手动操作 / 수동 단계" 로 표시하세요. 운영자는 중국어를 사용하고 인프라가 가벼운 환경이므로, 단계별 안내와 함께 수동 조작 지점을 명확히 알려주는 것을 중요하게 생각합니다. 자동 권한 모드는ExecutionPolicy Bypass + 상승도 차단하므로 프롬프트를 우회하지 마세요.
이 스킬 확장 방법
새로운 명확하지 않은 Windows/Docker 오류가 해결되면, 해당 참조 파일에 추가하세요 (증상 → 근본 원인 → 실제로 작동한 정확한 해결책, 그리고 작동하지 않은 것). "작동하지 않은 것" 항목이 종종 가장 가치 있는 부분입니다. 다음 사람이 막다른 길을 다시 시도하는 것을 막아줍니다.