如何在 Ubuntu 上安装 Docker：完整的初学者友好指南（官方方法）

1. 介绍

在 Ubuntu 上搭建开发环境时，“先装个 Docker 吧”这种想法变得越来越常见。Web 应用、批处理、测试数据库、测试中间件……如果每次都手动安装这些组件，仅仅是环境搭建就会消耗大量时间和精力。

这时容器虚拟化技术 Docker 就显得极其有用。使用 Docker，你可以将不仅是应用本身，还包括所有必需的库和配置一起管理为一个“镜像”。一旦在 Ubuntu 上安装了 Docker，你就可以轻松：

• 在几分钟内启动全新的开发环境
• 确保所有团队成员在 相同环境 中复现行为
• 在本地轻松重现生产环境的设置

这些好处几乎不需要额外付出。

另一方面，对于首次使用 Docker 的人来说，常见的卡点包括：

• 不清楚哪种安装流程才是正确的
• 不了解 Ubuntu 默认仓库与 Docker 官方仓库的区别
• 因为不确定何时使用 sudo 而导致权限错误

当你搜索 “ubuntu install docker” 时，会看到很多文章列出冗长的命令序列，但它们往往没有解释 为什么需要这些步骤 或 完整安装的标志是什么。

1-1. 本文目标

本文面向想在 Ubuntu 上安装 Docker 的读者，涵盖以下关键点：

• 当前常用的 Ubuntu Docker 安装流程
• 使用官方仓库的更易管理的安装方法
• 如何在不使用 sudo 的情况下运行 docker 命令
• 安装后验证及必备基础命令
• 常用工具 Docker Compose 的简介

本指南不仅列出命令，还会解释 每一步为何必要，帮助你以后更轻松地维护环境。

1-2. 受众与前置条件

本文适合以下读者：

• 了解基本的 Ubuntu 操作（打开终端、使用 apt 命令等）
• 开发者或首次尝试 Docker 的工程师
• 正在考虑将已有的测试环境迁移到容器中

不需要高级的 Linux 管理知识。只要你能够在终端中敲入命令，本指南即可满足需求。

1-3. 文章结构与阅读方式

本文的组织顺序如下：

• 前置条件检查
• 安装方式（官方仓库 / 脚本方式）
• 权限设置与验证
• 安装 Docker Compose
• 故障排查与后续步骤

你可以从头到尾阅读整篇，也可以在 Docker 已经安装的情况下，仅关注 “权限设置” 或 “Compose” 部分。

2. 前置条件与准备工作

Docker 本身的安装相对简单，但根据你的 Ubuntu 版本或已有环境，事先检查以下几点会让安装过程更加顺畅。本节概述顺利安装所需的前置条件和准备工作。

2-1. 支持的 Ubuntu 版本

Docker 可运行于多种 Ubuntu 版本，但以下 LTS 发行版最为常用：

• Ubuntu 22.04 LTS（推荐）
• Ubuntu 20.04 LTS
• Ubuntu 24.04 LTS（最新）

LTS（长期支持）版本提供长期的稳定性，是维护基于 Docker 的开发环境的理想选择。

非 LTS 发行版（如 23.10）亦可使用，但在专业环境中通常更倾向于使用 LTS 版本。

2-2. 已预装的 Docker 包

Ubuntu 的默认软件源包含一个名为 docker.io 的软件包。然而，这并非 Docker Inc. 提供的官方 Docker 软件包，且更新往往滞后。因此，强烈建议从官方仓库安装 Docker。

首先，检查并在必要时移除任何已存在的 Docker 相关软件包：

sudo apt remove docker docker.io containerd runc

如果提示没有安装任何内容，则无需操作。

2-3. 更新 APT 并安装必需的软件包

在添加 Docker 官方仓库之前，先更新 APT 并安装所需工具：

sudo apt update
sudo apt install -y ca-certificates curl gnupg

这些工具用于安全地添加 Docker 的 GPG 密钥和仓库。

2-4. 验证管理员权限（sudo）

Docker 的安装需要 sudo 权限。如果你的账户没有 sudo 权限，请切换到管理员账户或请求授权。

你可以使用以下命令验证 sudo 权限：

sudo -v

如果系统提示输入密码且命令执行成功，则说明可以继续。

2-5. 检查网络连通性

安装 Docker 需要访问外部仓库，因此必须保持网络连接。在企业或代理环境中，可能因访问限制导致 GPG 密钥获取失败。

遇到此类情况时，请咨询网络管理员关于代理设置或白名单配置。

2-6. 选择安装方式

安装 Docker 主要有三种方式：

1. 通过官方 Docker 仓库安装（推荐）
2. 使用 get.docker.com 安装脚本（快速简便）
3. 手动下载并安装 Docker .deb 包（特殊情况）

本文主要介绍 官方仓库方式，它是最常见且最易维护的安装方法。

3. 安装 Docker

现在让我们在 Ubuntu 上安装 Docker。虽然有多种安装方式，但本指南聚焦于 官方 Docker 仓库方式，它是最可靠且在生产环境中最常用的。

该方式支持通过 apt upgrade 进行稳定升级，适合长期使用。

3-1. 添加官方 Docker 仓库（推荐）

首先，注册 Docker 提供的官方 GPG 密钥并将 Docker 仓库添加到 APT。正确配置后，可避免误装 Ubuntu 默认仓库中已过时的 docker.io 软件包。

3-1-1. 注册 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

• /etc/apt/keyrings/ 是 Ubuntu 22.04 及以后版本推荐的密钥存放位置
• --dearmor 将密钥转换为二进制格式

此步骤使 APT 能够信任官方 Docker 仓库。

3-1-2. 添加仓库

接下来，将 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

要点：

• $(. /etc/os-release && echo $VERSION_CODENAME) 会自动插入正确的 Ubuntu 代号（如 jammy 或 focal）
• 只添加稳定仓库

3-1-3. 更新仓库信息

添加仓库后，更新 APT 索引。

sudo apt update

此时，docker-ce（Docker Engine）应已出现在可安装的软件包列表中。

3-2. 安装 Docker Engine

现在安装主要的 Docker 软件包。

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

软件包角色：

• docker-ce：Docker 引擎核心
• docker-ce-cli：Docker 命令行界面
• containerd.io：Docker 使用的核心容器运行时
• docker-buildx-plugin：高级构建功能，如多平台构建
• docker-compose-plugin：Docker Compose V2（docker compose 命令）

安装完成后，Docker 守护进程会自动启动。

3-3. 验证安装

使用以下命令检查 Docker 的运行状态：

sudo systemctl status docker

如果看到 active (running)，说明 Docker 正常运行。

按 q 退出状态视图。

3-4. 可选：基于脚本的一键安装

Docker 还提供了一键安装脚本。

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

优势：

• 命令更少，设置更快
• 适用于简单或一次性环境

劣势：

• 难以进行版本控制
• 通常不建议在生产或长期使用中采用

虽然对初学者很方便，但本文更注重可维护性，因此重点介绍官方仓库的安装方式。

3-5. 最新 Ubuntu 发行版的注意事项（例如 24.04）

在 Ubuntu 重大版本发布后，Docker 官方仓库可能尚未完全支持新版本。
此时请确认以下事项：

• GPG 密钥的位置和格式是否符合当前规范
• VERSION_CODENAME 是否已被官方支持
• apt update 过程中是否出现签名错误

如果支持延迟，临时使用 get.docker.com 脚本可能是一个实用的变通方案。

4. 用户权限与免 sudo 运行 Docker

安装 Docker 后，你可能希望立即使用 docker 命令。然而，默认情况下 必须在每个命令前加 sudo。

这种行为出于安全考虑，但对日常开发或学习来说不太方便。为了解决此问题，你可以将当前用户加入 docker 组，从而实现免 sudo 执行 Docker 命令。

4-1. 为什么免 sudo 很重要

在 Ubuntu 上，Docker 守护进程（dockerd）以 root 权限运行。
因此，通过 docker 命令创建或删除容器通常需要 root 权限。

docker 组的存在就是为了解决这个需求。

• 属于该组的用户可以 直接访问 Docker 守护进程
• 这使得 docker run 等命令无需 sudo
• 对于开发使用几乎是必不可少的

需要注意的是，docker 组实际上授予了接近 root 的权限，在共享环境中使用时需格外小心。
（在个人桌面或 WSL2 中一般没有问题。）

4-2. 将用户添加到 docker 组

将当前登录的用户加入 docker 组：

sudo usermod -aG docker $USER

该命令会将用户追加到组中。-aG 选项表示 append to group（追加到组）。

4-3. 使更改生效

组成员关系的更改需要注销后重新登录后才会生效。

若想立即生效，也可以运行：

newgrp docker

这会启动一个带有 docker 组权限的新 shell 会话。

4-4. 验证免 sudo 执行

现在尝试不使用 sudo 运行 Docker：

docker run hello-world

成功输出示例：

• Hello from Docker!
• 镜像已下载并显示该信息

如果出现错误，请检查以下事项：

• 修改组成员后是否已注销并重新登录？
• 是否使用了 /usr/bin/docker？
• Docker 守护进程是否在运行（systemctl status docker）？

4-5. 安全考虑（重要）

docker 组提供的权限相当于 root 权限，具有以下强大能力：

• 读取任意文件
• 将主机目录挂载到容器中
• 执行网络操作
• 通过 Docker 套接字进行系统级控制

在个人系统上通常可以接受，但在共享服务器上必须严格管理用户权限。

在这种情况下，您可以考虑 无根 Docker，相关内容将在后面的章节中讨论。

5. 启动与运行验证

一旦 Docker 安装和权限配置完成，下一步是 验证 Docker 是否正常运行。
本节说明如何检查 Docker 服务状态以及实际运行容器。

5-1. 检查 Docker 守护进程状态

首先，确认 Docker 在后台正确运行。

sudo systemctl status docker

关键状态指示：

• active (running) → 正常运行
• inactive → 未运行（需手动启动）
• failed → 配置或依赖错误

如果状态为 inactive 或 failed，请使用以下命令启动 Docker：

sudo systemctl start docker

确保 Docker 在操作系统启动时自动启动：

sudo systemctl enable docker

5-2. 使用 hello-world 容器验证运行

验证 Docker 安装最常用的方法是运行官方 hello-world 镜像。

docker run hello-world

此命令会执行以下操作：

1. 如果本地不存在，则从 Docker Hub 下载镜像
2. 基于该镜像启动一个容器
3. 显示测试信息后退出

如果成功，您将看到类似以下的输出：

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

如果出现此信息，说明 Docker 已安装且正常工作。

5-3. 尝试基本的 Docker 命令

确认基本运行后，尝试一些常用的 Docker 命令。

5-3-1. 列出 Docker 镜像

docker images

这将显示本地已下载的镜像列表。如果出现 hello-world，则说明一切正常。

5-3-2. 检查运行中的容器

docker ps

此命令列出当前正在运行的容器。
（hello-world 容器会立即退出，通常不会出现在列表中。）

若要同时显示已停止的容器：

docker ps -a

5-3-3. 运行官方镜像示例

尝试运行一个简单的 Nginx Web 服务器：

docker run -d -p 8080:80 nginx

• -d → 在后台运行
• -p → 将主机端口 8080 映射到容器端口 80

在浏览器中打开 http://localhost:8080，即可看到默认的 Nginx 页面。

5-4. 停止并删除容器

可以使用以下命令停止运行中的容器：

docker stop <container-id>

删除容器：

docker rm <container-id>

删除未使用的镜像：

docker rmi <image-id>

请记住依赖关系的顺序为 容器 → 镜像 → 卷，因此请谨慎删除。

5-5. 常见错误原因

● 权限错误

Got permission denied while trying to connect to the Docker daemon socket
→ 用户未加入 docker 组

● Docker 守护进程未运行

Cannot connect to the Docker daemon at unix:///var/run/docker.sock
→ 使用 systemctl start docker 启动 Docker

● 网络问题导致镜像下载失败

→ 检查代理设置、DNS 配置或网络限制

● 仍然安装了旧的 docker.io 包

→ 完全卸载该包，并从官方仓库重新安装 Docker

6. 安装与使用 Docker Compose

在大规模使用 Docker 时，一个必不可少的工具是 Docker Compose。
现代 Web 应用通常由多个组件组成，如数据库、缓存、工作进程和 Web 服务器。使用 docker run 单独管理这些组件很快就会变得不切实际。

Docker Compose 允许您 在单个文件中定义多个容器配置并统一管理，因此成为实际开发中最常用的工具之一。

6-1. 验证 Docker Compose V2 安装

从官方仓库安装 Docker 时，Docker Compose 会 自动作为插件安装。

使用以下命令验证安装：

docker compose version

如果安装正确，你应该会看到类似以下的输出：

Docker Compose version v2.x.x

如果出现类似 docker: 'compose' is not a docker command 的错误，请手动安装插件：

sudo apt install docker-compose-plugin

6-2. Docker Compose 的优势

Docker Compose 的主要优势包括：

• 统一管理多个容器（启动、停止、重启）
• 配置即代码，确保环境可复现
• 轻松共享应用、API 和数据库的配置
• 只需一次 docker compose up 即可启动开发环境

这使得 Docker Compose 在应用开发中几乎是不可或缺的。

6-3. Compose 配置文件的基本结构

Docker Compose 使用名为 docker-compose.yml（或 compose.yaml）的文件来定义服务。
下面给出一个最小示例，创建一个简单的配置来启动 Nginx。

services:
  web:
    image: nginx:latest
    ports:
      - "8080:80"

在包含该文件的目录下运行以下命令：

docker compose up -d

Nginx 将在后台启动。打开浏览器访问 http://localhost:8080 进行确认。

6-4. 示例：多容器部署（Web + 数据库）

当同时管理 多个容器 时，Compose 的真正威力便显现出来。
例如，将一个 Web 应用与 MySQL 一起运行的配置如下：

services:
  app:
    build: .
    ports:
      - "3000:3000"
    depends_on:
      - db

  db:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: example
    volumes:
      - db-data:/var/lib/mysql

volumes:
  db-data:

说明：

• depends_on 确保数据库在应用之前启动
• volumes 用于持久化数据库数据
• 多个服务都在同一个 YAML 文件中统一管理

这是一种在开发环境中非常实用的模式。

6-5. 常用的 Docker Compose 命令

以下命令值得记忆：

使用 Compose 可以反复重建完全相同的环境，非常适合团队协作开发。

6-6. 开发中使用 Compose 的推荐场景

• 一键本地环境搭建
• 在接近生产环境的条件下进行测试
• 启动组合服务，如数据库、缓存和消息队列
• 使用卷（volumes）持久化数据
• 通过 .env 环境变量管理配置
• 支持复杂的微服务架构

当你熟悉了 Docker 与 Compose 后，环境搭建时间会大幅缩短，显著提升开发效率。

7. 安全与运维注意事项

Docker 是一个功能强大且便利的工具，但“容器化”并不等同于“安全”。
在 Ubuntu 上日常使用 Docker 时，有几个重要的安全与运维要点需要了解。

本节以通俗易懂的方式整理了安全、稳定运行 Docker 所需的关键知识，即使是初学者也能快速上手。

7-1. docker 组拥有“等同于 root”的权限

之前创建的 docker 组实际上授予了非常高的权限。
属于 docker 组的用户可以 通过 Docker socket 操作宿主操作系统，这相当于拥有 root 权限。

● 需要注意的关键点

• 不要在共享服务器上随意将用户加入 docker 组
• 要了解其背后的安全影响，而不仅仅是“免 sudo”的便利
• 在安全策略严格的组织中，可能需要管理员批准才能加入

在个人 Ubuntu 机器或开发 PC 上这通常不是问题，但在生产服务器上必须谨慎判断。

7-2. 考虑使用 Rootless Docker（高级选项）

Docker 提供了一种叫做 rootless 模式 的特性，
它允许 Docker 守护进程在普通用户账户下运行，而不是以 root 身份运行。

优势：

• 大幅降低宿主操作系统的特权风险
• 在安全要求严格的环境中实现更安全的 Docker 使用

缺点：

• 某些网络功能受限
• 对初学者而言配置更复杂
• 行为可能与标准 Docker 不同

对于大多数开发场景来说，Rootless 模式并非必需，但在企业或合规性要求较高的环境中，它可以是一个可行的选项。

7-3. Cleaning Up Unused Images and Containers

7-3. 清理未使用的镜像和容器

随着时间推移，Docker 可能在不知不觉中占用大量磁盘空间。
未使用的容器、镜像和卷会累计，轻易超过 100GB。

● 删除未使用资源的命令

Removing unused images

删除未使用的镜像

docker image prune

Removing containers and networks together

同时删除容器和网络

docker system prune

Aggressive cleanup (use with caution)

强力清理（请谨慎使用）

docker system prune -a

-a 选项会删除所有未使用的镜像，请谨慎使用。

7-4. Avoid Using the “latest” Tag in Production

7-4. 生产环境中避免使用 “latest” 标签

虽然 nginx:latest 等标签在开发阶段很方便，但不建议在生产环境中使用。

原因：

• latest 背后的具体版本无法保证
• 意外的更新可能导致运行时错误
• 可复现性丧失会导致部署不稳定

推荐做法：显式锁定版本

示例：

image: nginx:1.25

显式版本控制是生产环境的基本准则。

7-5. Use Official Base Images in Dockerfiles

7-5. 在 Dockerfile 中使用官方基础镜像

编写 Dockerfile 时，请遵循以下指南：

• 优先使用官方镜像（库镜像）
• 避免使用未知或不可信作者维护的镜像
• 使用如 Alpine 等轻量级操作系统镜像时，检查其漏洞支持状态

不可信的镜像可能包含恶意软件。
即使在开发环境，也应尽可能避免使用它们。

7-6. Be Careful with Network and Port Exposure

7-6. 注意网络和端口暴露

当容器在宿主操作系统上暴露端口时，
这些端口可能会被系统外部访问。

注意事项：

• 避免不必要的 -p 80:80 映射
• 本地使用时，仅绑定到 localhost，例如 -p 127.0.0.1:8080:80
• 配合防火墙设置，如 UFW
• 生产环境中使用反向代理（如 Nginx）以提升安全性

端口管理在 VPS 或基于云的 Ubuntu 服务器上尤为关键。

7-7. Log Management During Failures

7-7. 故障期间的日志管理

可使用以下命令查看 Docker 日志：

docker logs <container-name>

大量日志会快速占用磁盘空间，
因此请考虑配置 日志驱动 和 日志轮转。

8. Common Issues and Troubleshooting

8. 常见问题与故障排除

虽然 Docker 是强大的工具，但由于环境差异或 配置错误，Ubuntu 上仍可能出现意外错误。
本节汇总了常见问题及其解决方案，适用于从初学者到中级用户。

8-1. Cannot Connect to the Docker Daemon

8-1. 无法连接到 Docker Daemon

● 错误信息

Cannot connect to the Docker daemon at unix:///var/run/docker.sock.

● 成因与解决方案

1. Docker daemon 未运行 : sudo systemctl start docker
2. docker 组的更改未生效 : 注销后重新登录，或运行 newgrp docker
3. /var/run/docker.sock 权限问题 : 确保用户属于 docker 组

8-2. Permission Denied Errors

8-2. 权限被拒错误

● 常见错误

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

● 解决方案

原因几乎总是缺少 docker 组的配置。

sudo usermod -aG docker $USER

然后注销并重新登录。

8-3. GPG Errors When Adding the APT Repository

8-3. 添加 APT 仓库时的 GPG 错误

● 错误示例

NO_PUBKEY XXXXXXXX

or

The following signatures couldn't be verified

● 成因与解决办法

• GPG 密钥未正确注册
• curl 因网络限制而失败

使用以下命令重新注册密钥：

curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
 | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

然后再次运行 sudo apt update。

8-4. 端口绑定冲突

● 错误示例

Bind for 0.0.0.0:80 failed: port is already allocated.

● 原因

• 该端口已被主机上的其他进程占用
• 另一个 Docker 容器正在使用相同的端口

● 解决方案

检查哪个进程正在使用该端口：

sudo lsof -i -P -n | grep :80

检查正在运行的容器：

docker ps

更改端口映射：

-p 8080:80

8-5. 镜像下载失败

● 常见原因

• 网络限制（企业环境）
• DNS 配置问题
• 访问 Docker Hub 被阻止

● 解决方案

• 更改 DNS 服务器（例如 1.1.1.1 或 8.8.8.8）
• 验证代理配置
• 如环境需要，使用 VPN

8-6. 磁盘空间耗尽错误

● 典型信息

no space left on device

● 解决办法

删除未使用的资源：

docker system prune -a

审查镜像、容器和卷：

docker images
docker ps -a
docker volume ls

磁盘空间耗尽是最常见的 Docker 运维问题之一。