企业官网建设流程全解析

在 Docker 容器中运行 Windows：基于 windows 项目的完整环境变量配置指南

【免费下载链接】windowsWindows inside a Docker container.项目地址: https://gitcode.com/GitHub_Trending/wi/windows

本文以 docs/environment.md 为骨架，完整解读 dockur/windows 项目暴露的全部环境变量，并结合 启动入口、版本解析逻辑、应答文件生成器 与 关机流程 等源码，说明每个变量的默认值来源、取值方式与底层消费路径，帮助你在部署容器时做到"改一个变量，知道它影响了什么"。读完本篇，你可以完整掌控 Windows 版本选择、CPU/内存/磁盘规格、网络模式、Web 界面、文件共享、启动固件与动态内存气球等全部可调维度。

环境变量总览：配置在启动管线中的位置

该容器把全部配置都收敛为环境变量，文档中说明：一个"Default 为空"的变量表示未设置，其值会在适用时自动确定。要理解这些变量如何生效，先看 入口脚本 的初始化管线：

. start.sh # 启动钩子 . utils.sh # 加载函数 . init.sh # 系统初始化 . memory.sh # 内存检查（消费 RAM_CHECK / RAM_SIZE） . server.sh # 启动 Web 服务（消费 WEB / WEB_PORT） . download.sh # 下载函数 . define.sh # 定义版本（消费 VERSION / EDITION / LANGUAGE） . mido.sh # 从微软下载 Windows（消费 MIDO / ESD） . answer.sh # 现代无人值守应答文件（消费 USERNAME / DOMAIN 等） . batch.sh # Win9x 无人值守 . sif.sh # NT5 无人值守 . legacy.sh # 旧版安装 . image.sh # 检测镜像文件 . install.sh # 执行安装 . disk.sh # 初始化磁盘（消费 DISK_* / STORAGE） . display.sh # 初始化图形（消费 DISPLAY / GPU / VRAM_SIZE） . audio.sh # 初始化音频（消费 AUDIO / SOUND） . network.sh # 初始化网络（消费 NETWORK / DHCP / BRIDGE） . samba.sh # 配置 Samba（消费 SAMBA / SHORTCUT） . boot.sh # 配置启动（消费 BOOT_MODE / TPM / SMM） . proc.sh # 初始化处理器（消费 CPU_CORES / KVM） . power.sh # 配置关机（消费 SHUTDOWN / TIMEOUT） . balloon.sh # 初始化内存气球（消费 BALLOONING_*） . config.sh # 组装 QEMU 参数 . finish.sh # 完成初始化

管线结束后，脚本组装cmd=(qemu-system-x86_64)并执行（见 entry.sh 第 39–39 行），其中镜像内的 QEMU 二进制由 Dockerfile 从 Helios 定制构建（qemu-helios:1.0.0）取得，这正是GPU变量提供 GPU 加速的前提。Dockerfile 同时声明了镜像级默认值：

VOLUME /storage EXPOSE 3389 8006 ENV VERSION="11" ENV RAM_SIZE="4G" ENV CPU_CORES="2" ENV DISK_SIZE="64G" ENTRYPOINT ["/usr/bin/tini", "-s", "/run/entry.sh"]

也就是说，VERSION、RAM_SIZE、CPU_CORES、DISK_SIZE四个变量在镜像层就有兜底默认值，其余变量则由init.sh与各子脚本在运行时赋予默认值（例如 power.sh 中的SHUTDOWN:="Y"与TIMEOUT:="105"）。

Windows 安装：版本、语言、账户与域

文档中 "Windows" 一节的完整变量表：

VERSION 的别名解析

从源码结构看，VERSION并不只接受11/10这类短写法。define.sh 的 parseVersion() 把一个宽松的大写归一化case分支把用户输入映射为内部镜像标识：

"11" | "11p" | "win11" | "pro11" | "windows11" | "windows 11" ) VERSION="win11x64" ;; "7u" | "win7u" | "windows7u" ) VERSION="win7x64-ultimate" ;; "22" | "2022" | "win22" | "windows 2022" ) VERSION="win2022-eval" ;;

支持的完整取值还包括11l/11ltsc（LTSC）、11e（Enterprise）、7x86（32 位）、hv（Hyper-V Server 2019）、core11/tiny11/tiny10（精简系统）、reactos等；Server 版本均以-eval评估版镜像下载。内部标识再决定两件事：一是 assets/ 目录下选择哪套.xml/.cmd应答文件模板（例如 win11x64.xml），二是各版本的最低资源要求，见 getRequiredMemory() / getRequiredDisk()（如 win11 需 2G 内存、32G 磁盘，win2003 只需 512M 内存、4G 磁盘）。RAM_CHECK=Y的内存检查即依赖这张表。

应答文件如何消费这些变量

answer.sh 的updateXML()是USERNAME、PASSWORD、DOMAIN、WORKGROUP、AUTOLOGIN、WIDTH/HEIGHT等变量的落点：它加载对应版本的应答文件模板（如 assets/win11x64.xml，内含 128MB EFI 分区、128MB MSR 分区与 NTFS 主分区的DiskConfiguration），然后依次执行updateUserXML（账户与显示）、updateLocaleXML（区域/键盘，缺省时回落到LANGUAGE）、域账户准备（DOMAIN设置时）或本地账户写入、工作组/域成员关系、自动登录（AUTOLOGIN）与首次登录命令（COMMAND）。其中 answer.sh 第 29–30 行 印证了显示默认值：

[ -z "${WIDTH:-}" ] && WIDTH="1280" [ -z "${HEIGHT:-}" ] && HEIGHT="720"

另外，脚本按/custom.xml→$STORAGE/custom.xml→/run/assets/custom.xml的优先级检查自定义应答文件（setXML()），存在时完全覆盖内置模板，这是文档未明说但源码可确认的扩展点。LANGUAGE的取值经 parseLanguage() 归一化（下划线转连字符）后与语言表匹配，未识别的值会直接报错终止。

CPU 与内存：从 KVM 加速到内存气球

几个要点：

• CPU_CORES支持half/max这类相对取值，half取宿主一半核心、max取全部；不指定时用数字（镜像默认2，见 Dockerfile）。SMP变量则让你直接覆盖完整的 QEMU-smp拓扑字符串（socket/core/thread 组合），未设置时脚本按CPU_CORES推导。
• KVM=Y是"近原生性能"的关键，前提是宿主机暴露/dev/kvm且 README 中的要求 满足（Linux 宿主开启 VT-x/AMD-V）。KVM=N可退回 TCG 软件模拟，仅用于无 KVM 的调试场景。
• RAM_BACKEND影响 QEMU 的-mem-path/memfd 后端选择，memfd取值在迁移等场景下更友好；RAM_CHECK=Y对应 entry.sh 中加载的 memory.sh，启动前比对宿主可用内存与RAM_SIZE，不足时报错退出，避免宿主机 OOM。
• VMX=Y会在 KVM 之上再嵌套暴露 VMX，用于来宾内部再跑一层虚拟化（如 Hyper-V 嵌套）；HV=Y则是针对 Windows 来宾的 Enlightenments 优化，默认开启。

存储：磁盘规格与数据目录

从源码结构看，这些变量由 entry.sh 管线中的 disk.sh 消费。几个实践细节：

• 主磁盘镜像、NVRAM/固件变量与下载的 ISO 都落在STORAGE（默认/storage，对应 Dockerfile 中的 VOLUME /storage），因此 compose 中务必用-v ./windows:/storage持久化，否则重建容器会丢机器。compose.yml 的官方示例正是如此挂载的。
• DISK_FMT=qcow2配合DISK_DISCARD=unmap可实现镜像瘦身；ALLOCATE=Y预分配则换取更稳定的随机 I/O 并避免写满文件系统。
• DISK_ROTATION=1会让来宾把磁盘识别为 SSD，Windows 因此启用 TRIM 与更积极的磁盘写入策略。
• 扩盘场景（如DISK_SIZE: "256G"）见 README 的说明：现有磁盘可以无数据丢失地扩容，但扩容后需在磁盘管理中手动扩展分区。

网络：桥接、macvtap 与用户模式

网络变量由 entry.sh 管线中的 network.sh 消费，可归纳为三档模式：

1. 默认 NAT 模式：QEMU 在BRIDGE（默认docker网桥）上创建名为TAP（默认qemu）的 tap 设备，容器与 Windows 共享一个 IP，宿主需做端口映射（3389 RDP、8006 Web 等）；来宾地址在未指定IP时自动从网桥段选取。HOST_PORTS可排除个别端口不参与转发。
2. macvtap 模式（DHCP=Y）：容器申请独立 IP，Windows 通过物理网段的 DHCP 再拿一个 IP，成为局域网真实成员。此模式需要/dev/vhost-net设备与NET_ADMIN能力，README 给出了完整 compose 写法。此模式下 Samba 主机名与接口切换为上行网卡（samba.sh 的 configureNetwork() 对DHCP分支做了区分）。
3. 用户模式（NETWORK=user）：由 QEMU 内置的 slirp/passt 用户态网络栈承担，无需 tap/桥接设备，适合无NET_ADMIN权限的环境；USER_PORTS指定额外转发端口，PASST_OPTS/PASST_DEBUG则调节 passt 后端。

ADAPTER默认virtio-net-pci，依赖镜像内打包的 virtio-win 驱动（Dockerfile 下载 virtio-win 驱动包）。MAC固定 MAC 有助于域环境或 DHCP 保留策略下的稳定身份。

显示与 Web 界面

从源码结构看，WIDTH/HEIGHT由 answer.sh 写入应答文件的显示设置，安装完成后 Windows 分辨率即按此配置；DISPLAY=web配合WEB=Y时，容器在WEB_PORT（默认 8006，Dockerfile 中 EXPOSE 8006）提供 noVNC 式查看器，power.sh 的启动成功提示 也会打印http://127.0.0.1:8006/访问地址。GPU=Y启用由 Helios 版 QEMU 提供的 3D 加速，需要把宿主渲染节点（默认/dev/dri/renderD128）以设备形式传入容器；VRAM_SIZE控制虚拟显存上限。LOSSY=Y用有损压缩换取低带宽下可用，PROTECT=Y则在 Web 界面前加一道密码门槛。AUDIO=Y与 SOUND 变量 联动：README 提示音频流仅在 Web 查看器中打开 Audio 选项时才传输。

文件共享：Samba 共享目录

samba.sh 印证了这三个开关的默认值，并在SAMBA=N或网络被禁用时直接返回：

: "${SAMBA:="Y"}" # Enable Samba : "${SAMBA_DEBUG:="N"}" # Disable debug : "${SAMBA_READONLY:="N"}" # Disable writes ... disabled "$SAMBA" && return 0 disabled "$NETWORK" && return 0

其 configureNetwork() 按DHCP模式切换绑定接口：macvtap 模式绑定上行网卡，用户模式仅绑定 loopback（由 QEMU 端口转发提供访问），桥接模式绑定BRIDGE；NetBIOS 名被截断到 15 个字符以符合 SMB 规范。使用方式是把宿主目录挂到/shared（见 README），Windows 桌面出现Shared文件夹与Z:盘（SHORTCUT=Y的产物），脚本还会在共享目录内写入一份readme.txt说明（writeReadme()）。

系统级 QEMU 参数

这一组是"最后手段"级别的控制面：MACHINE=q35选择现代 PCI Express 机型（Windows 10/11 推荐）；RNG=Y对 Windows 来宾尤其重要（熵源不足会拖慢随机数密集操作）；SM_BIOS可注入 SMBIOS 字符串（如厂商/产品名），UUID让同一台机器在多次运行间保持稳定的机器标识。ARGUMENTS是逃生舱：任何 QEMU 命令行片段都能塞进去，entry.sh 的执行语句 中${ARGS:+ $ARGS}会把它原样拼到qemu-system-x86_64之后——README 中的 USB 直通示例（ARGUMENTS: "-device usb-host,vendorid=0x1234,productid=0x1234"）正是这一机制的应用。MOUSE=usb-tablet使指针无需捕获即可相对移动，是 Web 查看器可用的基础。

启动：BOOT_MODE、固件与安全选项

entry.sh 第 6 行 给出默认值BOOT_MODE:="windows"。三种模式对应不同固件形态：windows走标准 UEFI（OVMF）启动；windows_secure开启安全启动所需的 SMM 与 TPM（TPM/SMM文档标注"通常由 BOOT_MODE 设置"，即由 boot.sh 按模式自动联动）；windows_legacy面向旧版 Windows，回退到 BIOS/SeaBIOS 传统引导。power.sh 中的引导识别逻辑 也印证了双引导路径：它同时维护 BIOS 模式（Booting from Hard Disk/DVD/CD）与 UEFI 模式（BdsDxe: starting Boot....）两套正则来判定启动进度。BOOT_INDEX=9对应 OVMF 的 Boot#### 条目编号，决定安装介质（DVD/USB）在启动列表中的优先级；MEDIA_TYPE可强制安装介质的设备类型（如usb）。CLEAR=Y会删除 NVRAM 变量文件（位于STORAGE目录）并重新初始化，适合换盘或修复启动项时使用。

内存气球：动态内存回收

文档在该节引用了 QEMU 内存气球的官方文档（见 environment.md 第 141 行 的注释），并给出：

从源码结构看，这些变量由 entry.sh 管线中的 balloon.sh 消费：BALLOONING=Y时容器运行一个监控器进程，按BALLOONING_INTERVAL秒轮询宿主内存压力——双通道触发（宿主 RAM 使用率阈值 + PSI 压力值），以KP/KI增益的 PI 控制器计算回收量，受BALLOONING_MIN_MEM（不低于RAM_SIZE的 33%）与BALLOONING_HYSTERESIS（128M 防抖）约束。默认N意味着 VM 全程独占RAM_SIZE；开启后，空闲的 Windows 会把内存还给宿主，适合一台物理机跑多个 Windows 容器的密集场景。

安装过程：下载、校验与收尾

mido.sh 展示了MIDO=Y的实现：容器直接与微软端点交互——先向微软的反滥用接口登记会话（session id），再请求 SKU 与下载链接，最终用仅 HTTPS、TLS1.2 的 curl 拉取 ISO，CONNECTIONS=4表示分片并发下载。ESD=Y走 ESD 封装（体积更小的分发格式）。define.sh 的 getMido() 中为每个内部版本维护了精确的 URL、文件大小与 SHA-256 校验和（如 win11x64 为d141f6...7736125440 字节），VERIFY=Y即按这些预定义校验和验证下载产物。REMOVE=Y在 Windows 首次从本地盘成功引导后删除 ISO（power.sh 的 markWindowsBooted() 会检查REMOVE并清理安装介质），为/storage省下 5–8 GB。COMMAND的用法见 README 示例：在自动安装最后一步执行单条命令，或挂载含install.bat的目录到/oem以运行脚本并携带附加文件。

关机：优雅的 ACPI 流程

power.sh 定义了两个默认值，并在 gracefulShutdown() 中实现完整逻辑：容器收到 SIGTERM（docker stop）时向 QEMU monitor 发送system_powerdown（ACPI 电源信号），等待 Windows 完成关机；若 power.sh 第 498–508 行 判定来宾尚不具备响应 ACPI 的条件（不支持 ACPI 的版本，或仍处于安装早期），会把超时缩短到 7–13 秒。SHUTDOWN=N时跳过整个信号处理，容器停止即断电（entry.sh 第 58 行 的enabled "$SHUTDOWN"分支）。因此 compose 文件建议保留 compose.yml 中的stop_grace_period: 2m，给 105 秒的 ACPI 流程留出余量。

调试：串口、监控器与日志

DEBUG=Y会在各阶段打印中间值（例如 power.sh 的 sendKey() 在失败且开启 DEBUG 时会回显 monitor 原始响应）；TRACE=Y等价于bash -x，逐条回显执行的 shell 命令。SERIAL默认mon:stdio把 QEMU monitor 挂到标准输出（供启动探测使用），设为 unix socket 或 TCP 端口后可外部接入telnet/socat操作 monitor。QMP建立 JSON 协议的机器级控制通道，QGA则依赖来宾内的 QEMU Guest Agent，二者结合可实现从容器外查询来宾状态（磁盘、进程、关机）。LOG=Y对排查install.bat失败尤其有用——日志落盘到 Windows 内C:\OEM\install.log，随共享文件夹或 RDP 取回。

实战配置示例

综合上文，一个完整的 compose 配置（在 compose.yml 官方基础上扩展）：

services: windows: image: dockurr/windows container_name: windows environment: VERSION: "11" # 或 10 / 2022 / 7u / tiny11 等，见 parseVersion 别名表 EDITION: "ltsc" # 可选：版次覆盖 LANGUAGE: "Chinese" # 或 en-US / en USERNAME: "docker" PASSWORD: "changeme" CPU_CORES: "4" # 或 half / max RAM_SIZE: "8G" DISK_SIZE: "128G" DISK_FMT: "qcow2" BALLOONING: "N" WEB_PORT: "8006" AUDIO: "N" SHUTDOWN: "Y" TIMEOUT: "105" devices: - /dev/kvm - /dev/net/tun cap_add: - NET_ADMIN ports: - "8006:8006" - "3389:3389/tcp" - "3389:3389/udp" volumes: - ./windows:/storage - ./shared:/shared # 对应 SAMBA 共享，Z: 盘 restart: always stop_grace_period: 2m

等价 Docker CLI（与 README 一致）：

docker run -it --rm --name windows \ -e "VERSION=11" -e "RAM_SIZE=8G" -e "CPU_CORES=4" \ -p 8006:8006 -p 3389:3389/tcp -p 3389:3389/udp \ --device=/dev/kvm --device=/dev/net/tun --cap-add NET_ADMIN \ -v "${PWD:-.}/windows:/storage" -v "${PWD:-.}/shared:/shared" \ --stop-timeout 120 docker.io/dockurr/windows

Kubernetes 部署可直接应用 kubernetes.yml。部署前按 README 的 KVM 检查 确认宿主机满足前提：kvm-ok报告 "KVM acceleration can be used"，且/dev/kvm存在。

小结

windows 项目的设计哲学是"一切皆环境变量"：镜像层（Dockerfile）只钉住VERSION/RAM_SIZE/CPU_CORES/DISK_SIZE四个兜底值，其余约 90 个变量由 entry.sh 的 24 段初始化管线分别消费，最终收敛为一条qemu-system-x86_64命令行加一套 Windows 应答文件。掌握这条"环境变量 → 初始化脚本 → QEMU 参数/unattend XML"的映射链，配合 docs/environment.md 的完整变量表，你就能在不改任何代码的前提下，精确裁剪这台容器化 Windows 的每一个维度——从安装哪一代 Windows、用什么语言键盘，到 KVM 加速、virtio 存储栈、macvtap 组网、Helios 3D 显卡、Samba 文件共享与 PI 控制器驱动的动态内存气球。

【免费下载链接】windowsWindows inside a Docker container.项目地址: https://gitcode.com/GitHub_Trending/wi/windows