🚀 使用 Docker Compose 部署 Dockurr Windows（容器化 Windows 系统）

🚀 使用 Docker Compose 部署 dockurr/windows 容器

本文档将指导你如何使用 Docker Compose 部署 dockurr/windows 容器，实现在 Docker 中运行 Windows 系统。

📖 项目简介

dockurr/windows 是一个开源项目，它允许你在 Docker 容器中运行完整的 Windows 操作系统。

核心特性 ： * ISO 下载器：自动下载所需的 Windows 版本镜像。 * KVM 加速：利用内核虚拟机 (KVM) 提供良好的性能。 * 基于 Web 的查看器：通过浏览器 (端口 8006) 直接访问 Windows 界面，方便安装操作。 * RDP 支持：安装完成后，可使用 Microsoft 远程桌面 (端口 3389) 获得更佳体验（包含音频、剪贴板共享等功能）。 * 多版本支持：支持从 Windows XP 到 Windows 11，以及 Windows Server 多个版本。 * 资源自定义：可灵活配置 CPU 核心数、内存和磁盘大小。

⚙️ 部署前准备

环境要求
- 操作系统：推荐使用 Linux 发行版。该项目在 Linux 环境下兼容性最佳。
- Docker 与 Docker Compose：确保系统中已安装 Docker 和 Docker Compose。
检查 KVM 支持 此项目需要 KVM 加速。在终端执行以下命令来检查：

sudo apt install cpu-checker -y  # 安装检查工具（适用于基于 Debian/Ubuntu 的系统）
kvm-ok

如果输出包含 "KVM acceleration can be used" 则表示支持。

🔧 配置 Docker Compose

创建一个名为 docker-compose.yml 的文件。
将以下配置内容复制到文件中，你可以根据注释和实际需求进行调整。

services:
  windows:
    image: dockurr/windows  # 官方镜像，自动适配架构
    container_name: dockurr  # 容器名称，便于管理
    devices: # 必须挂载的硬件设备（KVM 虚拟化依赖）
      - /dev/kvm  # KVM 核心设备（缺失会导致无法启动）  # KVM 设备，用于加速
      - /dev/net/tun # KVM 核心设备（缺失会导致无法启动）
      - /dev/vhost-net  # 新增关键设备  # 虚拟网络优化设备
      #如何通过磁盘？可以通过将磁盘设备添加到你的 compose 文件中来直接传递磁盘设备：
      #- /dev/sda1:/disk1
      #- /dev/sdc:/disk2
    cap_add:  # 赋予容器必要权限（不可省略）
      - NET_ADMIN     # 添加网络管理权限
      - SYS_ADMIN   # 系统管理权限（访问硬件设备） # 新增必要权限
      - SYS_RESOURCE # 资源控制权限
    privileged: true  # 特权模式（必须启用，否则无法访问 KVM 设备）# 关键修复点：
    ports: # 端口映射（Web 控制台 + RDP）
      - 8006:8006  # Web 控制台：主机 8006 → 容器 8006
      - 3389:3389/tcp  # RDP 协议（TCP）：主机 3389 → 容器 3389
      - 3389:3389/udp  # RDP 协议（UDP，优化音频/视频）
    stop_grace_period: 1m  # 停止容器时等待 1 分钟（确保 Windows 正常关机）
    #restart: on-failure
    restart: always  # 容器退出后自动重启（避免意外关机）
    #user: root
    environment:  # 资源与系统配置（根据宿主机调整）
      #KVM: "N"
      #VERSION: "win11"   # 明确指定版本                      # 使用默认版本名
      #要下载无法从上述列表中选择的不受支持的 ISO 映像，请在环境变量中指定该 ISO 的 URL，例如：VERSION
      #VERSION: "11"  # 指定 Windows 版本，例如 "11" 代表 Win11 Pro, "10" 代表 Win10 Pro
      #VERSION: "http://winiso/XP.iso"
      MANUAL: "N"    # 是否手动安装（N=自动安装，Y=手动安装，新手推荐 N）    #"Y" 可以手动安装并格式化挂载盘
      CPU_CORES: "12"   # 分配 CPU 核心数（不超过宿主机核心数，如 4 核宿主机设为 2-4，默认情况下容器最多允许使用 2 个 CPU 内核和 4 GB RAM。）
      RAM_SIZE: "10G"  #5G  # 分配内存大小（不超过宿主机可用内存，如 16GB 宿主机设为 8G）
      DISK_SIZE: "65G"   # 系统盘大小（建议 ≥40GB，Win11 需 ≥60GB）
      LANGUAGE: "Chinese"  # 系统语言（中文，可选值见配置注释）  #"French"
      #您可以选择： 🇦🇪 阿拉伯语， 🇧🇬 保加利亚语， 🇨🇳 中文， 🇭🇷 克罗地亚语， 🇨🇿 捷克语， 🇩🇰 丹麦语， 🇳🇱 荷兰语， 🇬🇧 英语， 🇪🇪 爱沙尼亚语， 芬兰语， 🇫🇷 🇫🇮 法语， 🇩🇪 德语， 🇬🇷 希腊语， 🇮🇱 希伯来语， 🇭🇺 匈牙利语， 🇮🇹 意大利语， 🇯🇵 日语， 🇰🇷 韩语， 🇱🇻 拉脱维亚语， 🇱🇹 立陶宛语， 🇳🇴 挪威语， 🇵🇱 波兰语， 🇵🇹 葡萄牙语， 🇷🇴 罗马尼亚语， 🇷🇺 俄语， 🇷🇸 塞尔维亚语， 🇸🇰 斯洛伐克语、🇸🇮斯洛文尼亚语、🇪🇸西班牙语、🇸🇪瑞典语、🇹🇭泰语、🇹🇷土耳其语和🇺🇦乌克兰语。
      #MANUAL: "Y" 
      #如果您坚持手动执行安装 #最好坚持自动安装，因为它会调整各种设置以防止在虚拟环境中运行 Windows 时出现常见问题。
      #如何配置用户名和密码？
      #默认情况下，在安装过程中创建一个 called 用户，其口令为空。Docker
      #如果您想使用不同的凭证，可以在 compose 文件中更改它们：
      #USERNAME: "Docker"  # 自定义 Windows 用户名（默认 Docker）
      #PASSWORD: "YourPass123"     # 自定义 Windows 用户名（默认 Docker）

      #键盘布局？
      #REGION: "en-US"
      #KEYBOARD: "en-US"
#如何使用 RDP 进行连接？
#Web 查看器主要用于安装过程中，因为它的图像质量很低，并且没有音频或剪贴板。
#因此，为了获得更好的体验，您可以使用任何 Microsoft 远程桌面客户端连接到容器的 IP，使用用户名并将密码留空。Docker
      #如何添加多个磁盘？

      # 删除 DISK2_SIZE（首次启动勿用）
      #DISK2_PATH: "/data" #/dev/sda1
      #DISK2_FORMAT: "ntfs"

      # 额外磁盘2大小（可选，扩容后原数据会丢失，需谨慎），请确保'data2.img'的体积与此参数值是对称的容量。
      DISK2_SIZE: "90G" 
      DISK3_SIZE: "64G"  # 额外磁盘3大小（可选）

      #ARGUMENTS: "-m 4096 -smp 11"
      #ARGUMENTS: "-drive file=/mnt/d.img,format=raw,if=virtio"
      #ARGUMENTS: "-drive file=/mnt/d/d.img,format=raw,if=virtio"
      #ARGUMENTS: "-drive file=/storage/win.img,format=qcow2,if=virtio"

      # 增加安全配置：
      SECURE_BOOT: "off"   # 关闭安全启动（避免部分 ISO 安装失败）
      TPM: "off"           # 关闭 TPM（简化安装，Win11 推荐开启，但需宿主机支持）
      #PUID: 0
      #PGID: 0
      #SAMBA_SHARE: "1"
      #SAMBA_NAME: "DataShare"
      #SAMBA_PATH: "/data"
      #SAMBA_user: "docker"
      #SAMBA_PASSWORD: "227" #password
      #SAMBA_SECURE: "0"
      #SAMBA_BROADCAST: "1"
      #SAMBA_WORKGROUP: "WORKGROUP"
      #SAMBA_WIN_PROTOCOL: "NT1"

    volumes:  # 卷挂载（数据持久化核心）
      #- ./win/XP.iso:/custom.iso
      #- ./win/2025.iso:/custom.iso
      - ./win:/storage    # 系统镜像存储：主机 ./win → 容器 /storage（Windows 系统文件）
      #- ./d:/mnt/d                          # 映射宿主机 ./d 到容器 /mnt/d
      - "./iso/XPsp3x86.iso:/custom.iso"   # 自定义 ISO：挂载本地 XP 镜像（无需则删除此行）

      #您也可以跳过下载并使用本地文件，方法是通过以下方式将其绑定到 compose 文件中
      #- /home/user/example.iso:/custom.iso
      #安装后如何运行脚本？
      #要在安装后运行您自己的脚本，您可以创建一个名为 的文件，并将其与它需要的任何其他文件（例如要安装的软件）一起放在一个文件夹中。install.bat
      #然后在 compose 文件中绑定该文件夹，如下所示：
      #-  /home/user/example:/oem
      #如何添加多个磁盘？
      #- ./data:/data
      #- ./data_2:/data_2
      #-  ./example:/data
      -  /mnt/10t/file/1/D/Downloads:/data  # 共享目录：主机下载目录 → 容器 /data（Windows 可访问）

      - ./storage2:/storage2  # 额外磁盘2：主机 ./storage2 → 容器 /storage2
      - ./storage3:/storage3  # 额外磁盘3：主机 ./storage3 → 容器 /storage3

      ##- /mnt/data/example:/storage3
      #- /etc/passwd:/etc/passwd:ro
      #- /etc/group:/etc/group:ro


#ISO损坏时：
# 在宿主机验证ISO
#md5sum ./iso/Win11_24H2_English_x64.iso
# 正确值：b9d5b5f1a4e9eb4e9b8d0d5c5d5b5f1a  (示例)

关键配置说明：

privileged: true：此配置为容器提供了广泛的系统权限，对于需要访问特定硬件设备（如 KVM）的容器是必要的。
devices 与 cap_add：将 /dev/kvm 设备传递给容器并添加 NET_ADMIN 权限，是 Windows 容器正常运行的关键。
environment：
- VERSION：指定要安装的 Windows 版本。常见选项有 "11", "10", "xp", "2022" (Server) 等。
- LANGUAGE：设置系统语言。
- CPU_CORES, RAM_SIZE, DISK_SIZE：根据宿主机的资源情况合理分配。
volumes：
- ./win_storage:/storage：强烈建议进行此映射，它将容器内的 Windows 系统盘和数据持久化存储在宿主机上，避免容器删除后系统丢失。

关键配置说明（新手必看）

配置项	作用与注意事项
`devices: /dev/kvm`	核心依赖，缺失会提示 “KVM not found”，需重新安装 KVM 依赖并确认虚拟化开启。
`privileged: true`	必须启用，否则容器无权限访问硬件设备，启动后会立即退出。
`CPU_CORES`/`RAM_SIZE`	不可超过宿主机资源（如 4 核 CPU 设为 12 会导致宿主机卡死），建议设为宿主机的 50%-70%。
`DISK_SIZE`	系统盘大小需 ≥40GB（WinXP 可设 20GB，Win11 需 ≥60GB），不足会导致安装失败。
`./iso/XPsp3x86.iso:/custom.iso`	自定义 ISO 挂载，若无需安装 XP 可删除此行，容器会自动下载默认 Windows 镜像（约 5GB，需耐心等待）。
`volumes: ./win:/storage`	系统镜像存储目录，删除会丢失 Windows 系统数据，务必定期备份。

🚀 启动与验证

启动容器 在 docker-compose.yml 文件所在目录下，执行： bash docker compose up -d 容器会在后台启动，并开始下载 Windows 镜像（首次启动耗时较长，请耐心等待）。
验证安装
- 打开浏览器，访问 http://你的服务器IP:8006。
- 你将能看到 Windows 的安装界面。注意：此项目的安装过程通常是全自动的。你只需等待安装完成，直到在 Web 查看器中看到 Windows 桌面。
- 安装完成后，为了获得更好的体验（如音频、剪贴板共享），建议使用 Microsoft 远程桌面 (RDP) 客户端连接至服务器的 3389 端口。
监控启动进度（关键！） Windows 安装过程需 10-30 分钟（取决于网络速度和硬件性能），通过日志查看进度：

docker compose logs -f dockurr  # 实时查看日志，按 Ctrl+C 退出

关键进度提示：
1. Downloading Windows ISO：正在下载默认 ISO（约 5GB，耐心等待）；
2. Starting Windows installation：开始自动安装系统；
3. Windows is ready：安装完成，可开始访问。

🛠️ 基础配置与使用

如何选择其他 Windows 版本？ 修改 docker-compose.yml 文件中的 VERSION 环境变量即可。例如，要安装 Windows 10 LTSC，可设置为 VERSION: "10l" 。项目支持众多版本，具体可参考中的版本列表。
如何与宿主机共享文件？
1. 在 docker-compose.yml 的 volumes 部分添加一个绑定挂载，例如：

-  /home/your_username/shared_folder:/data

2.  在 Windows 容器内，打开文件资源管理器，访问网络位置 `\\host.lan\Data` 即可访问宿主机上的 `/home/your_username/shared_folder` 目录 。

如何调整硬件资源？ 直接修改 docker-compose.yml 中的 CPU_CORES、RAM_SIZE 和 DISK_SIZE 环境变量，然后执行 docker compose down 停止容器，再执行 docker compose up -d 重新启动以应用更改。

🛠️ 基础配置与使用2

1. 首次使用：系统初始化

设置密码：进入 Windows 后，右键点击「此电脑」→「管理」→「本地用户和组」→「用户」→ 右键 Docker →「设置密码」，设置强密码（避免空密码风险）。
调整分辨率：右键桌面 →「显示设置」，根据需求调整分辨率（RDP 支持最高 4K）。
安装驱动 / 软件：可通过共享目录 /data（对应宿主机 /mnt/10t/file/1/D/Downloads）复制安装包到 Windows，安装常用软件（如浏览器、办公软件）。

2. 挂载额外磁盘（配置中的 DISK2/DISK3）

配置中 DISK2_SIZE/DISK3_SIZE 对应的磁盘需在 Windows 中初始化后才能使用：

进入 Windows，打开「磁盘管理」（Win+R 输入 diskmgmt.msc）；
找到未分配的磁盘（大小与 DISK2_SIZE/DISK3_SIZE 一致），右键 →「新建简单卷」；
按向导完成分区（推荐 NTFS 格式），分配驱动器号（如 D:、E:），完成后即可在「此电脑」中看到新磁盘。

3. 使用自定义 ISO 安装（如 Windows XP）

若需安装非默认系统（如 XP），需确保 ./iso/XPsp3x86.iso 已放入目录，且配置中保留 ./iso/XPsp3x86.iso:/custom.iso 挂载：

启动容器后，通过 Web 控制台访问（http://IP:8006）；
系统会从自定义 ISO 启动，按提示完成 XP 安装（手动分区、输入序列号等）；
安装完成后，重启容器即可通过 RDP 访问 XP 系统。

🔄 维护与管理

查看容器日志 bash docker compose logs windows 此命令有助于在启动失败或出现问题时进行排查。
停止和删除容器 bash docker compose down 此命令会停止并删除容器。注意：如果你没有使用 volumes 映射 /storage 目录，所有数据（包括安装的 Windows 系统）将会丢失。
更新容器镜像 bash docker compose pull docker compose down docker compose up -d

❓ 常见问题排查

Q: 启动容器后，Web 界面无法访问。
- A: 首先检查容器状态是否为 Up：docker compose ps。然后检查宿主机防火墙是否放行了 8006 端口。最后查看容器日志 docker compose logs windows 寻找错误信息。
Q: 安装 Windows 时非常卡顿。
- A: 确保已正确挂载 /dev/kvm 并检查 kvm-ok 输出正常。此外，可以为容器分配更多的 CPU 核心和内存。
Q: 如何解决容器启动时的权限错误？
- A: 确保当前用户已加入 docker 用户组。同时，配置中的 privileged: true 和 cap_add 也是解决权限问题的关键。
Q: 在 WSL 中部署需要注意什么？
- A: 在 WSL 环境下，可能需要在 environment 中添加 BOOT_MODE: "windows_plain" 配置。

❓ 常见问题排查2

1. 容器启动失败，日志提示 “KVM device not found”

原因：KVM 依赖未安装或虚拟化未开启。
解决：
1. 重新安装 KVM 依赖（见 “部署前准备 - 步骤 3”）；
2. 进入 BIOS/UEFI，在 “CPU Configuration” 中启用 “Intel VT-x” 或 “AMD-V”；
3. 重启宿主机，重新执行启动命令。

2. RDP 无法连接（提示 “远程桌面无法连接”）

原因 1：3389 端口未开放或被占用。

解决：执行 netstat -tuln | grep 3389 查看端口占用，释放端口或修改配置中 ports 为空闲端口（如 3390:3389），重启容器。 - 原因 2：Windows 系统未启动完成。

解决：查看容器日志，确认出现 “Windows is ready” 后再尝试连接。 - 原因 3：用户名 / 密码错误。

解决：默认用户名 Docker，密码为空；若已修改密码，需输入正确密码。

3. 安装过程卡死（日志长时间无变化）

原因：资源不足（CPU / 内存分配过少）或 ISO 损坏。
解决：
1. 增加 CPU_CORES/RAM_SIZE（如 4 核 CPU 设为 2，8GB 内存设为 4G）；
2. 若使用自定义 ISO，验证 ISO 完整性（执行 md5sum ./iso/XPsp3x86.iso，对比官方 MD5 值，不一致则重新下载）。

4. 额外磁盘不显示（Windows 磁盘管理中无未分配空间）

原因：配置中 DISK2_SIZE/DISK3_SIZE 未生效，或卷挂载路径错误。
解决：
1. 确认 volumes 中 ./storage2:/storage2/./storage3:/storage3 路径正确；
2. 停止容器，删除 ./storage2/./storage3 目录，重新启动容器（会重新创建磁盘镜像）；
3. 进入 Windows 磁盘管理，查看是否出现未分配空间。

5. 宿主机卡顿（CPU / 内存占用过高）

原因：CPU_CORES/RAM_SIZE 分配超过宿主机承载能力。
解决：停止容器，修改配置中 CPU_CORES 为宿主机核心数的 50%（如 4 核设为 2），RAM_SIZE 为宿主机可用内存的 50%（如 16GB 设为 8G），重新启动。

通过以上步骤，新手可成功部署容器化 Windows 系统，实现轻量办公、软件测试等需求。需注意：Dockurr Windows 不适合运行对硬件要求高的软件（如大型游戏、视频剪辑工具），更适合轻量场景。如需更复杂的虚拟机功能，可参考 Dockurr Windows 官方文档。