Jenkins外部Agent执行Docker命令报错：docker not found

问题背景与环境 #

我按Jenkins官方文档搭建了多容器部署环境，由Docker daemon（dind）容器支撑Jenkins主容器与独立外部Agent容器。

docker-compose.yml配置 #

services:
  jenkins-docker:
    image: docker:dind
    container_name: jenkins-docker
    privileged: true
    networks:
      jenkins: 
        aliases: 
          - docker
    environment:
      DOCKER_TLS_CERTDIR: /certs
    volumes:
      - jenkins-home:/var/jenkins_home
    ports:
      - "3000:3000"
      - "5000:5000"
      - "2376:2376"
    command: --storage-driver overlay2

  jenkins-master:
    build:
      context: .
      dockerfile: Dockerfile.jenkins-master
    image: jenkins-dockerized
    container_name: jenkins-master
    networks:
      jenkins: 
        aliases: 
          - jenkins
    environment:
      DOCKER_HOST: tcp://docker:2376
      DOCKER_CERT_PATH: /certs/client
      DOCKER_TLS_VERIFY: 1
      JAVA_OPTS: "-Dhudson.plugins.git.GitSCM.ALLOW_LOCAL_CHECKOUT=true"
    volumes:
      - jenkins-home:/var/jenkins_home
      - jenkins-docker-certs:/certs/client:ro
    ports:
      - "8085:8080"
      - "50000:50000"
    restart: on-failure
    depends_on:
          - jenkins-docker

  jenkins-agent-1:
      image: jenkins/ssh-agent:alpine-jdk17
      container_name: jenkins-agent-1
      networks:
        jenkins: 
          aliases: 
            - agent-1
      ports:
        - "4444:22"
      environment:
        - JENKINS_AGENT_SSH_PUBKEY=${JENKINS_AGENT_SSH_PUBKEY}
      depends_on:
        - jenkins-master

networks:
  jenkins:
    name: jenkins

volumes:
  jenkins-docker-certs:
    name: jenkins-docker-certs
  jenkins-home:
    name: jenkins-home
    driver: local
    driver_opts:
      type: none
      device: ../jenkins_home
      o: bind

Jenkins主容器Dockerfile（Dockerfile.jenkins-master） #

FROM jenkins/jenkins:2.479.2-jdk17
USER root
RUN apt-get update && apt-get install -y lsb-release
RUN curl -fsSLo /usr/share/keyrings/docker-archive-keyring.asc \
  https://download.docker.com/linux/debian/gpg
RUN echo "deb [arch=$(dpkg --print-architecture) \
  signed-by=/usr/share/keyrings/docker-archive-keyring.asc] \
  https://download.docker.com/linux/debian \
  $(lsb_release -cs) stable" > /etc/apt/sources.list.d/docker.list
RUN apt-get update && apt-get install -y docker-ce-cli
USER jenkins
RUN jenkins-plugin-cli --plugins "docker-workflow:580.vc0c340686b_54 json-path-api"

问题描述 #

内置Agent执行含Docker命令的流水线完全正常，但切换到外部Agent jenkins-agent-1 时，直接报错 docker: not found；不含Docker命令的流水线在外部Agent上运行正常。

已尝试操作 #

我给Agent安装了Docker客户端，但生成的镜像体积高达555MB，过于臃肿。尝试改用Alpine基础镜像缩体积，但未成功，当时用的Dockerfile如下：

FROM jenkins/ssh-agent:debian-jdk17
USER root
RUN apt-get update && apt-get install -y lsb-release curl
RUN curl -fsSLo /usr/share/keyrings/docker-archive-keyring.asc \
  https://download.docker.com/linux/debian/gpg
RUN echo "deb [arch=$(dpkg --print-architecture) \
  signed-by=/usr/share/keyrings/docker-archive-keyring.asc] \
  https://download.docker.com/linux/debian \
  $(lsb_release -cs) stable" > /etc/apt/sources.list.d/docker.list
RUN apt-get update && apt-get install -y docker-ce-cli

解决方案 #

1. 根源分析 #

docker: not found 是因为外部Agent基础镜像默认不带Docker客户端——你在Jenkins主容器的Dockerfile里安装了docker-ce-cli，但外部Agent的jenkins/ssh-agent:alpine-jdk17本身没有这个工具。

2. Alpine版本Agent镜像缩体积方案 #

Alpine用的是apk包管理器，无需添加Debian的Docker源，直接用官方仓库里的docker-cli包即可，镜像体积可压到200MB以内：

FROM jenkins/ssh-agent:alpine-jdk17
USER root
# 更新apk仓库+安装docker-cli+清理缓存减少体积
RUN apk update && \
    apk add --no-cache docker-cli && \
    rm -rf /var/cache/apk/*
# 配置Docker客户端连接到dind容器的环境变量
ENV DOCKER_HOST=tcp://docker:2376 \
    DOCKER_CERT_PATH=/certs/client \
    DOCKER_TLS_VERIFY=1
USER jenkins

3. docker-compose配套调整 #

要让Agent能访问dind的TLS证书，需给jenkins-agent-1添加证书卷挂载：

jenkins-agent-1:
    image: jenkins-agent-docker:alpine
    container_name: jenkins-agent-1
    networks:
      jenkins: 
        aliases: 
          - agent-1
    ports:
      - "4444:22"
    environment:
      - JENKINS_AGENT_SSH_PUBKEY=${JENKINS_AGENT_SSH_PUBKEY}
      - DOCKER_HOST=tcp://docker:2376
      - DOCKER_CERT_PATH=/certs/client
      - DOCKER_TLS_VERIFY=1
    volumes:
      - jenkins-docker-certs:/certs/client:ro
    depends_on:
      - jenkins-master

4. 验证步骤 #

1. 构建新Agent镜像：docker build -t jenkins-agent-docker:alpine -f Dockerfile.jenkins-agent .
2. 重启Agent容器：docker-compose up -d --force-recreate jenkins-agent-1
3. 运行含Docker命令的流水线，确认报错消失，同时镜像体积大幅缩小。

内容的提问来源于stack exchange，提问作者Cibs84