跳到主要内容

搭建 Jenkins

· 阅读需 14 分钟
XingHunm
XingHunm
Tech Enthusiast

本文详细介绍了如何从零搭建 Jenkins 环境，集成 Gitee、Node.js、Maven、Docker 等工具，实现自动化构建与部署（CI/CD）流程。

1. 搭建 Jenkins​

  • 拉取 jenkins 镜像

    执行以下命令拉取镜像(以 2.433-jdk17 版本为例):

    docker pull jenkins/jenkins:2.433-jdk17

    需要注意的是 jenkins 最新镜像是 jenkins/jenkins，而不是 jenkins:

  • 运行 jenkins 镜像

    执行以下命令拉取镜像(以 2.433-jdk17 版本为例):

    //var/jenkins/jenkins-data为本机某个目录
    //外网访问端口设置为18080
    docker run \
    -d \
    --name jenkins \
    --rm \
    -u root \
    -p 18080:8080 \
    -v /var/jenkins/jenkins-data:/var/jenkins_home \
    jenkins/jenkins:2.433-jdk17

    或者通过 docker-compose 启动，以下是 docker-compose.yml 文件:

    #docker-compose.yml
    version: "3"
    services:
      jenkins:
        image: jenkins/jenkins:2.433-jdk17
        container_name: jenkins
        user: root
        ports:
          - "18080:8080"
        environment:
          - TZ=Asia/Shanghai
        volumes:
          - /var/jenkins/jenkins-data:/var/jenkins_home

    执行docker-compose up -d命令启动。

  • 浏览器访问 18080 端口

    加载可能需要一些时间，完成后会出现下图的界面:

    执行以下命令获取管理员密码:

    docker exec jenkins bash -c "cat /var/jenkins_home/secrets/initialAdminPassword"
    =>d1bc30kecf304f1489423a2c74b2b59e

    填入管理员密码后继续，等待片刻后，安装推荐的插件。

  • 安装推荐的插件

    部分插件可能安装失败，安装失败后可尝试重试安装。安装完成后会进入到管理员账户的创建页面。

  • 创建管理员账户

    创建用户后会进入到示例配置页面。

  • 示例配置

    点击保存后，就能进入 jenkins 操作界面了:

    但是最好重启下容器(有些插件重启才会生效)，执行以下命令:

    docker restart jenkins

2. 配置 Node 环境​

  • 安装 Node 插件

    重启容器后访问 18080 端口，登录后就能进入 jenkins 主页了。进入主页后选择系统管理=>插件管理:

    在 Avaliable plugins 中搜索 nodejs，点击安装: 安装完成后重启容器。

  • 配置 Node

    重启完成后，在 jenkins 主页选择系统管理=>全局工具配置: node 版本选择的与开发环境一致，需预装 yarn(前端项目用 yarn 做包管理工具) 包管理工具。

    安装 yarn 的 npm 镜像源可以配置成淘宝:

    --registry=https://registry.npm.taobao.org yarn

3. 配置 Gitee​

  • 配置 Gitee 登录凭证

    在 jenkins docker 运行所在的服务器上生成 ssh key(如果有则不需要重新生成)，执行命令:

    ssh-keygen -t rsa

    将公钥 id_rsa.pub 的内容拷贝到 Gitee 设置页面 SSH 公钥配置当中:

  • 在 jenkins 中添加凭证

    在 jenkins 主页选择系统管理=>凭据=>系统(system)=>全局凭据: 下图中，用户名为 docker 运行的用户，Private Key 为上一步生成的 id_rsa 的内容。 点击 Create 创建生成凭证。

4. 创建流水线​

在创建流水线前先安装 Git Parameter 插件(为了支持配置 Git 参数)，在 jenkins 主页选择系统管理=>插件管理，在 Avaliable plugins 中搜索 Git Parameter plugin，点击安装，安装完成后重启容器。完成后进行以下操作:

  • 创建文件夹

    为了方便管理，先创建一个文件夹(在 jenkins 主页选择新建任务)，名为 multi-body:

  • 添加自由风格项目

    在上一步中创建的 multi-body 文件中选择新建 Item，创建一个自由风格的软件项目名为 micro-simulation:

  • 添加编译配置

    在上一步创建的 micro-simulation 项目中选择配置:

    • 配置参数

      为了构建时可以手动选择不同的分支进行编译，在参数化构建过程中选择添加 Git 参数:

    • 配置源码管理

      URL 填写 Gitee 上项目的 ssh 地址，Credentials 选前述生成的凭证(gitee-ssh)，分支填写上一步配置的名字(BRANCH_NAME):

    • 配置 Node 环境

    • 配置 build 命令

      yarn  //安装node_modules
      yarn build //执行build命令，build完后会在项目根目录生成rand-batch文件夹
      tar -czf rand-batch.tar.gz rand-batch

    • 归档上一步生成的 tar 文件

      下图中用于存档的文件目录是相对于项目根目录，归档后就能生成该 tar 文件的下载链接。

  • 开始构建

    上一步配置完成后，就可以开始根据配置文件构建项目了:

  • 查看构建结果

    构建完成后就能看到最后生成的 tar 文件了，点击可以下载。

    此外，对于构建的相关信息都可以点击构建序列号进行查看:

通过以上步骤，就能通过 jenkens 构建在 gitee 上的前端项目了。

5. 部署​

  • 安装 Publish Over SSH 插件

    jenkins 主页选择系统管理=>插件管理，在 Avaliable plugins 中搜索 Publish Over SSH，点击安装: 安装完成后重启容器。

  • 配置 SSH 免密登录

    首先在 Jenkins 服务器上生成 SSH 密钥对:

    ssh-keygen -t rsa

    然后将 Jenkins 服务器的公钥添加到目标服务器的 authorized_keys 中，实现免密登录。

    在目标服务器上执行命令(将 Jenkins 服务器的公钥内容追加到 authorized_keys):

    # 将Jenkins服务器的公钥内容追加到authorized_keys
    echo "Jenkins服务器的公钥内容" >> ~/.ssh/authorized_keys
    # 或者直接编辑authorized_keys文件
    vi ~/.ssh/authorized_keys

    确保 authorized_keys 文件权限正确:

    chmod 600 ~/.ssh/authorized_keys
    chmod 700 ~/.ssh

  • 配置 Publish Over SSH 插件

    重启完成后在系统管理=>系统配置会多出一个 Publish over SSH:

    下图中，Key 填入上一步生成的私钥 id_rsa 的内容，Name 随意起一个目标服务器的名称，Hostname 为目标服务器 IP，Username 为链接目标服务的用户名, 可以点击右下角的 Test Configution 进行连通性测试。

  • 添加构建后操作步骤 Send build artifacts over SSH

    进入项目配置页面，添加构建后操作步骤 Send build artifacts over SSH: Name 选择上一步配置好 ssh server，Source files 文件是相对于工作区，Remote directory 目录是相对于用户 ssh 登录默认目录，比如用户是 abc，ssh 默认登录目录可能是/home/abc，则最后上传的目录是/home/abc/www/packages，Exec command 就是登录到目标服务器后要执行的脚本，这里主要是将 tar 文件解压到目标目录。

自此就能够一键构建并部署项目了。

6. 通过 docker 进行编译​

有时候我们编译一个项目，需要安装很多依赖，比如编译 c++项目，可能需要安装 g++、cmake 等环境，而其他项目又可能需要其他环境，这时候配置 Jenkins 编译的同学就需要知道各个项目的上下文，编译方式等，这样就太过麻烦。假如各个项目的同学直接提供一个编译自己项目的 docker 镜像，那么配置 Jenkins 的同学只需要提供一个简单的配置模板就可以了。

假设编译项目的镜像已预先生成好并推送到镜像仓库 harbor(这里是私有部署的镜像仓库 192.168.30.32:18082)，镜像名为192.168.30.32:18082/library/semd-builder:0.0.1，接下来我们首先需要在 jenkins 里能执行 docker 命令:

  • 支持执行脚本时能够访问 docker 命令

    在执行脚本时能够访问 docker 命令，即在 docker 容器内部执行 docker 命令，可以在 jenkins 容器内安装 Docker 客户端

    apt-get update && apt-get install -y docker.io

    但是在容器删除后，基于 Jenkins 基础镜像重启 docker.io 会丢失，因此为了持久化，我们基于 jenkins 镜像生成一个安装了 docker.io 的镜像，Dockerfile 如下:

    # jenkins-docker-file
    FROM  jenkins/jenkins

    USER root

    RUN apt-get update && \
    apt-get install -y docker.io

    USER jenkins

    执行生成镜像命令, 生成名为 192.168.30.32:18082/library/xhm-jenkins:0.0.1 的镜像:

    docker image build --platform linux/amd64 -t 192.168.30.32:18082/library/xhm-jenkins:0.0.1 -f jenkins-docker-file .

    镜像生成后推送到本地镜像仓库，这样就可以使用基于官方镜像且安装好 docker.io 的镜像了。为了能在 Jenkins docker 内部使用 docker 命令，还需要在启动容器时映射 docker.sock:

    //docker-compose.yml
    version: '3'
    services:
    jenkins:
      image: 192.168.30.32:18082/library/xhm-jenkins:0.0.1
      container_name: jenkins
      user: root
      ports:
        - "18080:8080"
      volumes:
        - /var/run/docker.sock:/var/run/docker.sock
        - /var/jenkins/jenkins-data:/var/jenkins_home

    重启容器。

  • 配置 build 命令

    在 Build Steps 中添加执行 shell，运行 docker 就可以了。 下图中/var/jenkins/jenkins-data是我们运行 jenkins 时映射的/var/jenkins_home路径，$JOB_NAME在这里是multi-body/semd-build。 当运行 semd-build 镜像会执行内部的一个 build 脚本(生成镜像时已配置)。

7. 支持编译 Electron Windows 版本软件​

通过 electronuserland/builder:wine 这个镜像就能够在 linux 编译 windows 版本软件，为了方便使用将其生成本地镜像并推送到私有部署镜像仓库中，Dockerfile 如下:

# wine-docker-file
FROM electronuserland/builder:wine

WORKDIR /app

该镜像命名为 192.168.30.32:18082/library/xhm-wine:0.0.1，镜像生成好后就可以配置 Jenkins 的 build 脚本了:

#安装依赖，有可能有新的依赖
yarn

#将我们的项目目录映射到xhm-wine docker的/app目录，$JOB_NAME在这里是multi-body/rbmd-client-build
docker run -v /home/xhm/services/jenkins/jenkins-data/workspace/$JOB_NAME:/app   \

#映射electron cache目录，防止每次编译都下载
-v ~/.cache/electron:/root/.cache/electron \

#映射electron-builder cache目录，防止每次编译都下载
-v  ~/.cache/electron-builder:/root/.cache/electron-builder \

#用上述生成的xhm-wine:0.0.1镜像编译，yarn build:win是项目打包windows版本软件命令
192.168.30.32:18082/library/xhm-wine:0.0.1 yarn build:win

#编译完成后会在dist/win-unpacked目录下生成windows版本的软件
tar -czf rbmd-client.tar.gz -C dist win-unpacked

8. 支持编译 Java 项目​

  • 安装 Maven Integration plugin 插件

    jenkins 主页选择系统管理=>插件管理，在 Avaliable plugins 中搜索 Maven Integration plugin，点击安装，安装完成后重启容器。

  • 配置 Maven

    重启完成后，在 jenkins 主页选择系统管理=>全局工具配置=>新增 Maven=>自动安装:

  • 创建 Maven 项目

    jenkins 主页选择新建任务=>构建一个 maven 项目:

  • 配置源码管理

    同上，只需要换成 Java 项目地址。

  • 配置 build 命令

    • Root POM

      pom.xml 文件相对于 workspace 的路径

    • Goals and options

      添加 Maven 命令比如: package、clean 等。

  • 归档上一步生成的 jar 文件

    同上，只需要修改生成的 jar 文件的地址。

这样就可以 build 一个 Java 项目了。

9. 配置自动构建 (通用 WebHook + Nginx)​

通过 "触发远程构建" 以及 Nginx 转发来实现自动构建。这种方式不需要依赖特定的 Gitee 插件，且可以通过 Nginx 增加一层安全校验。

  • 配置 Jenkins 任务

    进入 Jenkins 任务配置页面，找到 构建触发器 (Build Triggers) 区域。

    1. 勾选 触发远程构建 (例如,使用脚本) (Trigger builds remotely)。
    2. 在 身份验证令牌 (Authentication Token) 中填写一个复杂的 Token（例如 Jk5s5T2r6Xp3M7n1V6b3H0fL1zW8）。

    此时，可以通过访问 JENKINS_URL/job/YOUR_JOB_NAME/build?token=TOKEN_NAME 来触发构建。

  • 配置 Nginx 转发与鉴权

    为了安全起见（避免直接暴露 Jenkins 端口或 Token），以及适配某些 Git 平台（如 Gitee）的 WebHook 请求格式，我们通过 Nginx 进行转发和简单的鉴权。

    在 Nginx 配置文件中添加以下 location：

    location /trigger-build {
        # 简单的鉴权：检查 URL 参数 secret 是否匹配
        if ($arg_secret != "rB9x217mP6vL2nQ3wE6jZ9yA1dC0") {
            return 401;
        }

        # 清空参数，避免将 secret 透传给 Jenkins (可选)
        set $args "";

        # 强制使用 GET 方法，绕过 Jenkins 对 POST 请求的 CSRF 检查
        proxy_method GET;
        proxy_set_header Content-Length "";
        proxy_set_header Content-Type "";

        # 转发到 Jenkins 内部地址
        # 注意：替换下面的 URL 为你实际的 Jenkins 构建地址, token 为上一步配置的 Token
        proxy_pass http://127.0.0.1:18024/view/all/job/unitarylab/job/unitarylab-developers-guide-deploy/build?token=Jk1s8T3r6Xp4M7n1V6b3H0fL1zW9;

        # 隐藏 Jenkins 的响应头，避免暴露内网信息
        proxy_hide_header X-Jenkins;
        proxy_hide_header X-Hudson;
    }

  • 配置 Gitee WebHook

    登录 Gitee，进入对应的代码仓库，选择 仓库设置 => WebHooks => 新建 WebHook。

    1. URL: 填入 Nginx 暴露的地址，并带上 secret 参数（上一步 Nginx 配置的）。 例如: http://YOUR_NGINX_DOMAIN/trigger-build?secret=rB9x217mP6vL2nQ3wE6jZ9yA1dC0
    2. WebHook 密码/签名密钥: 不需要填写（鉴权已在 Nginx 地址参数中处理）。
    3. 事件: 勾选 推送代码。

点击新建进行创建，创建完成后可以点击 测试 ，观察 Jenkins 是否触发构建。