18.1.1 Jenkins组件与工作原理

Jenkins 采用主从架构（Controller/Agent）与插件化体系，核心职责是接收任务、调度执行与汇总结果。理解组件与工作原理可帮助合理规划资源、隔离构建环境并提升稳定性。

原理草图（架构与执行流）#

核心组件与作用#

Controller（主控）：Web UI、任务调度、权限、插件管理与配置存储。
Agent（执行节点）：执行构建任务的机器/容器，通过标签（Label）匹配任务。
Executor（执行器）：每个节点的并发槽位，决定可同时运行的构建数量。
Job/Project：任务定义（Freestyle、Pipeline 等）。
Pipeline：Jenkinsfile 定义的流水线，支持阶段化与并行。
Queue（队列）：待执行任务缓冲区。
Plugin（插件）：提供 SCM、构建、通知、制品等扩展能力。

关键配置与存储#

JENKINS_HOME：作业、插件、构建记录、用户与凭据的核心目录。
Global Configuration：全局工具链与系统参数。
Credentials：集中管理 Git/镜像仓库/云服务凭据。

运行与执行流程（带示例）#

触发：Webhook/定时/手动/上游任务
排队：进入 Queue 等待匹配
分配节点：按 Label 与可用 Executor
拉取代码：SCM 插件
执行构建：Pipeline stage
结果归档：日志/制品
通知回调：邮件/IM/Webhook

示例：最小流水线（Jenkinsfile）

pipeline {
  agent { label 'linux' }
  stages {
    stage('Checkout') {
      steps { git url: 'https://github.com/example/repo.git', branch: 'main' }
    }
    stage('Build') {
      steps { sh 'make all' }
    }
    stage('Test') {
      steps { sh 'make test' }
    }
    stage('Archive') {
      steps { archiveArtifacts artifacts: 'dist/*.tar.gz', fingerprint: true }
    }
  }
  post {
    success { echo '构建成功' }
    failure { echo '构建失败' }
  }
}

组件工作原理示例（Controller 连接 Agent）#

1）在 Controller 上创建节点配置（示例为 SSH Agent）
- 节点名称：agent-linux-01
- 标签：linux
- 启动方式：SSH
- 远端工作目录：/var/jenkins

2）Agent 端准备用户与目录（示例）

# 创建 jenkins 用户与工作目录
sudo useradd -m -s /bin/bash jenkins
sudo mkdir -p /var/jenkins
sudo chown -R jenkins:jenkins /var/jenkins

3）Controller 端使用私钥连接（示例路径）

私钥文件：/var/lib/jenkins/.ssh/id_rsa
说明：用于 Controller 连接 Agent 的 SSH 凭据

4）验证 Agent 连接与执行器可用

# 在 Controller 节点检查 agent 是否在线（示意）
curl -s http://<jenkins-host>:8080/computer/agent-linux-01/api/json | jq '.offline'
# 预期输出：false

关键命令与目录说明#

# 查看 Jenkins 服务状态（systemd 环境）
systemctl status jenkins

# 常见目录（以 Debian/Ubuntu 包为例）
/var/lib/jenkins   # JENKINS_HOME
/var/log/jenkins   # 日志目录
/etc/default/jenkins  # 启动参数（端口、JENKINS_HOME）

常见问题排错（含命令）#

1）任务一直排队（No available executor）
- 原因：无可用执行器/节点离线/标签不匹配
- 处理：检查节点状态与标签

# 查看所有节点在线状态
curl -s http://<jenkins-host>:8080/computer/api/json | jq '.computer[] | {name,offline,temporarilyOffline}'

2）Agent 无法连接（SSH 失败）
- 原因：密钥权限/网络/用户无权限
- 处理：检查 SSH 与权限

# 在 Controller 上测试 SSH
ssh -i /var/lib/jenkins/.ssh/id_rsa jenkins@<agent-ip> 'hostname'
# 预期输出：agent-linux-01

3）插件冲突导致启动失败
- 原因：插件版本不兼容
- 处理：查看日志与禁用插件

# 查看日志定位报错插件
tail -n 200 /var/log/jenkins/jenkins.log

# 禁用插件（将 .jpi 改名为 .jpi.disabled）
cd /var/lib/jenkins/plugins
mv some-plugin.jpi some-plugin.jpi.disabled
systemctl restart jenkins

练习#

画出你当前团队的 Jenkins 架构（Controller + 至少2个 Agent），标注标签与执行器数量。
编写一个包含 3 个 stage 的 Jenkinsfile（含测试与制品归档）。
人为设置错误标签触发任务排队，使用命令定位并修复。