在 Ubuntu 26.04 (WSL2) 上通过阿里云镜像源安装 Docker CE 完整教程

适用环境 ：Ubuntu 26.04 LTS（resolute）、WSL2（systemd 已启用）、外网受限的内网/中国大陆网络

本教程包含：环境检测 → 安装 → 用户组配置 → 镜像加速器配置（解决 Docker 29 containerd-snapshotter 镜像失效问题）→ 验证

1. 环境检测

1.1 系统信息

bash 复制代码

uname -a
cat /etc/os-release

应当看到：

复制代码

Linux ... 6.18.x-microsoft-standard-WSL2 # ... x86_64 GNU/Linux
PRETTY_NAME="Ubuntu 26.04 LTS"
VERSION_CODENAME=resolute

1.2 关键依赖检查

bash 复制代码

# systemd 必须启用（WSL2 默认在 /etc/wsl.conf 中设置 [boot] systemd=true）
ps -p 1 -o comm=

# cgroup v2 必须挂载
stat -fc %T /sys/fs/cgroup/   # 应输出 cgroup2fs

# 必须有 curl
curl --version | head -1

# 必须有 iptables 或 nftables（Docker 网络依赖）
which iptables || which nft

如果 iptables / nftables 不存在，先安装：sudo apt-get install -y iptables

1.3 用户与磁盘

bash 复制代码

whoami
id                    # 必须包含 sudo 组
df -h /               # 至少 5 GB 可用
free -h               # 至少 1 GB 可用

2. 可行性分析

2.1 检查阿里云镜像是否支持你的发行版

bash 复制代码

curl -s -o /dev/null -w "%{http_code}\n" \
  https://mirrors.aliyun.com/docker-ce/linux/ubuntu/dists/$(. /etc/os-release && echo $VERSION_CODENAME)/Release

输出 200 → 支持，可继续
输出 404 → 当前 codename 未收录，可改用 jammy（22.04）兜底

2.2 检查镜像源 GPG 可达性

bash 复制代码

curl -s -o /dev/null -w "%{http_code}\n" \
  https://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg

应输出 200。

3. Docker CE 安装

一键脚本（推荐）：

bash 复制代码

# 3.1 预装系统依赖
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg iptables

# 3.2 添加阿里云 Docker GPG 公钥
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg \
  | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# 3.3 写入阿里云 apt 源（自动取当前 Ubuntu codename）
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://mirrors.aliyun.com/docker-ce/linux/ubuntu $(. /etc/os-release && echo $VERSION_CODENAME) stable" \
  | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 3.4 安装 Docker CE 及全家桶
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io \
                        docker-buildx-plugin docker-compose-plugin

# 3.5 启动并设置开机自启
sudo systemctl enable --now docker
sudo systemctl enable --now containerd

3.6 验证安装

bash 复制代码

docker --version              # Docker Engine 版本
docker compose version        # Compose 插件版本（注意是空格）
containerd --version
sudo systemctl is-active docker    # 应输出 active

预期输出示例：

复制代码

Docker version 29.6.1, build 8900f1d
Docker Compose version v5.2.0
containerd containerd.io 2.2.5
active

4. 用户组配置

把当前用户加入 docker 组，使普通用户免 sudo 使用 docker。

bash 复制代码

sudo usermod -aG docker $USER

# 验证
id $USER | grep docker        # 应包含 (docker)

⚠️ WSL2 中组员关系需要重新登录才能生效 。在 WSL 终端中执行 exit 后再次进入；或在当前 shell 临时生效：

bash 复制代码

newgrp docker    # 等价于重新登录到含 docker 组的会话

5. 镜像加速器配置

5.1 核心问题（Docker 29 踩坑必看）

Docker 29.x 默认启用 containerd snapshotter （存储驱动显示为 overlayfs / driver-type: io.containerd.snapshotter.v1）。在该模式下：

daemon.json 中的 registry-mirrors 不会生效
会出现日志 Host doesn't match cfgHost=registry-1.docker.io host=<mirror>
即使镜像源可达，pull 仍会回落到 registry-1.docker.io 然后超时

解决方法：关闭 containerd snapshotter，回到经典 overlay2 模式。

5.2 配置步骤

bash 复制代码

sudo tee /etc/docker/daemon.json > /dev/null <<'EOF'
{
  "features": {
    "containerd-snapshotter": false
  },
  "registry-mirrors": [
    "https://docker.xuanyuan.me",
    "https://docker.1ms.run",
    "https://docker.m.daocloud.io"
  ],
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "100m",
    "max-file": "3"
  },
  "storage-driver": "overlay2"
}
EOF

# 强制重启（systemctl restart 在某些场景下不会完全重启 dockerd，必须 kill）
sudo systemctl stop docker containerd
sudo killall -9 dockerd containerd 2>/dev/null
sleep 3
sudo systemctl start containerd
sudo systemctl start docker
sleep 4

5.3 验证镜像源生效

bash 复制代码

sudo docker info | grep -A 4 "Registry Mirrors:"

预期输出：

复制代码

 Registry Mirrors:
  https://docker.xuanyuan.me/
  https://docker.1ms.run/
  https://docker.m.daocloud.io/

同时检查存储驱动：

bash 复制代码

sudo docker info | grep -A 2 "Storage Driver"

应显示 Storage Driver: overlay2（不再是 overlayfs + containerd snapshotter）。

6. 验证

6.1 拉取并运行 hello-world

bash 复制代码

sudo docker pull hello-world
sudo docker run --rm hello-world

预期结尾输出：

复制代码

Hello from Docker!
This message shows that your installation appears to be working correctly.
...

6.2 验证免 sudo（需重新登录后）

bash 复制代码

docker ps
docker images
docker compose version

6.3 验证 compose 插件

bash 复制代码

mkdir -p /tmp/test-compose && cd /tmp/test-compose
cat > docker-compose.yml <<'EOF'
services:
  hello:
    image: hello-world
EOF
sudo docker compose up

7. 常见问题排查

Q1：pull 镜像一直超时，但镜像源 ping 可达

症状：

复制代码

failed to do request: Head "https://registry-1.docker.io/v2/...": dial tcp ...:443: i/o timeout
warning msg="Host doesn't match" cfgHost=registry-1.docker.io host=<mirror>

原因：Docker 29 默认 containerd snapshotter 模式使 registry-mirrors 失效。

解决：参见 §5.2，关闭 snapshotter 并 kill -9 重启。

Q2：`sudo systemctl restart docker` 后 PID 不变，配置未生效

原因：systemd 的 Restart= 配置有时不会完全重启 dockerd。

解决：sudo killall -9 dockerd containerd 后再 systemctl start。

Q3：`docker compose` 报 `command not found`

原因：未安装 docker-compose-plugin。

解决：sudo apt-get install docker-compose-plugin，新命令格式是 docker compose（带空格），不是 docker-compose。

Q4：用户加入 docker 组后仍需 sudo

原因：组成员关系需重新登录会话才生效。

解决：

在 WSL 中 exit 后重新进入
或在当前 shell 执行 newgrp docker
或重启 WSL（在 PowerShell 中 wsl --shutdown 然后重开）

Q5：MySQL 官方源报 `Release 404`

症状：Ign:6 http://repo.mysql.com/apt/ubuntu resolute InRelease / Err:7 ... Release / 404 Not Found

原因：第三方源（如 MySQL 官方）尚未支持 Ubuntu 26.04 codename。

解决：暂时禁用该源，或改用 Docker 部署 MySQL。

bash 复制代码

sudo ls /etc/apt/sources.list.d/          # 找到 mysql 源
sudo mv /etc/apt/sources.list.d/mysql.list /etc/apt/sources.list.d/mysql.list.bak
sudo apt-get update

Q6：能否让多个用户共享 docker？

bash 复制代码

sudo usermod -aG docker user1
sudo usermod -aG docker user2
# 这些用户重新登录后均免 sudo 使用 docker

8. 常用命令速查

8.1 Docker 服务管理

bash 复制代码

sudo systemctl status docker        # 查看状态
sudo systemctl start docker         # 启动
sudo systemctl stop docker          # 停止
sudo systemctl restart docker       # 重启（不可靠时用 killall）
sudo journalctl -u docker -f        # 查看日志

8.2 镜像操作

bash 复制代码

docker images                       # 列出本地镜像
docker search nginx                 # 搜索镜像（若镜像源支持）
docker pull nginx:1.27              # 拉取镜像
docker rmi nginx:1.27               # 删除镜像
docker image prune -a               # 清理未使用镜像
docker tag nginx:1.27 mynginx:v1    # 打标签

8.3 容器操作

bash 复制代码

docker ps -a                        # 列出所有容器
docker run -d --name web -p 80:80 nginx:1.27   # 后台启动
docker logs -f web                  # 查看日志
docker exec -it web bash            # 进入容器
docker stop web                     # 停止容器
docker start web                    # 启动容器
docker rm -f web                    # 强制删除容器

8.4 docker compose（v2 插件）

bash 复制代码

docker compose up -d                # 后台启动
docker compose down                 # 停止并删除
docker compose ps                   # 查看状态
docker compose logs -f              # 查看日志
docker compose pull                 # 拉取所有镜像
docker compose exec web bash        # 进入服务

8.5 网络与卷

bash 复制代码

docker network ls                   # 网络列表
docker network create mynet         # 创建网络
docker volume ls                    # 卷列表
docker volume create mydata         # 创建卷
docker system df                    # 磁盘占用
docker system prune -a              # 清理所有未使用资源

附录 A：本教程实测环境快照

text 复制代码

OS:           Ubuntu 26.04 LTS (resolute)
Kernel:       6.18.33.1-microsoft-standard-WSL2
CPU:          Intel i9-12900H (10C/20T)
Memory:       23 GiB
Disk:         1 TB (3.3 GB used)
systemd:      PID 1 = systemd
cgroup:       v2 (cgroup2fs)
Docker:       29.6.1
Compose:      v5.2.0
containerd:   2.2.5
runc:         1.3.6
Storage:      overlay2 (经典模式，containerd-snapshotter=false)
User:         lhz (sudo + docker 组)

附录 B：配置文件最终样例

`/etc/docker/daemon.json`

json 复制代码

{
  "features": {
    "containerd-snapshotter": false
  },
  "registry-mirrors": [
    "https://docker.xuanyuan.me",
    "https://docker.1ms.run",
    "https://docker.m.daocloud.io"
  ],
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "100m",
    "max-file": "3"
  },
  "storage-driver": "overlay2"
}

`/etc/apt/sources.list.d/docker.list`

复制代码

deb [arch=amd64 signed-by=/etc/apt/keyrings/docker.gpg] https://mirrors.aliyun.com/docker-ce/linux/ubuntu resolute stable

在 Ubuntu 26.04 (WSL2) 上通过阿里云镜像源安装 Docker CE 完整教程