在 Linux 上装 Docker看起来就是几条命令的事但实际上我接手过的服务器环境里相当一部分排查工作都发生在“安装”和“第一次启动”这两个阶段。网络超时、软件源不可用、GPG 公钥失效、内核驱动不匹配、权限没配上每一个报错背后都有对应的原因和固定的解法。这篇文章把我在 Ubuntu、Debian、CentOS 等主流发行版上安装 Docker 时反复踩过的坑梳理一遍给出具体的报错特征、排查思路和可直接复制的操作步骤适合正在做环境初始化的运维同学也适合第一次在 Linux 上跑 Docker 的新手。1. 装之前先检查这三件事能避开一半的坑很多人装 Docker 失败其实不是安装步骤出了问题而是前置条件没满足。与其报错之后各种查不如在动手之前花两分钟确认系统状态很多高频错误根本不会出现。1.1 系统版本与内核要求别急着敲命令Docker 对 Linux 系统本身有基本要求64 位架构、内核版本不能太老、需要支持特定的存储驱动和网络功能。以 2024 年左右的 Docker Engine 版本为例官方要求内核 3.10 以上但实际上如果你用的发行版内核太旧即使装上了 Docker启动时也会遇到 overlay2 存储驱动不可用、网络命名空间异常等问题表现就是docker run卡住或者直接报Error starting daemon。先跑下面这条命令确认基础环境uname -r cat /etc/os-release我遇到过一台 CentOS 7 老机器内核停在 3.10.0-327Docker 装是装上了但启动容器时各种诡异问题后来直接把内核升级到 3.10.0-1160 才消停。所以我的建议是优先使用发行版的 LTS 内核Ubuntu 20.04/22.04、Debian 11/12、CentOS 7.9、Rocky Linux 9 这类系统默认内核基本都没问题。如果内核太老请在安装 Docker 之前先解决内核升级的问题不要在旧内核上硬刚 Docker。另外还要确认系统架构是 amd64 还是 arm64。很多人在树莓派或者国产 ARM 服务器上安装时直接复制了 x86 的安装命令结果下载 404 或者装完启动报错。用arch命令看一眼心里就有数。1.2 软件源与网络环境大部分报错的根源Docker 的安装包不在系统默认源里需要手动添加 Docker 官方源或镜像源。这一步对国内服务器来说是最容易出问题的环节。默认源访问不稳定apt-get update或yum makecache就经常超时报错信息里几乎都带着Could not connect、Connection timed out、Failed to fetch这些字样。在动手装 Docker 之前先确认自己的软件源配置是否正常。Ubuntu 上用apt-get update跑一遍看有没有异常CentOS 上用yum repolist检查源是否可用。如果你的服务器本身访问系统默认源都很慢那大概率是网络环境的问题先把系统源替换成国内镜像源再继续往下走。这不是绕路而是排掉一个最大的干扰项。1.3 Unix Socket 权限装完第一秒就会遇到的权限问题Docker 安装完成后客户端是通过 Unix Socket 与守护进程通信的默认 socket 文件属于root用户。如果你不是 root 用户直接执行docker ps大概率就会看到这条经典报错permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock这个问题严格来说不属于“安装”阶段但它几乎总是跟着安装一起被问到所以我把它放在前置检查里。解决思路很简单把当前用户加入docker组。这个我会在第三章展开讲但你现在只需要知道安装完 Docker 之后如果不想每次都用sudo就必须处理这个权限问题别等到报错了再临时查。2. 安装过程中的高频报错与处理方案前置检查做完了进入真正的安装环节。这一阶段我按错误类型拆开讲每个错误给出报错特征、原因判断和解决命令。2.1 网络超时与源不可达换源是正路最典型的情况是在 Ubuntu 上执行apt-get install docker-ce时卡在下载阶段然后报E: Failed to fetch http://download.docker.com/linux/ubuntu/dists/jammy/InRelease Could not connect to download.docker.com这个报错几乎可以肯定是网络无法稳定访问 Docker 官方源导致的。解决思路就是换一个可达的源。我常用的做法是把手动添加的 Docker 源替换为国内镜像源以 Ubuntu 22.04 为例操作如下# 删除原来的 Docker 源配置 rm -f /etc/apt/sources.list.d/docker.list # 添加国内可用源 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 sudo apt-get updateCentOS 7 上则是修改/etc/yum.repos.d/docker-ce.repo里的 baseurl把download.docker.com替换成对应的国内镜像地址。替换完之后再安装速度差别非常明显。这里有一个需要说明的原理APT 在添加第三方源时要求源里带有 GPG 公钥信息用于校验软件包签名。所以你不仅要改源地址还得保证对应的公钥已经导入到 keyring 文件里。很多人在改完源之后发现报NO_PUBKEY错误就是因为只改了地址没同步公钥。2.2 GPG 公钥校验失败签名对不上号报错信息长这样时问题就出在公钥环节W: GPG error: https://download.docker.com/linux/ubuntu jammy InRelease: The following signatures couldnt be verified because the public key is not available: NO_PUBKEY 4D1BB29B63D98E6D这个错误的意思是APT 找到了 Docker 源但没有对应的公钥来验证软件包的签名。解决方法是重新导入 Docker 的 GPG 公钥。Ubuntu/Debian 上推荐的做法是把公钥转成二进制 keyring 格式放到/etc/apt/keyrings/下sudo install -m 0755 -d /etc/apt/keyrings sudo curl -fsSL https://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.gpg sudo chmod ar /etc/apt/keyrings/docker.gpg注意这里的公钥地址要和源地址保持一致。如果你用的是阿里云镜像源公钥也从阿里云拉否则可能出现公钥内容和源地址不匹配的情况。CentOS 上对应的是rpm --import导入公钥报错时会有类似的提示。实操中有个小坑很多人curl公钥时在代理环境或防火墙环境下失败拿到的文件是 HTML 错误页导入时提示公钥文件无效。所以导入前可以先file docker.gpg看看文件类型正常应该是OpenPGP Public Key或data。2.3 依赖冲突与半成品安装先清理再重装Debian 系系统上最容易遇到的另一类报错是The following packages have unmet dependencies: docker-ce : Depends: containerd.io ( 1.6.0) but it is not going to be installed或者 CentOS 上出现Error: Package: docker-ce-xxx.el7.x86_64 requires: container-selinux 2.107这类问题的本质是系统中已有的软件包和新装的 Docker 组件存在依赖版本冲突。处理思路是先把旧的、损坏的包清理干净再重新安装。我的操作习惯是# Ubuntu/Debian sudo apt-get remove -y docker docker-engine docker.io containerd runc sudo apt-get autoremove -y # CentOS/RHEL sudo yum remove -y docker docker-client docker-client-latest docker-common docker-latest docker-latest-logrotate docker-logrotate docker-engine sudo yum clean all清理之后同步更新一下系统索引再重新执行安装命令。如果 apt 仍然提示依赖不满足可以用apt-get install -f修复依赖关系然后再装 Docker。装的时候建议把docker-ce docker-ce-cli containerd.io三个包放在同一条命令里安装让包管理器自己协调版本不要一个个装。2.4 软件包 404 或找不到索引过期与架构不匹配有时候报错是E: Unable to locate package docker-ce或者 CentOS 上显示No package docker-ce available.这个报错的原因通常不是“Docker 不存在”而是apt-get update/yum makecache没有把 Docker 源的索引拉下来。先执行一次更新sudo apt-get update如果更新后还是找不到包检查源文件里的架构标识。比如你在 x86_64 机器上用了[archarm64]的参数那肯定找不到包。用dpkg --print-architecture或uname -m确认一下实际架构。还有一种情况是发行版版本名不匹配。比如 Ubuntu 的某个非 LTS 版本生命周期结束Docker 源里已经没有对应版本的目录。这时候要么升级系统要么改用该发行版最近的支持版本源。判断方法是访问你配置的源地址看看有没有对应的发行版目录名。3. 启动时最常遇到的三个“硬骨头”安装完成不等于万事大吉systemctl start docker这一下才是真正的考验。我把启动阶段最高频的三个问题单独拿出来讲因为它们的报错特征非常明显而且一旦遇到网上搜到的答案往往比较分散。3.1 permission denieddocker 组的身份生效时机这个开头提过但具体解法值得完整展开。报错全文是permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock原因在于/var/run/docker.sock这个 socket 文件默认属于root用户和docker组普通用户没有访问权限。官方推荐做法是把当前用户加入docker组sudo usermod -aG docker $USER很多人执行完这条命令之后立刻重新登录甚至重启却发现依然没权限。这里有一个很容易被忽略的机制用户组身份是在登录时初始化的。如果你是在当前会话里执行usermod这个会话内已经缓存的组身份不会自动刷新所以“退出重新登录”是对的但如果你用的是 SSH需要退出整个 SSH 会话再重新连接而不只是开一个新的终端标签页。如果不想重新登录也有一个临时方案可以立即生效newgrp docker这条命令会在当前 shell 里重新初始化组身份执行之后docker ps就能直接跑通。不过这个只对当前终端有效重新登录后依然需要确认用户已经在docker组里。加组之后可以用id命令验证id $USER输出里如果出现docker组就说明配置成功了。这里也顺带提一下如果你是用 root 身份在服务器上直接操作每次docker命令不写sudo就能跑通是因为 root 本身不受文件权限限制。但长期用 root 操作 Docker 不是好习惯容器里的进程映射到宿主机用户时会有安全隐患建议单独建运维账号来管理 Docker。3.2 iptables 相关启动失败nftables 后端冲突CentOS 8、Rocky Linux、部分 Debian 系系统上systemctl start docker会得到这样的结果Job for docker.service failed because the control process exited with error code.查看详细日志journalctl -u docker.service -n 50日志里如果出现了iptables failed、Failed to load nftables、unable to create NAT chain这类关键词基本就是 iptables 后端和 Docker 不兼容的问题。新版本的 Linux 发行版默认可能使用 nftables 作为防火墙后端而 Docker 引擎在特定版本和内核组合下依赖的是传统 iptables。解决方案是把系统防火墙后端强制切回 legacy 模式# Debian/Ubuntu sudo update-alternatives --set iptables /usr/sbin/iptables-legacy sudo update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy # RHEL/CentOS 8 sudo dnf install -y iptables-legacy sudo update-alternatives --set iptables /usr/sbin/iptables-legacy切换之后重启 Dockersudo systemctl restart docker如果日志是报Failed to start Docker Application Container Engine但看不到 iptables 字样那就去翻更早的日志或者执行dockerd --debug前台启动把错误信息完整暴露出来。我遇到过不少因为 systemd 日志被截断导致信息不全的案例前台启动是排查这类问题最直接的手段。3.3 cgroup 驱动不匹配docker info 里的警告Docker 启动成功了但你执行docker info时可能会看到警告WARNING: No cpu cfs quota support WARNING: No io.weight support或者容器运行时报failed to create task for container: failed to create controller这通常和 cgroup 驱动设置有关。Docker 在 Linux 上支持两种 cgroup 驱动cgroupfs和systemd。如果你的系统使用 systemd 作为 init 系统官方推荐让 Docker 使用systemd驱动因为它和 systemd 的资源管理机制配合更稳定。配置方式是在/etc/docker/daemon.json里加入{ exec-opts: [native.cgroupdriversystemd] }改完之后重启 Dockersudo systemctl restart docker docker info | grep cgroup输出里如果显示Cgroup Driver: systemd说明配置生效了。另外如果你用的是较老的内核且文件系统不支持某些特性警告可能依然存在这时候要考虑升级内核而不是反复调 Docker 参数。4. 镜像拉取与容器使用阶段的典型故障装好了、启动了接下来大概率会遇到的是镜像拉取和容器运行的问题。这些虽然严格来说不属于“安装错误”但新装完 Docker 的用户往往会在第一时间去拉第一个镜像这些错误就紧跟着出现。4.1 镜像拉取超时与搜索失败配置 registry mirror新装好的 Docker 默认从 Docker Hub 拉取镜像。由于网络可达性原因国内执行docker pull nginx经常出现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)或者拉取进度卡在某个百分比不动。最常规的解决方案是给 Docker 配置国内可靠的镜像加速器。编辑/etc/docker/daemon.json如果文件不存在就新建加入{ registry-mirrors: [ https://docker.m.daocloud.io, https://dockerproxy.com, https://docker.mirrors.ustc.edu.cn ] }这里的加速地址用过多个选择两个相对稳定的即可。注意daemon.json是 JSON 格式配置错误会导致 Docker 启动失败。改完后先执行sudo systemctl restart docker再执行docker info确认 Registry Mirrors 列表是否加载。有时配置了加速器后拉取行为会变成 404 或者 manifest unknown大概率是加速器对某个镜像的同步不完整。这时候可以换一个加速器地址或者直接指定完整镜像路径拉取。如果是私有仓库的镜像则不需要走公网加速器应确认insecure-registries是否配置正确。4.2 存储驱动异常overlay2 与 XFS 的兼容问题执行docker pull或启动容器时报Error starting daemon: error initializing graphdriver: driver not supported或者较长日志里出现overlay2: backing file system is unsupported这说明 Docker 无法使用默认的 overlay2 存储驱动。overlay2 要求底层文件系统支持 d_type 特性。如果你用的是 XFS 文件系统并且创建时没有开启 ftype 选项就会出现这个错误老版本的内核也有类似限制。判断当前文件系统df -T /var/lib/docker如果显示是 xfs 且报错可以考虑两种方案一是重新格式化分区为 ext4 或带 ftype 的 XFS但这需要重装系统或迁移数据二是在不支持 overlay2 的旧内核机器上临时切换到 vfs 或 devicemapper 驱动但性能会明显下降不推荐长期使用。{ storage-driver: vfs }这个配置能让 Docker 在旧环境上跑起来但体验很差镜像占据的磁盘空间成倍增加。我的经验是如果生产环境遇到这个问题优先考虑升级系统或更换分区格式而不是妥协用 vfs。4.3 容器内无法解析域名DNS 配置问题运行容器时发现容器内无法访问域名比如curl: (6) Could not resolve host: www.baidu.com宿主机网络正常容器外一切正常问题多半出在 Docker 的 DNS 配置上。Docker 默认会从宿主机读取 DNS 配置但在某些网络环境比如 systemd-resolved 监听在 127.0.0.53 上下容器内无法访问这个地址。解决方法是在daemon.json里显式指定 DNS{ dns: [223.5.5.5, 114.114.114.114] }重启 Docker 后重新创建容器即可生效。注意已经运行的容器不会自动更新 DNS 配置需要重新创建。5. 一次完整的 Ubuntu 安装实操流程前面讲的是错误分析这一节我给出一套完整的、经过多次验证的 Ubuntu 22.04 安装流程每一步都写清楚目的和验证方式。其他发行版的操作大同小异只需替换包管理命令。5.1 清理旧环境与系统准备sudo apt-get remove -y docker docker-engine docker.io containerd runc sudo apt-get update即使你的机器上从来没有装过 Docker也建议执行一次清理命令避免系统里残留的旧版 containerd 或 runc 与新版冲突。接着安装 Docker 依赖的基础工具sudo apt-get install -y ca-certificates curl gnupg lsb-release这些工具是添加 GPG 公钥和源的必需组件。很多精简版系统默认没有curl或gnupg这里一并装上。5.2 添加 Docker 源与安装创建 keyring 目录并导入公钥sudo install -m 0755 -d /etc/apt/keyrings sudo curl -fsSL https://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.gpg sudo chmod ar /etc/apt/keyrings/docker.gpg添加源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执行更新并安装sudo apt-get update sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin这里的docker-buildx-plugin和docker-compose-plugin是构建镜像和编排容器时需要的插件建议一次性装好。CentOS/RHEL 系用yum-config-manager --add-repo添加源然后yum install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin逻辑是相同的。5.3 启动配置与权限sudo systemctl enable --now docker sudo systemctl status docker确认 Active 状态是active (running)。接着把当前用户加进 docker 组sudo usermod -aG docker $USER newgrp dockernewgrp让当前会话立即生效。如果docker ps能列出空表而不报权限错误说明权限配置成功。5.4 验证安装并配置加速器执行官方测试镜像docker run hello-world如果能正常打印出Hello from Docker!的说明文字整个安装流程已经完成。接着配置镜像加速器编辑/etc/docker/daemon.json写入{ registry-mirrors: [ https://docker.m.daocloud.io, https://docker.mirrors.ustc.edu.cn ], exec-opts: [native.cgroupdriversystemd], log-driver: json-file, log-opts: { max-size: 100m, max-file: 3 } }这里的日志配置是我个人习惯限制单个容器日志文件大小避免日志无限膨胀把磁盘写满。重启 Docker 后再执行docker info确认 Cgroup Driver 为 systemd、Registry Mirrors 已加载整套环境就算真正可用了。6. 常见问题排查速查表与个人经验最后把上面所有问题浓缩成一张速查表方便直接对照。报错特征主要原因处理方向Could not connect to download.docker.com官方源网络不可达替换为国内镜像源NO_PUBKEY签名错误GPG 公钥未导入或不匹配重新下载并导入公钥Unable to locate package docker-ce索引过期或架构不符先 update再查 archpackage docker-ce requires containerd.io依赖版本冲突清理旧包后一次性安装三件套permission denied ... docker.sock用户不在 docker 组usermod -aG docker并重新登录iptables failed/nftables报错防火墙后端不兼容切换 iptables-legacydriver not supported/ overlay2 xfs文件系统缺 d_type重格分区或换驱动request canceled while waiting for connection拉取镜像超时配置 registry-mirrorsTemporary failure in name resolution容器内 DNS 异常显式配置 dns 字段这里面每一条我都实际遇到过而且踩过坑的版本不止一种。就拿公钥问题来说有一次我顺手把公钥下载到了家目录然后切换了用户去执行导入结果明明文件存在却提示找不到文件目录后来才意识到是路径问题。这类问题排查时候多看看绝对路径少用~和相对路径。我个人的习惯是任何一台新服务器上装 Docker都会先花五分钟检查内核版本、文件系统和软件源这五分钟的“慢”确实能省下后面不少工夫。装完之后立刻把daemon.json配置好包括镜像加速、日志限制、cgroup 驱动而不是等出了问题再补。还有一点想提醒的是/var/lib/docker所在分区要留够空间容器镜像和数据卷的膨胀速度往往比你预期的快。如果再遇到没写进这里的 Docker 安装错误先执行journalctl -u docker.service -n 100看完整日志多半能从日志里直接定位到原因这个习惯比到处搜索更能解决问题。
在 Linux 上装 Docker看起来就是几条命令的事但实际上我接手过的服务器环境里相当一部分排查工作都发生在“安装”和“第一次启动”这两个阶段。网络超时、软件源不可用、GPG 公钥失效、内核驱动不匹配、权限没配上每一个报错背后都有对应的原因和固定的解法。这篇文章把我在 Ubuntu、Debian、CentOS 等主流发行版上安装 Docker 时反复踩过的坑梳理一遍给出具体的报错特征、排查思路和可直接复制的操作步骤适合正在做环境初始化的运维同学也适合第一次在 Linux 上跑 Docker 的新手。1. 装之前先检查这三件事能避开一半的坑很多人装 Docker 失败其实不是安装步骤出了问题而是前置条件没满足。与其报错之后各种查不如在动手之前花两分钟确认系统状态很多高频错误根本不会出现。1.1 系统版本与内核要求别急着敲命令Docker 对 Linux 系统本身有基本要求64 位架构、内核版本不能太老、需要支持特定的存储驱动和网络功能。以 2024 年左右的 Docker Engine 版本为例官方要求内核 3.10 以上但实际上如果你用的发行版内核太旧即使装上了 Docker启动时也会遇到 overlay2 存储驱动不可用、网络命名空间异常等问题表现就是docker run卡住或者直接报Error starting daemon。先跑下面这条命令确认基础环境uname -r cat /etc/os-release我遇到过一台 CentOS 7 老机器内核停在 3.10.0-327Docker 装是装上了但启动容器时各种诡异问题后来直接把内核升级到 3.10.0-1160 才消停。所以我的建议是优先使用发行版的 LTS 内核Ubuntu 20.04/22.04、Debian 11/12、CentOS 7.9、Rocky Linux 9 这类系统默认内核基本都没问题。如果内核太老请在安装 Docker 之前先解决内核升级的问题不要在旧内核上硬刚 Docker。另外还要确认系统架构是 amd64 还是 arm64。很多人在树莓派或者国产 ARM 服务器上安装时直接复制了 x86 的安装命令结果下载 404 或者装完启动报错。用arch命令看一眼心里就有数。1.2 软件源与网络环境大部分报错的根源Docker 的安装包不在系统默认源里需要手动添加 Docker 官方源或镜像源。这一步对国内服务器来说是最容易出问题的环节。默认源访问不稳定apt-get update或yum makecache就经常超时报错信息里几乎都带着Could not connect、Connection timed out、Failed to fetch这些字样。在动手装 Docker 之前先确认自己的软件源配置是否正常。Ubuntu 上用apt-get update跑一遍看有没有异常CentOS 上用yum repolist检查源是否可用。如果你的服务器本身访问系统默认源都很慢那大概率是网络环境的问题先把系统源替换成国内镜像源再继续往下走。这不是绕路而是排掉一个最大的干扰项。1.3 Unix Socket 权限装完第一秒就会遇到的权限问题Docker 安装完成后客户端是通过 Unix Socket 与守护进程通信的默认 socket 文件属于root用户。如果你不是 root 用户直接执行docker ps大概率就会看到这条经典报错permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock这个问题严格来说不属于“安装”阶段但它几乎总是跟着安装一起被问到所以我把它放在前置检查里。解决思路很简单把当前用户加入docker组。这个我会在第三章展开讲但你现在只需要知道安装完 Docker 之后如果不想每次都用sudo就必须处理这个权限问题别等到报错了再临时查。2. 安装过程中的高频报错与处理方案前置检查做完了进入真正的安装环节。这一阶段我按错误类型拆开讲每个错误给出报错特征、原因判断和解决命令。2.1 网络超时与源不可达换源是正路最典型的情况是在 Ubuntu 上执行apt-get install docker-ce时卡在下载阶段然后报E: Failed to fetch http://download.docker.com/linux/ubuntu/dists/jammy/InRelease Could not connect to download.docker.com这个报错几乎可以肯定是网络无法稳定访问 Docker 官方源导致的。解决思路就是换一个可达的源。我常用的做法是把手动添加的 Docker 源替换为国内镜像源以 Ubuntu 22.04 为例操作如下# 删除原来的 Docker 源配置 rm -f /etc/apt/sources.list.d/docker.list # 添加国内可用源 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 sudo apt-get updateCentOS 7 上则是修改/etc/yum.repos.d/docker-ce.repo里的 baseurl把download.docker.com替换成对应的国内镜像地址。替换完之后再安装速度差别非常明显。这里有一个需要说明的原理APT 在添加第三方源时要求源里带有 GPG 公钥信息用于校验软件包签名。所以你不仅要改源地址还得保证对应的公钥已经导入到 keyring 文件里。很多人在改完源之后发现报NO_PUBKEY错误就是因为只改了地址没同步公钥。2.2 GPG 公钥校验失败签名对不上号报错信息长这样时问题就出在公钥环节W: GPG error: https://download.docker.com/linux/ubuntu jammy InRelease: The following signatures couldnt be verified because the public key is not available: NO_PUBKEY 4D1BB29B63D98E6D这个错误的意思是APT 找到了 Docker 源但没有对应的公钥来验证软件包的签名。解决方法是重新导入 Docker 的 GPG 公钥。Ubuntu/Debian 上推荐的做法是把公钥转成二进制 keyring 格式放到/etc/apt/keyrings/下sudo install -m 0755 -d /etc/apt/keyrings sudo curl -fsSL https://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.gpg sudo chmod ar /etc/apt/keyrings/docker.gpg注意这里的公钥地址要和源地址保持一致。如果你用的是阿里云镜像源公钥也从阿里云拉否则可能出现公钥内容和源地址不匹配的情况。CentOS 上对应的是rpm --import导入公钥报错时会有类似的提示。实操中有个小坑很多人curl公钥时在代理环境或防火墙环境下失败拿到的文件是 HTML 错误页导入时提示公钥文件无效。所以导入前可以先file docker.gpg看看文件类型正常应该是OpenPGP Public Key或data。2.3 依赖冲突与半成品安装先清理再重装Debian 系系统上最容易遇到的另一类报错是The following packages have unmet dependencies: docker-ce : Depends: containerd.io ( 1.6.0) but it is not going to be installed或者 CentOS 上出现Error: Package: docker-ce-xxx.el7.x86_64 requires: container-selinux 2.107这类问题的本质是系统中已有的软件包和新装的 Docker 组件存在依赖版本冲突。处理思路是先把旧的、损坏的包清理干净再重新安装。我的操作习惯是# Ubuntu/Debian sudo apt-get remove -y docker docker-engine docker.io containerd runc sudo apt-get autoremove -y # CentOS/RHEL sudo yum remove -y docker docker-client docker-client-latest docker-common docker-latest docker-latest-logrotate docker-logrotate docker-engine sudo yum clean all清理之后同步更新一下系统索引再重新执行安装命令。如果 apt 仍然提示依赖不满足可以用apt-get install -f修复依赖关系然后再装 Docker。装的时候建议把docker-ce docker-ce-cli containerd.io三个包放在同一条命令里安装让包管理器自己协调版本不要一个个装。2.4 软件包 404 或找不到索引过期与架构不匹配有时候报错是E: Unable to locate package docker-ce或者 CentOS 上显示No package docker-ce available.这个报错的原因通常不是“Docker 不存在”而是apt-get update/yum makecache没有把 Docker 源的索引拉下来。先执行一次更新sudo apt-get update如果更新后还是找不到包检查源文件里的架构标识。比如你在 x86_64 机器上用了[archarm64]的参数那肯定找不到包。用dpkg --print-architecture或uname -m确认一下实际架构。还有一种情况是发行版版本名不匹配。比如 Ubuntu 的某个非 LTS 版本生命周期结束Docker 源里已经没有对应版本的目录。这时候要么升级系统要么改用该发行版最近的支持版本源。判断方法是访问你配置的源地址看看有没有对应的发行版目录名。3. 启动时最常遇到的三个“硬骨头”安装完成不等于万事大吉systemctl start docker这一下才是真正的考验。我把启动阶段最高频的三个问题单独拿出来讲因为它们的报错特征非常明显而且一旦遇到网上搜到的答案往往比较分散。3.1 permission denieddocker 组的身份生效时机这个开头提过但具体解法值得完整展开。报错全文是permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock原因在于/var/run/docker.sock这个 socket 文件默认属于root用户和docker组普通用户没有访问权限。官方推荐做法是把当前用户加入docker组sudo usermod -aG docker $USER很多人执行完这条命令之后立刻重新登录甚至重启却发现依然没权限。这里有一个很容易被忽略的机制用户组身份是在登录时初始化的。如果你是在当前会话里执行usermod这个会话内已经缓存的组身份不会自动刷新所以“退出重新登录”是对的但如果你用的是 SSH需要退出整个 SSH 会话再重新连接而不只是开一个新的终端标签页。如果不想重新登录也有一个临时方案可以立即生效newgrp docker这条命令会在当前 shell 里重新初始化组身份执行之后docker ps就能直接跑通。不过这个只对当前终端有效重新登录后依然需要确认用户已经在docker组里。加组之后可以用id命令验证id $USER输出里如果出现docker组就说明配置成功了。这里也顺带提一下如果你是用 root 身份在服务器上直接操作每次docker命令不写sudo就能跑通是因为 root 本身不受文件权限限制。但长期用 root 操作 Docker 不是好习惯容器里的进程映射到宿主机用户时会有安全隐患建议单独建运维账号来管理 Docker。3.2 iptables 相关启动失败nftables 后端冲突CentOS 8、Rocky Linux、部分 Debian 系系统上systemctl start docker会得到这样的结果Job for docker.service failed because the control process exited with error code.查看详细日志journalctl -u docker.service -n 50日志里如果出现了iptables failed、Failed to load nftables、unable to create NAT chain这类关键词基本就是 iptables 后端和 Docker 不兼容的问题。新版本的 Linux 发行版默认可能使用 nftables 作为防火墙后端而 Docker 引擎在特定版本和内核组合下依赖的是传统 iptables。解决方案是把系统防火墙后端强制切回 legacy 模式# Debian/Ubuntu sudo update-alternatives --set iptables /usr/sbin/iptables-legacy sudo update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy # RHEL/CentOS 8 sudo dnf install -y iptables-legacy sudo update-alternatives --set iptables /usr/sbin/iptables-legacy切换之后重启 Dockersudo systemctl restart docker如果日志是报Failed to start Docker Application Container Engine但看不到 iptables 字样那就去翻更早的日志或者执行dockerd --debug前台启动把错误信息完整暴露出来。我遇到过不少因为 systemd 日志被截断导致信息不全的案例前台启动是排查这类问题最直接的手段。3.3 cgroup 驱动不匹配docker info 里的警告Docker 启动成功了但你执行docker info时可能会看到警告WARNING: No cpu cfs quota support WARNING: No io.weight support或者容器运行时报failed to create task for container: failed to create controller这通常和 cgroup 驱动设置有关。Docker 在 Linux 上支持两种 cgroup 驱动cgroupfs和systemd。如果你的系统使用 systemd 作为 init 系统官方推荐让 Docker 使用systemd驱动因为它和 systemd 的资源管理机制配合更稳定。配置方式是在/etc/docker/daemon.json里加入{ exec-opts: [native.cgroupdriversystemd] }改完之后重启 Dockersudo systemctl restart docker docker info | grep cgroup输出里如果显示Cgroup Driver: systemd说明配置生效了。另外如果你用的是较老的内核且文件系统不支持某些特性警告可能依然存在这时候要考虑升级内核而不是反复调 Docker 参数。4. 镜像拉取与容器使用阶段的典型故障装好了、启动了接下来大概率会遇到的是镜像拉取和容器运行的问题。这些虽然严格来说不属于“安装错误”但新装完 Docker 的用户往往会在第一时间去拉第一个镜像这些错误就紧跟着出现。4.1 镜像拉取超时与搜索失败配置 registry mirror新装好的 Docker 默认从 Docker Hub 拉取镜像。由于网络可达性原因国内执行docker pull nginx经常出现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)或者拉取进度卡在某个百分比不动。最常规的解决方案是给 Docker 配置国内可靠的镜像加速器。编辑/etc/docker/daemon.json如果文件不存在就新建加入{ registry-mirrors: [ https://docker.m.daocloud.io, https://dockerproxy.com, https://docker.mirrors.ustc.edu.cn ] }这里的加速地址用过多个选择两个相对稳定的即可。注意daemon.json是 JSON 格式配置错误会导致 Docker 启动失败。改完后先执行sudo systemctl restart docker再执行docker info确认 Registry Mirrors 列表是否加载。有时配置了加速器后拉取行为会变成 404 或者 manifest unknown大概率是加速器对某个镜像的同步不完整。这时候可以换一个加速器地址或者直接指定完整镜像路径拉取。如果是私有仓库的镜像则不需要走公网加速器应确认insecure-registries是否配置正确。4.2 存储驱动异常overlay2 与 XFS 的兼容问题执行docker pull或启动容器时报Error starting daemon: error initializing graphdriver: driver not supported或者较长日志里出现overlay2: backing file system is unsupported这说明 Docker 无法使用默认的 overlay2 存储驱动。overlay2 要求底层文件系统支持 d_type 特性。如果你用的是 XFS 文件系统并且创建时没有开启 ftype 选项就会出现这个错误老版本的内核也有类似限制。判断当前文件系统df -T /var/lib/docker如果显示是 xfs 且报错可以考虑两种方案一是重新格式化分区为 ext4 或带 ftype 的 XFS但这需要重装系统或迁移数据二是在不支持 overlay2 的旧内核机器上临时切换到 vfs 或 devicemapper 驱动但性能会明显下降不推荐长期使用。{ storage-driver: vfs }这个配置能让 Docker 在旧环境上跑起来但体验很差镜像占据的磁盘空间成倍增加。我的经验是如果生产环境遇到这个问题优先考虑升级系统或更换分区格式而不是妥协用 vfs。4.3 容器内无法解析域名DNS 配置问题运行容器时发现容器内无法访问域名比如curl: (6) Could not resolve host: www.baidu.com宿主机网络正常容器外一切正常问题多半出在 Docker 的 DNS 配置上。Docker 默认会从宿主机读取 DNS 配置但在某些网络环境比如 systemd-resolved 监听在 127.0.0.53 上下容器内无法访问这个地址。解决方法是在daemon.json里显式指定 DNS{ dns: [223.5.5.5, 114.114.114.114] }重启 Docker 后重新创建容器即可生效。注意已经运行的容器不会自动更新 DNS 配置需要重新创建。5. 一次完整的 Ubuntu 安装实操流程前面讲的是错误分析这一节我给出一套完整的、经过多次验证的 Ubuntu 22.04 安装流程每一步都写清楚目的和验证方式。其他发行版的操作大同小异只需替换包管理命令。5.1 清理旧环境与系统准备sudo apt-get remove -y docker docker-engine docker.io containerd runc sudo apt-get update即使你的机器上从来没有装过 Docker也建议执行一次清理命令避免系统里残留的旧版 containerd 或 runc 与新版冲突。接着安装 Docker 依赖的基础工具sudo apt-get install -y ca-certificates curl gnupg lsb-release这些工具是添加 GPG 公钥和源的必需组件。很多精简版系统默认没有curl或gnupg这里一并装上。5.2 添加 Docker 源与安装创建 keyring 目录并导入公钥sudo install -m 0755 -d /etc/apt/keyrings sudo curl -fsSL https://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.gpg sudo chmod ar /etc/apt/keyrings/docker.gpg添加源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执行更新并安装sudo apt-get update sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin这里的docker-buildx-plugin和docker-compose-plugin是构建镜像和编排容器时需要的插件建议一次性装好。CentOS/RHEL 系用yum-config-manager --add-repo添加源然后yum install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin逻辑是相同的。5.3 启动配置与权限sudo systemctl enable --now docker sudo systemctl status docker确认 Active 状态是active (running)。接着把当前用户加进 docker 组sudo usermod -aG docker $USER newgrp dockernewgrp让当前会话立即生效。如果docker ps能列出空表而不报权限错误说明权限配置成功。5.4 验证安装并配置加速器执行官方测试镜像docker run hello-world如果能正常打印出Hello from Docker!的说明文字整个安装流程已经完成。接着配置镜像加速器编辑/etc/docker/daemon.json写入{ registry-mirrors: [ https://docker.m.daocloud.io, https://docker.mirrors.ustc.edu.cn ], exec-opts: [native.cgroupdriversystemd], log-driver: json-file, log-opts: { max-size: 100m, max-file: 3 } }这里的日志配置是我个人习惯限制单个容器日志文件大小避免日志无限膨胀把磁盘写满。重启 Docker 后再执行docker info确认 Cgroup Driver 为 systemd、Registry Mirrors 已加载整套环境就算真正可用了。6. 常见问题排查速查表与个人经验最后把上面所有问题浓缩成一张速查表方便直接对照。报错特征主要原因处理方向Could not connect to download.docker.com官方源网络不可达替换为国内镜像源NO_PUBKEY签名错误GPG 公钥未导入或不匹配重新下载并导入公钥Unable to locate package docker-ce索引过期或架构不符先 update再查 archpackage docker-ce requires containerd.io依赖版本冲突清理旧包后一次性安装三件套permission denied ... docker.sock用户不在 docker 组usermod -aG docker并重新登录iptables failed/nftables报错防火墙后端不兼容切换 iptables-legacydriver not supported/ overlay2 xfs文件系统缺 d_type重格分区或换驱动request canceled while waiting for connection拉取镜像超时配置 registry-mirrorsTemporary failure in name resolution容器内 DNS 异常显式配置 dns 字段这里面每一条我都实际遇到过而且踩过坑的版本不止一种。就拿公钥问题来说有一次我顺手把公钥下载到了家目录然后切换了用户去执行导入结果明明文件存在却提示找不到文件目录后来才意识到是路径问题。这类问题排查时候多看看绝对路径少用~和相对路径。我个人的习惯是任何一台新服务器上装 Docker都会先花五分钟检查内核版本、文件系统和软件源这五分钟的“慢”确实能省下后面不少工夫。装完之后立刻把daemon.json配置好包括镜像加速、日志限制、cgroup 驱动而不是等出了问题再补。还有一点想提醒的是/var/lib/docker所在分区要留够空间容器镜像和数据卷的膨胀速度往往比你预期的快。如果再遇到没写进这里的 Docker 安装错误先执行journalctl -u docker.service -n 100看完整日志多半能从日志里直接定位到原因这个习惯比到处搜索更能解决问题。
![第1章，[Win32 章节]：动态链接库](http://pic.xiahunao.cn/yaotu/第1章，[Win32 章节]：动态链接库)
