Jenkins 使用容器运行自动化任务详细文档

一、文档目的与适用范围

本文档旨在详细说明如何通过 Docker 容器 在 Jenkins 中运行自动化任务（如代码编译、单元测试、打包部署等），涵盖从基础镜像制备到流水线落地的全流程，并解决容器化过程中的环境一致性、权限管理、资源隔离等关键问题。

适用场景：Jenkins 自动化构建/测试任务（如 Java 编译、C/C++ 交叉编译、Python 脚本执行等）；

适用人群：Jenkins 管理员、DevOps 工程师、自动化测试工程师。

二、使用容器运行 Jenkins 任务的核心优势

容器化自动化任务的核心价值在于解决传统物理机/虚拟机环境的痛点，具体优势如下：

1. 环境一致性，消除"在我这能跑"问题

容器镜像包含任务所需的全部依赖（如 JDK、编译器、测试框架），镜像一旦构建，无论在哪个 Jenkins 节点运行，环境完全一致；
避免因节点环境差异（如依赖版本冲突、配置不同）导致的"本地能跑、Jenkins 跑不通"问题。

2. 资源隔离，避免任务间干扰

每个容器是独立的运行环境，不同任务（如 Python 2.7 项目和 Python 3.9 项目）可使用不同镜像，互不干扰；
容器占用的资源（CPU、内存）可通过参数限制（如 --cpus、-m），避免单个任务耗尽节点资源。

3. 快速部署与销毁，提升资源利用率

容器启动时间通常在秒级，远快于虚拟机；
任务执行完成后可自动销毁容器（--rm 参数），不残留临时文件和环境配置，节点无需定期清理。

4. 版本化管理，可追溯与回滚

容器镜像支持版本标签（如 java:17-alpine-v1.0），可追溯每个版本的环境配置；
若新镜像存在问题，可快速回滚到历史稳定版本。

三、容器化的局限性：必须使用物理机的场景

尽管容器优势显著，但以下场景因容器技术的限制，必须使用物理机（或虚拟机）运行 Jenkins 任务：

1. 涉及 UI 界面交互的任务

场景示例：Selenium 自动化测试（需启动 Chrome/Firefox 浏览器）、GUI 客户端打包（如 Windows 桌面应用）、需要图形化工具（如 Qt Creator）的任务；
原因：容器默认是无图形化界面的环境，虽可通过 X11 转发实现 GUI 显示，但配置复杂且稳定性差，物理机可直接调用本地显示服务，兼容性更好。

2. 需直接操作硬件设备的任务

场景示例：USB 设备调试（如嵌入式设备烧录）、串口通信（如单片机程序下载）、GPU 密集型任务（如深度学习模型训练）；
原因：容器需通过 --device 参数显式挂载硬件设备，且对部分硬件（如 GPU）的驱动支持不足，物理机可直接识别和操作硬件，稳定性更高。

3. 对性能敏感的超大型任务

场景示例：大型项目编译（如 Linux 内核编译）、海量数据处理（如 TB 级日志分析）；
原因：容器存在少量性能开销（如文件系统挂载、网络转发），超大型任务对性能要求极高，物理机可避免这部分开销；此外，物理机可直接使用本地磁盘，IO 性能优于容器挂载。

4. 依赖宿主机内核特性的任务

场景示例：内核模块开发、使用特定内核参数的任务（如内存页大小配置）；
原因：容器共享宿主机内核，若任务需修改内核配置或依赖特定内核版本，必须使用物理机（或对应内核版本的虚拟机）。

四、基础镜像的获取与选择

基础镜像是容器环境的"基石"，选择合适的基础镜像可减少后续定制工作量，常见获取方式如下：

1. 从官方仓库获取通用基础镜像

官方镜像安全性高、更新及时，适合作为定制的起点，主要来源：

Docker Hub ：Docker 官方维护的公共仓库，包含 ubuntu、alpine、centos、openjdk、python 等通用镜像；
- 示例：ubuntu:22.04（Ubuntu 22.04 系统）、openjdk:17-jdk-alpine（包含 JDK 17 的轻量 Alpine 镜像）；
厂商私有仓库 ：如阿里云镜像仓库（registry.cn-hangzhou.aliyuncs.com）、华为云镜像仓库，可加速国内访问（避免 Docker Hub 网络超时）。

选择原则：

轻量化优先 ：优先选择 Alpine 版本（如 alpine:3.18），镜像体积仅几 MB 到几十 MB，启动快、节省存储；
版本明确 ：避免使用 latest 标签（版本不固定，可能导致环境突变），指定具体版本（如 ubuntu:22.04 而非 ubuntu:latest）；
安全性：选择官方认证的镜像（Docker Hub 上带"Official Image"标识），定期更新镜像以修复漏洞。

2. 定制专属基础镜像（通用场景）

若官方镜像无法满足基础环境需求（如需预装 Git、Maven、编译器），可基于官方镜像定制，步骤如下：

步骤 1：编写 Dockerfile（以 Java 编译环境为例）

创建 Dockerfile 文件，定义镜像的构建逻辑：

dockerfile 复制代码

# 1. 选择官方基础镜像（Alpine 版本，轻量化）
FROM openjdk:17-jdk-alpine3.18

# 2. 维护者信息（可选）
LABEL maintainer="devops@example.com"
LABEL description="Java 17 + Maven 3.9 + Git 基础镜像，用于 Jenkins 编译任务"

# 3. 安装基础依赖（Git、Maven，Alpine 使用 apk 包管理器）
RUN apk update && \
    apk add --no-cache git maven && \
    # 清理缓存，减少镜像体积
    rm -rf /var/cache/apk/*

# 4. 配置环境变量（可选，如 Maven 仓库地址）
ENV MAVEN_OPTS="-Dmaven.repo.local=/root/.m2/repository"
ENV PATH="$PATH:/usr/share/maven/bin"

# 5. 设置默认工作目录（Jenkins 任务可覆盖）
WORKDIR /workspace

步骤 2：构建基础镜像

在 Dockerfile 所在目录执行 docker build 命令，生成镜像：

bash 复制代码

# 语法：docker build -t 镜像名称:标签 -f Dockerfile 构建上下文目录
docker build -t jenkins-java-base:17-maven3.9 -f Dockerfile .

参数说明：
- -t：为镜像打标签（格式：仓库地址/镜像名:版本，若不指定仓库地址，默认是本地镜像）；
- -f：指定 Dockerfile 路径（默认是当前目录的 Dockerfile，可省略）；
- .：构建上下文目录（Docker 会读取该目录下的文件用于构建，如需要复制的配置文件）。

步骤 3：验证基础镜像

运行镜像并执行命令，验证环境是否正常：

bash 复制代码

# 启动容器并执行命令，验证 JDK、Maven、Git 版本
docker run --rm jenkins-java-base:17-maven3.9 sh -c "java -version && mvn -v && git --version"

若输出正确的版本信息，说明基础镜像构建成功。

五、自动化基础环境部署到基础镜像（复杂场景）

对于复杂自动化环境（如嵌入式编译工具链、定制化测试框架），需在基础镜像中部署完整依赖，以 IAR 嵌入式编译环境 为例，步骤如下：

1. 准备环境依赖文件

IAR 编译器安装包（如 iar_installer.run）；
编译器许可证文件（如 license.dat）；
自动化安装脚本（如 install_iar.sh，用于静默安装）。

2. 编写 Dockerfile（嵌入式编译环境）

dockerfile 复制代码

# 基础镜像：选择 Ubuntu 22.04（兼容性更好，适合嵌入式工具链）
FROM ubuntu:22.04

# 安装依赖（IAR 安装需要的库）
RUN apt update && \
    apt install -y libx11-6 libgtk-3-0 libcanberra-gtk3-module && \
    rm -rf /var/lib/apt/lists/*

# 复制 IAR 安装文件和脚本到镜像
COPY iar_installer.run /tmp/
COPY install_iar.sh /tmp/
COPY license.dat /opt/iar/license/

# 赋予执行权限并静默安装 IAR
RUN chmod +x /tmp/iar_installer.run /tmp/install_iar.sh && \
    /tmp/install_iar.sh && \
    # 清理安装文件，减少镜像体积
    rm -rf /tmp/*

# 配置 IAR 环境变量（编译器路径加入 PATH）
ENV PATH="$PATH:/opt/iar/bin"
ENV IAR_LICENSE_FILE="/opt/iar/license/license.dat"

WORKDIR /workspace

3. 编写静默安装脚本（install_iar.sh）

嵌入式工具链通常需要交互安装，通过静默参数实现自动化：

bash 复制代码

#!/bin/sh
# IAR 静默安装脚本（具体参数需参考 IAR 安装文档）
/tmp/iar_installer.run --mode silent --prefix /opt/iar --accept-license

4. 构建并验证镜像

bash 复制代码

# 构建镜像
docker build -t jenkins-iar-base:8.50.9 -f Dockerfile .

# 验证 IAR 编译器
docker run --rm jenkins-iar-base:8.50.9 iccarm --version

若输出 IAR ANSI C Compiler V8.50.9，说明嵌入式环境部署成功。

六、镜像打包推送到私有仓库

为了在多 Jenkins 节点间共享镜像，需将定制好的镜像推送到私有仓库（如 Harbor、Nexus、GitLab Container Registry），以 Harbor 私有仓库 为例：

1. 私有仓库准备

已部署 Harbor 仓库（如地址：harbor.example.com）；
创建项目（如 jenkins-images，用于存储 Jenkins 相关镜像）；
拥有仓库的推送权限（用户名/密码或 Token）。

2. 镜像标签重命名（符合私有仓库格式）

私有仓库镜像标签需遵循格式：仓库地址/项目名/镜像名:版本，执行以下命令重命名：

bash 复制代码

# 原镜像：jenkins-java-base:17-maven3.9
# 重命名为：harbor.example.com/jenkins-images/jenkins-java-base:17-maven3.9
docker tag jenkins-java-base:17-maven3.9 harbor.example.com/jenkins-images/jenkins-java-base:17-maven3.9

3. 登录私有仓库

bash 复制代码

# 语法：docker login 仓库地址 -u 用户名 -p 密码
docker login harbor.example.com -u devops -p Harbor12345

若使用 Token 登录，-p 后填 Token；
登录成功后，Docker 会保存凭据到 ~/.docker/config.json（后续推送无需重复登录）。

4. 推送镜像到私有仓库

bash 复制代码

# 语法：docker push 仓库地址/项目名/镜像名:版本
docker push harbor.example.com/jenkins-images/jenkins-java-base:17-maven3.9

推送进度可通过终端输出查看，若显示 Pushed 且无错误，说明推送成功；
推送完成后，可在 Harbor 仓库的 jenkins-images 项目中看到该镜像。

5. 权限管理（可选）

为确保镜像安全，需配置私有仓库权限：

给 Jenkins 节点分配"拉取权限"（仅允许拉取，禁止推送，避免误操作）；
定期清理过期镜像（如 Harbor 的"镜像清理规则"，删除 30 天未使用的镜像）。

七、容器节点配置到 Jenkins

Jenkins 运行容器任务，需将"支持 Docker 的节点"配置为 Jenkins Agent，节点类型分为 Docker-in-Docker（DIND） 和 外部 Docker 节点，以下为两种方式的配置步骤：

方式 1：外部 Docker 节点（推荐，稳定性高）

适用于已安装 Docker 的物理机/虚拟机，Jenkins Agent 直接调用节点本地的 Docker 服务。

步骤 1：节点安装 Docker 环境

Linux 节点 （以 Ubuntu 为例）：

bash 复制代码

# 安装 Docker
apt update && apt install -y docker.io
# 启动 Docker 服务
systemctl enable docker && systemctl start docker
# 给 Jenkins Agent 用户（如 jenkins）添加 Docker 权限（避免 sudo）
usermod -aG docker jenkins

Windows 节点 ：
下载并安装 Docker Desktop，启用"WSL 2 后端"，并给 Jenkins 服务用户添加 Docker 权限。

步骤 2：在 Jenkins 中添加节点

登录 Jenkins 管理界面 → Manage Jenkins → Manage Nodes and Clouds → New Node；
配置节点基本信息：
- Node name：节点名称（如 docker-node-01）；
- Type：选择"Permanent Agent"；
- Remote root directory：Jenkins Agent 工作目录（如 /home/jenkins/workspace，Linux）或 C:\jenkins\workspace（Windows）；
- Labels：添加标签（如 docker linux，后续流水线通过标签指定节点）；
配置节点启动方式（以"SSH"为例，适合 Linux 节点）：
- Launch method：选择"Launch agents via SSH"；
- Host：节点 IP 地址（如 172.16.5.181）；
- Credentials：添加节点的 SSH 凭证（用户名/密码或私钥）；
配置 Docker 环境变量（关键）：
- 点击"Advanced" → "Environment variables" → "Add"；
- 添加变量 DOCKER_HOST，值为 unix:///var/run/docker.sock（Linux）或 npipe:////./pipe/docker_engine（Windows）；
- 也可以添加其他变量、比如IAR路径、SDK路径，后续直接使用docker run -v 参数映射目录到容器内
配置默认工具路径（git、jdk等）：
点击"Save"，Jenkins 会自动连接节点，若节点状态为"Online"，说明配置成功。

方式 2：Docker-in-Docker（DIND，适合动态节点）

适用于无固定节点的场景（如 Kubernetes 集群），Jenkins 动态创建容器作为 Agent，且容器内可运行 Docker 命令（嵌套 Docker）。

步骤 1：安装 Jenkins 插件

登录 Jenkins → Manage Jenkins → Plugins → Available Plugins；
搜索并安装 Docker Pipeline、Docker、Kubernetes Plugin（若用 Kubernetes）；
重启 Jenkins 使插件生效。

步骤 2：配置 DIND 云节点

Manage Jenkins → Manage Nodes and Clouds → Configure Clouds → Add a new cloud → Docker；
配置 Docker 服务地址：
- Docker Host URI：若 Jenkins Master 本地有 Docker，填 unix:///var/run/docker.sock；若用远程 Docker，填 tcp://<远程IP>:2376；
配置 Agent 模板：
- Name：模板名称（如 dind-agent）；
- Docker Image：选择 DIND 基础镜像（如 docker:dind）；
- Labels：添加标签（如 docker-dind）；
- Volumes：挂载 Docker sock 文件（/var/run/docker.sock:/var/run/docker.sock）；
- Privileged mode：勾选"Privileged"（DIND 需特权模式）；
点击"Save"，动态节点配置完成，流水线可通过标签 docker-dind 调用该节点。

验证节点 Docker 可用性

在 Jenkins 中创建"自由风格项目"，执行以下构建步骤，验证节点 Docker 是否正常：

bash 复制代码

# 执行 Docker 命令，验证版本
docker --version
# 运行测试容器
docker run --rm hello-world

若输出 Hello from Docker!，说明节点 Docker 配置成功。

八、流水线脚本：鉴权并拉取容器镜像

Jenkins 流水线需先通过私有仓库鉴权，再拉取镜像，核心是 凭证管理 和 镜像拉取命令 的结合。

1. 在 Jenkins 中添加私有仓库凭证

登录 Jenkins → Manage Jenkins → Manage Credentials → Global → Add Credentials；
选择凭证类型：
- 若私有仓库是 Harbor/Nexus，选择 Username with password；
- 若用 Docker Hub 或 Token 认证，选择 Docker Hub Token 或 Secret text；
配置凭证信息：
- Username：私有仓库用户名（如 devops）；
- Password：私有仓库密码或 Token；
- ID：凭证唯一标识（如 harbor-cred，后续流水线引用）；
- Description：描述（如 Harbor 私有仓库凭证）；
点击"Create"，凭证添加完成。

2. 流水线脚本：鉴权并拉取镜像

以下为声明式流水线示例，包含"鉴权 → 拉取镜像 → 验证"步骤：

groovy 复制代码

pipeline {
    // 指定容器节点（通过标签匹配）
    agent {
        node {
            label 'docker linux'  // 匹配配置好的 Docker 节点
        }
    }
    // 定义环境变量（私有仓库地址、镜像信息）
    environment {
        HARBOR_URL = 'harbor.example.com'  // 私有仓库地址
        IMAGE_NAME = 'jenkins-images/jenkins-java-base'  // 镜像名（含项目名）
        IMAGE_TAG = '17-maven3.9'  // 镜像版本
        // 完整镜像地址
        FULL_IMAGE = "${HARBOR_URL}/${IMAGE_NAME}:${IMAGE_TAG}"
    }
    stages {
        stage('Docker 鉴权与拉取镜像') {
            steps {
                // 1. 鉴权：使用 Jenkins 凭证登录私有仓库
                withCredentials([usernamePassword(
                    credentialsId: 'harbor-cred',  // 凭证 ID（与添加时一致）
                    usernameVariable: 'HARBOR_USER',
                    passwordVariable: 'HARBOR_PWD'
                )]) {
                    sh """
                        # 登录 Harbor 仓库
                        docker login ${HARBOR_URL} -u ${HARBOR_USER} -p ${HARBOR_PWD}
                        # 拉取镜像
                        docker pull ${FULL_IMAGE}
                        # 验证镜像是否拉取成功
                        docker images | grep ${IMAGE_NAME}
                    """
                }
            }
        }
    }
    post {
        // 任务结束后登出私有仓库（可选，避免残留凭证）
        always {
            sh "docker logout ${HARBOR_URL}"
        }
    }
}

关键说明：

withCredentials：Jenkins 安全凭证管理插件，避免密码明文暴露在日志中；
docker login：登录私有仓库，若登录成功，终端会显示 Login Succeeded；
docker pull：拉取镜像，若镜像已存在（本地缓存），会提示 Status: Image is up to date；
post.always：无论任务成功或失败，都会执行登出操作，保护凭证安全。

九、启动容器并执行命令（含 docker run 参数详解）

流水线中通过 docker run 启动容器，并在容器内执行自动化命令（如编译、测试），以下为完整示例及参数详解。

1. 完整流水线示例（启动容器执行编译任务）

groovy 复制代码

pipeline {
    agent { node { label 'docker linux' } }
    environment {
        HARBOR_URL = 'harbor.example.com'
        IMAGE_NAME = 'jenkins-images/jenkins-java-base'
        IMAGE_TAG = '17-maven3.9'
        FULL_IMAGE = "${HARBOR_URL}/${IMAGE_NAME}:${IMAGE_TAG}"
        // Jenkins 工作目录（宿主机路径）
        WORKSPACE_DIR = "${WORKSPACE}"
        // 容器内工作目录（与宿主机保持一致，便于挂载）
        CONTAINER_WORKSPACE = "/workspace"
    }
    stages {
        stage('拉取代码') {
            steps {
                // 1. 先在宿主机拉取代码（避免容器内重复拉取）
                checkout scm: [
                    $class: 'GitSCM',
                    branches: [[name: '*/main']],
                    userRemoteConfigs: [[
                        url: 'ssh://git@bitbucket.org/example/project.git',
                        credentialsId: 'bitbucket-ssh-cred'  // Git 凭证
                    ]]
                ]
            }
        }
        stage('启动容器执行编译') {
            steps {
                withCredentials([usernamePassword(
                    credentialsId: 'harbor-cred',
                    usernameVariable: 'HARBOR_USER',
                    passwordVariable: 'HARBOR_PWD'
                )]) {
                    sh """
                        # 登录并拉取镜像
                        docker login ${HARBOR_URL} -u ${HARBOR_USER} -p ${HARBOR_PWD}
                        docker pull ${FULL_IMAGE}
                        
                        # 启动容器并执行编译命令（关键步骤）
                        docker run \
                            --rm \  # 任务结束后自动删除容器
                            --label jenkins.buildId=${BUILD_ID} \  # 添加 Jenkins 构建标签（便于后续管理）
                            --user $(id -u):$(id -g) \  # 指定容器内用户（与宿主机一致，避免权限问题）
                            -v ${WORKSPACE_DIR}:${CONTAINER_WORKSPACE} \  # 挂载宿主机代码目录到容器
                            -w ${CONTAINER_WORKSPACE} \  # 设置容器内工作目录
                            -e "BUILD_ID=${BUILD_ID}" \  # 传递 Jenkins 环境变量到容器
                            -e "MAVEN_OPTS=-Dmaven.test.skip=true" \  # 传递自定义环境变量
                            --cpus 2 \  # 限制容器使用 2 个 CPU 核心
                            -m 4g \  # 限制容器使用 4GB 内存
                            ${FULL_IMAGE} \  # 指定使用的镜像
                            sh -c '  # 容器内执行的命令（编译项目）
                                echo "容器内工作目录: \$PWD";
                                echo "Jenkins 构建 ID: \$BUILD_ID";
                                mvn clean package -DskipTests;  # Maven 编译命令
                            '
                        
                        # 登出仓库
                        docker logout ${HARBOR_URL}
                    """
                }
            }
        }
        stage('归档产物') {
            steps {
                // 从宿主机工作目录归档编译产物（容器内编译的产物已同步到宿主机）
                archiveArtifacts artifacts: 'target/*.jar', fingerprint: true
            }
        }
    }
}

2. `docker run` 关键参数详解

参数	作用说明	示例值	注意事项
`--rm`	容器退出后自动删除，避免残留容器	`--rm`	生产环境推荐使用，避免节点容器堆积
`--label`	给容器添加标签，便于筛选和管理（如关联 Jenkins 构建 ID）	`--label jenkins.buildId=123`	标签格式：`key=value`，可添加多个（如 `--label project=demo`）
`--user UID:GID`	指定容器内运行用户的 UID 和 GID（与宿主机一致，避免权限问题）	`--user 1001:1001`	可通过 `id -u`（宿主机当前用户 UID）和 `id -g`（GID）获取
`-v 宿主机路径:容器路径`	挂载宿主机目录到容器，实现文件同步（如代码目录、产物目录）	`-v /home/jenkins/workspace:/workspace`	路径必须是绝对路径；若容器路径不存在，Docker 会自动创建
`-w 容器路径`	设置容器内的工作目录，后续命令默认在此目录执行	`-w /workspace`	通常与挂载的代码目录一致，避免路径混乱
`-e 变量名=值`	传递环境变量到容器（如 Jenkins 变量、自定义配置）	`-e BUILD_ID=123`	可添加多个 `-e` 参数；容器内通过 `$变量名` 引用
`--cpus N`	限制容器使用的 CPU 核心数（避免单个任务占用过多资源）	`--cpus 2`	N 可以是小数（如 `--cpus 1.5`，表示 1.5 个核心）
`-m 内存大小`	限制容器使用的内存（避免内存溢出）	`-m 4g`（4GB）或 `-m 2048m`（2048MB）	若容器内存超过限制，Docker 会杀死容器，需根据任务需求合理设置
`--privileged`	给容器特权模式（如需要访问宿主机硬件、修改内核参数）	`--privileged`	非必要不使用，存在安全风险（容器可操作宿主机内核）
`--network 网络模式`	指定容器网络模式（如桥接、主机网络）	`--network host`	若任务需访问宿主机服务（如本地数据库），可使用 `--network host`

十、代码拉取与同步：宿主机拉取 + 容器挂载

在容器中执行自动化任务，代码同步的最佳实践是 "宿主机拉取代码 → 挂载到容器"，而非"容器内拉取代码"，原因如下：

避免容器内重复配置 Git 凭证（宿主机已配置 Jenkins Git 凭证）；
宿主机拉取的代码可缓存，后续构建无需重新拉取（节省时间）；
容器内编译的产物直接同步到宿主机，便于 Jenkins 归档和后续步骤使用。

具体实现步骤（已集成到第九节的流水线示例中）

宿主机拉取代码 ：

通过 Jenkins 的 checkout scm 步骤，在宿主机的 WORKSPACE 目录拉取代码（Git 凭证已在 Jenkins 中配置，无需容器内再配置）。
挂载代码目录到容器 ：

通过 docker run -v ${WORKSPACE_DIR}:${CONTAINER_WORKSPACE}，将宿主机的代码目录挂载到容器内，容器内可直接访问代码文件。
容器内执行命令 ：

在容器内执行编译、测试等命令（如 mvn clean package），操作的是挂载目录中的代码，产物（如 target/*.jar）会自动同步到宿主机的 WORKSPACE 目录。
宿主机归档产物 ：

Jenkins 直接从宿主机的 WORKSPACE 目录归档产物（archiveArtifacts 步骤），无需从容器内拷贝。

优势总结

效率高：宿主机代码缓存，避免重复拉取；
权限易管理 ：代码目录属主是 Jenkins 用户，容器内通过 --user 参数匹配 UID/GID，避免权限冲突；
可维护性好：代码拉取和产物归档都在宿主机完成，流程清晰，便于问题排查。

十一、权限问题：容器内修改权限导致宿主机清理失败

在容器中执行 chown、chmod 等命令，可能导致宿主机代码目录的属主/权限被修改（如容器内用 root 用户执行 chown -R root:root /workspace），后续 Jenkins 清理目录时因"权限不足"失败。

问题原因

容器内的用户 UID/GID 与宿主机用户映射：若容器内用 root（UID=0）修改目录权限，宿主机上该目录的属主会变成 root（而非 Jenkins 用户，UID=1001）；
Jenkins 清理目录时使用的是 Jenkins 用户（UID=1001），对 root 属主的目录无删除权限，导致清理失败。

解决方案

方案 1：启动容器时指定宿主机用户 UID/GID（预防为主）

在 docker run 中通过 --user $(id -u):$(id -g) 指定容器内用户的 UID/GID，与宿主机 Jenkins 用户一致，容器内操作的文件属主始终是 Jenkins 用户，避免权限变更：

bash 复制代码

# 宿主机 Jenkins 用户 UID=1001，GID=1001
docker run --user $(id -u):$(id -g) -v ${WORKSPACE}:/workspace ...

原理：容器内用户的 UID/GID 与宿主机 Jenkins 用户一致，文件的属主在宿主机和容器内保持统一，后续清理无权限问题；
适用场景：任务无需 root 权限（如编译、测试），是最推荐的方案。

方案 2：容器内操作后恢复权限（补救措施）

若任务必须用 root 权限（如安装依赖），需在容器任务结束后恢复目录权限，步骤如下：

记录宿主机目录原始 UID/GID ：在启动容器前，通过 stat 命令获取宿主机代码目录的原始属主；
容器内操作后恢复权限：在容器内执行完任务后，用原始 UID/GID 恢复目录权限。

流水线示例：

groovy 复制代码

stage('启动容器执行任务并恢复权限') {
    steps {
        sh """
            # 1. 记录宿主机代码目录的原始 UID/GID
            ORIGIN_UID_GID=\$(stat -c "%u:%g" ${WORKSPACE_DIR})
            echo "宿主机原始 UID:GID = \${ORIGIN_UID_GID}"
            
            # 2. 启动容器（用 root 用户执行任务）
            docker run \
                --rm \
                --user root:root \  # 用 root 权限执行任务
                -v ${WORKSPACE_DIR}:${CONTAINER_WORKSPACE} \
                -w ${CONTAINER_WORKSPACE} \
                ${FULL_IMAGE} \
                sh -c '
                    # 容器内执行需要 root 权限的任务（如安装依赖）
                    apt update && apt install -y libxxx-dev;
                    # 执行编译任务
                    mvn clean package;
                    # 3. 恢复目录权限为宿主机原始 UID/GID
                    chown -R ${ORIGIN_UID_GID} ${CONTAINER_WORKSPACE};
                '
        """
    }
}

原理：通过 stat -c "%u:%g" 获取宿主机目录原始 UID/GID，容器内任务结束后用 chown 恢复，确保宿主机目录属主不变；
注意事项：ORIGIN_UID_GID 是宿主机变量，需在 docker run 命令外定义，通过字符串拼接传递到容器内。

方案 3：Jenkins 清理时使用 root 权限（最后手段）

若上述方案无法实施，可在 Jenkins 清理步骤中使用 sudo 或 root 权限删除目录，步骤如下：

给 Jenkins 用户添加 sudo 权限（无需密码）：

bash 复制代码

# 编辑 sudoers 文件
visudo
# 添加一行：jenkins ALL=(ALL) NOPASSWD: /bin/rm, /bin/rmdir

流水线清理步骤：

groovy 复制代码

post {
    always {
        // 用 sudo 权限清理目录
        sh "sudo rm -rf ${WORKSPACE_DIR}/*"
    }
}

风险：sudo 权限存在安全隐患（Jenkins 用户可执行 rm -rf / 等危险命令），非必要不使用。

十二、总结

优先选择"外部 Docker 节点"：稳定性高于 DIND，避免嵌套 Docker 的性能开销和安全风险；
镜像轻量化 ：基础镜像优先选择 Alpine 版本，定制镜像时清理缓存（如 rm -rf /var/cache/apk/*），减少镜像体积；
权限最小化 ：启动容器时用 --user 指定非 root 用户，避免权限变更导致的宿主机问题；
代码同步方式：采用"宿主机拉取 + 容器挂载"，避免容器内重复配置凭证和拉取代码；
镜像版本化 ：镜像标签包含明确版本（如 17-maven3.9），避免使用 latest，便于回滚；
安全鉴权 ：私有仓库凭证通过 Jenkins withCredentials 管理，避免明文暴露；任务结束后执行 docker logout，清理凭证。

Jenkins 使用容器运行自动化任务详细文档