Docker 安装与疑难问题排查解决指南

本文档记录了一次完整的 Docker 安装、配置镜像加速以及解决一系列复杂配置不生效问题的过程，旨在为遇到类似“幽灵”问题的用户提供一份从入门到深度排查的完整指南。

一、 Docker 标准安装与配置（Ubuntu）

在 Ubuntu 系统上安装 Docker Engine 的标准步骤。

1. 准备工作

更新 apt 包索引并安装必要的依赖软件。

Bash

1
2
sudo apt-get update
sudo apt-get install ca-certificates curl

2. 添加 Docker 官方 GPG 密钥

为了确保下载的软件包是官方且未被篡改的，需要添加 Docker 的 GPG 密钥。

Bash

1
2
3
4
5
6
7
8
# 创建用于存放密钥的目录
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 包管理器去哪里下载 Docker。

Bash

1
2
3
4
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

4. 安装 Docker 引擎

更新 apt 索引并安装 Docker。

Bash

1
2
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y

二、 问题一：Docker 拉取镜像超时

在国内网络环境下，直接从官方 Docker Hub 拉取镜像经常会遇到超时问题。

初始错误

1
Error response from daemon: Get "https://registry-1.docker.io/v2/": net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)

解决方案：配置国内镜像加速器

最有效的解决方法是使用国内云服务商提供的镜像加速服务，例如阿里云。

  1. 获取加速器地址 访问阿里云容器镜像服务控制台，在“镜像加速器”页面找到你的专属地址，格式为 https://<你的ID>.mirror.aliyuncs.com。
  2. 创建 Docker 配置文件 创建或修改 /etc/docker/daemon.json 文件，并写入你的加速器地址。 Bash 
    1
    2
    3
    4
    5
    6
    sudo mkdir -p /etc/docker
    sudo tee /etc/docker/daemon.json <<-'EOF'
    {
      "registry-mirrors": ["https://<你的ID>.mirror.aliyuncs.com"]
    }
    EOF
  3. 重启 Docker 服务 Bash 
    1
    2
    sudo systemctl daemon-reload
    sudo systemctl restart docker

三、 问题二：镜像配置不生效的深度排查

这是一个复杂问题的排查过程，记录了当 daemon.json 的配置看似正确但并未生效时的解决思路。

核心症状

即使 daemon.json 配置正确且 Docker 服务已重启，docker info 命令的输出中 Registry Mirrors 字段依然为空，拉取镜像时仍然请求官方地址。

排查过程

  1. 确认配置文件和服务状态
    • cat /etc/docker/daemon.json：确认文件内容和 JSON 格式无误。
    • sudo systemctl status docker：确认 Docker 服务处于 active (running) 状态，且启动日志无明显错误。
  2. 寻找更高优先级的配置（失败的尝试）
    • ls -l /etc/systemd/system/docker.service.d/：检查是否存在 systemd 覆盖文件。初始排查时发现该目录不存在。
  3. 定位根本原因（关键发现）
    • ps aux | grep dockerd：检查正在运行的 Docker 守护进程的实际启动参数。
    • 发现：启动命令为 /usr/bin/dockerd -H fd:// ...，其中并没有包含 --config-file /etc/docker/daemon.json 参数。
    • 结论：当前系统的 Docker 服务在启动时，并未被配置为自动加载 /etc/docker/daemon.json 文件。

修复尝试：强制加载配置文件

通过创建 systemd 覆盖文件来修改 Docker 的启动命令。

Bash

1
2
3
4
5
6
7
8
9
10
11
12
13
# 1. 创建目录
sudo mkdir -p /etc/systemd/system/docker.service.d

# 2. 创建覆盖文件，强制加载 daemon.json
sudo tee /etc/systemd/system/docker.service.d/override.conf <<-'EOF'
[Service]
ExecStart=
ExecStart=/usr/bin/dockerd --config-file /etc/docker/daemon.json -H fd:// --containerd=/run/containerd/containerd.sock
EOF

# 3. 重载配置并重启服务
sudo systemctl daemon-reload
sudo systemctl restart docker

结果：在本次排查中，即便是执行了上述修复，问题依然存在，这指向了更深层次的环境问题。

四、 最终解决方案：彻底重装 Docker

当所有常规和深度排查手段都失效时，说明 Docker 的安装环境可能已处于一种无法预知的“损坏”状态。最可靠的解决方案是彻底清理并重装。

  1. 彻底卸载 Docker Bash 
    1
    sudo apt-get purge docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y
  2. 清理所有残留文件（非常重要） 警告：此操作会删除所有本地的 Docker 镜像、容器和数据卷。 Bash 
    1
    2
    3
    4
    sudo rm -rf /var/lib/docker
    sudo rm -rf /var/lib/containerd
    sudo rm -rf /etc/docker
    sudo rm -rf /etc/systemd/system/docker.service.d
  3. 从一个纯净的状态重新安装 重复本文档 第一节 中的所有安装步骤。
  4. 在首次启动前配置镜像 在完成安装后、启动 Docker 服务之前，先创建好镜像配置文件。 Bash 
    1
    2
    3
    4
    5
    6
    sudo mkdir -p /etc/docker
    sudo tee /etc/docker/daemon.json <<-'EOF'
    {
      "registry-mirrors": ["https://<你的ID>.mirror.aliyuncs.com"]
    }
    EOF
  5. 启动并验证 Bash 
    1
    2
    3
    sudo systemctl start docker
    sudo systemctl enable docker
    docker info | grep "Registry Mirrors"
    经过彻底重装，所有隐藏的配置冲突和状态问题都应被清除，镜像配置最终生效。

五、 附录：解决 wget SSL 连接失败问题

问题描述

在使用 wget 下载文件时，出现 无法建立 SSL 连接。 的错误。

根本原因

最常见的原因是客户端的系统时间不正确。SSL 证书有严格的有效期，如果系统时间与真实时间偏差过大（即使只是一天），就会导致证书验证失败。

解决方案

  1. 校准系统时间（首选） 使用 timedatectl 命令开启网络时间同步（NTP）。 Bash 
    1
    sudo timedatectl set-ntp true
    然后使用 date 命令验证时间是否已校准。
  2. 更新 CA 根证书（备选） 如果时间准确无误，可以尝试强制重装系统的 CA 证书包。 Bash 
    1
    2
    sudo apt-get update
    sudo apt-get install --reinstall ca-certificates