Ubuntu系统Docker安装配置全攻略:从零到精通的避坑指南
1. 为什么在Ubuntu上安装Docker值得你花时间
如果你正在看这篇文章,大概率是刚接触Ubuntu或者Docker,甚至两者都是。你可能会想,网上教程那么多,随便找一个不就行了?确实,在Ubuntu上安装Docker的命令行操作,核心就那么几步,很多文章几分钟就能讲完。但为什么我还要写这篇“最详细”的教程?因为我在过去几年里,见过太多人卡在那些看似简单、实则暗藏玄机的环节上。比如,安装后
docker
命令必须用
sudo
,否则就报权限错误;或者安装时因为网络问题,一个简单的
apt update
都能卡半天;更常见的是,安装完Docker Desktop后,系统提示“Virtualization support not detected”,直接启动失败,让人一头雾水。
这些坑,我都踩过。所以这篇教程的目的,不仅仅是让你把Docker装上,更是让你理解每一步背后的逻辑,知道为什么会出问题,以及出了问题该怎么解决。我会从最基础的准备工作讲起,涵盖 APT仓库安装 和 便捷脚本安装 两种最主流的方法,并详细解释它们的优劣。更重要的是,我会花大量篇幅讲解安装后的 必备配置 和 排错指南 ,这些都是你真正开始使用Docker前必须跨过的门槛。文末的“干货大礼包”也不是虚的,我会分享一套我日常在用的Docker命令速查清单、镜像加速配置以及几个能极大提升效率的Docker Compose模板。
无论你是刚装好Ubuntu的开发新手,还是需要在服务器上部署容器的运维,这篇文章都能帮你建立一个清晰、稳固的起点。我们不止步于“能用”,更要追求“好用”和“懂用”。
2. 安装前的核心准备:避开80%的失败陷阱
很多人安装失败,问题往往出在准备工作没做好。直接执行安装命令,就像没看说明书就组装家具,很容易把螺丝拧错地方。这一章,我们就来彻底搞定安装前的环境,确保你的系统已经为Docker铺好了路。
2.1 系统架构与版本确认:选对跑道
首先,打开你的终端。我们需要确认两件事:系统架构和Ubuntu版本。
查看系统架构:
uname -m
常见的输出有
x86_64
(64位Intel/AMD)、
aarch64
(64位ARM,如树莓派4、苹果M系列芯片、云服务器ARM实例)。Docker对这两种主流架构都有很好的支持。如果你的输出是
i386
或
i686
,说明是32位系统,
现代Docker已不再支持
,你需要考虑升级到64位系统。
查看Ubuntu版本:
lsb_release -a
重点关注
Release
这一行,比如
22.04
(Jammy Jellyfish) 或
20.04
(Focal Fossa)。Docker官方维护的APT仓库支持Ubuntu的LTS(长期支持)版本,如 20.04, 22.04, 24.04等。非LTS版本理论上也能装,但可能遇到依赖库冲突,稳定性无法保证,生产环境强烈建议使用LTS版本。
注意 :网上有些老旧教程会要求你使用
docker.io这个包,它是Ubuntu官方仓库里一个较旧、功能可能不全的Docker版本。我们的目标是安装Docker官方维护的最新稳定版,所以必须配置Docker官方的APT仓库。
2.2 卸载旧版本与清理冲突:打扫干净屋子再请客
如果你的系统之前尝试安装过Docker或者其他容器运行时(如
podman
、
containerd
),为了避免潜在的冲突,最好先清理一遍。这不是必须步骤,但是一个好习惯。
执行以下命令移除可能的旧版本和相关包:
sudo apt remove docker docker-engine docker.io containerd runc
这个命令可能会提示某些包未安装,没关系,继续即可。然后,清理残留的配置和数据(如果你想保留镜像和容器数据,请跳过
rm -rf
那行):
sudo apt autoremove --purge
# 谨慎操作!这会删除所有Docker相关数据,包括镜像、容器、卷和网络配置。
sudo rm -rf /var/lib/docker
sudo rm -rf /var/lib/containerd
2.3 虚拟化支持检查:Docker Desktop的“入场券”
这里是一个超级大坑,尤其对于想在Ubuntu桌面版上安装
Docker Desktop
的用户。Docker Desktop依赖于系统的硬件虚拟化支持(如Intel VT-x或AMD-V)。如果BIOS中未开启,或者你使用的是某些虚拟机或云主机,就可能遇到
Virtualization support not detected
的错误。
如何检查?
对于物理机或本地虚拟机,可以安装
cpu-checker
工具:
sudo apt update && sudo apt install cpu-checker -y
kvm-ok
如果输出包含
KVM acceleration can be used
,恭喜你,虚拟化已启用。如果显示
KVM acceleration can NOT be used
,你需要重启进入BIOS/UEFI设置,找到
Virtualization Technology
、
VT-x
、
AMD-V
或
SVM
等选项并启用它。
对于云服务器(如AWS EC2、阿里云ECS),情况更复杂。大多数现代云主机的虚拟化是透传的,但Docker Desktop可能无法直接检测到。 一个更通用的建议是:在Linux服务器环境或追求轻量化的桌面使用场景下,直接安装Docker Engine(即命令行版本的Docker),而不是Docker Desktop。 Docker Engine不依赖图形界面和特定的硬件虚拟化检测,更稳定、更节省资源,也是生产环境的标准选择。本教程后续将主要围绕Docker Engine的安装展开。
3. 两种主流安装方法详解与选型
准备好了系统环境,现在进入正题:安装Docker。我将详细介绍两种最可靠的方法,并告诉你分别在什么情况下该用哪一种。
3.1 方法一:通过APT仓库安装(推荐,最可控)
这是Docker官方文档推荐的方法,也是我最喜欢的方式。它的优点在于完全可控:你知道软件包从哪里来,更新机制是什么,并且能方便地安装特定版本。整个过程分为三步:添加Docker的官方GPG密钥和APT仓库源,然后安装。
第一步:安装必要的工具并添加GPG密钥
首先,确保
ca-certificates
、
curl
、
gnupg
等工具已安装:
sudo apt update
sudo apt install ca-certificates curl gnupg -y
接着,创建用于存储GPG密钥的目录,并下载Docker官方的GPG公钥。这个密钥用于验证从Docker仓库下载的软件包的完整性,防止被篡改。
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
第二步:添加Docker的APT仓库源
我们需要告诉系统的APT包管理器,去哪里找Docker的软件包。根据你的系统架构,添加对应的仓库地址。以下命令适用于
x86_64
/
amd64
架构:
echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
$(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
这条命令看起来很复杂,其实它做了几件事:
$(dpkg --print-architecture)
自动获取你的系统架构;
signed-by
指定了上一步导入的GPG密钥路径;
$(. /etc/os-release && echo “$VERSION_CODENAME”)
自动获取你系统的Ubuntu代号(如
jammy
for 22.04)。这样就生成了一个针对你当前系统定制的仓库源配置。
第三步:更新源并安装Docker 添加新仓库后,必须更新本地软件包索引:
sudo apt update
现在,你可以安装Docker了。我们安装的是包含Docker CLI、Docker Daemon、Containerd和Docker Compose插件等完整组件的包:
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y
安装完成后,Docker服务(
dockerd
)会自动启动,并设置为开机自启。你可以用以下命令验证:
sudo systemctl status docker
如果看到
active (running)
的字样,说明服务已成功运行。
3.2 方法二:使用便捷安装脚本(快速,但需谨慎)
Docker官方也提供了一个自动化安装脚本
get-docker.sh
。它的优点是极其简单,一条命令搞定,适合快速测试环境搭建。
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
这个脚本会自动检测你的系统,完成上述方法一中的所有步骤。 但是,我强烈不推荐在生产环境或重要的开发机上直接使用这个方法。 原因有三:
- 缺乏透明度 :脚本在后台执行了大量操作,你无法精确知道它修改了哪些系统配置。
- 版本不可控 :它总是安装最新的稳定版,如果你需要锁定某个特定版本(比如为了兼容性),这个方法做不到。
-
潜在风险
:从网络直接下载并执行脚本存在安全风险(尽管Docker官方脚本是可信的)。你应该至少先查看一下脚本内容 (
cat get-docker.sh) 再决定是否执行。
选型建议 :
- 个人学习、快速搭建测试环境 :如果不介意上述风险,可以用脚本,省时省力。
- 开发主力机、生产服务器 : 务必使用APT仓库安装 。这是标准的、可审计的、可复现的安装方式,符合运维最佳实践。
4. 安装后的关键配置:让Docker真正“好用”
安装成功只是第一步。默认配置下的Docker用起来会有些别扭,比如每次命令都要加
sudo
。这一章,我们来优化配置,提升使用体验。
4.1 解决“Permission denied”问题:将用户加入docker组
默认情况下,只有
root
用户和
docker
组的用户才能执行Docker命令。为了避免每次输入
sudo
,我们需要将当前用户添加到
docker
组。
sudo usermod -aG docker $USER
重要 :执行此命令后, 必须完全注销当前用户会话,然后重新登录 ,或者重启电脑。仅仅新开一个终端窗口是无效的,因为组权限的变更不会应用到已存在的会话中。
重新登录后,验证是否生效:
docker version
如果能正常显示Client和Server的版本信息,而不需要
sudo
,说明配置成功。
警告 :将用户加入
docker组等同于赋予该用户root权限。因为Docker守护进程以root身份运行,而docker组的用户可以通过Docker命令间接操作主机系统(例如,挂载主机目录到容器)。因此,请仅在你信任的个人电脑或受控服务器上这样做。在多用户系统或生产环境中,需要更精细的权限控制。
4.2 配置国内镜像加速器:告别“拉取超时”
从Docker Hub拉取镜像时,国内网络速度可能很慢甚至失败。配置一个国内镜像加速器可以极大提升体验。国内常用的有阿里云、中科大、网易云等。
这里以阿里云镜像加速器为例(你需要有一个阿里云账号,免费注册即可):
- 访问 https://cr.console.aliyun.com/cn-hangzhou/instances/mirrors
-
登录后,你会看到为你分配的专属加速器地址,格式如
https://xxxx.mirror.aliyuncs.com。 -
在Ubuntu上,编辑Docker的守护进程配置文件:
sudo nano /etc/docker/daemon.json -
如果文件不存在,会新建一个。将以下内容写入(将
https://xxxx.mirror.aliyuncs.com替换成你的实际地址):
你可以配置多个镜像源,用逗号隔开。{ "registry-mirrors": ["https://xxxx.mirror.aliyuncs.com"] } -
保存并退出编辑器(在nano中按
Ctrl+X,然后按Y,再按Enter)。 -
重新加载配置并重启Docker服务:
sudo systemctl daemon-reload sudo systemctl restart docker -
验证配置是否生效:
在输出信息中查找docker infoRegistry Mirrors,如果看到你配置的地址,说明成功。
4.3 验证安装:运行你的第一个容器
让我们用一个最经典的例子来验证整个Docker环境是否工作正常:
docker run --rm hello-world
这条命令会让Docker从仓库拉取一个名为
hello-world
的极小镜像,并基于它创建一个容器运行。容器执行一段简单的输出后会自动停止并删除(
--rm
参数的作用)。
如果你看到类似下面的输出,那么恭喜你,Docker已经在你的Ubuntu系统上成功安装并配置完毕!
Hello from Docker!
This message shows that your installation appears to be working correctly.
...
5. 实战排错指南:从报错信息到解决方案
即使按照教程一步步来,你也可能会遇到问题。这一章,我汇总了几个最常见的错误及其排查思路,希望能帮你快速定位问题。
5.1 网络问题导致安装失败
症状
:在执行
sudo apt update
或
sudo apt install docker-ce
时,长时间卡住或报错
Failed to fetch ... Connection timed out
。
排查与解决 :
-
检查网络连通性
:
ping 8.8.8.8或ping download.docker.com,看是否能通。 -
更换APT源
:可能是Ubuntu默认的软件源访问慢。可以尝试更换为国内镜像源,如阿里云、清华大学的源。修改
/etc/apt/sources.list文件,将archive.ubuntu.com和security.ubuntu.com替换为mirrors.aliyun.com或mirrors.tuna.tsinghua.edu.cn,然后再次sudo apt update。 -
使用代理
:如果你处在需要代理的网络环境,需要为
apt配置代理。可以临时在sudo后加上环境变量:sudo env http_proxy=http://your-proxy:port https_proxy=http://your-proxy:port apt update。或者永久配置在/etc/apt/apt.conf.d/目录下创建一个代理配置文件。
5.2 Docker服务启动失败
症状
:执行
sudo systemctl status docker
显示
failed
或
inactive
,日志中可能有各种错误。
排查与解决 :
-
查看详细日志
:
sudo journalctl -u docker.service --no-pager -n 50可以查看Docker服务的最近50行日志,通常错误信息就在这里。 -
检查端口冲突
:Docker默认使用Unix socket (
/var/run/docker.sock) 和可能监听TCP端口(如果配置了)。确保没有其他程序占用相关资源。可以用sudo netstat -tlnp | grep :2375(或2376) 检查。 -
检查存储驱动
:旧系统或某些文件系统可能与Docker默认的存储驱动不兼容。可以尝试在
/etc/docker/daemon.json中指定overlay2驱动(对于现代Ubuntu通常是默认且最佳的):{ "storage-driver": "overlay2" } -
检查内核模块
:Docker依赖一些内核模块,如
overlay、br_netfilter等。使用lsmod | grep overlay和lsmod | grep br_netfilter检查它们是否已加载。如果没有,尝试sudo modprobe overlay和sudo modprobe br_netfilter手动加载。
5.3 用户加入docker组后仍无权限
症状
:执行
usermod
命令并重新登录后,运行
docker ps
依然提示
Got permission denied
。
排查与解决 :
- 确认是否已重新登录 :这是最常见的原因。请务必 注销图形界面或关闭所有终端窗口,然后重新登录 ,或者直接重启电脑。
-
检查用户所属组
:运行
groups命令,查看输出中是否包含docker。 -
检查Docker socket权限
:运行
ls -l /var/run/docker.sock。其所属组应为docker,权限类似srw-rw----。如果不是,可以尝试sudo chown root:docker /var/run/docker.sock。 -
检查
/etc/group文件 :确保你的用户名确实在docker组那一行里。cat /etc/group | grep docker。
5.4 拉取镜像速度慢或失败
症状
:
docker pull
命令速度极慢,或最终报错
net/http: request canceled
。
排查与解决 :
-
确认镜像加速器配置正确
:严格按照4.2节步骤操作,并确保
daemon.json格式正确(JSON格式严格,不能有尾随逗号)。重启服务后务必用docker info验证。 -
尝试不同的镜像源
:阿里云加速器有时也会不稳定。可以尝试添加多个镜像源,或者换用中科大的源
https://docker.mirrors.ustc.edu.cn/或网易的源https://hub-mirror.c.163.com/。 -
直接使用国内镜像仓库
:对于一些常用镜像(如
ubuntu,nginx,mysql),可以直接从国内仓库拉取,例如docker pull registry.cn-hangzhou.aliyuncs.com/library/ubuntu:22.04。拉下来后,再通过docker tag命令改回通用名。
6. 进阶配置与管理:打造高效Docker工作流
基础安装和配置完成后,我们可以进一步优化,让Docker更好地融入你的开发或运维工作流。这里分享几个我实践中觉得非常有用的配置。
6.1 数据目录迁移:为系统盘减负
Docker默认将所有数据(镜像、容器、卷)存储在
/var/lib/docker
。随着使用,这个目录会变得非常庞大,可能挤占系统盘空间。我们可以将其迁移到更大的数据盘上。
步骤 :
-
停止Docker服务
:
sudo systemctl stop docker。 -
复制数据
:假设新目录是
/data/docker。使用rsync同步数据能保留权限属性:sudo rsync -avxP /var/lib/docker/ /data/docker/。 -
修改配置
:编辑
/etc/docker/daemon.json,添加data-root配置项:{ "data-root": "/data/docker", "registry-mirrors": ["https://xxxx.mirror.aliyuncs.com"] } -
启动并验证
:
sudo systemctl start docker,然后运行docker info,查看输出的Docker Root Dir是否已变为新路径。
警告 :此操作有风险,务必在操作前备份重要数据。确保新目录的磁盘空间充足,并且文件系统支持Docker所需的特性(如
overlay2存储驱动通常需要xfs或ext4并开启d_type支持)。
6.2 日志配置:防止容器日志撑爆磁盘
默认情况下,每个容器的日志(JSON文件驱动)会无限增长,可能占用大量磁盘空间。我们需要配置日志轮转和大小限制。
编辑
/etc/docker/daemon.json
,添加
log-driver
和
log-opts
配置:
{
"log-driver": "json-file",
"log-opts": {
"max-size": "10m",
"max-file": "3"
}
}
这会将每个容器的日志文件大小限制在10MB,最多保留3个文件(即最新的约30MB日志)。修改后需要重启Docker服务生效。
6.3 Docker Compose的安装与使用
虽然我们在安装
docker-compose-plugin
后,可以使用
docker compose
命令(注意是空格,不是横杠),但很多人还是习惯独立的
docker-compose
命令行工具。这里也提供其安装方法:
从GitHub Release直接下载二进制文件(推荐) :
# 下载最新稳定版,请访问 https://github.com/docker/compose/releases 查看最新版本号
sudo curl -L "https://github.com/docker/compose/releases/download/v2.24.5/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
# 赋予执行权限
sudo chmod +x /usr/local/bin/docker-compose
# 验证安装
docker-compose --version
使用Docker Compose,你可以通过一个
docker-compose.yml
文件来定义和运行多容器应用,极大地简化了复杂应用的部署和管理。例如,一个典型的Web应用栈(Nginx + Python + MySQL)的Compose文件骨架如下:
version: '3.8'
services:
web:
image: python:3.9-slim
volumes:
- ./app:/code
working_dir: /code
command: python app.py
ports:
- "8000:8000"
depends_on:
- db
db:
image: mysql:8.0
environment:
MYSQL_ROOT_PASSWORD: example
MYSQL_DATABASE: myapp
volumes:
- db_data:/var/lib/mysql
volumes:
db_data:
在包含此文件的目录下,只需运行
docker-compose up -d
,所有服务就会按定义启动。
7. 实用干货大礼包:提升效率的脚本与清单
最后,兑现标题的承诺,分享一些我日常积累的实用资源。这些不是花架子,而是能切实在你使用Docker时节省时间、减少错误的工具。
7.1 Docker常用命令速查清单
把这张表保存下来,或者贴在便利贴上,能覆盖你80%的日常操作:
| 类别 | 命令 | 说明 |
|---|---|---|
| 镜像管理 |
docker images
| 列出本地镜像 |
docker pull <镜像名>:<标签>
| 拉取镜像 | |
docker rmi <镜像ID>
| 删除本地镜像 | |
docker build -t <标签> .
| 构建镜像(在当前目录) | |
| 容器生命周期 |
docker run -d --name <名称> <镜像>
| 后台运行容器 |
docker run -it --rm <镜像> /bin/bash
| 交互式运行并进入容器,退出即删 | |
docker start/stop/restart <容器>
| 启动/停止/重启容器 | |
docker rm <容器>
| 删除已停止的容器 | |
docker rm -f <容器>
| 强制删除运行中的容器 | |
| 容器操作 |
docker ps
| 查看运行中的容器 |
docker ps -a
| 查看所有容器(包括已停止) | |
docker exec -it <容器> /bin/bash
| 进入正在运行的容器 | |
docker logs -f <容器>
| 实时查看容器日志 | |
docker cp <本地路径> <容器>:<路径>
| 从宿主机复制文件到容器 | |
| 系统与清理 |
docker system df
| 查看Docker磁盘使用情况 |
docker system prune -a
| 危险 清理所有未使用的镜像、容器、网络和构建缓存 | |
docker volume ls
| 列出数据卷 | |
docker network ls
| 列出网络 |
7.2 一键安装与配置脚本
如果你需要经常在新机器上部署Docker,可以把本章的核心步骤写成一个脚本。下面是一个示例脚本
install_docker.sh
,它包含了安装、用户组配置和镜像加速(需要你替换
<你的加速器地址>
):
#!/bin/bash
# 安装Docker Engine (APT仓库方式)
set -e # 遇到错误即停止
echo “正在安装必要工具...”
sudo apt update
sudo apt install -y ca-certificates curl gnupg
echo “添加Docker官方GPG密钥...”
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
echo “添加Docker APT仓库...”
echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
$(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
echo “更新源并安装Docker...”
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
echo “将当前用户加入docker组...”
sudo usermod -aG docker $USER
echo “配置阿里云镜像加速器...”
sudo tee /etc/docker/daemon.json <<-‘EOF’
{
“registry-mirrors”: [“<你的加速器地址>”],
“log-driver”: “json-file”,
“log-opts”: {
“max-size”: “10m”,
“max-file”: “3”
}
}
EOF
echo “重启Docker服务...”
sudo systemctl daemon-reload
sudo systemctl restart docker
echo “安装完成!请注销并重新登录,以使docker组权限生效。”
echo “验证命令: docker run --rm hello-world”
使用方法:
chmod +x install_docker.sh && sudo ./install_docker.sh
。
注意
:脚本中的镜像加速器地址需要你自行替换。
7.3 简易开发环境Docker Compose模板
这里提供一个用于Python Web开发的通用环境模板
docker-compose.dev.yml
,它包含了Python应用、MySQL数据库和PgAdmin(数据库管理工具):
version: ‘3.8’
services:
db:
image: mysql:8.0
environment:
MYSQL_ROOT_PASSWORD: rootpassword
MYSQL_DATABASE: mydb
MYSQL_USER: devuser
MYSQL_PASSWORD: devpassword
ports:
- “3306:3306”
volumes:
- mysql_data:/var/lib/mysql
healthcheck:
test: [“CMD”, “mysqladmin”, “ping”, “-h”, “localhost”]
timeout: 20s
retries: 10
pgadmin:
image: dpage/pgadmin4
environment:
PGADMIN_DEFAULT_EMAIL: admin@example.com
PGADMIN_DEFAULT_PASSWORD: admin
ports:
- “5050:80”
depends_on:
- db
web:
build: .
# 假设你的Dockerfile在当前目录
volumes:
- .:/code
# 挂载代码目录,实现代码热更新
ports:
- “8000:8000”
depends_on:
db:
condition: service_healthy
# 等待数据库健康检查通过后再启动
command: python manage.py runserver 0.0.0.0:8000
# 根据你的项目启动命令修改
volumes:
mysql_data:
这个模板展示了服务依赖、健康检查、数据持久化、配置分离等实用技巧。你可以根据实际项目修改镜像、端口、环境变量和启动命令。
安装Docker本身并不复杂,但围绕它的配置、优化和问题排查,才是真正体现经验的地方。我希望这篇超过5000字的详细指南,不仅能帮你顺利完成安装,更能让你理解每个步骤的意义,在遇到问题时不再慌张。Docker是一个强大的工具,熟练掌握它,会为你的开发、测试和部署工作流带来质的飞跃。如果在实践中还有任何具体问题,多查看官方文档和社区讨论,那是最好的老师。
更多推荐



所有评论(0)