docker 命令找不到速查：command not found、daemon 没起与权限三岔口

更新时间：2026-10-24。FAQ 速查页，面向刚装完 Docker 敲下 docker ps 就碰一鼻子灰的同学。「docker 用不了」的本质是一条链上的三个环节各自独立：客户端二进制在不在（command not found）、守护进程起没起（Cannot connect to the Docker daemon）、你的身份能不能跟守护进程说话（permission denied）。三者报错原文完全不同，修法互不相干，但排错现场常被混为一谈。病因收敛在六根轴上：客户端根本没装或装了没进 PATH、daemon 服务未启动或启动失败、当前用户不在 docker 组、rootless 模式的 socket 路径不同、桌面版（Mac/Windows）的虚拟机没起、以及 snap 包带来的 PATH 与权限隔离坑。顺一遍基本必中。如果是容器内权限问题而不是宿主机 docker 不可用，转 Docker 权限被拒速查。

本文要回答的问题

• docker: command not found 是没装还是 PATH 问题，怎么快速区分？
• Cannot connect to the Docker daemon 是 daemon 没起吗，怎么确认？
• 为什么 sudo 能跑、普通用户就 permission denied？
• rootless 模式下 socket 在哪，为什么脚本里连不上？
• Mac/Windows 桌面版和 Linux 直装的排错思路差在哪？

一、报错原文与典型现象

三类报错对应链条上的三个环节，原文各自特征鲜明（安装路径以 /proj/demo 占位）：

# 环节一：客户端二进制找不到
$ docker ps
bash: docker: command not found
# zsh 或 Windows PowerShell 同义
zsh: command not found: docker

# 环节二：客户端在，但连不上守护进程
$ docker ps
Cannot connect to the Docker daemon at unix:///var/run/docker.sock.
Is the docker daemon running?

# 环节三：daemon 在跑，但你没权限
$ docker ps
permission denied while trying to connect to the Docker daemon
socket at unix:///var/run/docker.sock

读现象按环节定性：command not found 是 shell 在 PATH 里找不到二进制，docker 这套东西在你机器上等于不存在；Cannot connect 是客户端活着、按默认 socket 地址敲门没人应；permission denied 是门里有人但不开——socket 文件的属主权限把你挡了。三类报错有时同一天连环出现（新装机先 not found，装完变 Cannot connect，加组前又 permission denied），按链条顺序逐个修。

二、病因处置速查表

报错现象 / 场景	可能原因	快速验证	处置
command not found	客户端未安装	which docker 无输出	装 docker-ce-cli 或桌面版
装完仍 not found	二进制不在 PATH（snap/手动装）	找实际路径后 echo PATH 比对	把目录加进 PATH 或建软链
Cannot connect，新装机	daemon 服务未启动	systemctl status docker	systemctl enable --now docker
Cannot connect，桌面版	桌面应用没启动（虚拟机没起）	看托盘图标与应用状态	启动桌面应用等就绪
permission denied	当前用户不在 docker 组	groups 看有无 docker	usermod 加组后重新登录
脚本里 Cannot connect	rootless 的 socket 不在默认路径	echo DOCKER_HOST 与 XDG 目录	显式 export DOCKER_HOST 指向用户 socket

三、排查决策图

下面这张图是标准排查路线，颜色按角色区分：红是报错入口与命中的根因，蓝是排查动作，绿是通过分支，橙是修复动作，紫是防复发沉淀。

读这张图抓主线：按「客户端 → daemon → 权限」的顺序逐环确认，每一环的验证命令就一个（which / systemctl status / groups），命中哪环修哪环。这张图特意把三个蓝色排查节点串成链，因为现场最常见的错误是跳步——daemon 没起却去折腾用户组，客户端没装却去 systemctl。

四、逐条排查展开

command not found：先确认「装没装」再查「PATH 认不认」。 which docker 没输出时分两种：真没装——按发行版包装（apt/dnf 的 docker-ce-cli，或桌面版）；装了但 shell 找不到——常见于 snap 安装（二进制在 snap 自己的 bin 目录，部分桌面环境的 PATH 不含它）、手动解压到自定义目录、或新装的 PATH 改动未生效（当前 shell 还是旧环境）。定位实际路径后，要么把目录加进 shell 配置文件的 PATH，要么向标准 bin 目录建软链。验证闭环：新开一个终端再敲 docker version，Client 段能打印即此环通过。

Cannot connect：daemon 是死是活一条命令定案。 Linux 直装场景 systemctl status docker 看服务状态：inactive 就是没起，systemctl enable --now docker 拉起并设为开机自启；failed 要 journalctl -u docker 看启动失败原因——常见是存储驱动不兼容、数据目录磁盘满、或配置文件写错。桌面版（Mac/Windows）的 daemon 跑在桌面应用管的虚拟机里，应用没启动或还在初始化时同样报 Cannot connect，看托盘图标状态，等它转绿。WSL2 场景还要注意：daemon 由桌面版的 WSL 集成注入，集成开关没开时 WSL 里就是 Cannot connect。

permission denied：sudo 能跑就是组问题。 docker socket 默认属 root 与 docker 组，普通用户不在组里就敲不开门。修法：sudo usermod -aG docker 用户名，然后完全退出重新登录（su 切一下不算，组关系要在新登录会话里重建），groups 看到 docker 即生效。安全口径要清楚：docker 组成员等价于 root（可以挂载宿主机根目录起容器），服务器上只给可信账号；CI 环境不愿加组就用 sudo 包一层，别为了方便把 socket 权限改成人人可写。

rootless 模式：socket 不在老地方。 rootless 的 daemon 以用户身份跑，socket 落在用户运行时目录下，路径与默认的 /var/run/docker.sock 完全不同。表现是：终端里手动能跑（安装脚本已把 DOCKER_HOST 写进 shell 配置），但 cron、systemd user service、CI 脚本里 Cannot connect——这些环境没加载你的 shell 配置。修法：在脚本/服务单元里显式 export DOCKER_HOST=unix:// 加 rootless socket 的实际路径（从 docker context ls 或安装输出抄），别依赖交互式 shell 的环境继承。

桌面版与直装的思路差异。 Linux 直装：客户端、daemon、socket 都在本机，三环一机排完。桌面版多一层虚拟机：客户端在宿主机，daemon 在桌面应用的 VM 里，中间靠桌面应用做转发——所以桌面版的 Cannot connect 优先查「应用起没起、资源分配够不够（内存给太小 VM 起不来）」，而不是查 systemctl。WSL2 里还多一个开关：桌面版设置页的 WSL 集成要对着具体发行版打开，没开的话 WSL 里看 daemon 就是不存在。版本不匹配的报错（client 与 daemon API version 差太远）也多发生在桌面版自动升级后，处置是客户端跟着升级或用 DOCKER_API_VERSION 临时对齐，详见 Docker 版本不兼容速查。

snap 装的坑要单独记。 snap 包的 docker 有双重隔离：二进制在 snap 路径下（PATH 坑）、且 snap 的沙箱权限模型会拦宿主机目录挂载等操作。症状是「命令在、daemon 也在、但挂目录报权限错」。生产机器建议用官方 apt/dnf 源直装，snap 只适合桌面体验。

多 context 与远程 daemon 是进阶坑。 装了多个 docker 环境（本机直装 + 桌面版 + 远程构建机）的机器，docker context ls 可能列出好几条，当前 context 指向哪条，命令就打到哪个 daemon。症状极具迷惑性：本地明明起了容器，docker ps 却是空的——因为 context 指向了远程机器。处置是 docker context use 切回正确的那个；CI 脚本里建议显式指定 context 或 DOCKER_HOST，不继承交互式环境的状态。验证闭环统一用 docker version：Client 与 Server 两段都能打印出来，说明客户端、daemon、权限三环全通，只打出 Client 段就是后两环还有问题。

五、规范做法与预防

• 装机清单固化：装 docker 写成脚本——装包、起服务并设自启、加用户组、跑一次 docker run hello-world 闭环验证，四步缺一不可。
• 安装后自检脚本入库：which docker && systemctl is-active docker && groups | grep docker && docker ps，一行通过才算装好。
• rootless 环境显式声明：用到 rootless 的项目，README 与脚本头部写死 DOCKER_HOST，不依赖交互式环境。
• 桌面版资源给够：Mac/Windows 桌面应用里内存与磁盘配额按项目基线给，VM 起不来的 Cannot connect 多半是资源卡死。
• 服务器慎用 docker 组：组等价 root，账号授权走评审；构建机优先 rootless 或远程 DOCKER_HOST 隔离。
• 避开 snap 装 docker：服务器与 CI 一律官方源直装，减少 PATH 与沙箱两类坑。

这一篇在知识体系里的位置

本篇是 Docker 排错速查簇的环境入口篇，定位「宿主机上 docker 这条链通不通」：链通了但容器内操作报权限错看 Docker 权限被拒速查；daemon 在跑但拉镜像超时看 Docker 拉取限流速查；客户端与 daemon 版本对不上看 Docker 版本不兼容速查。「客户端 → daemon → 权限，三环按序逐个验证」这条主线对一切「docker 用不了」类报错通用。

一句话总结

docker 命令用不了先按报错原文定环：command not found 是客户端环节——which docker 确认装没装、在不在 PATH，snap 装的注意二进制路径；Cannot connect to the Docker daemon 是 daemon 环节——Linux 直装看 systemctl status docker，桌面版看应用与虚拟机起没起，rootless 场景检查脚本里有没有显式 export DOCKER_HOST；permission denied 是权限环节——sudo 能跑就把用户加进 docker 组并完全重新登录，记住组等价 root 只授可信账号。三环按序排、装机四步闭环加自检脚本，这类报错基本绝迹。