dockur/windowsDocker 컨테이너에서 KVM 가속, 자동 설치, 사용자 지정 가능한 리소스를 사용하여 Windows를 실행합니다. 여러 Windows 버전, USB 패스스루, macvlan 네트워킹을 지원합니다.
<h1 align="center">Windows<br />
<div align="center">
<a href="https://github.com/dockur/windows"><img src="https://raw.githubusercontent.com/dockur/windows/master/.github/logo.png" title="로고" style="max-width:100%;" width="96" /></a>
</div>
<div align="center">
[![Build]][build_url]
[![Version]][tag_url]
[![Size]][tag_url]
[![Package]][pkg_url]
[![Pulls]][hub_url]
</div></h1>
Docker 컨테이너 안의 Windows.
## 기능 ✨
- Docker 컨테이너 안에서 Windows 실행
- 자동 다운로드 및 무인 설치
- 최신 및 구형 Windows 버전 지원
- KVM 가속을 통한 네이티브에 가까운 성능
- CPU, 메모리 및 스토리지 할당 사용자 지정
- 메모리 벌루닝을 통한 동적 메모리 할당
- USB 패스스루 및 호스트 폴더 공유
- NAT, user-mode, macvlan 및 macvtap 네트워킹 지원
## 동영상 📺
[](https://www.youtube.com/watch?v=xhGYobuG508)
## 사용법 🐳
##### Docker Compose:
```yaml
services:
windows:
image: dockurr/windows
container_name: windows
environment:
VERSION: "11"
devices:
- /dev/kvm
- /dev/net/tun
cap_add:
- NET_ADMIN
ports:
- 8006:8006
- 3389:3389/tcp
- 3389:3389/udp
volumes:
- ./windows:/storage
restart: always
stop_grace_period: 2m
```
##### Docker CLI:
```bash
docker run -it --rm --name windows -e "VERSION=11" -p 8006:8006 --device=/dev/kvm --device=/dev/net/tun --cap-add NET_ADMIN -v "${PWD:-.}/windows:/storage" --stop-timeout 120 docker.io/dockurr/windows
```
##### Kubernetes:
```shell
kubectl apply -f https://raw.githubusercontent.com/dockur/windows/refs/heads/master/kubernetes.yml
```
##### GitHub Codespaces:
[](https://codespaces.new/dockur/windows)
##### 그래픽 설치 프로그램:
[](https://winboat.app)
## 요구 사항 ⚙️
- KVM을 지원하는 Linux 호스트의 Docker 또는 Podman.
- 중첩 가상화가 활성화된 Windows 11의 Docker Desktop 또는 Podman (Desktop).
- 최소 4GB의 사용 가능한 RAM.
- 최소 64GB의 여유 디스크 공간.
> [!NOTE]
> Linux, macOS 및 Windows 10용 Docker Desktop은 현재 컨테이너에 KVM 액세스를 제공하지 않으므로 지원되지 않습니다.
## FAQ 💬
### 어떻게 사용하나요?
아주 간단합니다! 다음 단계를 따르세요:
- 컨테이너를 시작하고 웹 브라우저에서 [8006 포트](http://127.0.0.1:8006/)에 연결하세요.
- 마법이 펼쳐지는 동안 편안히 기다리세요. 전체 설치가 완전 자동으로 진행됩니다.
- 바탕 화면이 보이면 Windows 설치가 사용할 준비가 된 것입니다.
새 머신을 즐기고 이 저장소에 스타를 꼭 남겨 주세요!
### Windows 버전을 선택하려면 어떻게 하나요?
기본적으로 Windows 11 Pro가 설치됩니다. 그러나 다운로드할 다른 Windows 버전을 지정하려면 compose 파일에 `VERSION` 환경 변수를 추가할 수 있습니다:
```yaml
environment:
VERSION: "10"
```
아래 값 중에서 선택하세요:
| **값** | **버전** | **크기** |
|---|---|---|
| `11` | Windows 11 Pro | 7.9 GB |
| `11l` | Windows 11 LTSC | 4.7 GB |
| `11e` | Windows 11 Enterprise | 6.6 GB |
||||
| `10` | Windows 10 Pro | 5.7 GB |
| `10l` | Windows 10 LTSC | 4.6 GB |
| `10e` | Windows 10 Enterprise | 5.2 GB |
||||
| `8e` | Windows 8.1 Enterprise | 3.7 GB |
| `7u` | Windows 7 Ultimate | 3.1 GB |
| `vu` | Windows Vista Ultimate | 3.0 GB |
| `xp` | Windows XP Professional | 0.6 GB |
| `2k` | Windows 2000 Professional | 0.4 GB |
||||
| `2025` | Windows Server 2025 | 7.6 GB |
| `2022` | Windows Server 2022 | 6.0 GB |
| `2019` | Windows Server 2019 | 5.3 GB |
| `2016` | Windows Server 2016 | 6.5 GB |
| `2012` | Windows Server 2012 | 4.3 GB |
| `2008` | Windows Server 2008 | 3.0 GB |
| `2003` | Windows Server 2003 | 0.6 GB |
> [!TIP]
> Windows ARM64 버전을 설치하려면 [dockur/windows-arm](https://github.com/dockur/windows-arm/)을 사용하세요.
### 스토리지 위치를 변경하려면 어떻게 하나요?
스토리지 위치를 변경하려면 compose 파일에 다음 바인드 마운트를 포함하세요:
```yaml
volumes:
- ./windows:/storage
```
예제 경로 `./windows`를 원하는 스토리지 폴더 또는 named volume으로 바꾸세요.
### 디스크 크기를 변경하려면 어떻게 하나요?
기본 크기 64GB를 확장하려면 compose 파일에 `DISK_SIZE` 설정을 추가하고 원하는 용량으로 설정하세요:
```yaml
environment:
DISK_SIZE: "256G"
```
> [!TIP]
> 이 설정은 데이터 손실 없이 기존 디스크를 더 큰 용량으로 조정하는 데에도 사용할 수 있습니다. 다만 추가된 디스크 공간이 할당되지 않음으로 표시되므로 이후에 [디스크 파티션을 수동으로 확장](https://learn.microsoft.com/en-us/windows-server/storage/disk-management/extend-a-basic-volume?tabs=disk-management)해야 합니다.
### 호스트와 파일을 공유하려면 어떻게 하나요?
설치가 끝나면 바탕 화면에 `Shared`라는 폴더가 생기며, 이 폴더를 사용해 호스트 머신과 파일을 교환할 수 있습니다.
이 용도로 호스트의 폴더를 선택하려면 compose 파일에 다음 바인드 마운트를 포함하세요:
```yaml
volumes:
- ./example:/shared
```
예제 경로 `./example`를 원하는 공유 폴더로 바꾸면 해당 폴더가 `Shared`로 표시됩니다.
### CPU 또는 RAM 용량을 어떻게 변경하나요?
기본적으로 Windows는 CPU 코어 2개와 4GB RAM을 사용할 수 있습니다.
이를 조정하려면 다음 환경 변수를 사용해 원하는 용량을 지정할 수 있습니다:
```yaml
environment:
RAM_SIZE: "8G"
CPU_CORES: "4"
```
### 사용자 이름과 암호를 어떻게 설정하나요?
기본적으로 `Docker`라는 사용자가 생성되며 암호는 `admin`입니다.
설치 중 다른 자격 증명을 설정하려면 compose 파일에서 구성할 수 있습니다:
```yaml
environment:
USERNAME: "bill"
PASSWORD: "gates"
```
### Windows 언어를 선택하려면 어떻게 하나요?
기본적으로 영어 버전의 Windows가 다운로드됩니다.
그러나 다운로드할 다른 언어를 지정하려면 compose 파일에 `LANGUAGE` 환경 변수를 추가할 수 있습니다:
```yaml
environment:
LANGUAGE: "French"
```
다음 중에서 선택할 수 있습니다: 🇦🇪 아랍어, 🇧🇬 불가리아어, 🇨🇳 중국어, 🇭🇷 크로아티아어, 🇨🇿 체코어, 🇩🇰 덴마크어, 🇳🇱 네덜란드어, 🇬🇧 영어, 🇪🇪 에스토니아어, 🇫🇮 핀란드어, 🇫🇷 프랑스어, 🇩🇪 독일어, 🇬🇷 그리스어, 🇮🇱 히브리어, 🇭🇺 헝가리어, 🇮🇹 이탈리아어, 🇯🇵 일본어, 🇰🇷 한국어, 🇱🇻 라트비아어, 🇱🇹 리투아니아어, 🇳🇴 노르웨이어, 🇵🇱 폴란드어, 🇵🇹 포르투갈어, 🇷🇴 루마니아어, 🇷🇺 러시아어, 🇷🇸 세르비아어, 🇸🇰 슬로바키아어, 🇸🇮 슬로베니아어, 🇪🇸 스페인어, 🇸🇪 스웨덴어, 🇹🇭 태국어, 🇹🇷 터키어, 🇺🇦 우크라이나어.
### 키보드 레이아웃을 선택하려면 어떻게 하나요?
선택한 언어의 기본값이 아닌 키보드 레이아웃이나 로캘을 설정하려면 다음과 같이 `KEYBOARD` 및 `REGION` 변수를 추가할 수 있습니다:
```yaml
environment:
REGION: "en-US"
KEYBOARD: "en-US"
```
### 사용자 지정 이미지를 설치하려면 어떻게 하나요?
지원되지 않는 ISO 이미지를 다운로드하려면 `VERSION` 환경 변수에 해당 URL을 지정하세요:
```yaml
environment:
VERSION: "https://example.com/win.iso"
```
또는 다운로드를 건너뛰고 대신 로컬 파일을 사용하려면 compose 파일에 다음과 같이 바인드하면 됩니다:
```yaml
volumes:
- ./example.iso:/custom.iso
```
예제 경로 `./example.iso`를 원하는 ISO 파일 이름으로 바꾸세요. 이 경우 `VERSION` 값은 무시됩니다.
### 설치 후 스크립트를 실행하려면 어떻게 하나요?
설치 후 자신의 스크립트를 실행하려면 `install.bat`이라는 파일을 만들고 필요한 추가 파일(예: 설치할 소프트웨어)과 함께 폴더에 넣으세요.
그런 다음 compose 파일에 해당 폴더를 다음과 같이 바인드하세요:
```yaml
volumes:
- ./example:/oem
```
예제 폴더 `./example`는 `C:\OEM`에 복사되며 해당 폴더 안의 `install.bat` 파일은 자동 설치의 마지막 단계에서 실행됩니다.
### 수동 설치를 수행하려면 어떻게 하나요?
가상 환경에서 Windows를 실행할 때 발생하는 일반적인 문제를 방지하기 위해 다양한 설정을 조정해 주는 자동 설치를 사용하는 것이 좋습니다.
그러나 (자기 책임 하에) 설치를 수동으로 수행하려면 compose 파일에 다음 환경 변수를 추가하세요:
```yaml
environment:
MANUAL: "Y"
```
### RDP로 연결하려면 어떻게 하나요?
웹 뷰어는 주로 설치 중에 사용하도록 설계되었습니다. RDP보다 응답성이 낮고 클립보드 공유와 같은 기능을 지원하지 않기 때문입니다.
따라서 더 나은 환경을 위해 사용자 이름 `Docker`와 암호 `admin`을 사용하여 모든 Microsoft 원격 데스크톱 클라이언트로 컨테이너의 IP에 연결할 수 있습니다.
Play 스토어에서 제공되는 [Android](https://play.google.com/store/apps/details?id=com.microsoft.rdc.androidx)용 RDP 클라이언트와 Apple Store의 [iOS](https://apps.apple.com/nl/app/microsoft-remote-desktop/id714464092?l=en-GB)용 RDP 클라이언트가 있습니다. Linux에서는 [FreeRDP](https://www.freerdp.com/)를 사용할 수 있고 Windows에서는 검색창에 `mstsc`를 입력하면 됩니다.
### 오디오를 활성화하려면 어떻게 하나요?
오디오는 RDP를 사용하지 않는 한 기본적으로 비활성화되어 있습니다. 브라우저로 스트리밍하려면 다음 환경 변수를 추가하세요:
```yaml
environment:
AUDIO: "Y"
```
그런 다음 웹 뷰어에서 **설정 → 고급** 아래의 **오디오**를 활성화하세요. 스트림은 이 옵션이 활성화된 동안에만 동작하므로 그 외에는 추가 대역폭을 사용하지 않습니다.
### 컨테이너에 개별 IP 주소를 할당하려면 어떻게 하나요?
기본적으로 컨테이너는 호스트와 IP 주소를 공유하는 브리지 네트워킹을 사용합니다.
컨테이너에 개별 IP 주소를 할당하려면 다음과 같이 macvlan 네트워크를 만들 수 있습니다:
```bash
docker network create -d macvlan \
--subnet=192.168.0.0/24 \
--gateway=192.168.0.1 \
--ip-range=192.168.0.100/28 \
-o parent=eth0 vlan
```
로컬 서브넷에 맞게 이 값을 반드시 수정하세요.
네트워크를 만든 후에는 compose 파일을 다음과 같이 변경하세요:
```yaml
services:
windows:
container_name: windows
..<snip>..
networks:
vlan:
ipv4_address: 192.168.0.100
networks:
vlan:
external: true
```
이 방법의 추가 이점은 기본적으로 모든 포트가 노출되므로 더 이상 포트 매핑을 수행할 필요가 없다는 것입니다.
> [!IMPORTANT]
> macvlan의 설계상 호스트와 컨테이너 간 통신이 허용되지 않으므로 이 IP 주소는 Docker 호스트에서 액세스할 수 없습니다. 이 문제가 우려된다면 [두 번째 macvlan](https://blog.oddbit.com/post/2018-03-12-using-docker-macvlan-networks/#host-access)을 생성하여 해결해야 합니다.
### Windows가 라우터에서 IP 주소를 받게 하려면 어떻게 하나요?
컨테이너를 [macvlan](#how-do-i-assign-an-individual-ip-address-to-the-container)으로 구성한 후에는 실제 PC처럼 라우터에서 IP를 요청하여 Windows를 홈 네트워크의 일부로 만들 수 있습니다.
컨테이너와 Windows가 별도의 IP 주소를 갖는 이 모드를 활성화하려면 compose 파일에 다음 줄을 추가하세요:
```yaml
environment:
DHCP: "Y"
devices:
- /dev/vhost-net
device_cgroup_rules:
- 'c *:* rwm'
```
### 디스크를 여러 개 추가하려면 어떻게 하나요?
추가 디스크를 만들려면 compose 파일을 다음과 같이 수정하세요:
```yaml
environment:
DISK2_SIZE: "32G"
DISK3_SIZE: "64G"
volumes:
- ./example2:/storage2
- ./example3:/storage3
```
### 디스크를 패스스루하려면 어떻게 하나요?
디스크 장치나 파티션을 compose 파일에 다음과 같이 추가하여 직접 패스스루할 수 있습니다:
```yaml
devices:
- /dev/sdb:/disk1
- /dev/sdc1:/disk2
```
주 드라이브로 사용하려면 `/disk1`을 사용하고(설치 중에 포맷됨), 보조 드라이브로 추가하려면 `/disk2` 이상을 사용하세요(이 드라이브는 변경되지 않습니다).
### USB 장치를 패스스루하려면 어떻게 하나요?
USB 장치를 패스스루하려면 먼저 `lsusb` 명령으로 공급업체 ID와 제품 ID를 확인한 후 compose 파일에 다음과 같이 추가하세요:
```yaml
environment:
ARGUMENTS: "-device usb-host,vendorid=0x1234,productid=0x1234"
devices:
- /dev/bus/usb
```
> [!WARNING]
> Windows 설치가 끝나기 전에 USB 대용량 저장 장치를 추가하면 설치가 실패할 수 있습니다. 더 심각한 경우 해당 드라이브가 시스템 디스크로 포맷되어 모든 데이터가 손실될 수 있습니다! 따라서 처음 컨테이너를 실행할 때는 항상 연결을 해제해 두세요.
### 이것들이 사용 가능한 모든 옵션인가요?
아니요. 지원되는 모든 설정에 대한 전체 개요는 [환경 변수](https://github.com/dockur/windows/blob/master/docs/environment.md) 페이지를 참조하세요.
### KVM을 사용할 수 있는지 확인하려면 어떻게 하나요?
먼저 플랫폼과 컨테이너 런타임이 위에 나열된 [요구 사항](#requirements-️)을 충족하는지 확인하세요.
Linux 호스트에서는 `cpu-checker`를 설치하고 실행하세요:
```bash
sudo apt install cpu-checker
sudo kvm-ok
```
정상적인 구성에서는 다음과 같이 표시됩니다:
```text
KVM acceleration can be used
```
KVM 장치가 존재하는지도 확인할 수 있습니다:
```bash
ls -l /dev/kvm
```
KVM을 사용할 수 없는 경우 다음 사항을 확인하세요:
- BIOS 또는 UEFI에서 하드웨어 가상화(`Intel VT-x` 또는 `AMD-V`)가 활성화되어 있는지 확인하세요.
- 호스트 자체가 가상 머신인 경우 중첩 가상화가 활성화되어 있는지 확인하세요.
- VPS 또는 클라우드 제공업체가 중첩 가상화를 지원하는지 확인하세요.
`kvm-ok`가 성공했지만 컨테이너가 여전히 KVM을 사용할 수 없다고 보고하는 경우, 권한 또는 장치 액세스 문제를 배제하기 위해 Compose 파일에 임시로 `privileged: true`를 추가할 수 있습니다.
### 컨테이너에서 macOS를 실행하려면 어떻게 하나요?
그 용도로 [dockur/macos](https://github.com/dockur/macos)를 사용할 수 있습니다. 자동 설치를 제외하고 동일한 기능을 많이 공유합니다.
### 컨테이너에서 Linux 데스크톱을 실행하려면 어떻게 하나요?
그 경우 [qemus/qemu](https://github.com/qemus/qemu)를 사용할 수 있습니다.
### 이 프로젝트는 합법인가요?
네, 이 프로젝트는 오픈소스 코드만 포함하며 Windows 자체를 배포하지 않습니다. 코드에서 찾을 수 있는 제품 키는 Microsoft가 평가 목적으로 게시한 일반 설치 키이며 유효한 정품 인증 라이선스가 아닙니다.
유효한 Windows 라이선스를 보유하고 사용이 Microsoft의 라이선스 조건을 준수하는지 확인할 책임은 사용자에게 있습니다.
## 스타 🌟
[](https://github.com/dockur/windows/stargazers)
## 면책 조항 ⚖️
*이 프로젝트에서 언급된 제품 이름, 로고, 브랜드 및 기타 상표는 해당 상표 소유자의 자산입니다. 이 프로젝트는 Microsoft Corporation과 제휴, 후원 또는 보증 관계가 아닙니다.*
[build_url]: https://github.com/dockur/windows/
[hub_url]: https://hub.docker.com/r/dockurr/windows/
[tag_url]: https://hub.docker.com/r/dockurr/windows/tags
[pkg_url]: https://github.com/dockur/windows/pkgs/container/windows
[Build]: https://github.com/dockur/windows/actions/workflows/build.yml/badge.svg
[Size]: https://img.shields.io/docker/image-size/dockurr/windows/latest?color=066da5&label=size
[Pulls]: https://img.shields.io/docker/pulls/dockurr/windows.svg?style=flat&label=pulls&logo=docker
[Version]: https://img.shields.io/docker/v/dockurr/windows/latest?arch=amd64&sort=semver&color=066da5
[Package]: https://img.shields.io/badge/dynamic/json?url=https://ipitio.github.io/backage/dockur/windows/windows.json&query=$.downloads&logo=github&style=flat&color=066da5&label=pulls