你有没有遇到过这样的场景费了好大劲把 Docker 装上兴冲冲地敲下docker ps结果屏幕上一行红字permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock这种感觉就像门锁装好了却发现钥匙孔被自己忽略了人反而被刚装好的门锁挡在门外。这几年我在 Ubuntu、CentOS、Debian 上反复安装 Docker也在群里看过无数类似的报错截图翻来覆去其实都是那几类原因。这篇文章不会去复述“Docker 是什么”而是把安装阶段、启动阶段、装完跑不起来这三个环节里最常见的高频报错一条条拆开报错长什么样、根因在哪、怎么排查、怎么彻底解决。适合刚入门的 Linux 同学也适合运维同事在群里遇到问题直接转发。1. 安装前先把这三类环境问题排掉少走一半弯路1.1 内核版本与 overlay 文件系统为什么 CentOS 7 最容易翻车Docker 本质上是依赖 Linux 内核的 namespace、cgroup、网络桥接等能力才能跑起来的容器运行时。所以内核太老往往不是“能不能装上”的问题而是“装完能不能正常启动”的问题。官方对内核版本有过一个建议值3.10 以上。但这里很多人会误解以为只要内核大于 3.10 就可以闭眼装最新版 Docker。实际体验告诉我CentOS 7 默认的 3.10 内核装新版 docker-ce装是能装上启动起来什么都可能发生。我遇到的最典型报错有两类一类是failed to mount overlay: operation not permitted另一类是启动容器时打开 Docker 日志看到backing filesystem is unsupported。前者通常和 overlay 模块没有被加载有关后者常出现在/var/lib/docker所在分区是 xfs 且没有开启 ftype 的场景。在动手安装之前建议先跑三条命令确认环境uname -r grep overlay /proc/filesystems findmnt -o TARGET,FSTYPE,OPTIONS /var/lib/docker第一条看内核版本第二条确认 overlay 文件系统是否被内核支持第三条看/var/lib/docker将来要落盘的位置是什么文件系统。如果findmnt显示 xfs并且后续安装报 overlay 相关错误可以用xfs_info看一下有没有ftype1xfs_info /var/lib/docker 2/dev/null | grep ftype如果返回的ftype0overlay2 基本是没法在这个目录上用的要么换 ext4 分区要么在格式化时加上-n ftype1。对大多数临时环境来说还有一个快速验证方法就是在启动 Docker 时临时指定另一个存储驱动sudo dockerd --storage-driver vfs不过 vfs 性能一般只适合临时排错不能作为长期方案。如果你的生产服务器是 CentOS 7 的老内核我更建议直接把系统内核整体升级或者换用较新的系统发行版而不是在这里硬顶着降级 Docker 版本。1.2 旧版本残留一把梭重装反而埋雷很多新手遇到 Docker 装不上第一反应是卸载重装。但麻烦的是过去你可能不是通过官方 Docker 仓库装的而是直接apt install docker.io或者yum install docker这两个包是发行版自带的 Docker和现在官方源里的 docker-ce 在文件路径、服务名称、默认启动方式上都有差异。只删包不删配置是最常见的残留形式。比如/var/lib/docker目录里可能还留着上一任 Docker 创建的数据卷、容器目录和镜像层/etc/docker下可能还有旧的 daemon.json应用服务可能已经注册了docker.service。装新包时这些残留会让系统出现同名文件冲突甚至出现“明明是新版本行为却像旧版本”的诡异现象。安装前先检查一下系统里现在的包# Ubuntu / Debian apt list --installed 2/dev/null | grep -i docker # CentOS / RHEL rpm -qa | grep -i docker如果确实存在旧包可以卸载但在卸载之前务必想清楚/var/lib/docker里有没有你要保留的数据卷如果有先备份再卸载。网上很多教程直接让你rm -rf /var/lib/docker这个操作对生产环境来说风险非常大删掉之后里面所有容器数据都找不回来。1.3 软件源与网络环境装之前先确认能不能连上仓库其实大部分“安装失败”都不是因为命令敲错了而是网络环境没确认。Docker 安装包来自官方仓库如果你的机器所在网络无法访问官方仓库后面每一步都可能是错的。安装前简单验证一下网络curl -I https://download.docker.com这条命令能返回正常的 HTTP 响应头说明网络通路没问题如果超时、拒绝连接、证书校验失败那你要先解决软件源连通性的问题。对国内服务器来说更常见的做法是配置一个能访问的软件源然后再把 Docker 官方仓库添加到软件源列表中。这里需要注意一个概念安装 Docker 用的是“软件源”而装完 Docker 后拉取镜像用的是“镜像加速器”。这是两个完全不同的东西。软件源解决的是apt-get install docker-ce能不能找到包的问题镜像加速器解决的是docker pull nginx能不能快速拉取镜像的问题。很多人把这两个混为一谈结果安装包下载不下来以为是镜像加速没配好实际上问题根本不在一个层面。2. 安装阶段高频报错元数据、候选版本和依赖三座大山2.1 仓库元数据获取失败404 和 Release 文件不存在的根源在 Ubuntu / Debian 系统上添加 Docker 官方仓库你大概率会看到下面这类报错E: The repository https://download.docker.com/linux/ubuntu focal Release does not have a Release file. W: Failed to fetch https://download.docker.com/linux/ubuntu/dists/focal/InRelease 404 Not Found第一反应不要怀疑官方仓库挂了99% 是自己源配错了。最常见的有三种情况arch架构写错了比如把amd64写成armhf发行版代号写死了比如你明明是 Ubuntu 20.04focal源里却写的bionic系统里残留了一两个已经失效的旧 Docker 源和官方源叠加在一起。正确的添加方式如下sudo mkdir -p /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg echo deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable | sudo tee /etc/apt/sources.list.d/docker.list /dev/null sudo apt-get update这里的$(lsb_release -cs)会自动获取你当前系统的代号不要自己写死。如果你添加的是独立官方仓库文件最好先检查/etc/apt/sources.list.d/里是否已经存在其他 docker 相关的.list文件避免源重复grep -r download.docker.com /etc/apt/sources.list /etc/apt/sources.list.d/找到多余的旧源文件直接把对应.list文件删除或注释掉再apt-get update一次。这类问题就解决了。2.2 E: Package docker-ce has no installation candidate这个报错在 Ubuntu 上很经典E: Package docker-ce has no installation candidate看到它不要直接判定为“没有这个软件”。先用apt-cache policy docker-ce看一眼候选版本信息apt-cache policy docker-ce如果输出里没有任何版本说明系统压根没从 Docker 源里拿到元数据。这时候检查两件事源文件到底有没有被加载、加载之后版本代号是否正确。我之前帮一个朋友排查过他是在 Ubuntu 20.04 上复制的教程但是教程里把源写成了https://download.docker.com/linux/ubuntu bionic stable于是lsb_release -cs返回的是focal源却指向 bionic。虽然 Bionic 仓库也存在但和当前系统不匹配apt 直接找不到可用的候选版本。在 CentOS 上类似报错是No package docker-ce available.这时检查仓库有没有被添加yum repolist enabled | grep docker如果没有就需要先装yum-utils再用yum-config-manager --add-repo把官方仓库加进去。CentOS 7 上添加官方源的命令如下sudo yum install -y yum-utils sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo sudo yum install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin注意 CentOS 8 以后用的是dnf但命令思路完全一致。很多时候 no candidate 的根源就是源没配上靠apt-cache policy或yum list一步一步定位比反复重装高效得多。2.3 依赖冲突containerd.io 版本过低和 libseccomp 问题在 CentOS 7 和部分旧版 Ubuntu 上安装新版 Docker经常会遇到一个尴尬Error: Package: docker-ce-24.0.0-1.el7.x86_64 (docker-ce-stable) Requires: containerd.io 1.4.1或者是装完 Docker 之后第一次跑容器就报Error starting userland proxy: listen tcp 0.0.0.0:xxxx: bind: address already in use后一个大多是端口占用跟依赖无关。前面这个 containerd.io 的要求是 Docker 安装阶段的常见问题。系统本身可能已经装了 containerd但版本太老不满足 Docker 的要求。最简单的解决办法是先用yum或apt单独安装一个满足版本要求的 containerd.io再继续装 docker-ce。在 CentOS 7 上我习惯这样处理sudo yum install -y containerd.io sudo yum install -y docker-ce docker-ce-cli如果默认源里 containerd.io 版本还是太低就手动从官方仓库对应的 stable 目录下载一份 rpm 安装。需要注意不要随便用--allowerasing强行覆盖系统自带的 containerd这样容易把系统里其他依赖 containerd 的组件弄坏。另外还有一个容易被忽略的依赖libseccomp。CentOS 7 上如果 libseccomp 版本太低Docker 装好后运行容器可能会报docker: Error response from daemon: seccomp profile specified in spec but not loaded.解决办法就是把 libseccomp 升级到较新版本。这类依赖报错的共同特点是看起来是 Docker 的问题实际上是系统基础库版本和 Docker 要求不匹配。遇到这种问题建议直接看报错的Requires字段它已经把答案写得很清楚了。2.4 GPG 公钥报错签名验证不过关GPG 相关报错有两种常见长相第一种是W: GPG error: https://download.docker.com/linux/ubuntu focal InRelease: The following signatures couldnt be verified because the public key is not available: NO_PUBKEY xxxxxx第二种是添加 keyring 时gpg: no valid OpenPGP data found.第一种的根源通常是之前用旧方式apt-key adv --keyserver ... --recv-keys添加过公钥但公钥没有正确写入新版本系统认可的 keyring 位置或者你只加了源文件没加公钥。第二种通常是curl -fsSL下载 GPG 文件时没有真正拿到 GPG 内容可能拿到了一个 HTML 错误页也有可能网络中间层把文件劫持过滤了。现在官方推荐的方式就不再建议用apt-key而是把公钥单独下载成二进制 keyring 文件并在源文件中通过signed-by指定curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg添加过之后可以验证一下这个 keyring 文件是否正常gpg --show-keys /etc/apt/keyrings/docker.gpg能看到公钥信息说明文件没问题。之后源文件里写清楚signed-by/etc/apt/keyrings/docker.gpgGPG 报错基本消失。2.5 磁盘空间不足No space left on device 有时候是 inode 耗尽安装 Docker 时如果系统日志里出现dpkg: error processing archive docker-ce_..._amd64.deb No space left on device第一步自然是df -h /看磁盘。但有时候你会发现根分区明明还有十几个 G却依然报这个错这时候要看 inodedf -h / df -i /df -i显示的是 inode 使用率。inode 耗尽时哪怕磁盘还有空间也写不了文件。常见原因是/var或/tmp下积累了海量小文件。可以先清理 apt 缓存sudo apt-get clean sudo rm -rf /var/cache/apt/archives/*.deb再删掉一些确定没用的旧日志。如果/var/lib/docker以后要承载大量镜像和容器数据强烈建议在安装前就规划好独立数据盘用软链接把/var/lib/docker指到大容量分区。否则等跑一段时间再迁移代价会大得多。3. 启动阶段三大经典报错daemon 起不来、权限拒绝、网络桥接异常3.1 先分清是 client 连不上还是 daemon 没起来很多人报错只贴一行“Cannot connect to the Docker daemon”实际上问题分两层Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?说明 docker 客户端连不上 socketdaemon 可能没启动permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock说明 socket 存在但权限不够。如果是第一种先看服务状态sudo systemctl status docker sudo journalctl -u docker --no-pager -n 50如果服务根本没起尝试启动并设置开机自启sudo systemctl enable --now docker如果服务状态显示 failed就要看日志。另外一个很有用的排查方法是直接在前台跑 daemon用--debug参数能看到最原始的日志sudo dockerd --debug这会占住当前终端千万别开着它继续用同窗口等排查完 CtrlC 退出再用 systemctl 正常管理 Docker。3.2 daemon 启动失败iptables 与 br_netfilter 是最容易被忽略的元凶有一种启动失败systemctl status docker显示的是Failed to start Docker Application Container Engine.打开 journalctl 日志里面能看到Failed to program FILTER chain: iptables failed: No such file or directory或者是iptables failed: Operation not permitted这类报错在云主机上很常见根因多半是内核没加载br_netfilter模块。Docker 要管理容器网络需要在 bridge 网桥上配置 iptables 规则而这依赖br_netfilter。先手动加载试试sudo modprobe br_netfilter然后看一眼是否生效lsmod | grep br_netfilter如果模块加载成功再确认内核参数 ip_forward 已开启sudo sysctl -w net.ipv4.ip_forward1为了重启后仍然生效建议写一个持久化配置sudo tee /etc/modules-load.d/docker.conf EOF br_netfilter EOF sudo tee /etc/sysctl.d/docker.conf EOF net.bridge.bridge-nf-call-iptables 1 net.ipv4.ip_forward 1 EOF sudo sysctl --systemCentOS 上如果装了 firewalld也可能和 Docker 的 iptables 管理发生冲突表现为容器网络忽好忽坏。不要一上来就systemctl stop firewalld先确认内核模块和转发参数有没有配好很多时候问题并不在防火墙服务本身。3.3 权限拒绝不要用 chmod 777 硬解开头提到的 permission denied 报错本质是 socket 文件权限不对。/var/run/docker.sock默认属于root:docker普通用户不在 docker 组里自然连不上。正规做法是把当前用户加入 docker 组sudo usermod -aG docker 你的用户名然后重新登录或者执行一次newgrp docker再执行id确认当前用户的 groups 里已经包含 docker。newgrp docker只对当前终端生效最彻底的方式还是注销再重新登录。这里要特别提醒一个反面操作不要直接sudo chmod 777 /var/run/docker.sock。这确实能让你立刻运行 docker 命令但它让系统里所有用户都有权访问 Docker socket而 Docker socket 的权限约等于 root 权限等于把一大片攻击面露给了别人。网上很多老教程这么写我一直不推荐。同理也别为了让某个用户能运行 docker 而把用户直接加到 sudoers那不是解决问题是制造更大的问题。另外如果机器上装了 Docker Desktop for Linux又同时用系统包安装了 Docker Engine可能会出现两个 daemon 并存的情况。此时docker context list会看到default和desktop-linux两个 context虽然都能连但指向的是不同的 socket。排查这类问题先去docker context ls看清楚当前 context再决定要不要切换docker context use desktop-linux3.4 容器网络与 DNS装好后跑第一个容器才发现的问题docker run --rm hello-world成功不代表网络一定没问题。很多人装完 Docker接着跑 Nginx 或业务容器才发现容器里访问外网超时、DNS 解不出来。这时候去看容器内 DNS 和一个关键链路docker run --rm busybox nslookup www.example.com如果 DNS 解析失败常见原因包括宿主机转发没开、防火墙 FORWARD 链默认 DROP、Docker 默认网段和宿主机已有网段冲突。后面这个冲突比较隐蔽如果宿主机本来就用了172.17.0.0/16Docker 的 docker0 默认也在这段容器网络就会很混乱。要规避这类问题我习惯提前在/etc/docker/daemon.json里把网络、DNS、存储都写清楚{ storage-driver: overlay2, bip: 10.88.0.1/24, dns: [223.5.5.5, 8.8.8.8] }bip可以按自己环境调整注意不要和已有内网网段冲突。改完配置后重启 Dockersudo systemctl restart docker这个操作不会删除已有容器但会重建 docker0 网桥如果之前有容器正在运行重启后所有容器会联动重启所以最好在业务低峰期操作。4. 安装完成之后这些高频“后续问题”也会被误报成 Docker 安装失败4.1 docker-compose 还是 docker compose装错版本带来的疑问安装完 Docker 后很多人会顺手搜“docker compose 安装”结果看到新旧两种写法docker-compose和docker compose搞不清该装哪个。新版本 Docker Engine 已经内置了 compose 插件安装包名称通常是docker-compose-plugin。装完之后直接docker compose version就能看到版本信息不需要额外下载二进制。如果你还在用老项目里的docker-compose命令而系统里没这个命令通常会报bash: docker-compose: command not found这时候不要急着去装旧版 Python 二进制的 docker-compose先确认你的 Docker 版本够不够新。新版写法 docker compose 是官方默认方向老命令docker-compose主要是历史项目还在用。如果确实需要老命令可以手动下二进制到/usr/local/bin但要给它执行权限并且留意和插件版不要冲突否则可能出现“同一个目录两种 compose 语法加了参数行为却不一样”的情况。4.2 拉取镜像超时和镜像加速设置这不是安装错误安装完 Docker 后有人第一次docker pull nginx就卡住半天之后报i/o timeout或者EOF第一反应是“Docker 坏了”。其实这是镜像仓库网络可达性问题。解决思路不是重装 Docker而是给/etc/docker/daemon.json配置镜像加速地址。注意这个文件和安装阶段配置软件源的文件不是一回事。一个常见配置{ registry-mirrors: [https://你的镜像加速地址], storage-driver: overlay2, log-driver: json-file, log-opts: { max-size: 10m, max-file: 3 } }JSON 文件里不能写注释不能多逗号写完之后用docker info检查配置是否生效docker info | grep -A 3 Registry Mirrors如果配置了多个加速地址并且某个地址不可用可以只保留可用的一个。设置完必须systemctl restart docker。顺带提一个常见误区安装阶段用的软件源和拉镜像用的加速源是完全独立的。软件源配错了apt-get install docker-ce会失败加速镜像源配错了docker pull会失败。排查时别搞混。4.3 容器内 MySQL “连不上”的排查思路安装完 Docker很多人第一件事就是跑 MySQL 容器然后发现有各种“连不上”的问题。最常见的就是ERROR 2002 (HY000): Cant connect to local MySQL server through socket /var/run/mysqld/mysqld.sock这个报错的本质是你在宿主机上执行 mysql 客户端如果主机名写localhost客户端会优先找本地 socket 文件而不是走 TCP 端口。解决办法很简单用127.0.0.1代替localhostmysql -h 127.0.0.1 -P 3306 -uroot -p如果还是连不上按这个路径排查docker ps ss -lntp | grep 3306 docker logs mysql容器名docker ps看容器是否在运行ss -lntp看端口有没有映射出去docker logs看 MySQL 有没有真正启动完成。碰到 MySQL 8 的caching_sha2_password认证问题那是客户端驱动和认证插件不兼容不是 Docker 安装的问题可以从驱动版本或容器内 MySQL 认证配置入手解决。我再强调一个容易混淆的点容器里的localhost指的是容器自身不是宿主机。你进入容器后写localhost:3306连的是容器内的进程在宿主机上写localhost:3306可能因为客户端找 socket 而扑空。理解这一点很多“连不上”的问题就迎刃而解了。4.4 Docker Desktop for Linux 的特殊情况很多新手搜索 Docker 安装时会遇到 Docker Desktop for Linux 的安装教程。这里要说清楚Linux 服务器场景绝大多数情况不需要 Docker Desktop只需要 Docker Engine 和 Docker Compose 插件就够了。 Docker Desktop 面向的是本地开发桌面环境需要图形界面配合还要 systemd 用户级服务支持。没有图形界面的纯服务器装了也用不起来反而会带来两个 daemon 冲突的问题。如果确实在 Linux 桌面上装了 Docker Desktop但又发现命令行里连接的是另一个 daemon多半是 context 的问题。执行docker context ls看到default和desktop-linux两个 context 时用docker context use desktop-linux切换。这个坑不大但很容易让刚从 Windows / macOS 转 Linux 的同学卡很久。5. 我的排查顺序与几个“不要”清单5.1 一个从实践沉淀下来的排查路线安装和启动 Docker 遇到问题时我从不急着重装而是按固定顺序查一遍。这个顺序不一定适合所有人但对大多数“安装常见错误”很管用步骤操作定位的问题1systemctl status dockerDocker 服务是否在运行2journalctl -u docker --no-pager -n 50daemon 启动时的具体报错3sudo dockerd --debug前台运行拿到更原始的错误输出4sudo dmesggrep -i docker5ls -l /var/run/docker.socksocket 权限和所属组是否正常6df -h /和df -i /磁盘和 inode 空间是否充足7grep -r docker /etc/apt/sources.list.d/软件源是否重复或写错这套顺序基本能把 90% 的问题落在某一类里。比如第 2 步出现 iptables那问题在内核模块第 5 步出现权限那就去处理组权限第 6 步满了清理空间。很多看起来复杂的报错只是因为一开始跳过了前几步直接重装导致问题反复出现。5.2 不要做的几件事第一件事上面已经说过不要chmod 777 /var/run/docker.sock。这会让系统里的任何用户都拿到 Docker socket 的控制权长远看是高危行为。第二件事不要把数据随意留在/var/lib/docker里就卸载。很多人重装 Docker 之前直接删目录等发现自己的数据库容器数据全没了才追悔莫及。卸载前至少确认这个目录下有没有需要保留的卷du -sh /var/lib/docker如果目录很大又有正在运行的旧容器先备份再卸载。第三件事不要看到 GPG 报错就去下载一长串公钥硬塞进系统信任库。新版系统已经明确不推荐使用apt-key如果某个教程还在用apt-key adv --keyserver可以直接跳过它改用gpg --dearmor写入 keyring。第四件事不要在 CentOS 上一遇到 SELinux 拦截就去setenforce 0。容器启动报错如果和 SELinux 相关优先给目录打正确标签或者确认 Docker 的selinux-enabled配置是否匹配你的系统。长期关闭 SELinux 等于把安全层拆掉不划算。5.3 一个“装完先别急着跑业务”的小建议我自己每次装完 Docker不会立刻跑业务容器而是先走一条三连验证链路先跑一个 hello-world 镜像确认客户端、daemon、镜像拉取链路正常再跑一个 Nginx 容器并映射端口用curl 127.0.0.1验证端口映射最后用docker logs看一眼容器日志是否能正常输出。三个验证全部通过再往里面装 MySQL、Redis 这些东西。这样能很自然地把问题隔离在“Docker 环境”和“业务应用”两个层面不至于一个数据库连不上还要怀疑 Docker 是不是装坏了。还有一类容易被误报为“Docker 安装失败”的问题是容器内应用依赖缺失。比如某些脚本管理面板容器启动后提示依赖没有安装新手第一反应是重装 Docker。实际上你应该用docker logs看容器输出问题往往出在应用镜像构建时依赖没锁好和 Docker 本身没关系。容器跑不起来先查容器日志这是一个非常重要的习惯。对我来说Docker 安装错误的最大规律就是大多数问题都不是 Docker 本身的问题。它像一个挑剔的房客对内核、网络、权限、存储、软件源都有要求。只要环境配合到位安装和启动往往一次就能过。如果你今天又栽在某个报错上建议先停下来打开日志看一眼再决定下一步行动而不是反复卸载重装。最后再分享一个小技巧我会在安装前顺手把uname -r、df -h /、grep -r docker /etc/apt/sources.list.d/这三条命令的输出留存在终端里出问题时直接从这几处找线索往往几分钟就能定位。
