众元AI学习空间

06_DockerDesktop与WSL2安装验收手册

11分钟阅读

Docker Desktop 与 WSL 2 安装验收手册（Windows）

首次使用：W03-D04；W08-D05 复用并重新验收。
本课程使用 Linux 容器与 WSL 2 后端。
安装完成不等于 Docker 可用；最终必须跑过 Engine、Compose、hello-world 和课程镜像。

0. 先读许可和设备要求

Docker 官方当前说明：个人、教育、非商业开源和符合条件的小型企业可免费使用 Docker Desktop；较大企业和政府实体可能需要付费订阅。学校/公司的设备先确认组织许可，不由学生个人点击代替组织决策。

课前检查：

  • Windows 10/11 64 位且仍在 Microsoft 支持周期；具体最低版本以上课当天 Docker 官方要求 为准。
  • 至少 8 GB 内存。
  • BIOS/UEFI 已启用硬件虚拟化。任务管理器 → 性能 → CPU 可查看“虚拟化”。
  • WSL 版本至少满足 Docker 当前要求（官方页面当前写 2.1.5+）。
  • 首次启用 WSL 2 需要管理员权限，并且可能需要重启。
  • 课程盘预留足够空间；镜像、容器和卷会继续增长。

当前备课机 2026-08-21 实测 C 盘仅约 5 GB 可用，暂不应直接按默认位置安装 Docker Desktop。优先把 C 盘可用空间整理到至少 20 GB；若明确要把 WSL 数据放到其他盘，先确定一个专用空目录并记录位置，再使用本节的高级安装方式。不要把整个 D/E 盘根目录直接作为 Docker 数据目录。

先在 PowerShell 执行：

winver
wsl --version
wsl --status
systeminfo

记录输出，不要只写“电脑应该支持”。

1. 安装或更新 WSL 2

已经有现代 WSL

wsl --version
wsl --update
wsl --status

更新可能要求管理员权限或重启。完成后重新执行 wsl --version。

没有 WSL 或不显示版本详情

  1. 保存工作，关闭其他重要程序。
  2. 右键 PowerShell，选择“以管理员身份运行”。
  3. 执行：
wsl --install
  1. 按提示重启 Windows。
  2. 若同时安装了 Ubuntu，首次打开时由学生本人设置 Linux 用户名和密码；本课程 Docker 操作仍在 Windows/PowerShell 中完成，不要求把课程项目搬进 Ubuntu。
  3. 重启后执行：
wsl --version
wsl --status
wsl -l -v

如果 wsl --install 只显示帮助，说明 WSL 可能已经存在；使用 wsl --update。组织禁用 Microsoft Store 时，使用 Microsoft/Docker 官方提供的离线 MSI 路线，由管理员处理，不从未知镜像下载。

2. 检查硬件虚拟化

打开任务管理器 → 性能 → CPU，确认“虚拟化：已启用”。

若显示禁用：

  • 不在课堂上盲目修改 BIOS。
  • 记录电脑品牌和型号，由设备所有者或管理员按厂商文档启用 Intel VT-x / AMD-V / SVM。
  • 公司管控设备、云桌面或虚拟机可能不允许嵌套虚拟化，应改用教师演示机或符合条件的备用机。

Dockerfile 静态检查不能代替这项真机条件。

3. 安装 Docker Desktop

  1. 打开 Docker Desktop Windows 官方安装页。
  2. 普通 Intel/AMD 电脑下载 x86_64；只有明确的 Windows on ARM 设备才选 ARM 构建。
  3. 双击 Docker Desktop Installer.exe。
  4. 如果安装器询问模式，普通学生优先使用官方推荐的 per-user 模式；组织统一安装则按管理员策略。
  5. 后端选择 WSL 2。本课程不需要 Windows Containers。
  6. 完成安装并关闭安装器。
  7. 从开始菜单手动启动 Docker Desktop。官方说明安装后不会自动启动。
  8. 首次启动阅读并确认 Docker Subscription Service Agreement；组织许可不明确时先停下询问。
  9. 基础本地课程不强制注册 Docker Hub。若界面允许跳过登录，可先完成本机容器验收；组织强制登录时按组织账号流程处理。
  10. 等待 Docker Desktop 明确显示 Engine 已运行，再打开新的 TRAE 终端。

当前备课机需要改数据位置时

若已经从官方页面下载 Docker Desktop Installer.exe，并决定使用例如 D:\DockerDesktopData 这一专用目录，可在安装器所在目录的 PowerShell 执行官方支持的 per-user 参数：

New-Item -ItemType Directory -Path 'D:\DockerDesktopData'
Start-Process 'Docker Desktop Installer.exe' -Wait `
  -ArgumentList 'install', '--user', '--wsl-default-data-root=D:\DockerDesktopData'

执行前先确认目标目录不是现有项目、资料或盘符根目录，并且空间充足。安装后仍要检查 Docker Desktop 实际数据位置和 docker system df；改数据位置不能代替 C 盘为 Windows 和应用本体保留正常运行空间。

4. 四层基础验收

4.1 CLI 存在

docker --version
where.exe docker

这只证明命令存在。

4.2 Engine 响应

docker version
docker info

docker version 应同时出现 Client 与 Server；docker info 应返回服务端信息。只有 Client 没有 Server，通常是 Docker Desktop 未启动或 Engine 仍在初始化。

4.3 Compose 可用

docker compose version

课程使用带空格的 docker compose，不要求旧版独立 docker-compose。

4.4 真实拉取并运行最小镜像

docker run --rm hello-world

这一步需要联网拉取镜像。看到容器真实运行并退出，才完成基础安装验收。下载受限时记录 registry 错误，由教师处理组织代理/镜像，不关闭 TLS 校验。

5. W03-D04 Commerce API + MySQL 运行检查

在学生/团队自己的 W03-commerce-web 项目根目录执行。应用与 MySQL 的服务名、端口和环境变量以本人仓库已经审查的 compose.yaml 为准，不照抄教师绝对路径：

docker compose config
docker compose build
docker compose up -d
docker compose ps
docker compose logs --no-color --tail 100
Invoke-RestMethod http://127.0.0.1:8000/health

通过标准：镜像真实构建、API 与 MySQL 容器真实运行、/health 成功、日志没有泄露密码或 Key。随后通过 API 创建一笔教学订单，重启容器，再查询同一 order_id，证明 MySQL Volume 中的数据仍在。

再用浏览器访问最小 API Consumer，完成真实列表和订单路径。最后只停止本次项目：

docker compose down

不要在没有数据确认和教师授权的情况下增加 -v；docker compose down -v 会删除命名卷中的数据。

完整证据应包括：build、run、ps/health、logs、浏览器端到端和卷重启后的数据检查。docker compose config 只证明 YAML 可解析。

7. W08 复用前的重新检查

不需要重装 Docker，但上课前执行：

docker version
docker info
docker compose version
docker system df

然后在 W08 项目执行自己的 build/run/health/log/volume 验收。W03 曾经成功不能证明数周后的 W08 环境仍然正常。

8. 常见故障

docker 找不到

完全退出并重开 TRAE，执行 where.exe docker。若 Docker Desktop 已装但 PATH 未刷新，优先重启应用/系统，不手写未知安装路径。

只有 Client，没有 Server

打开 Docker Desktop，等待 Engine ready；检查错误通知、WSL 状态和 Docker Desktop Troubleshoot 页面。

WSL kernel version too low

wsl --update
wsl --shutdown

重启 Docker Desktop，再查 wsl --version 与 docker info。

虚拟化未启用

按第 2 节交给设备所有者/管理员处理。云桌面或虚拟机还需宿主机支持嵌套虚拟化。

端口 8000 / 80 已占用

Get-NetTCPConnection -State Listen | Where-Object LocalPort -In 80,8000
docker ps

先找出是本机进程还是旧容器，不直接结束未知进程。停止自己启动的旧服务后重试。

镜像拉取失败

保存完整 registry、DNS、证书或超时错误。组织网络按官方 Docker Desktop 代理设置处理；不添加未知镜像源，不关闭证书校验。

Docker Desktop 启动后占用过高

先查看 Docker Desktop Resources 设置和 docker system df。清理镜像、容器、卷可能删除环境和数据，必须先识别具体对象并由学生确认，不执行无差别 prune。

9. 课堂验收单

Windows 版本：
内存：
虚拟化：已启用 / 未启用
WSL 版本：
Docker Client：
Docker Server：
Compose：
hello-world：成功 / 失败
W03 build：
W03 container health：
W03 logs：
W03 浏览器端到端：
卷重启证据：
仍待处理的问题：

证据分级：安装器完成 < CLI 存在 < Engine 响应 < 最小容器 < 课程镜像 < 完整端到端。不能互相替代。

反向链接