Ubuntu Docker 安装手册

一、前言

本文档提供在 Ubuntu 系统上安装 Docker Engine 的完整指南，包含多种安装方法、配置说明以及常见问题解决方案。

支持的 Ubuntu 版本

Docker Engine 支持以下 64 位 Ubuntu 版本：

Ubuntu 版本	代号	支持状态
Ubuntu 26.04	Resolute (LTS)	✅ 支持
Ubuntu 25.10	Questing	✅ 支持
Ubuntu 24.04	Noble (LTS)	✅ 推荐
Ubuntu 22.04	Jammy (LTS)	✅ 推荐

支持的架构

x86_64 (amd64)
armhf
arm64
s390x
ppc64le (ppc64el)

注意：Linux Mint 等 Ubuntu 衍生发行版未经官方支持（尽管可能可以工作）。

二、前置条件检查

2.1 系统版本检查

bash 复制代码

# 查看 Ubuntu 版本
cat /etc/os-release

# 查看系统架构
uname -m

# 查看内核版本（建议 3.10 及以上）
uname -r

# 查看系统是否为 64 位
dpkg --print-architecture

2.2 防火墙注意事项

⚠️ 警告

安装 Docker 前，请注意以下安全影响和防火墙兼容性问题：

如果使用 ufw 或 firewalld 管理防火墙设置，请注意当使用 Docker 暴露容器端口时，这些端口会绕过防火墙规则。
Docker 仅兼容 iptables-nft 和 iptables-legacy，不支持使用 nft 创建的防火墙规则。
确保任何防火墙规则集都使用 iptables 或 ip6tables 创建，并将它们添加到 DOCKER-USER 链。

2.3 检查现有 Docker 安装

bash 复制代码

# 检查是否已安装 Docker
docker --version

# 检查已安装的 Docker 相关包
dpkg -l | grep -i docker

# 检查 Docker 服务状态
systemctl status docker 2>/dev/null || echo "Docker 服务未安装或未运行"

三、卸载旧版本

3.1 卸载冲突包

在安装 Docker Engine 之前，需要卸载任何冲突的软件包：

bash 复制代码

# 卸载非官方 Docker 包和冲突包
sudo apt remove $(dpkg --get-selections docker.io docker-compose docker-compose-v2 docker-doc podman-docker containerd runc | cut -f1)

3.2 需要卸载的冲突包清单

包名	说明
`docker.io`	Ubuntu 官方仓库提供的 Docker
`docker-compose`	Docker Compose 旧版本
`docker-compose-v2`	Docker Compose v2
`docker-doc`	Docker 文档包
`podman-docker`	Podman 兼容包
`containerd`	独立的 containerd
`runc`	独立的 runc

注意：存储在 /var/lib/docker/ 中的镜像、容器、卷和网络在卸载 Docker 时不会自动删除。

3.3 完全清理（可选）

如果需要彻底清理所有 Docker 数据：

bash 复制代码

# 停止 Docker 服务
sudo systemctl stop docker 2>/dev/null || true

# 删除 Docker 数据目录
sudo rm -rf /var/lib/docker
sudo rm -rf /var/lib/containerd

# 删除配置文件
sudo rm -rf /etc/docker

# 删除 apt 源配置
sudo rm -f /etc/apt/sources.list.d/docker.*
sudo rm -rf /etc/apt/keyrings/docker.asc

四、安装方法

Docker 提供多种安装方式，根据需求选择：

方法	适用场景	难度	推荐度
APT 仓库安装	生产环境、长期维护	中	⭐⭐⭐⭐⭐
手动安装 DEB 包	离线环境、特殊需求	中	⭐⭐⭐
便捷脚本安装	测试环境、快速体验	低	⭐⭐

方法一：使用 APT 仓库安装（推荐）

这是官方推荐的安装方式，便于后续升级和维护。

步骤 1：更新系统并安装依赖

bash 复制代码

# 更新包索引
sudo apt update

# 安装必要的依赖包
sudo apt install -y \
    ca-certificates \
    curl \
    gnupg \
    lsb-release \
    apt-transport-https \
    software-properties-common

步骤 2：添加 Docker 官方 GPG 密钥

bash 复制代码

# 创建 keyrings 目录
sudo install -m 0755 -d /etc/apt/keyrings

# 下载 Docker 官方 GPG 密钥
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc

# 设置适当的权限
sudo chmod a+r /etc/apt/keyrings/docker.asc

步骤 3：添加 Docker APT 仓库

bash 复制代码

# 添加 Docker 仓库到 APT 源
sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

# 更新包索引
sudo apt update

步骤 4：安装 Docker Engine

安装最新版本：

bash 复制代码

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

安装特定版本：

bash 复制代码

# 查看可用版本列表
apt list --all-versions docker-ce

# 示例输出：
# docker-ce/noble 5:29.4.3-1~ubuntu.24.04~noble amd64
# docker-ce/noble 5:29.4.2-1~ubuntu.24.04~noble amd64

# 安装指定版本（替换为实际版本号）
VERSION_STRING="5:29.4.3-1~ubuntu.24.04~noble"
sudo apt install -y docker-ce=$VERSION_STRING docker-ce-cli=$VERSION_STRING containerd.io docker-buildx-plugin docker-compose-plugin

安装的包说明：

包名	说明
`docker-ce`	Docker Engine（社区版）
`docker-ce-cli`	Docker 命令行工具
`containerd.io`	容器运行时
`docker-buildx-plugin`	Docker Buildx 构建插件
`docker-compose-plugin`	Docker Compose 插件

方法二：手动安装 DEB 包

适用于离线环境或无法访问 Docker 仓库的情况。

步骤 1：下载 DEB 包

访问 https://download.docker.com/linux/ubuntu/dists/，按以下路径下载：

选择你的 Ubuntu 版本（如 noble、jammy）
进入 pool/stable/ 目录
选择系统架构（amd64、armhf、arm64 等）
下载以下文件：
- containerd.io_<版本>_<架构>.deb
- docker-ce_<版本>_<架构>.deb
- docker-ce-cli_<版本>_<架构>.deb
- docker-buildx-plugin_<版本>_<架构>.deb
- docker-compose-plugin_<版本>_<架构>.deb

步骤 2：安装 DEB 包

bash 复制代码

# 进入下载目录
cd ~/downloads

# 安装所有 DEB 包
sudo dpkg -i ./containerd.io_*.deb \
  ./docker-ce_*.deb \
  ./docker-ce-cli_*.deb \
  ./docker-buildx-plugin_*.deb \
  ./docker-compose-plugin_*.deb

# 如果提示依赖问题，修复依赖
sudo apt-get install -f

方法三：使用便捷脚本安装

⚠️ 警告：仅推荐用于测试和开发环境，不推荐用于生产环境。

步骤 1：预览脚本（可选）

bash 复制代码

# 下载脚本
curl -fsSL https://get.docker.com -o get-docker.sh

# 预览将要执行的步骤
sudo sh ./get-docker.sh --dry-run

步骤 2：执行安装

bash 复制代码

# 运行安装脚本
sudo sh get-docker.sh

安装预发布版本

bash 复制代码

# 下载测试版脚本
curl -fsSL https://test.docker.com -o test-docker.sh

# 执行安装
sudo sh test-docker.sh

五、服务配置

5.1 创建 Docker 配置目录

bash 复制代码

sudo mkdir -p /etc/docker

5.2 配置 Docker Daemon

创建 daemon.json 配置文件：

bash 复制代码

sudo tee /etc/docker/daemon.json <<'EOF'
{
  "data-root": "/var/lib/docker",
  "storage-driver": "overlay2",
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "100m",
    "max-file": "3"
  },
  "live-restore": true,
  "exec-opts": ["native.cgroupdriver=systemd"],
  "registry-mirrors": [
    "https://docker.mirrors.ustc.edu.cn",
    "https://hub-mirror.c.163.com",
    "https://mirror.baidubce.com"
  ]
}
EOF

5.3 配置说明

配置项	说明	默认值
`data-root`	Docker 数据存储目录	`/var/lib/docker`
`storage-driver`	存储驱动，推荐 `overlay2`	`overlay2`
`log-driver`	日志驱动	`json-file`
`log-opts.max-size`	单个日志文件最大大小	`100m`
`log-opts.max-file`	日志文件保留数量	`3`
`live-restore`	Docker 重启时保持容器运行	`true`
`exec-opts`	使用 systemd 管理 cgroups	-
`registry-mirrors`	镜像加速地址	-

5.4 配置镜像加速（中国大陆用户）

编辑 /etc/docker/daemon.json 添加镜像加速：

bash 复制代码

sudo tee /etc/docker/daemon.json <<'EOF'
{
  "registry-mirrors": [
    "https://docker.mirrors.ustc.edu.cn",
    "https://hub-mirror.c.163.com",
    "https://mirror.baidubce.com",
    "https://ccr.ccs.tencentyun.com"
  ]
}
EOF

常用镜像加速源：

镜像源	地址
中科大	`https://docker.mirrors.ustc.edu.cn`
网易云	`https://hub-mirror.c.163.com`
百度云	`https://mirror.baidubce.com`
腾讯云	`https://ccr.ccs.tencentyun.com`
阿里云	`https://<你的ID>.mirror.aliyuncs.com`

六、启动与验证

6.1 启动 Docker 服务

bash 复制代码

# 重新加载 systemd 配置
sudo systemctl daemon-reload

# 启动 Docker
sudo systemctl start docker

# 设置开机自启
sudo systemctl enable docker

# 查看 Docker 状态
sudo systemctl status docker

6.2 验证安装

bash 复制代码

# 查看 Docker 版本
docker --version

# 查看 Docker 详细信息
sudo docker info

# 运行测试容器
sudo docker run hello-world

预期输出：

复制代码

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

6.3 验证 Docker Compose

bash 复制代码

# 查看 Docker Compose 版本
docker compose version

# 或者旧版命令
docker-compose --version

6.4 检查已安装的包

bash 复制代码

# 查看已安装的 Docker 相关包
dpkg -l | grep docker

# 预期输出示例：
# ii  docker-buildx-plugin   0.14.0-1~ubuntu.24.04~noble   amd64
# ii  docker-ce              5:26.1.3-1~ubuntu.24.04~noble amd64
# ii  docker-ce-cli          5:26.1.3-1~ubuntu.24.04~noble amd64
# ii  docker-compose-plugin  2.27.0-1~ubuntu.24.04~noble   amd64

七、用户权限配置

7.1 创建 docker 用户组

安装 Docker 时会自动创建 docker 用户组，如果没有则手动创建：

bash 复制代码

# 创建 docker 组
sudo groupadd docker 2>/dev/null || echo "docker 组已存在"

7.2 将用户添加到 docker 组

bash 复制代码

# 将当前用户加入 docker 组
sudo usermod -aG docker $USER

# 或者指定特定用户
sudo usermod -aG docker username

7.3 使权限生效

bash 复制代码

# 方法 1：重新登录（推荐）
# 注销并重新登录系统

# 方法 2：使用 newgrp（临时生效）
newgrp docker

# 验证无需 sudo 运行 docker
docker run hello-world

7.4 验证非 root 用户使用 Docker

bash 复制代码

# 测试非 root 用户运行 Docker
docker ps

# 如果报错 "permission denied"，检查：
# 1. 用户是否在 docker 组：groups $USER
# 2. docker.sock 权限：ls -la /var/run/docker.sock

八、常见问题与故障排除

8.1 安装问题

问题 1：无法添加 GPG 密钥

症状：

复制代码

curl: (35) error:0A000126:SSL routines::unexpected eof while reading

解决方案：

bash 复制代码

# 使用备用方式添加密钥
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 9DC858229FC7DD38854AE2D88D81803C0EBFCD88

问题 2：无法找到包

症状：

复制代码

E: Unable to locate package docker-ce

解决方案：

bash 复制代码

# 1. 检查仓库是否正确添加
cat /etc/apt/sources.list.d/docker.sources

# 2. 更新包索引
sudo apt update

# 3. 检查系统版本是否受支持
cat /etc/os-release | grep VERSION_CODENAME

问题 3：依赖问题

症状：

复制代码

dpkg: dependency problems prevent configuration of docker-ce

解决方案：

bash 复制代码

# 修复依赖关系
sudo apt-get install -f

# 清理并重新安装
sudo apt clean
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io

8.2 服务启动问题

问题 1：Docker 无法启动

诊断步骤：

bash 复制代码

# 查看详细错误日志
sudo journalctl -u docker.service -xe

# 检查配置文件语法
sudo dockerd --config-file /etc/docker/daemon.json --validate

# 手动启动查看错误
sudo dockerd

常见原因及解决：

原因	解决方案
配置文件语法错误	检查 `/etc/docker/daemon.json` JSON 格式
存储驱动不支持	修改 `storage-driver` 为 `vfs` 或其他支持的驱动
端口冲突	检查是否有其他服务占用 Docker 端口

问题 2：存储驱动错误

症状：

复制代码

Error starting daemon: error initializing graphdriver: driver not supported

解决方案：

bash 复制代码

# 检查支持的存储驱动
sudo docker info 2>/dev/null | grep "Storage Driver" || echo "Docker 未运行"

# 修改存储驱动
sudo tee /etc/docker/daemon.json <<'EOF'
{
  "storage-driver": "overlay2"
}
EOF

sudo systemctl restart docker

8.3 网络问题

问题 1：无法拉取镜像

症状：

复制代码

Error response from daemon: Get "https://registry-1.docker.io/v2/": net/http: request canceled

解决方案：

bash 复制代码

# 1. 检查网络连接
ping registry-1.docker.io

# 2. 配置 DNS
sudo tee /etc/docker/daemon.json <<'EOF'
{
  "dns": ["8.8.8.8", "8.8.4.4"]
}
EOF

# 3. 配置镜像加速（中国大陆）
# 参见第五章配置镜像加速

# 4. 重启 Docker
sudo systemctl restart docker

问题 2：容器无法访问外网

诊断：

bash 复制代码

# 测试容器网络
docker run --rm busybox ping -c 4 8.8.8.8

# 检查 iptables
sudo iptables -L -n | grep DOCKER

# 检查 IP 转发
sysctl net.ipv4.ip_forward

解决方案：

bash 复制代码

# 开启 IP 转发
echo "net.ipv4.ip_forward=1" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

# 重启 Docker
sudo systemctl restart docker

8.4 权限问题

问题 1：权限被拒绝

症状：

复制代码

got permission denied while trying to connect to the Docker daemon socket

解决方案：

bash 复制代码

# 1. 检查用户是否在 docker 组
groups $USER

# 2. 如果没有，添加用户
sudo usermod -aG docker $USER

# 3. 重新登录或执行
newgrp docker

# 4. 检查 docker.sock 权限
ls -la /var/run/docker.sock

# 5. 修复权限（临时）
sudo chmod 666 /var/run/docker.sock

问题 2：SELinux/AppArmor 限制

诊断：

bash 复制代码

# 检查 SELinux 状态
getenforce 2>/dev/null || echo "SELinux 未安装"

# 检查 AppArmor 状态
sudo aa-status

解决方案：

bash 复制代码

# 临时禁用 SELinux（不推荐长期使用）
sudo setenforce 0

# 或为 Docker 添加规则
# 参见官方文档配置 SELinux/AppArmor 策略

8.5 性能问题

问题 1：Docker 占用磁盘空间过大

诊断：

bash 复制代码

# 查看 Docker 磁盘使用情况
docker system df -v

# 查看日志文件大小
sudo du -sh /var/lib/docker/containers/*/local-logs

清理方案：

bash 复制代码

# 清理未使用的数据
docker system prune -a --volumes

# 清理日志（配置日志轮转）
sudo tee /etc/docker/daemon.json <<'EOF'
{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}
EOF

sudo systemctl restart docker

8.6 升级问题

升级 Docker Engine

bash 复制代码

# 方法 1：使用 apt 升级（推荐）
sudo apt update
sudo apt upgrade docker-ce docker-ce-cli containerd.io

# 方法 2：安装特定版本
VERSION_STRING="5:29.4.3-1~ubuntu.24.04~noble"
sudo apt install docker-ce=$VERSION_STRING docker-ce-cli=$VERSION_STRING

九、卸载 Docker

9.1 卸载 Docker 包

bash 复制代码

# 卸载 Docker Engine、CLI、containerd 和 Docker Compose
sudo apt purge -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin docker-ce-rootless-extras

# 自动删除不需要的依赖
sudo apt autoremove -y

9.2 删除 Docker 数据

⚠️ 警告：这将删除所有镜像、容器、卷和自定义配置，操作不可逆！

bash 复制代码

# 删除 Docker 数据目录
sudo rm -rf /var/lib/docker
sudo rm -rf /var/lib/containerd

# 删除配置文件
sudo rm -rf /etc/docker

# 删除 APT 源配置
sudo rm -f /etc/apt/sources.list.d/docker.*
sudo rm -f /etc/apt/keyrings/docker.asc

# 删除便捷脚本（如果使用）
rm -f get-docker.sh test-docker.sh

9.3 删除 docker 用户组（可选）

bash 复制代码

# 从所有用户中移除 docker 组
sudo delgroup docker

十、附录

10.1 常用命令速查

Docker 服务管理

bash 复制代码

# 启动 Docker
sudo systemctl start docker

# 停止 Docker
sudo systemctl stop docker

# 重启 Docker
sudo systemctl restart docker

# 查看状态
sudo systemctl status docker

# 开机自启
sudo systemctl enable docker

# 禁用开机自启
sudo systemctl disable docker

# 查看日志
sudo journalctl -u docker.service -f

Docker 容器管理

bash 复制代码

# 运行容器
docker run -d --name myapp -p 8080:80 nginx:alpine

# 查看运行中的容器
docker ps

# 查看所有容器
docker ps -a

# 停止容器
docker stop myapp

# 启动容器
docker start myapp

# 删除容器
docker rm myapp

# 查看容器日志
docker logs -f myapp

# 进入容器
docker exec -it myapp /bin/sh

Docker 镜像管理

bash 复制代码

# 查看本地镜像
docker images

# 拉取镜像
docker pull nginx:alpine

# 删除镜像
docker rmi nginx:alpine

# 构建镜像
docker build -t myapp:latest .

# 给镜像打标签
docker tag myapp:latest myapp:v1.0

# 推送镜像到仓库
docker push myapp:v1.0

Docker Compose 管理

bash 复制代码

# 启动服务
docker compose up -d

# 停止服务
docker compose down

# 查看服务状态
docker compose ps

# 查看日志
docker compose logs -f

# 重启服务
docker compose restart

# 构建镜像
docker compose build

系统清理

bash 复制代码

# 清理未使用的容器、网络、镜像和缓存
docker system prune

# 清理所有未使用的数据（包括卷）
docker system prune -a --volumes

# 清理 dangling 镜像
docker image prune

# 清理未使用的卷
docker volume prune

# 清理构建缓存
docker builder prune

10.2 推荐镜像清单

镜像名称	用途	推荐标签	拉取命令
nginx	Web 服务器	alpine	`docker pull nginx:alpine`
redis	缓存数据库	alpine	`docker pull redis:alpine`
mysql	关系型数据库	8.0	`docker pull mysql:8.0`
postgres	关系型数据库	alpine	`docker pull postgres:alpine`
mongo	文档数据库	latest	`docker pull mongo`
node	Node.js 运行时	lts-alpine	`docker pull node:lts-alpine`
python	Python 运行时	3.11-slim	`docker pull python:3.11-slim`
alpine	轻量基础镜像	latest	`docker pull alpine`
busybox	基础工具	latest	`docker pull busybox`

10.3 官方资源

资源	链接
Docker 官方文档	https://docs.docker.com/
Ubuntu 安装指南	https://docs.docker.com/engine/install/ubuntu/
Docker Hub	https://hub.docker.com/
Docker GitHub	https://github.com/docker/docker-ce
安装脚本仓库	https://github.com/docker/docker-install

10.4 故障排除检查清单

在提交问题报告前，请确认以下信息：

Ubuntu 版本和架构：
bash 复制代码
```
cat /etc/os-release && uname -m
```

Docker 版本：

bash 复制代码

docker version 2>/dev/null || echo "Docker 未安装"

Docker 服务状态：
bash 复制代码
```
sudo systemctl status docker
```

错误日志：

bash 复制代码

sudo journalctl -u docker.service --no-pager -n 50

系统资源：
bash 复制代码
```
df -h && free -h
```

文档信息

最后更新：2026-05-09
适用系统：Ubuntu 22.04/24.04/25.10/26.04 (LTS)
Docker 版本 ：26.x / 27.x / 28.x / 29.x
小黑蛋

注意：本文档基于 Docker 官方文档编写，建议定期查看官方文档获取最新信息。