在 Ubuntu 26.04 上安装 Docker CE 教程

在 Ubuntu 26.04 上安装 Docker CE 教程

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

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

目录

1. 环境检测
2. Docker CE 安装
3. 镜像加速器配置
4. 用户组配置
5. 验证
6. 常见问题排查
7. 常用命令速查

1. 环境检测

1.1 系统信息

uname-acat/etc/os-release

应看到：

PRETTY_NAME="Ubuntu 26.04 LTS" VERSION_CODENAME=resolute

1.2 关键依赖检查

# cgroup v2 必须挂载stat-fc%T /sys/fs/cgroup/# 应输出 cgroup2fs# 必须有 curlcurl--version|head-1# 必须有 iptables 或 nftableswhichiptables||whichnft

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

1.3 用户与磁盘

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

1.4 阿里云镜像可达性

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 预装系统依赖

sudoapt-getupdatesudoapt-getinstall-yca-certificatescurlgnupg iptables

2.2 添加阿里云 Docker GPG 公钥

sudoinstall-m0755-d/etc/apt/keyringscurl-fsSLhttps://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg\|sudogpg--dearmor-o/etc/apt/keyrings/docker.gpgsudochmoda+r /etc/apt/keyrings/docker.gpg

2.3 写入阿里云 apt 源

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"\|sudotee/etc/apt/sources.list.d/docker.list>/dev/null

2.4 安装 Docker CE 及全家桶

sudoapt-getupdatesudoapt-getinstall-ydocker-ce docker-ce-cli containerd.io\docker-buildx-plugin docker-compose-plugin

2.5 启动并设置开机自启

sudosystemctlenable--nowdockersudosystemctlenable--nowcontainerd

2.6 验证版本

docker--version# Docker Engine 版本dockercompose version# Compose 插件版本（注意是空格）containerd--versionsudosystemctl is-activedocker# 应输出 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

sudotee/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。

sudosystemctl stopdockercontainerdsudokillall-9dockerd containerd2>/dev/nullsleep3sudosystemctl start containerdsudosystemctl startdockersleep4

3.4 验证配置生效

sudodockerinfo|grep-A4"Registry Mirrors:"sudodockerinfo|grep-A2"Storage Driver"

预期输出：

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

4. 用户组配置

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

sudousermod-aGdocker$USERid$USER|grepdocker# 应包含 (docker)

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

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

5. 验证

5.1 拉取并运行 hello-world

sudodockerpull hello-worldsudodockerrun--rmhello-world

预期结尾输出：

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

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

dockerpsdockerimagesdockercompose version

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

5.3 验证 compose 插件

mkdir-p/tmp/test-compose&&cd/tmp/test-composecat>docker-compose.yml<<'EOF' services: hello: image: hello-world EOFsudodockercompose 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 部署：

sudomv/etc/apt/sources.list.d/mysql.list /etc/apt/sources.list.d/mysql.list.baksudoapt-getupdate

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

sudousermod-aGdockeruser1sudousermod-aGdockeruser2# 这些用户重新登录后均免 sudo 使用 docker

7. 常用命令速查

7.1 Docker 服务管理

sudosystemctl statusdocker# 查看状态sudosystemctl startdocker# 启动sudosystemctl stopdocker# 停止sudosystemctl restartdocker# 重启（不可靠时用 killall）sudojournalctl-udocker-f# 查看日志

7.2 镜像操作

dockerimages# 列出本地镜像dockersearch nginx# 搜索镜像（若镜像源支持）dockerpull nginx:1.27# 拉取镜像dockerrmi nginx:1.27# 删除镜像dockerimage prune-a# 清理未使用镜像dockertag nginx:1.27 mynginx:v1# 打标签

7.3 容器操作

dockerps-a# 列出所有容器dockerrun-d--nameweb-p80:80 nginx:1.27# 后台启动dockerlogs-fweb# 查看日志dockerexec-itwebbash# 进入容器dockerstop web# 停止容器dockerstart web# 启动容器dockerrm-fweb# 强制删除容器

7.4 docker compose（v2 插件）

dockercompose up-d# 后台启动dockercompose down# 停止并删除dockercomposeps# 查看状态dockercompose logs-f# 查看日志dockercompose pull# 拉取所有镜像dockercomposeexecwebbash# 进入服务

7.5 网络与卷

dockernetworkls# 网络列表dockernetwork create mynet# 创建网络dockervolumels# 卷列表dockervolume create mydata# 创建卷dockersystemdf# 磁盘占用dockersystem prune-a# 清理所有未使用资源

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

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

{"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：与原教程的差异说明