grafana/ci-build-windows

Windows CI 构建环境镜像文档

1. 镜像概述

1.1 简介

本镜像基于 Windows Server 容器技术构建，提供标准化的 Windows 平台 CI/CD 构建环境。集成主流开发工具链、依赖管理工具及环境配置，旨在消除"在我机器上能运行"的环境差异问题，确保跨团队、跨环境的构建一致性。

1.2 主要用途

• 作为 CI/CD 流程中的 Windows 构建节点，执行自动化构建、测试及打包任务
• 提供一致的开发环境，简化 Windows 应用构建流程的配置与维护
• 支持与主流 CI 平台（Jenkins、GitHub Actions、GitLab CI 等）无缝集成
• 快速部署临时构建环境，满足多版本并行开发需求

2. 核心功能和特性

• 预装完整工具链
  包含 .NET SDK（支持 Framework/Core/5+ 全版本）、Visual Studio Build Tools、MSBuild、PowerShell 7+ 等核心构建工具

• 依赖管理集成
  内置 NuGet、Chocolatey、npm（Windows 版）等依赖管理工具，支持一键安装项目依赖

• 多版本兼容性
  提供基于 Windows Server 2019 (ltsc2019)、2022 (ltsc2022) 的镜像变体，适配不同项目的系统依赖需求

• 环境隔离与一致性
  容器化设计确保每次构建在隔离环境中执行，避免依赖冲突和环境污染

• 可定制化配置
  通过环境变量、卷挂载实现工具版本控制、缓存策略及构建参数的灵活配置

• CI 平台适配
  内置与主流 CI 系统兼容的日志输出格式和进程管理机制，支持后台任务执行与结果返回

3. 使用场景和适用范围

3.1 典型使用场景

• Windows 应用开发团队的日常 CI 流程（自动化构建、单元测试、代码质量检查）
• .NET 系列应用（Framework/Core/.NET 5+）的持续集成构建与打包
• 依赖 Windows 特定组件（如 IIS、Windows SDK、DirectX）的项目构建
• 跨平台项目中 Windows 目标平台的构建验证
• 企业内部 CI/CD 流水线中的标准化 Windows 构建节点

3.2 适用范围

• 开发框架：.NET（全版本）、C/C++（Windows SDK）、PowerShell 脚本、WPF/WinForms 桌面应用等
• 团队规模：小型开发团队至大型企业级研发团队
• 部署环境：本地 Docker 环境、私有容器 registry、云容器服务（Azure Container Instances、AWS ECS Windows 等）

4. 使用方法和配置说明

4.1 基本要求

• Docker 环境：需安装支持 Windows 容器的 Docker Desktop（启用 Windows 容器模式）
• 宿主系统：Windows 10/11 专业版/企业版或 Windows Server 2019/2022（需启用容器功能）
• 网络：可访问 Docker Hub 或私有 registry，构建过程需联网获取依赖（如适用）

4.2 Docker Run 命令示例

基础构建示例

powershell
docker run --rm `
  -v ${PWD}:/src `
  -v ${PWD}/output:/output `
  mcr.microsoft.com/windows/servercore:ltsc2022-windows-ci `
  powershell -Command "cd /src; dotnet build -o /output"

指定 .NET SDK 版本

powershell
docker run --rm `
  -e DOTNET_SDK_VERSION=7.0.400 `
  -v ${PWD}:/src `
  -v ${PWD}/output:/output `
  mcr.microsoft.com/windows/servercore:ltsc2022-windows-ci `
  powershell -Command "dotnet --version; cd /src; dotnet build"

4.3 Docker Compose 配置示例

yaml
version: '3.8'

services:
  windows-ci-build:
    image: mcr.microsoft.com/windows/servercore:ltsc2022-windows-ci
    container_name: windows-ci-instance
    environment:
      - DOTNET_SDK_VERSION=8.0.100
      - HTTP_PROXY=http://proxy.corp.com:8080
      - BUILD_CACHE_DIR=C:\cache
      - LOG_LEVEL=debug
    volumes:
      - ${PWD}/src:C:\src:ro                # 只读挂载源代码
      - ${PWD}/artifacts:C:\output          # 挂载构建输出目录
      - ${PWD}/.nuget-cache:C:\cache        # 缓存卷加速依赖下载
    command: >
      powershell -Command "
        dotnet restore C:\src\MyProject.sln --packages C:\cache;
        dotnet build C:\src\MyProject.sln -c Release -o C:\output;
        dotnet test C:\src\MyProject.Tests\MyProject.Tests.csproj --no-restore
      "

4.4 环境变量配置说明

4.5 卷挂载说明

4.6 CI 系统集成示例

GitHub Actions 集成

yaml
# .github/workflows/windows-build.yml
name: Windows CI Build
on: [push, pull_request]

jobs:
  build:
    runs-on: windows-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Run Windows CI container
        run: |
          docker run --rm `
            -e DOTNET_SDK_VERSION=7.0 `
            -e BUILD_CACHE_DIR=C:\cache `
            -v ${PWD}:/src `
            -v ${PWD}/artifacts:/output `
            -v ${PWD}/cache:/cache `
            mcr.microsoft.com/windows/servercore:ltsc2022-windows-ci `
            powershell -Command "cd /src; dotnet build -o /output"

      - name: Upload artifacts
        uses: actions/upload-artifact@v3
        with:
          name: windows-build-output
          path: artifacts/

Jenkins Pipeline 集成

groovy
pipeline {
  agent any
  stages {
    stage('Windows Build') {
      steps {
        script {
          docker.image('mcr.microsoft.com/windows/servercore:ltsc2022-windows-ci').withRun(
            "-e DOTNET_SDK_VERSION=7.0 " +
            "-v ${workspace}/src:C:/src " +
            "-v ${workspace}/output:C:/output"
          ) { c ->
            docker exec c powershell -Command "dotnet build C:/src/MyApp.csproj -o C:/output"
          }
        }
      }
      post {
        success {
          archiveArtifacts artifacts: 'output/**/*.dll', fingerprint: true
        }
      }
    }
  }
}

5. 使用场景和适用范围

5.1 典型应用场景

• .NET 应用开发团队：自动化构建 .NET Framework/.NET Core 项目
• Windows 桌面应用：WPF/WinForms 应用的 CI/CD 流程
• Windows 驱动开发：依赖 Windows SDK 的驱动程序构建验证
• 企业内部 CI 流水线：作为标准化 Windows 构建节点集成到 Jenkins/GitLab CI
• 跨平台项目验证：确保项目在 Windows 环境的构建兼容性

5.2 环境要求

• Docker 环境：Docker Desktop (Windows) 4.0+，启用 Windows 容器模式
• 宿主机配置：至少 4 核 CPU、8GB 内存、50GB 可用磁盘空间
• 网络：可访问 Docker Hub/私有 registry 及依赖下载源（如 NuGet.org）

6. 注意事项

1. 镜像版本选择：根据项目依赖选择基础镜像版本（如 ltsc2019 对应 Windows Server 2019，ltsc2022 对应 2022），避免版本混用导致兼容性问题。

2. 资源分配：Windows 容器资源消耗高于 Linux 容器，建议为 CI 节点配置至少 8GB 内存，构建大型项目时需增加至 16GB。

3. 路径格式：容器内路径需使用 Windows 风格（如 C:\src），Docker CLI 中可兼容 Unix 风格路径（如 /src），但卷挂载推荐显式使用 C:\ 前缀。

4. 安全更新：定期拉取镜像更新以获取工具链安全补丁，生产环境建议固定版本标签（如 ltsc2022-v1.2.0）而非使用 latest。

5. 权限控制：宿主机挂载目录需确保容器进程有读写权限（Windows 下建议将目录设置为"共享给容器"）。

7. 常见问题解决

Q：构建时报错"依赖项下载失败"？

A：检查网络连接或配置 HTTP_PROXY 环境变量；挂载缓存卷（如 .nuget-cache）避免重复下载；验证依赖源（NuGet 源）可访问性。

Q：容器内无法访问挂载的源代码？

A：确认宿主机路径格式正确（如 C:\projects\src），且未设置只读权限（除非明确指定 :ro）；检查 Windows Defender 或防火墙是否阻止容器访问文件。

Q：.NET SDK 版本切换无效？

A：部分基础镜像仅预装指定版本 SDK，需选择包含目标版本的镜像标签（如 ltsc2022-sdk-7.0）；或通过 Chocolatey 在容器内手动安装：

powershell
choco install dotnet-sdk-8.0 -y --no-progress

Q：与 GitHub Actions Windows Runner 兼容性问题？

A：GitHub Actions Windows Runner 已内置部分构建工具，简单场景可直接使用 Runner 环境；复杂环境建议通过 services 配置容器化构建：

yaml
services:
  windows-ci:
    image: mcr.microsoft.com/windows/servercore:ltsc2022-windows-ci
    volumes:
      - ${{ github.workspace }}:/src