Ubuntu 系统 Docker 安装避坑指南

前言

针对安装过程中出现的 "无法连接 Docker 官方服务器" 、"GPG 密钥文件冲突" 、"SSL 连接重置" 等问题，本方案全程使用国内阿里云镜像源，彻底避开官方服务器访问瓶颈，同时提供分步操作说明与错误处理机制，确保新手也能顺利完成安装。

一、准备工作

1. 系统要求

• 支持版本：Ubuntu 20.04 LTS / Ubuntu 22.04 LTS（64位，推荐官方 LTS 版本以保证稳定性）
• 权限要求：拥有 sudo 权限（普通用户需确保能执行管理员命令）
• 网络要求：能访问互联网（国内网络环境即可，无需科学上网）

2. 系统更新与旧版本卸载

若之前安装过 Docker 旧版本或残留文件，需先清理，避免冲突：

# 1. 更新系统包索引，确保依赖包为最新
sudo apt-get update && sudo apt-get upgrade -y

# 2. 卸载旧版 Docker 相关组件
sudo apt-get remove -y docker.io docker-ce docker-ce-cli containerd.io docker-compose-plugin

# 3. 删除 Docker 数据目录（避免残留配置干扰新安装）
sudo rm -rf /var/lib/docker /var/lib/containerd

二、核心安装步骤（全程国内镜像源）

1. 安装必要依赖包

Docker 安装需依赖证书、curl 等工具，先提前安装：

sudo apt-get install -y ca-certificates curl gnupg lsb-release apt-transport-https

• ca-certificates：用于验证 HTTPS 仓库的证书
• apt-transport-https：允许 apt 通过 HTTPS 协议下载软件包

2. 配置阿里云 Docker 镜像源（关键避坑步骤）

核心问题：直接访问 Docker 官方源（download.docker.com）易出现网络超时或连接重置，改用阿里云镜像源可大幅提升成功率。

# 1. 创建 GPG 密钥存储目录（若不存在则自动创建）
sudo mkdir -p /etc/apt/keyrings

# 2. 下载阿里云 Docker GPG 密钥（自动覆盖已存在的密钥文件，无需手动确认）
curl -fsSL https://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg | sudo gpg --dearmor --yes -o /etc/apt/keyrings/docker.gpg

# 3. 添加阿里云 Docker 仓库到系统源列表
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://mirrors.aliyun.com/docker-ce/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 4. 设置密钥文件权限（确保 apt 能正常读取密钥）
sudo chmod a+r /etc/apt/keyrings/docker.gpg

• --yes：自动覆盖已存在的 docker.gpg 文件，避免 "文件已存在" 的交互提示
• $(dpkg --print-architecture)：自动识别系统架构（如 amd64、arm64）
• $(lsb_release -cs)：自动识别 Ubuntu 版本代号（如 22.04 对应 jammy，20.04 对应 focal）

3. 安装 Docker 核心组件

# 1. 更新包索引（让系统识别新添加的阿里云 Docker 仓库）
sudo apt-get update

# 2. 安装 Docker 引擎、CLI、容器运行时及 Compose 插件
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

特殊情况处理：服务重启确认界面

若安装过程中弹出 "服务重启选择" 界面：

• 无需手动勾选，系统默认已选中需重启的必要服务（如 containerd、网络服务等）
• 按 Tab 键切换光标到 选项，再按 Enter 键确认即可
• 作用：重启依赖服务以适配新安装的 Docker 组件，确保功能正常

三、权限配置（可选但推荐）

默认情况下，docker 命令需通过 sudo 执行（如 sudo docker run），将当前用户添加到 docker 用户组，可避免每次输入 sudo：

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

# 提示：需注销当前用户并重新登录，权限设置才会生效
echo "权限配置完成！请注销当前会话并重新登录，即可直接使用 docker 命令（无需 sudo）"

四、验证安装（确认 Docker 正常工作）

安装完成后，通过以下命令验证是否成功：

1. 验证 Docker 版本

# 查看 Docker 引擎版本
docker --version
# 示例输出：Docker version 24.0.6, build ed223bc

# 查看 Docker Compose 版本（Compose 已集成到 Docker 插件中）
docker compose version
# 示例输出：Docker Compose version v2.20.3

2. 运行测试容器（核心验证步骤）

通过运行官方 hello-world 容器，确认 Docker 引擎能正常启动容器：

# 若已配置用户组权限，可去掉 sudo；未配置则需加 sudo
sudo docker run --rm hello-world

成功标志：

终端输出以下内容，说明 Docker 安装成功且能正常拉取镜像、运行容器：

Hello from Docker!
This message shows that your installation appears to be working correctly.
...（后续为 Docker 工作原理说明，可忽略）

五、常见问题处理（针对安装失败的补救措施）

1. 问题：执行 apt-get update 时仍提示 "网络连接失败"

原因：DNS 配置异常，无法解析阿里云镜像源域名。解决方法：手动配置阿里云 DNS：

# 1. 添加阿里云 DNS 到系统配置
echo "nameserver 223.5.5.5" | sudo tee -a /etc/resolv.conf
echo "nameserver 223.6.6.6" | sudo tee -a /etc/resolv.conf

# 2. 重启网络服务使 DNS 配置生效
sudo systemctl restart systemd-resolved

# 3. 重新更新包索引
sudo apt-get update

2. 问题：需要安装特定版本的 Docker（如兼容旧项目）

解决方法：先列出可用版本，再指定版本安装：

# 1. 列出阿里云仓库中可用的 Docker 版本
apt-cache madison docker-ce

# 2. 安装指定版本（以 24.0.6 为例，需替换为实际需要的版本）
sudo apt-get install -y docker-ce=5:24.0.6-1~ubuntu.22.04~jammy docker-ce-cli=5:24.0.6-1~ubuntu.22.04~jammy containerd.io docker-compose-plugin

六、Docker 服务管理（日常运维常用命令）

操作需求	命令
启动 Docker 服务	sudo systemctl start docker
停止 Docker 服务	sudo systemctl stop docker
重启 Docker 服务	sudo systemctl restart docker
设置 Docker 开机自启	sudo systemctl enable docker
关闭 Docker 开机自启	sudo systemctl disable docker
查看 Docker 服务状态	sudo systemctl status docker

总结

本方案通过以下核心措施规避安装错误：

• 全程阿里云镜像源：替代官方源，解决网络超时、连接重置问题
• 自动覆盖密钥文件：用 --yes 参数跳过 "文件已存在" 的交互提示
• 分步清理旧版本：避免残留配置与新版本冲突
• 提供 DNS 补救方案：解决国内网络环境下的域名解析问题

按照此文档操作，可在 Ubuntu 系统中稳定完成 Docker 及 Docker Compose 的安装，适用于开发、测试及生产环境。