Container Desktop 安装与配置指南

适用于 Windows 系统的 Docker 容器化开发环境搭建。Container Desktop 是 Docker Desktop 的开源替代品，基于 WSL2 后端，提供完整的 Docker 引擎支持。

1. 环境要求

组件	要求
操作系统	Windows 10 22H2+ / Windows 11
WSL	WSL2 已启用并设为默认
CPU	支持虚拟化（BIOS 中已开启）
内存	建议 ≥ 8 GB

1.1 启用 WSL2

powershell 复制代码

# 以管理员身份运行 PowerShell
wsl --install

# 或手动启用
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

# 重启后设置 WSL2 为默认
wsl --set-default-version 2

1.2 验证 WSL

powershell 复制代码

wsl --list --verbose

输出应显示 WSL 版本为 2。

2. 安装 Container Desktop

2.1 下载安装包

访问 Container Desktop 官方 GitHub Releases 下载最新版安装包。

2.2 安装步骤

运行安装程序 ContainerDesktopInstaller.exe，按照向导完成安装。安装完成后桌面会出现 ContainerDesktop 图标。

2.3 安装后的文件结构

复制代码

C:\Program Files\ContainerDesktop\
├── ContainerDesktop.exe          # 主程序（GUI）
├── cli\
│   ├── docker.exe                # 自带 Docker CLI
│   └── docker-compose.exe
├── ContainerDesktop.dll
└── ...

用户数据目录：

复制代码

%LOCALAPPDATA%\ContainerDesktop\    # 即 C:\Users\<用户名>\AppData\Local\ContainerDesktop\
├── config.json                     # 主配置文件
├── logs\
│   ├── log.txt
│   └── log_001.txt                 # 运行日志
├── certs\                          # TLS 证书
└── wsl\                            # WSL 磁盘镜像
    ├── distro\ext4.vhdx            # 基础发行版
    └── data-distro\ext4.vhdx       # 持久化数据

3. 基本使用

3.1 启动 Container Desktop

双击 ContainerDesktop.exe（或从开始菜单启动）。启动后会在系统托盘中显示图标。

powershell 复制代码

# 命令行启动
Start-Process "C:\Program Files\ContainerDesktop\ContainerDesktop.exe"

3.2 验证 Docker 是否运行

powershell 复制代码

docker version

正常输出应包含以下内容：

复制代码

Client:
 Version:           28.3.0
Server:
 Engine:
  Version:          28.3.0

3.3 运行第一个容器

powershell 复制代码

docker run hello-world

3.4 查看日志

powershell 复制代码

Get-Content "$env:LOCALAPPDATA\ContainerDesktop\logs\log_001.txt" -Tail 50

日志关键信息：

[INF] Docker daemon started. --- Docker 引擎启动成功
[INF] Daemon configuration updated. --- 配置已应用
[WRN] Listening for port forward messages stopped unexpectedly --- 端口转发异常（通常可自动恢复）

4. 配置镜像加速器

在国内网络环境下，访问 Docker Hub 可能不稳定，配置镜像加速器可以显著提升拉取速度。

4.1 通过 GUI 配置（推荐）

打开 Container Desktop
右键单击系统托盘图标 → Settings
在 Docker Engine 选项卡中编辑 JSON 配置
添加 registry-mirrors 字段，例如：

json 复制代码

{
  "registry-mirrors": ["https://hub.1panel.dev"]
}

点击 Apply & Restart

4.2 通过配置文件修改

Container Desktop 的配置存储在 %LOCALAPPDATA%\ContainerDesktop\config.json 中，DaemonConfig 字段保存 Docker daemon 配置。

powershell 复制代码

# 读取配置文件
$configPath = "$env:LOCALAPPDATA\ContainerDesktop\config.json"
$config = Get-Content $configPath -Raw | ConvertFrom-Json

# 设置镜像加速器
$config.DaemonConfig = '{
  "registry-mirrors": ["https://hub.1panel.dev"]
}'

# 写回文件
$config | ConvertTo-Json -Depth 10 | Set-Content $configPath -Encoding UTF8

4.3 可用的镜像加速器

地址	提供方
`https://hub.1panel.dev`	1Panel
`https://docker.m.daocloud.io`	DaoCloud
`https://dockerproxy.com`	DockerProxy
`https://docker.nju.edu.cn`	南京大学镜像站

注意： 镜像加速器可能随时变更，建议使用前确认其可用性。

4.4 验证配置是否生效

powershell 复制代码

docker info | Select-String "Registry Mirrors" -Context 0,2

输出应包含：

复制代码

 Registry Mirrors:
  https://hub.1panel.dev/

4.5 切换 Docker Desktop 用户

如果之前使用 Docker Desktop，Container Desktop 会读取 C:\ProgramData\Docker\config\daemon.json 中的配置，但优先使用 自己的 config.json 中的 DaemonConfig 字段。

5. Docker CLI 集成

5.1 使用系统 Docker CLI

Container Desktop 安装后会自动将 docker 命令指向 npipe:////./pipe/docker_engine，与系统 CLI 兼容。

powershell 复制代码

# 查看当前 Docker 上下文
docker context inspect

5.2 使用 Container Desktop 自带的 CLI

powershell 复制代码

& "C:\Program Files\ContainerDesktop\cli\docker.exe" version
& "C:\Program Files\ContainerDesktop\cli\docker-compose.exe" version

5.3 常用 Docker 命令

powershell 复制代码

# 容器管理
docker ps                     # 列出运行中容器
docker ps -a                  # 列出所有容器
docker start <container>      # 启动容器
docker stop <container>       # 停止容器
docker rm <container>         # 删除容器

# 镜像管理
docker images                 # 列出本地镜像
docker pull <image>           # 拉取镜像
docker rmi <image>            # 删除镜像
docker build -t <name> .      # 从 Dockerfile 构建镜像

# 日志与调试
docker logs <container>       # 查看容器日志
docker exec -it <container> sh  # 进入容器 shell

6. 项目容器化开发

6.1 在项目中使用 Docker

以 PoshC2 项目为例，项目根目录已有 Dockerfile：

dockerfile 复制代码

# 使用 Docker 构建
docker build -t poshc2 .
docker run -it poshc2

6.2 使用 Docker Compose

powershell 复制代码

docker compose up -d
docker compose logs -f
docker compose down

6.3 挂载工作目录进行开发

powershell 复制代码

docker run -it --rm -v "${PWD}:/workspace" -w /workspace python:3.11 bash

6.4 多架构构建

powershell 复制代码

docker buildx build --platform linux/amd64,linux/arm64 -t myapp:latest .

7. 常见问题

7.1 Docker daemon 未启动

现象： docker version 只显示 Client 信息，报错 The system cannot find the file specified

解决方案：

检查 Container Desktop 进程是否在运行：
powershell 复制代码
```
Get-Process ContainerDesktop
```

如果进程未运行，启动它：

powershell 复制代码

Start-Process "C:\Program Files\ContainerDesktop\ContainerDesktop.exe"

等待 30-60 秒，检查日志：
powershell 复制代码
```
Get-Content "$env:LOCALAPPDATA\ContainerDesktop\logs\log_001.txt" -Tail 10
```
看到 [INF] Docker daemon started. 即表示启动成功。

如果进程运行但 Docker 仍未启动，尝试重启：

powershell 复制代码

Get-Process ContainerDesktop | Stop-Process -Force
Start-Process "C:\Program Files\ContainerDesktop\ContainerDesktop.exe"

7.2 WSL shutdown 后 Docker 无法重启

现象： 执行 wsl --shutdown 后 Container Desktop 启动失败，日志显示循环重启

原因： WSL VM 关闭后，Container Desktop 的 WSL distro 状态异常

解决方案：

重启 Container Desktop（自动重建 WSL 连接）
如果不行，重启 Windows
避免在 Container Desktop 运行时执行 wsl --shutdown

7.3 拉取镜像超时或失败

现象： docker pull 报 context deadline exceeded 或 net/http: request canceled

原因： Docker Hub 连接不稳定（常见于中国大陆网络）

解决方案：

配置镜像加速器（见第 4 节）

检查网络连通性：

powershell 复制代码

Test-NetConnection -ComputerName hub.1panel.dev -Port 443

尝试使用其他镜像加速器地址

7.4 端口转发异常

日志信息： [WRN] Listening for port forward messages stopped unexpectedly, trying to restart.

通常不影响正常使用，Container Desktop 会自动尝试重启端口转发服务。如果遇到端口映射不生效，可重启 Container Desktop。

7.5 磁盘空间不足

Container Desktop 的 WSL 磁盘镜像存储在：

复制代码

%LOCALAPPDATA%\ContainerDesktop\wsl\distro\ext4.vhdx
%LOCALAPPDATA%\ContainerDesktop\wsl\data-distro\ext4.vhdx

清理未使用的镜像和容器：

powershell 复制代码

docker system prune -a

附录：配置文件参考

`config.json` 完整结构

json 复制代码

{
  "EnabledDistributions": [],
  "PortForwardInterfaces": [],
  "DnsMode": 0,
  "DnsAddresses": null,
  "PortForwardingEnabled": false,
  "DaemonConfig": "{\n  \"registry-mirrors\": [\"https://hub.1panel.dev\"]\n}",
  "Certificates": [],
  "HostEntryMode": 0,
  "HostEntryAdapter": null
}

字段	说明
`DaemonConfig`	Docker daemon 配置（JSON 字符串）
`DnsMode`	DNS 模式（0=自动）
`PortForwardingEnabled`	端口转发开关
`EnabledDistributions`	启用的 WSL 发行版

Docker daemon 配置选项

可参考 Docker daemon 官方文档配置 DaemonConfig，常用选项：

json 复制代码

{
  "registry-mirrors": ["https://hub.1panel.dev"],
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  },
  "storage-driver": "overlay2"
}

Container Desktop 安装与配置指南

目录

1. 环境要求

1.1 启用 WSL2

1.2 验证 WSL

2. 安装 Container Desktop

2.1 下载安装包

2.2 安装步骤

2.3 安装后的文件结构

3. 基本使用

3.1 启动 Container Desktop

3.2 验证 Docker 是否运行

3.3 运行第一个容器

3.4 查看日志

4. 配置镜像加速器

4.1 通过 GUI 配置（推荐）

4.2 通过配置文件修改

4.3 可用的镜像加速器

4.4 验证配置是否生效

4.5 切换 Docker Desktop 用户

5. Docker CLI 集成

5.1 使用系统 Docker CLI

5.2 使用 Container Desktop 自带的 CLI

5.3 常用 Docker 命令

6. 项目容器化开发

6.1 在项目中使用 Docker

6.2 使用 Docker Compose

6.3 挂载工作目录进行开发

6.4 多架构构建

7. 常见问题

7.1 Docker daemon 未启动

7.2 WSL shutdown 后 Docker 无法重启

7.3 拉取镜像超时或失败

7.4 端口转发异常

7.5 磁盘空间不足

附录：配置文件参考

config.json 完整结构

Docker daemon 配置选项

`config.json` 完整结构