1. 问题现象与根因定位
1.1 报错现场还原
Pipeline 跑到docker build或docker push这一步，控制台突然甩出一行红字：
docker: not found第一次遇到这个报错的人，十有八九会先去 Jenkins 服务器上敲一遍docker version，发现宿主机上 Docker 明明装得好好的，命令行也能正常跑。于是就开始怀疑人生：明明装了，为什么 Jenkins 说找不到？
这个现象的本质，是Jenkins 执行 Pipeline 的环境和你手动登录 SSH 的环境不是同一个。你 SSH 进去用的是登录 Shell，加载了完整的 PATH 环境变量；而 Jenkins Agent 执行sh步骤时用的是非交互式 Shell，PATH 往往只有/usr/bin:/bin这类最基础的路径，/usr/local/bin或者 Docker 自定义安装路径根本没被包含进去。
1.2 三种典型触发场景
根据我这些年排查的经验，这个报错基本逃不出下面三种情况：
| 场景 | 典型特征 | 根因 |
|---|---|---|
| Agent 容器内无 Docker | Pipeline 跑在 K8s Pod 或 Docker Agent 里 | Agent 镜像本身没装 Docker 客户端 |
| PATH 未包含 Docker 路径 | 宿主机装了 Docker，手动能跑 | 非交互式 Shell 的 PATH 缺失 |
| Docker 未安装或服务未启动 | 全新节点首次接入 | 环境初始化遗漏 |
先别急着改 Jenkinsfile，第一步永远是确认报错发生在哪个节点上。Pipeline 里加一句sh 'hostname && whoami && echo $PATH'，把执行环境的信息打出来，比盲目猜测高效得多。我见过太多人上来就改配置，结果改的是 Master 节点，实际报错在某个远程 Agent 上，白折腾半天。
1.3 为什么这个报错如此高频
Jenkins 的架构决定了它是一个"调度器"角色，真正干活的 Agent 可能分布在完全不同的机器或容器里。而 Docker 的安装方式又特别多样——有的用包管理器装，二进制在/usr/bin/docker；有的用官方脚本装，落在/usr/local/bin/docker；还有的通过 snap 安装，路径又不一样。这种"调度与执行分离"加上"安装路径不统一"的组合，就是docker: not found反复出现的土壤。
理解这一点很关键：解决思路不是"让 Jenkins 找到 Docker"，而是"让执行 Pipeline 的那个具体环境能找到 Docker"。方向对了，后面的操作才不会跑偏。
2. 环境排查的完整操作流程
2.1 第一步：锁定报错节点
在 Pipeline 的报错步骤前后插入诊断命令，这是最稳妥的做法：
pipeline { agent any stages { stage('Diagnose') { steps { sh ''' echo "=== Node Info ===" hostname whoami echo "=== PATH ===" echo $PATH echo "=== Which Docker ===" which docker || echo "docker not in PATH" echo "=== Common Paths ===" ls -l /usr/bin/docker 2>/dev/null || echo "not in /usr/bin" ls -l /usr/local/bin/docker 2>/dev/null || echo "not in /usr/local/bin" ''' } } } }这段脚本会一次性把关键信息全部打出来。重点看三个地方：hostname告诉你跑在哪台机器，$PATH告诉你搜索路径，which docker和后面的ls告诉你 Docker 到底在不在、在哪。
提示：如果 Pipeline 用了
agent { label 'xxx' }指定了特定节点，诊断脚本一定要跑在同一个 label 的节点上，否则信息没有参考价值。
2.2 第二步：区分"没装"和"没找到"
拿到诊断输出后，判断逻辑很清晰：
- 如果
ls /usr/bin/docker和ls /usr/local/bin/docker都提示不存在，那就是真的没装，去装 Docker。 - 如果某个路径下能看到 docker 可执行文件，但
which docker找不到，那就是PATH 问题，去修 PATH。 - 如果
which docker能找到，但 Pipeline 里还是报 not found，那可能是Jenkins 缓存了旧的环境变量，需要重启 Agent 或重新连接节点。
这个判断过程看起来简单，但实际排查中经常被跳过。我见过有人明明 Docker 装在/usr/local/bin，却一直在/usr/bin下面找，然后得出"没装"的错误结论，又去重装一遍，纯属浪费时间。
2.3 第三步：验证 Docker 服务状态
找到 Docker 可执行文件只是第一步，还得确认 Docker 守护进程在正常运行：
# 检查服务状态 systemctl status docker # 检查 socket 文件 ls -l /var/run/docker.sock # 直接测试 docker info如果docker info报Cannot connect to the Docker daemon，那问题就从"找不到命令"变成了"连不上守护进程"，这是另一个层面的问题，通常和权限或服务未启动有关。把这两类问题分开处理，思路会清晰很多。
3. 针对性解决方案与配置实操
3.1 方案一：修复 PATH 环境变量
这是最常见也最容易解决的场景。有两种改法，各有适用场合。
改法 A：在 Pipeline 里临时指定 PATH
pipeline { agent any environment { PATH = "/usr/local/bin:/usr/bin:/bin:${env.PATH}" } stages { stage('Build') { steps { sh 'docker build -t myapp:latest .' } } } }这种改法的好处是改动范围小、不影响其他任务，适合只有个别 Pipeline 需要 Docker 的情况。缺点是每个需要的 Pipeline 都得写一遍，重复度高。
改法 B：在节点级别配置全局环境变量
进入Manage Jenkins→Manage Nodes and Clouds→ 选中对应节点 →Configure→ 在Node Properties里勾选Environment variables，添加：
Name: PATH Value: /usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin这种改法一次配置，该节点上所有任务生效，适合节点上大量任务都需要 Docker 的场景。但要注意别把 PATH 覆盖得太干净，把系统原有的路径都丢了，反而引发新问题。稳妥的做法是在原有 PATH 基础上追加，而不是完全替换。
3.2 方案二：为 Agent 容器安装 Docker 客户端
如果 Pipeline 跑在 Docker Agent 或 K8s Pod 里，Agent 镜像本身可能就没带 Docker。这时候需要在镜像里补上。
以常见的 Agent 基础镜像为例，在 Dockerfile 里加一段：
USER root RUN apt-get update && \ apt-get install -y docker.io && \ rm -rf /var/lib/apt/lists/* USER jenkins这里有个关键点：只装 Docker 客户端就够了，不需要装完整的 Docker 引擎。因为容器内的 Pipeline 通常是通过挂载宿主机的/var/run/docker.sock来调用宿主机的 Docker 守护进程，容器内只需要有docker这个命令行工具即可。
对应的 Pipeline 配置需要挂载 socket：
pipeline { agent { docker { image 'my-jenkins-agent:latest' args '-v /var/run/docker.sock:/var/run/docker.sock' } } stages { stage('Build') { steps { sh 'docker build -t myapp:latest .' } } } }注意：挂载 docker.sock 意味着容器内的进程拥有了操作宿主机 Docker 的权限，这在安全上需要评估。生产环境建议配合权限控制，或者改用 Kaniko、Buildah 这类无需守护进程的构建工具。
3.3 方案三：使用绝对路径调用
如果不想动环境变量，最直接的办法就是在 Pipeline 里用绝对路径：
sh '/usr/local/bin/docker build -t myapp:latest .'这种写法简单粗暴，适合临时救急。但缺点也很明显——路径硬编码，换台机器可能就失效了。如果团队里不同节点的 Docker 安装路径不一致，维护起来会很痛苦。所以这只推荐作为临时方案，长期还是应该统一环境。
3.4 方案对比与选型建议
| 方案 | 适用场景 | 优点 | 缺点 |
|---|---|---|---|
| Pipeline 内指定 PATH | 个别任务需要 | 改动小、隔离性好 | 重复配置 |
| 节点全局环境变量 | 节点上多任务需要 | 一次配置全局生效 | 影响范围大 |
| Agent 镜像装客户端 | 容器化 Agent | 环境自包含 | 需重建镜像 |
| 绝对路径调用 | 临时救急 | 立竿见影 | 硬编码难维护 |
选型时先问自己两个问题：这个节点上还有多少任务需要 Docker？如果只有一两个，用方案一；如果一大片，用方案二。Agent 是长期存在的还是临时的？长期存在就改镜像，临时的话改 Pipeline 更划算。
4. 常见问题排查与避坑经验
4.1 排查速查表
| 现象 | 可能原因 | 排查命令 | 解决方向 |
|---|---|---|---|
| docker: not found | PATH 缺失 | echo $PATH | 补 PATH |
| docker: not found | 未安装 | ls /usr/bin/docker | 安装 Docker |
| Cannot connect to daemon | 服务未启动 | systemctl status docker | 启动服务 |
| Permission denied | 用户不在 docker 组 | groups | 加用户组 |
| 手动能跑 Pipeline 不能 | Shell 环境差异 | 对比 PATH | 统一环境 |
4.2 几个容易踩的坑
坑一：改了 PATH 但没生效
Jenkins 的环境变量有缓存机制，改完节点配置后，有时候需要断开节点重新连接，或者重启 Agent 进程，新配置才会加载。我遇到过改完配置死活不生效的情况，折腾半天才发现是缓存问题。
坑二：docker 组权限没配
即使 Docker 命令找到了，非 root 用户执行时可能报permission denied while trying to connect to the Docker daemon socket。这是因为用户不在 docker 组里。解决方法是：
sudo usermod -aG docker jenkins改完之后必须重新登录（或重启 Jenkins 服务）才生效，因为用户组信息是在登录时加载的。
坑三：容器内挂载 socket 后权限不匹配
容器内 jenkins 用户的 UID 和宿主机 docker 组的 GID 对不上，导致 socket 访问被拒。这种情况要么调整容器内用户 UID，要么用--group-add把宿主机 docker 组加进容器。
坑四：多节点环境配置不一致
团队里几台 Agent 的 Docker 安装方式不同，导致 Pipeline 在不同节点上表现不一样。这种问题最隐蔽，因为"有时候能跑有时候不能跑"。解决办法是统一节点初始化脚本，把 Docker 安装路径、用户组配置标准化。
4.3 我的实操心得
排查这类问题，我总结了一个"三步定位法"：先定位节点，再定位路径，最后定位权限。按这个顺序走，90% 的docker: not found都能在十分钟内解决。
另外强烈建议在 Pipeline 里加一个环境自检 stage，每次构建前先跑一遍诊断脚本。虽然多花几秒钟，但能在问题发生时第一时间拿到现场信息，比事后去翻日志高效得多。这个习惯帮我省下了大量排查时间。
还有一点，别迷信"重装大法"。很多人一遇到 not found 就重装 Docker，结果装完还是报错，因为根因根本不在安装上。先诊断，再动手，这是铁律。
5. 长期治理与工程化建议
5.1 统一 Agent 基础镜像
如果团队用容器化 Agent，最彻底的方案是维护一个标准化的 Agent 基础镜像，把 Docker 客户端、常用构建工具、环境变量全部预置好。所有 Pipeline 都基于这个镜像跑，环境差异问题从源头消除。
镜像里可以固化这些内容：
FROM jenkins/inbound-agent:latest USER root RUN apt-get update && \ apt-get install -y docker.io git curl && \ usermod -aG docker jenkins && \ rm -rf /var/lib/apt/lists/* ENV PATH="/usr/local/bin:${PATH}" USER jenkins这样构建出来的镜像，Docker 命令、PATH、用户组权限全部就位，Pipeline 里直接调docker就行，不用再操心环境问题。
5.2 用声明式 Pipeline 固化环境检查
把环境自检做成一个可复用的共享库，所有 Pipeline 引用它：
// vars/checkDocker.groovy def call() { sh ''' if ! command -v docker &> /dev/null; then echo "ERROR: docker not found in PATH" echo "Current PATH: $PATH" exit 1 fi docker version ''' }然后在 Pipeline 里checkDocker()一行调用。这样既保证了检查的一致性，又避免了每个 Pipeline 重复写诊断代码。
5.3 考虑无守护进程的构建方案
如果安全策略不允许挂载 docker.sock，或者团队想彻底摆脱"环境依赖"的困扰，可以考虑Kaniko或Buildah这类无需 Docker 守护进程的镜像构建工具。它们直接在用户空间完成构建，不依赖 Docker 命令，从根上避免了docker: not found这类问题。
当然，迁移有成本，需要评估现有 Pipeline 的改造量。但对于新建项目，我倾向于直接上这类方案，省心。
5.4 建立节点健康检查机制
给每个 Agent 节点配一个定时健康检查任务，定期验证 Docker 可用性、磁盘空间、网络连通性等关键指标。一旦发现异常提前告警，而不是等 Pipeline 跑挂了才发现。这种"预防式运维"的思路，比事后救火有价值得多。
具体做法可以用 Jenkins 的定时任务，也可以用外部监控系统。核心是把环境问题暴露在构建之前，而不是构建之中。
6. 写在最后的一点体会
docker: not found这个报错本身不复杂，但它折射出的是 CI/CD 环境管理的一个核心命题：调度环境与执行环境的差异，是绝大多数"诡异问题"的根源。理解了这一点，不只是这个报错，很多类似的"明明装了却找不到""手动能跑自动不行"的问题，都能找到统一的排查思路。
我个人的习惯是，每接入一个新节点，第一件事就是跑一遍完整的环境自检，把 Docker、Git、构建工具、网络全部验证一遍，形成一份"节点基线"。后续任何异常，都拿现状和基线对比，差异点往往就是问题所在。这个方法看起来笨，但特别有效，推荐你也试试。
环境治理这件事，投入在前期的每一分钟，都会在后期以十倍的效率回报回来。与其每次报错都手忙脚乱地救火，不如花点时间把基础打牢。
