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

这个脚本会自动检测你的系统,完成上述方法一中的所有步骤。 但是,我强烈不推荐在生产环境或重要的开发机上直接使用这个方法。 原因有三:

  1. 缺乏透明度 :脚本在后台执行了大量操作,你无法精确知道它修改了哪些系统配置。
  2. 版本不可控 :它总是安装最新的稳定版,如果你需要锁定某个特定版本(比如为了兼容性),这个方法做不到。
  3. 潜在风险 :从网络直接下载并执行脚本存在安全风险(尽管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拉取镜像时,国内网络速度可能很慢甚至失败。配置一个国内镜像加速器可以极大提升体验。国内常用的有阿里云、中科大、网易云等。

这里以阿里云镜像加速器为例(你需要有一个阿里云账号,免费注册即可):

  1. 访问 https://cr.console.aliyun.com/cn-hangzhou/instances/mirrors
  2. 登录后,你会看到为你分配的专属加速器地址,格式如 https://xxxx.mirror.aliyuncs.com
  3. 在Ubuntu上,编辑Docker的守护进程配置文件:
    sudo nano /etc/docker/daemon.json
    
  4. 如果文件不存在,会新建一个。将以下内容写入(将 https://xxxx.mirror.aliyuncs.com 替换成你的实际地址):
    {
      "registry-mirrors": ["https://xxxx.mirror.aliyuncs.com"]
    }
    
    你可以配置多个镜像源,用逗号隔开。
  5. 保存并退出编辑器(在nano中按 Ctrl+X ,然后按 Y ,再按 Enter )。
  6. 重新加载配置并重启Docker服务:
    sudo systemctl daemon-reload
    sudo systemctl restart docker
    
  7. 验证配置是否生效:
    docker info
    
    在输出信息中查找 Registry 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

排查与解决

  1. 检查网络连通性 ping 8.8.8.8 ping download.docker.com ,看是否能通。
  2. 更换APT源 :可能是Ubuntu默认的软件源访问慢。可以尝试更换为国内镜像源,如阿里云、清华大学的源。修改 /etc/apt/sources.list 文件,将 archive.ubuntu.com security.ubuntu.com 替换为 mirrors.aliyun.com mirrors.tuna.tsinghua.edu.cn ,然后再次 sudo apt update
  3. 使用代理 :如果你处在需要代理的网络环境,需要为 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 ,日志中可能有各种错误。

排查与解决

  1. 查看详细日志 sudo journalctl -u docker.service --no-pager -n 50 可以查看Docker服务的最近50行日志,通常错误信息就在这里。
  2. 检查端口冲突 :Docker默认使用Unix socket ( /var/run/docker.sock ) 和可能监听TCP端口(如果配置了)。确保没有其他程序占用相关资源。可以用 sudo netstat -tlnp | grep :2375 (或2376) 检查。
  3. 检查存储驱动 :旧系统或某些文件系统可能与Docker默认的存储驱动不兼容。可以尝试在 /etc/docker/daemon.json 中指定 overlay2 驱动(对于现代Ubuntu通常是默认且最佳的):
    {
      "storage-driver": "overlay2"
    }
    
  4. 检查内核模块 :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

排查与解决

  1. 确认是否已重新登录 :这是最常见的原因。请务必 注销图形界面或关闭所有终端窗口,然后重新登录 ,或者直接重启电脑。
  2. 检查用户所属组 :运行 groups 命令,查看输出中是否包含 docker
  3. 检查Docker socket权限 :运行 ls -l /var/run/docker.sock 。其所属组应为 docker ,权限类似 srw-rw---- 。如果不是,可以尝试 sudo chown root:docker /var/run/docker.sock
  4. 检查 /etc/group 文件 :确保你的用户名确实在 docker 组那一行里。 cat /etc/group | grep docker

5.4 拉取镜像速度慢或失败

症状 docker pull 命令速度极慢,或最终报错 net/http: request canceled

排查与解决

  1. 确认镜像加速器配置正确 :严格按照4.2节步骤操作,并确保 daemon.json 格式正确(JSON格式严格,不能有尾随逗号)。重启服务后务必用 docker info 验证。
  2. 尝试不同的镜像源 :阿里云加速器有时也会不稳定。可以尝试添加多个镜像源,或者换用中科大的源 https://docker.mirrors.ustc.edu.cn/ 或网易的源 https://hub-mirror.c.163.com/
  3. 直接使用国内镜像仓库 :对于一些常用镜像(如 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 。随着使用,这个目录会变得非常庞大,可能挤占系统盘空间。我们可以将其迁移到更大的数据盘上。

步骤

  1. 停止Docker服务 sudo systemctl stop docker
  2. 复制数据 :假设新目录是 /data/docker 。使用 rsync 同步数据能保留权限属性: sudo rsync -avxP /var/lib/docker/ /data/docker/
  3. 修改配置 :编辑 /etc/docker/daemon.json ,添加 data-root 配置项:
    {
      "data-root": "/data/docker",
      "registry-mirrors": ["https://xxxx.mirror.aliyuncs.com"]
    }
    
  4. 启动并验证 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是一个强大的工具,熟练掌握它,会为你的开发、测试和部署工作流带来质的飞跃。如果在实践中还有任何具体问题,多查看官方文档和社区讨论,那是最好的老师。

更多推荐