Windows11 Docker-Desktop 下 Jenkins 安装部署及 Gitee 项目构建docker部署指南

本文是准备在Docker Desktop下安装jenkins，然后将gitee拉取maven项目并构建完成后再部署到本机的docker上。

一、环境准备

（一）基础环境要求

  1. 操作系统：Windows 11 专业版/企业版（需开启 Hyper-V 功能，Docker Desktop 依赖）
  2. Docker Desktop：已安装并正常运行（建议版本 24.0+，确保与 Jenkins 容器兼容性）
  3. 硬件配置：至少 4GB 内存（Jenkins 运行建议 8GB+，避免构建时内存不足）
  4. 网络环境：可访问外网（用于下载 Jenkins 镜像、Maven 安装包、Gitee 项目代码）

（二）目录提前创建

以存放地点为D盘为例。在 D 盘手动创建如下目录结构（避免 Docker 挂载时权限问题）：

D:\docker\jenkins\
├─ data # Jenkins 数据持久化目录
└─ workspace # 项目构建工作空间

二、Jenkins 安装部署（Docker-Compose + Dockerfile）

（一）配置文件编写

1. docker-compose.yml

创建路径：D:\docker\jenkins\docker-compose.yml，内容如下：

version: '3.8'
services:
jenkins:
build: . # 依赖当前目录下的 Dockerfile 构建镜像
container_name: jenkins-docker
privileged: true # 授予容器特权，便于操作 Docker 套接字
restart: always # 容器异常退出时自动重启
ports:
- "8080:8080" # Jenkins 网页访问端口
- "50000:50000" # Jenkins 代理通信端口
environment:
- TZ=Asia/Shanghai # 配置时区为上海，避免时间同步问题
volumes:
# 数据持久化挂载
- D:/docker/jenkins/data:/var/jenkins_home
- D:/docker/jenkins/workspace:/var/jenkins_home/workspace
# 挂载 Docker 套接字，实现容器内操作主机 Docker
- /var/run/docker.sock:/var/run/docker.sock
group_add:
- "999" # Docker 组 GID，确保容器内用户有权限访问 Docker 套接字
volumes:
jenkins_data: # 定义数据卷，增强数据安全性
2. Dockerfile 安装说明

Dockerfile的核心作用是基于官方Jenkins镜像进行定制化构建，提前将Docker客户端等必备工具集成到镜像中，形成专用的Jenkins镜像。相比容器启动后手动安装工具，此方式可确保工具环境与镜像绑定，避免容器重启、重建后工具丢失或配置失效的问题，同时保证每次部署的环境一致性。以下是完整的Dockerfile配置及关键说明：

Dockerfile 配置内容

创建路径：D:\docker\jenkins\Dockerfile，内容如下：

# 基于官方 Jenkins LTS 镜像（稳定版，适合生产环境）
FROM jenkins/jenkins:lts

# 切换到 root 用户，用于安装依赖工具
USER root

# 安装 Docker 29.1.2 客户端（适配 x86_64 架构，与 Docker Desktop 兼容）
RUN curl -L "https://mirrors.aliyun.com/docker-ce/linux/static/stable/x86_64/docker-29.1.2.tgz" -o /tmp/docker.tgz \
&& tar -zxvf /tmp/docker.tgz -C /tmp \
&& cp /tmp/docker/docker /usr/bin/ \
&& chmod +x /usr/bin/docker \ # 赋予执行权限
&& rm -rf /tmp/docker.tgz /tmp/docker # 清理临时文件

# 安装必要工具（解决构建时缺少命令的问题）
RUN apt-get update && apt-get install -y \
git \ # 用于拉取 Gitee 代码
curl \
vim \ # 文本编辑工具
&& rm -rf /var/lib/apt/lists/* # 清理 apt 缓存

# 切回 jenkins 用户，避免权限过高导致的安全问题
USER jenkins

（二）启动 Jenkins 容器

  1. 打开 Windows 终端（管理员模式），切换到目录：
cd D:\docker\jenkins
  1. 构建并启动容器（首次启动需下载镜像，耗时较长）：
docker-compose down && docker-compose up -d --build
  1. 验证启动状态：
docker ps | grep jenkins-docker

若出现容器信息，说明启动成功。

三、Jenkins 初始化配置

（一）首次访问与解锁

  1. 浏览器访问：http://localhost:8080
  2. 获取初始管理员密码：
    方式 1：容器内查看（终端执行）：
docker exec -it jenkins-docker cat /var/jenkins_home/secrets/initialAdminPassword

方式 2：本地目录查看（直接打开文件）：

D:\docker\jenkins\data\secrets\initialAdminPassword
  1. 输入密码解锁后，选择「安装推荐插件」（包含 Git、Maven 集成等必备插件）。
  2. 创建管理员用户（记住用户名和密码，用于后续登录）。
  3. 必装插件安装（补充推荐插件外的核心插件）：首次安装的推荐插件可能无法满足Gitee集成与Docker构建需求，需手动补充安装以下核心插件，操作步骤如下：
  4. 进入Jenkins首页，点击左侧「系统管理」→「插件管理」→「可选插件」。
  5. 在搜索框中分别搜索以下插件，勾选后点击「直接安装」（可批量勾选后统一安装），安装完成后建议重启Jenkins以确保插件生效：
  6. Gitee Plugin：核心功能是实现Jenkins与Gitee仓库的联动，支持拉取Gitee代码、触发WebHook构建等，是Gitee项目集成的必备插件。
  7. Docker Plugin：提供Jenkins与Docker的集成能力，支持在构建步骤中调用Docker命令、管理Docker镜像和容器，简化镜像构建与部署流程。
  8. Docker Pipeline：若后续使用Pipeline流水线构建项目，此插件不可或缺，支持在Jenkinsfile中编写Docker相关的流水线脚本。
  9. Maven Integration Plugin：增强Jenkins对Maven项目的支持，可直接在构建步骤中选择Maven版本并执行编译、打包等命令，避免手动配置Maven环境变量的繁琐。
  10. 插件安装验证：安装完成后，进入「系统管理」→「插件管理」→「已安装」，在搜索框中输入插件名称，能查询到则说明安装成功。

（二）JDK 环境配置（自带 JDK 优化）

Jenkins 镜像自带 OpenJDK，无需额外安装，只需配置 JAVA_HOME：

  1. 提前验证 Java 的实际安装位置（关键步骤）

先通过终端进入 Jenkins 容器，执行以下命令查看 Java 的可执行文件路径和安装目录：

# 1. 进入Jenkins容器（jenkins-docker为容器名，需替换为你的实际容器名）
docker exec -it jenkins-docker /bin/bash

# 2. 查看java可执行文件的绝对路径（最常用）
which java

# 3. 查看java的二进制文件、源码、帮助文档等所有相关路径
whereis java

# 4. 也可直接查看镜像中JAVA_HOME的配置值（验证路径用）
echo $JAVA_HOME

示例输出：

  • which java 可能返回：/opt/java/openjdk/bin/java
  • whereis java 可能返回：java: /opt/java/openjdk/bin/java /opt/java/openjdk/share/man/man1/java.1
  • 由此可确定JAVA_HOME的根路径为：/opt/java/openjdk
  1. Jenkins 页面配置 JDK

登录 Jenkins 后，依次进入：「系统管理」→「全局工具配置」→「JDK」模块，按以下步骤配置：

  • 点击「新增 JDK」
  • 取消勾选「自动安装」（因为是镜像自带 JDK，无需自动下载）
  • 填写配置项：
  • 名称：jdk21（可自定义，建议与 JDK 版本对应，如 jdk17、jdk8）
  • JAVA_HOME：填写上述命令验证后的路径（如/opt/java/openjdk）
  1. 配置验证（两种方式，任选其一即可）

方式一：直接在容器内验证（快速查看）

# jenkins-docker为容器名，需替换为你的实际容器名
docker exec -it jenkins-docker echo $JAVA_HOME

示例输出：/opt/java/openjdk（与配置路径一致即为正确）

方式二：在 Jenkins 页面验证（确认配置生效）

  1. 登录 Jenkins，依次进入：「系统管理」→「系统信息」
  2. 在页面中找到 java.home 或 JAVA_HOME 字段，查看其值是否与配置的路径一致
  3. 可额外查看java.version字段，确认 JDK 版本符合预期

（三）Maven 环境配置（自动安装 + 环境变量）

  1. Maven 自动安装（核心步骤，必须）

  2. 进入「系统管理」→「全局工具配置」→「Maven」。

  3. 点击「新增 Maven」，配置：

  • 名称：maven3.9.11（自定义，建议与版本对应）
  • 勾选「自动安装」
  • 版本：选择3.9.11

  1. 点击「保存」，Maven 会在首次构建时自动下载安装（Jenkins 任务会自动使用此路径）。

  2. 配置 Maven 环境变量（容器内操作，可选）

此步骤仅用于在容器终端手动执行 Maven 命令（如mvn -v），Jenkins 任务无需配置。

  1. 进入 Jenkins 容器终端：
docker exec -it jenkins-docker /bin/bash
  1. 追加环境变量到.bashrc（路径与「全局工具配置」的 Maven 名称一致）：
# 配置M2_HOME（对应名称maven3.9.11）
echo 'export M2_HOME=/var/jenkins_home/tools/hudson.tasks.Maven_MavenInstallation/maven3.9.11' >> ~/.bashrc
# 追加到PATH
echo 'export PATH=$M2_HOME/bin:$PATH' >> ~/.bashrc

3. 使配置生效并验证（仅容器终端用）：

```bash
source ~/.bashrc
mvn -v # 输出版本信息则容器终端可用

（四）Docker 客户端授权验证

容器内已通过 Dockerfile 安装 Docker 客户端，需验证是否正常使用：

在 Jenkins 容器终端执行：

docker --version # 输出 Docker 版本信息，说明安装成功
docker ps # 能列出主机 Docker 容器，说明套接字挂载正常

若出现「permission denied」错误，执行以下授权命令（容器内 root 用户）：

chmod 666 /var/run/docker.sock # 临时授权（容器重启后失效）
# 永久授权方案：在宿主机添加 Jenkins 用户到 Docker 组（Windows 无需额外操作，Docker Desktop 已自动配置）

四、Gitee 项目集成与构建配置

（一）Gitee插件配置（已安装插件的后续设置）

安装Gitee Plugin后，需进行基础配置以建立Jenkins与Gitee的连接：

  1. 进入「系统管理」→「系统配置」，下拉至「Gitee配置」模块。
  2. 点击「Gitee连接」后的「添加」，选择「Gitee API 令牌」类型，配置如下：
  3. 连接名称：自定义（如「Gitee-Connection」）
  4. Gitee域名URL：默认https://gitee.com（公开Gitee仓库无需修改）
  5. Gitee API 令牌：点击「添加」，选择「全局凭据」，输入Gitee私人令牌（获取路径：Gitee个人设置→私人令牌→生成，勾选api权限），描述填写「Gitee-API-Token」后保存。
  6. 点击「测试连接」，显示「Success」则说明Gitee连接配置成功，点击「保存」完成设置。
  7. 进入 Jenkins 「系统管理」→「插件管理」→「可选插件」。
  8. 搜索「Gitee」，勾选插件后点击「直接安装」，安装完成后重启 Jenkins。

（二）配置 Gitee 访问凭证（公开项目可以不用配置）

  1. 进入 Jenkins 「系统管理」→「凭据管理」→「系统」→「全局凭据」→「添加凭据」。
  2. 选择「Username with password」类型，配置如下：
  3. Username：Gitee 用户名
  4. Password：Gitee 密码或私人令牌（推荐私人令牌，获取路径：Gitee → 个人设置 → 私人令牌 → 生成令牌，勾选 repo 权限）
  5. ID：自定义（如 gitee-cred），后续构建配置会用到
  6. 点击「确定」保存凭据。

（三）创建自由风格软件项目

  1. 点击 Jenkins 首页「新建任务」，输入项目名称（如 springboot-hello），选择「自由风格软件项目」，点击「确定」。

（四）项目源码管理配置

  1. 选择「Git」，在「仓库 URL」中输入 Gitee 项目地址（如 https://gitee.com/xxx/springboot-hello.git）。
  2. 在「凭据」中选择步骤（二）创建的 Gitee 凭据。
  3. 「分支说明符」填写 */main（或项目实际分支名，如 */master）。

（五）构建触发器配置（自动构建）

选择以下任意一种自动构建方式：

  1. 轮询 SCM（适合小型项目推荐）：

  2. 勾选「轮询 SCM」，在「日程表」中输入 H/10 * * * *（每 10 分钟检查一次 Gitee 代码更新）。

  3. Gitee WebHook（实时触发）：

​ 注意：此方式需要jenkins服务器有公网IP（或者使用代理穿透模式）

  1. 勾选「触发远程构建（例如，使用脚本）」，设置「身份验证令牌」（如 jenkins-gitee-hook-123）。
  2. 登录 Gitee 项目 → 管理 → WebHook → 添加 WebHook，配置如下：
  • URL：http://[Jenkins 主机 IP]:8080/job/springboot-hello/build?token=jenkins-gitee-hook-123
  • 事件：勾选「Push 事件」
  • 点击「添加」，并测试 WebHook（显示「成功」则配置生效）。

（六）构建步骤配置（Maven 构建及Shell 脚本）

说明：项目本身是8088端口（application中设置），docker映射端口8888，jenkins端口8080

构建前置步骤（Pre Steps）配置，包含 Maven 构建与 Shell 脚本两部分，具体内容如下：

  1. Maven 构建「Pre Steps」→「调用顶级 Maven 目标」。
  • Maven 版本：选择之前自动安装的maven版本
  • 目标：clean package -DskipTests（作用：清理旧构建产物，编译、打包项目，同时跳过单元测试）
  1. 执行 shell「Pre Steps」→「执行Shell」。

输入以下 Shell 脚本（用于拉取代码、编译打包、构建 Docker 镜像、启动容器）：

# 1. 进入当前任务的工作空间
cd $WORKSPACE
#cd /var/jenkins_home/workspace/SpringBootDemo

# 2. 复制项目中的Dockerfile到Jar包所在目录（target）
cp src/main/docker/Dockerfile target/

# 3.进入target
cd target

# 4. 重命名Jar包为app.jar（与项目中Dockerfile的COPY指令匹配）
#说明springboot-hello.jar为项目中pom.xml中指定、app.jar为项目中Dockerfile中一致
mv springboot-hello.jar app.jar

# 5. 构建Docker镜像
docker build -t springboot-hello:latest .

# 6. 定义容器名称和端口（避免与Jenkins端口冲突）
CONTAINER_NAME="my-springboot-app"
HOST_PORT=8888 # 与Jenkins的8080端口区分

# 7. 停止并删除旧容器
echo "停止并删除旧容器: $CONTAINER_NAME"
docker stop $CONTAINER_NAME || echo "旧容器未运行，跳过停止"
docker rm $CONTAINER_NAME || echo "旧容器不存在，跳过删除"

# 8. 启动新容器（将jar的8088映射到主机8888端口）
echo "启动新容器: $CONTAINER_NAME，端口映射$HOST_PORT:8888"
docker run -d --name $CONTAINER_NAME -p $HOST_PORT:8088 springboot-hello:latest || echo "容器启动失败"

（七）Gitee 项目中 Dockerfile 示例（必须）

核心说明：Dockerfile目录结构要求

Gitee项目中Dockerfile必须放在指定目录下，否则Jenkins构建脚本无法正常识别！以下是完整的项目目录结构规范，请严格遵循。

  1. Gitee项目标准目录结构
# 项目根目录（与Gitee仓库根目录一致）
springboot-hello/
├─ src/
│ ├─ main/
│ │ ├─ docker/ # 固定Dockerfile存放目录，不可修改
│ │ │ └─ Dockerfile # 本次配置的核心文件
│ │ ├─ java/ # 项目源代码目录
│ │ └─ resources/ # 配置文件目录
│ └─ test/ # 测试代码目录
├─ pom.xml # Maven项目核心配置文件
└─ README.md # 项目说明文档
  1. Dockerfile配置内容（适配OpenJDK 21，与Jenkins环境一致）

在上述src/main/docker目录下创建Dockerfile，内容如下：

# 基础镜像（选择与项目 JDK 版本一致的镜像）
FROM openjdk:21-jdk-slim

# 工作目录
WORKDIR /app

# 复制 Jar 包到容器（与 Shell 脚本中重命名的 app.jar 一致）
COPY app.jar /app/app.jar

# 暴露端口（与 Spring Boot 项目配置的 server.port 一致）
EXPOSE 8080

# 启动命令
ENTRYPOINT ["java", "-jar", "/app/app.jar"]
  1. 项目pom.xml（样例Demo展示）
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>4.0.0</version>
<relativePath/> <!-- lookup parent from repository -->
</parent>
<groupId>com.example</groupId>
<artifactId>springboot-hello</artifactId>
<version>1.0</version>
<name>springboot-hello</name><!--生成的jar文件名-->
<description>Demo project for Spring Boot</description>
<url/>

<properties>
<java.version>21</java.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-webmvc</artifactId>
</dependency>

<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-thymeleaf</artifactId>
</dependency>

<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-webmvc-test</artifactId>
<scope>test</scope>
</dependency>
</dependencies>

<build>
<!-- 联动项目版本：finalName = 项目名 + 版本号 -->
<finalName>${project.artifactId}</finalName>

<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<version>4.0.0</version>
<executions>
<execution>
<goals>
<goal>repackage</goal>
</goals>
<configuration>
<overwrite>true</overwrite>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>

</project>

五、构建测试与部署验证

（一）手动触发构建

  1. 进入 Jenkins 项目页面，点击「立即构建」。
  2. 查看构建日志：点击「构建历史」中的最新构建记录 →「控制台输出」，查看构建过程是否有错误。
  3. 构建成功条件：
  4. 日志显示「SUCCESS」（Maven 编译成功）。
  5. 执行 docker ps 能看到 my-springboot-app 容器运行。

（二）访问部署的项目

浏览器访问：http://localhost:8888（映射的主机端口），若能正常显示项目页面，说明部署成功。
说明：新容器端口：8088，映射的主机端口：8888，jenkins端口：8080

六、关键注意事项补充

（一）路径相关问题

  1. Windows 目录挂载格式：Docker Compose 中 Windows 路径使用 / 分隔（如 D:/docker/jenkins/data），避免使用 \（转义字符问题）。
  2. Jenkins 工作空间路径：容器内路径为 /var/jenkins_home/workspace/[项目名]，与本地 D:/docker/jenkins/workspace 同步。

（二）权限问题

  1. 容器内操作 Docker 时，若出现权限不足，可临时执行 chmod 666 /var/run/docker.sock，但容器重启后需重新执行（生产环境建议配置 Docker 组权限）。
  2. Windows 本地目录权限：确保 D:\docker\jenkins 目录有「完全控制」权限（右键目录 → 属性 → 安全 → 编辑 → 赋予 Everyone 完全控制）。

（三）版本兼容性

  1. JDK版本选择：项目及Jenkins环境优先推荐使用OpenJDK 21，其具备更优的性能与长期支持特性，适配主流框架（如Spring Boot 3.x+）。需确保项目pom.xml中配置的JDK版本（如<maven.compiler.source>21</maven.compiler.source>）与Jenkins中配置的JDK版本一致，避免编译冲突。
  2. JDK在线下载问题处理：Jenkins在线安装JDK时，可能因网络波动、镜像源失效等问题导致下载错误或中断。建议提前下载对应版本JDK压缩包（OpenJDK 21下载地址：清华镜像站，选择OpenJDK21U-jdk_x64_linux_hotspot_21.0.5_11.tar.gz），并按以下步骤配置：
  3. 将下载的JDK压缩包上传至Jenkins数据目录：D:\docker\jenkins\data\tools\hudson.model.JDK\jdk21（手动创建jdk21目录）；
  4. 进入Jenkins容器终端，执行解压命令：tar -zxvf /var/jenkins_home/tools/hudson.model.JDK/jdk21/OpenJDK21U-jdk_x64_linux_hotspot_21.0.5_11.tar.gz -C /var/jenkins_home/tools/hudson.model.JDK/jdk21/；
  5. 在Jenkins“全局工具配置”的JDK设置中，取消“自动安装”，填写JDK名称为jdk21，JAVA_HOME设为/var/jenkins_home/tools/hudson.model.JDK/jdk21/jdk21.0.5+11（解压后的实际目录名，需根据压缩包版本调整）。
  6. Docker 客户端版本：需与 Docker Desktop 版本兼容（本文使用 29.1.2，若 Docker Desktop 版本较低，需降低客户端版本）。
  7. Maven 与 JDK 兼容性：Maven 3.9+ 建议搭配 JDK 11+，若使用 OpenJDK 21，推荐 Maven 3.9.5 及以上版本，避免版本不兼容导致编译失败。

（四）构建优化

  1. 依赖缓存：Maven 依赖会缓存到 D:/docker/jenkins/data/.m2 目录，首次构建后后续构建会加快。
  2. 镜像缓存：Docker 构建时会利用缓存，若修改 Dockerfile 后需重新构建，可添加 --no-cache 参数（如 docker build --no-cache -t springboot-hello:latest .）。

（五）故障排查

  1. Jenkins 启动失败：查看容器日志 docker logs jenkins-docker，常见原因：端口占用（8080/50000 端口被其他程序占用，需修改 docker-compose.yml 中的端口映射）。
  2. 构建时拉取 Gitee 代码失败：检查凭据是否正确、网络是否能访问 Gitee、项目地址是否有误。
  3. Docker 构建镜像失败：查看控制台输出中的 Docker 构建日志，常见原因：Dockerfile 路径错误、Jar 包名称不匹配、端口被占用。

（六）安全建议

  1. 避免使用 root 用户运行 Jenkins 容器，生产环境可自定义 Jenkins 用户 UID/GID，与宿主机一致。
  2. Gitee 凭据优先使用私人令牌，且仅授予必要权限（如 repo），避免泄露密码。
  3. 定期更新 Jenkins 镜像、插件及 Docker 客户端版本，修复安全漏洞。
posted @ 2025-12-15 14:34  大象老师  阅读(5)  评论(0)    收藏  举报