Jenkins 全局配置及工具验证教程

Jenkins 全局配置及工具验证教程

一、前提准备

1. Jenkins 已安装并启动 ：确保 Jenkins 服务正常运行（访问 http://<Jenkins服务器IP>:8080 可打开控制台）。

2. 管理员权限：使用管理员账号登录 Jenkins（后续配置需管理员权限）。

3. 必要插件安装：

   • Role-based Authorization Strategy：用于配置"基于角色的授权策略"（安全配置必需）。
   • NodeJS Plugin：用于配置 NodeJS 工具（自动安装 NodeJS 必需）。
   • Maven Integration plugin：用于 Maven 工具集成（可选，部分 Jenkins 版本默认已包含）。

   插件安装方法 ：

   进入 Jenkins 首页 → Manage Jenkins → Plugins → Available plugins，搜索上述插件并安装，安装后重启 Jenkins。

二、全局安全配置

1. 进入安全配置页面

Jenkins 首页 → Manage Jenkins → Security → Configure Global Security（全局安全配置）。

2. 配置安全域（Security Realm）

• 选择"Jenkins专有用户数据库" ：
  • 勾选 Enable Jenkins' own user database（启用 Jenkins 内置用户数据库）。
  • 取消勾选 Allow users to sign up（禁止用户自助注册，仅管理员手动创建用户）。

3. 配置授权策略（Authorization Strategy）

• 选择"Role-Based Strategy" ：
  • 在 Authorization 下，选择 Role-Based Strategy（基于角色的授权策略）。

4. 保存配置

点击页面底部 Save（保存）按钮，使安全配置生效。

三、全局工具配置

进入工具配置页面：Jenkins 首页 → Manage Jenkins → Global Tool Configuration（全局工具配置）。

1. JDK 配置（手动指定已安装的 JDK）

• 点击"JDK installations" → "Add JDK" ：
  • Name ：填写 JDK17（自定义名称，需与后续流水线脚本中一致）。
  • 取消勾选"Install automatically"（不自动安装，使用服务器已有的 JDK）。
  • JAVA_HOME ：填写 /opt/java/openjdk（服务器上 JDK17 的实际安装路径，需确保该路径存在且权限正确）。
• 点击 Save（临时保存，后续配置完成后统一保存）。

2. Git 配置（指定服务器已安装的 Git）

• 点击"Git installations" → "Add Git" ：
  • Name ：填写 git（自定义名称，需与后续验证步骤中命令对应）。
  • Path to Git executable ：填写 /usr/bin/git（服务器上 Git 可执行文件路径，可通过 which git 命令确认路径）。
• 点击 Save（临时保存）。

3. Maven 配置（自动安装指定版本）

• 点击"Maven installations" → "Add Maven" ：
  • Name ：填写 Maven3.9（自定义名称，需与后续流水线脚本中一致）。
  • 勾选"Install automatically"（自动安装）。
  • 选择"Install from Apache"（从 Apache 官方源下载）。
  • Version ：在下拉列表中选择 3.9.12（确保版本号与用户需求一致）。
• 点击 Save（临时保存）。

4. NodeJS 配置（自动安装并全局安装 pnpm）

• 点击"NodeJS installations" → "Add NodeJS" ：
  • Name ：填写 NodeJS20（自定义名称，需与后续流水线脚本中一致）。
  • 勾选"Install automatically"（自动安装）。
  • Version ：在下拉列表中选择 NodeJS 20.19.6（确保版本号正确）。
  • Global npm packages to install ：填写 npm install -g pnpm@10.18.3（全局安装指定版本的 pnpm）。
• 点击 Save（最终保存所有工具配置）。

四、验证全局工具是否可用（创建流水线任务）

1. 新建流水线任务

• Jenkins 首页 → New Item （新建任务）：
  • Name ：填写 流水线工具测试（自定义任务名称）。
  • 类型 ：选择 Pipeline（流水线）。
  • 点击 OK 进入任务配置页面。

2. 配置流水线脚本

• Pipeline 区域 → Definition ：选择 Pipeline script（直接输入 Groovy 脚本）。

• Script 框中粘贴以下流水线脚本：

  pipeline {
      agent any  // 在任意可用节点执行（若为单机 Jenkins，即本地执行）
      tools {
          jdk 'JDK17'       // 对应全局工具配置中 JDK 的名称（必须完全一致）
          maven 'Maven3.9'  // 对应全局工具配置中 Maven 的名称
          nodejs 'NodeJS20' // 对应全局工具配置中 NodeJS 的名称
      }
      stages {
          stage('验证工具版本') {  // 定义"验证工具版本"阶段
              steps {
                  sh 'java -version'   // 验证 JDK 版本
                  sh 'mvn -v'         // 验证 Maven 版本
                  sh 'node -v'        // 验证 NodeJS 版本
                  sh 'npm -v'         // 验证 npm 版本
                  sh 'pnpm -v'        // 验证 pnpm 版本（全局安装）
                  sh 'git --version'  // 验证 Git 版本
              }
          }
      }
  }

• 勾选"Use Groovy Sandbox"（使用 Groovy 沙盒，允许脚本在安全环境中执行）。

3. 保存并构建任务

• 点击页面底部 Save（保存任务配置）。
• 回到任务页面，点击 Build Now（立即构建），触发流水线执行。

五、查看构建结果与验证

1. 查看构建日志

• 任务页面 → Build History （构建历史）中，点击最新的构建编号（如 #1）→ Console Output（控制台输出），查看工具验证结果。

2. 预期日志输出（工具版本验证成功）

• java -version ：输出 JDK17 版本信息（如 openjdk version "17.0.x"）。
• mvn -v ：输出 Maven 3.9.12 版本信息（如 Apache Maven 3.9.12）。
• node -v ：输出 NodeJS 20.19.6 版本（如 v20.19.6）。
• npm -v ：输出 npm 版本（NodeJS 20.19.6 自带 npm 版本，如 10.8.1）。
• pnpm -v ：输出 pnpm 10.18.3 版本（如 10.18.3）。
• git --version ：输出 Git 版本（如 git version 2.34.1）。

3. 常见问题排查

（1）工具版本验证失败（如 mvn: command not found）

• 原因：Maven 自动安装失败（网络问题或版本不存在）。
• 解决 ：
  1. 进入 Manage Jenkins → Global Tool Configuration → Maven installations，检查 Maven 安装状态（若显示"Installed"则成功，否则失败）。
  2. 若自动安装失败，可手动下载 Maven 3.9.12 到服务器，解压后在全局工具配置中取消"自动安装"，手动填写 MAVEN_HOME 路径（如 /opt/maven/apache-maven-3.9.12）。

（2）pnpm 未找到（pnpm: command not found）

• 原因 ：NodeJS 全局 npm 包安装失败（npm install -g pnpm@10.18.3 执行失败）。
• 解决 ：
  1. 查看 NodeJS 安装日志：进入 Manage Jenkins → Global Tool Configuration → NodeJS installations ，点击 NodeJS20 后的"安装日志"，检查是否有 npm 安装错误。
  2. 手动在 Jenkins 节点执行 npm install -g pnpm@10.18.3，确保 pnpm 安装成功。

（3）Git 路径错误（git: command not found）

• 原因 ：/usr/bin/git 路径不存在（服务器未安装 Git 或路径错误）。
• 解决 ：在 Jenkins 服务器执行 which git 获取实际路径，更新全局工具配置中的"Path to Git executable"。

六、总结

通过以上步骤，完成了 Jenkins 全局安全配置（专有用户数据库+基于角色授权）、全局工具配置（JDK/Git/Maven/NodeJS），并通过流水线任务验证了所有工具的可用性。若所有工具版本均正常输出，则全局工具配置生效，可用于后续项目构建。