Jenkins Docker执行器镜像文档

1. 镜像概述和主要用途

该Docker镜像包含Jenkins服务，支持两种Docker运行模式：直接使用主机Docker服务器或在容器内部运行Docker服务器（Docker-in-Docker）。主要用途是提供一个集成Docker环境的Jenkins服务，用于执行需要Docker支持的CI/CD构建任务。

2. 核心功能和特性

• 双Docker模式支持：可连接主机Docker服务器或在容器内运行独立Docker服务器
• 数据持久化：支持通过绑定挂载或数据容器存储Jenkins数据（JENKINS_HOME）
• 灵活部署：无需特权模式即可使用主机Docker；容器内Docker需特权模式
• 用户配置优化：Jenkins以root用户运行，家目录与JENKINS_HOME统一，便于注入SSH密钥、dockercfg等配置

3. 使用场景和适用范围

• 高性能构建场景：需直接访问主机Docker资源，追求构建速度（推荐使用主机Docker模式）
• 隔离多租户场景：需限制Jenkins实例对主机Docker的访问，确保环境隔离（推荐使用Docker-in-Docker模式）
• 数据持久化需求：需跨容器重启保留Jenkins配置、工作区和构建历史

4. 详细使用方法和配置说明

4.1 使用主机Docker服务器

通过绑定挂载主机的/var/run/docker.sock套接字文件，使Jenkins容器直接使用主机Docker服务。无需特权模式，性能接近原生。

部署命令：

docker run -p 8080:8080 -v /var/run/docker.sock:/var/run/docker.sock --name jenkins-1 onesysadmin/jenkins-docker-executors

• 端口映射：8080:8080（Jenkins Web界面）
• 关键挂载：/var/run/docker.sock:/var/run/docker.sock（绑定主机Docker套接字）

4.2 在Docker内运行Docker服务器

在容器内部启动独立Docker服务器，需启用特权模式。容器会自动检测/var/run/docker.sock是否存在，不存在时自动启动内部Docker服务。

部署命令：

docker run --privileged -p 8080:8080 --name jenkins-1 onesysadmin/jenkins-docker-executors

• 特权模式：--privileged（必需，用于容器内Docker服务运行）

4.3 数据持久化配置

默认JENKINS_HOME路径为/var/jenkins，可通过环境变量覆盖。数据持久化支持两种方式：

4.3.1 绑定主机目录

直接将主机目录挂载到容器的JENKINS_HOME，适用于需要主机直接访问Jenkins工作区的场景。

操作步骤：

1. 在主机创建数据目录：

   mkdir /var/jenkins
   

2. 启动容器并绑定目录：

   docker run -d \
     -v /var/run/docker.sock:/var/run/docker.sock \  # （如使用主机Docker）
     -v /var/jenkins:/var/jenkins \                 # 绑定主机数据目录到JENKINS_HOME
     -p 8080:8080 \
     --name jenkins-1 \
     onesysadmin/jenkins-docker-executors
   

4.3.2 使用数据容器

通过数据容器（Data Container）存储JENKINS_HOME，实现数据与业务容器解耦，便于独立备份。

操作步骤：

1. 创建数据容器（仅存储卷，无运行进程）：

   docker run --name JENKINS_DATA -v /var/jenkins busybox true
   

2. 启动Jenkins容器并挂载数据卷：

   docker run -d \
     -v /var/run/docker.sock:/var/run/docker.sock \  # （如使用主机Docker）
     --volumes-from JENKINS_DATA \                   # 继承数据容器的卷
     -p 8080:8080 \
     --name jenkins-1 \
     onesysadmin/jenkins-docker-executors
   

4.4 Jenkins用户与权限

• 运行用户：Jenkins服务在容器内以root用户运行
• 家目录配置：root用户家目录被覆盖为JENKINS_HOME（默认/var/jenkins），便于通过数据卷注入配置文件（如SSH密钥、dockercfg认证文件等）

5. Docker-in-Docker模式注意事项

使用容器内Docker服务器时需注意以下限制：

1. 性能损耗：容器内Docker构建速度比主机Docker慢50%以上（因存储引擎限制，默认使用vfs而非主机存储驱动）
2. 数据卷残留：容器停止后，内部Docker创建的/var/lib/docker数据卷不会自动清除，需手动清理（删除容器时使用docker rm -v命令，-v参数会移除容器关联的匿名卷）
3. 回环设备耗尽：若Docker服务器未正常关闭，可能导致回环设备（loopback devices）未释放，需重启主机解决
4. 临时文件路径：部分Jenkins插件会向/tmp目录写入临时文件，该目录仅存在于Jenkins容器内，其他容器无法访问。建议将临时文件路径配置到工作区（JENKINS_HOME下）

6. 在Jenkins容器内构建/运行Docker镜像

在Jenkins构建任务中可直接使用docker命令，行为与原生环境一致。无需额外配置，支持镜像构建、容器运行等标准Docker操作。

注意：避免在容器内Docker中再次运行该Jenkins镜像，防止嵌套过深导致环境异常。

7. 配置参数说明

7.1 环境变量

7.2 卷挂载点