在 Ubuntu 26.04 上安装 Docker CE 教程

适用环境 ：Ubuntu 26.04 LTS（resolute）、原生 Linux（非 WSL2）、国内网络

本教程特点：去掉 WSL2 冗余检测，保留国内镜像源与 Docker 29 containerd-snapshotter bug 修复，从零到 hello-world 仅需 7 条命令。

1. 环境检测

1.1 系统信息

bash 复制代码

uname -a
cat /etc/os-release

应看到：

复制代码

PRETTY_NAME="Ubuntu 26.04 LTS"
VERSION_CODENAME=resolute

1.2 关键依赖检查

bash 复制代码

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

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

# 必须有 iptables 或 nftables
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 可用

1.4 阿里云镜像可达性

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。

2. Docker CE 安装

2.1 预装系统依赖

bash 复制代码

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg iptables

2.2 添加阿里云 Docker GPG 公钥

bash 复制代码

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

2.3 写入阿里云 apt 源

bash 复制代码

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

2.4 安装 Docker CE 及全家桶

bash 复制代码

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io \
                        docker-buildx-plugin docker-compose-plugin

2.5 启动并设置开机自启

bash 复制代码

sudo systemctl enable --now docker
sudo systemctl enable --now containerd

2.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

3. 镜像加速器配置

3.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 模式。

3.2 写入 daemon.json

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

3.3 强制重启服务

systemctl restart 在某些场景下不会完全重启 dockerd，必须 kill -9。

bash 复制代码

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

3.4 验证配置生效

bash 复制代码

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

预期输出：

复制代码

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

 Storage Driver: overlay2

4. 用户组配置

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

bash 复制代码

sudo usermod -aG docker $USER
id $USER | grep docker        # 应包含 (docker)

组成员关系需要重新登录才能生效。在当前 shell 临时生效：

bash 复制代码

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

5. 验证

5.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.
...

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

bash 复制代码

docker ps
docker images
docker compose version

如果当前 shell 还没生效，可用 sg docker -c 'docker ps' 临时验证。

5.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

预期：容器启动并打印 Hello from Docker!，退出码 0。

6. 常见问题排查

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 失效。

解决：参见 §3.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

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

解决：

在终端 exit 后重新进入
或在当前 shell 执行 newgrp docker
或使用 sg docker -c 'docker ...' 临时以 docker 组身份执行

Q5：第三方源（如 MySQL 官方）报 `Release 404`

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

原因：第三方源尚未支持 Ubuntu 26.04 codename。

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

bash 复制代码

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

7. 常用命令速查

7.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        # 查看日志

7.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    # 打标签

7.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                    # 强制删除容器

7.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        # 进入服务

7.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:       7.0.0-27-generic（原生 Linux，非 WSL2）
APT 源:       mirrors.aliyun.com/ubuntu + mirrors.aliyun.com/docker-ce
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

附录 C：与原教程的差异说明

项目	原教程（WSL2 版）	本教程（精简版）
适用环境	WSL2（systemd 启用）	原生 Linux
systemd 检测	需要 `ps -p 1 -o comm=`	不需要
WSL2 特定步骤	`/etc/wsl.conf` systemd 配置	无
添加阿里云源	✓	✓
关闭 snapshotter	✓	✓
镜像加速器	✓	✓
killall -9 重启	✓	✓
用户组配置	✓	✓
验证流程	hello-world + compose	同上（更详细）

在 Ubuntu 26.04 上安装 Docker CE 教程