在 Debian 上实现 Jenkins 分布式构建
一 架构与准备
- 架构要点：由 Jenkins Master 负责调度与界面展示，实际构建在多个 Agent/节点 上执行；通过给节点设置 标签（Label） 并按标签分配任务，实现按操作系统、工具链或业务线的调度与隔离。每个节点可配置多个 执行器（Executor） 控制并发。为提升吞吐，可横向扩展多个 Agent 并配合外部 负载均衡（如 Nginx/HAProxy）或 Kubernetes 动态扩缩容。
- 环境建议：所有节点安装 Java 11 或 17（Debian 推荐 OpenJDK），确保网络互通（Master 与 Agent 之间开放必要端口，如 8080 控制台与 JNLP 端口），并为构建工具（如 JDK、Maven、Git、Docker）在各节点预装或配置好路径。
二 安装与初始化 Master
- 安装 Java 与 Jenkins（Debian 稳定源）：
- 安装 Java（示例为 OpenJDK 11）：
- sudo apt update && sudo apt install -y openjdk-11-jdk
- java -version
- 添加 Jenkins 仓库与密钥并安装：
- curl -fsSL https://pkg.jenkins.io/debian-stable/jenkins.io.key | sudo tee /usr/share/keyrings/jenkins-keyring.asc > /dev/null
- echo deb [signed-by=/usr/share/keyrings/jenkins-keyring.asc] https://pkg.jenkins.io/debian-stable binary/ | sudo tee /etc/apt/sources.list.d/jenkins.list > /dev/null
- sudo apt-get update && sudo apt-get install -y jenkins
- sudo systemctl start jenkins && sudo systemctl enable jenkins
- 初始化控制台：访问 http://<master_ip>:8080，解锁管理员密码：
- sudo cat /var/lib/jenkins/secrets/initialAdminPassword
- 基础配置：进入 Manage Jenkins → Configure System 设置 Jenkins URL；在 Global Tool Configuration 配置 JDK、Git、Maven、Docker 等工具路径，便于各节点统一调用。
三 添加与管理 Agent 节点
- 方式一 SSH 启动（Master 主动连接 Agent，Linux 常用）
- 在 Agent 节点准备运行环境：安装 JDK，建议创建 jenkins 用户与 SSH 密钥对，将 Master 的公钥加入 /home/jenkins/.ssh/authorized_keys，并确保 Master 可免密 SSH 登录该用户。
- 在 Master 上添加凭据：进入 Manage Jenkins → Credentials → Global credentials → Add SSH Key，录入私钥（用户名如 jenkins）。
- 新增节点：进入 Manage Jenkins → Manage Nodes → New Node，类型选 Permanent Agent，填写：
- Name、Labels（如：linux-node、jdk11、maven）、Remote root directory（如：/home/jenkins）、Number of executors（建议与 CPU 核数相当）、Usage（默认“尽可能使用”或“仅匹配标签的任务”）。
- Launch method 选 Launch agents via SSH，指定 Host、Credentials 与 JavaPath（如 /usr/bin/java），保存后自动连接。
- 方式二 JNLP 启动（Agent 主动连接 Master，跨平台）
- 在 Master 开启 JNLP：进入 Manage Jenkins → Security → 代理配置（TCP port for JNLP），选择固定端口或随机端口。
- 新增节点（同上），Launch method 选 Launch agent by connecting it to the controller，保存后页面会给出启动命令与 Secret。
- 在 Agent 节点下载 agent.jar（如 http://:8080/jenkins/jnlpJars/agent.jar），执行：
- java -jar agent.jar -url http://:8080/jenkins/ -secret -name -workDir “<remote_root>”
- 连接成功后，节点状态显示为 已连接，即可接收任务。
四 运行与调度示例
- 按标签调度任务（Freestyle）
- 在任务配置的 Restrict where this project can be run 填入节点标签（如：linux-node），使该任务只在匹配标签的 Agent 上执行。
- 按标签调度任务（Pipeline）
- 在仓库根目录创建 Jenkinsfile：
- pipeline {
agent { label ‘linux-node’ }
stages {
stage(‘Checkout’) { steps { git ‘https://github.com/your/repo.git’ } }
stage(‘Build’) { steps { sh ‘mvn clean package’ } }
stage(‘Test’) { steps { sh ‘mvn test’ } }
}
}
- 在 Manage Jenkins → Manage Nodes 为不同 Agent 设置差异化 Labels（如：jdk11、jdk17、nodejs16、docker），并在 Pipeline 或任务中通过 label 精确选择执行环境，实现多环境并行与隔离。
五 优化与常见问题
- 并发与隔离
- 合理设置每个节点的 Executors（通常接近 CPU 核数），避免资源争用；通过 Labels 将 JDK 版本、工具链、操作系统 不同的任务隔离到对应节点，减少冲突与漂移。
- 高可用与扩展
- 横向扩展多个 Agent 提升吞吐；对控制台与构建流量可前置 Nginx/HAProxy 做负载均衡；在更复杂的场景可引入 Kubernetes 动态创建/销毁 Agent Pod，实现弹性伸缩与资源优化。
- 常见故障排查
- JNLP 方式无法连接：检查 JNLP 端口 是否开放、Master URL 是否可达、时间与证书是否一致；必要时在 Master 的 代理配置 中开启或固定端口。
- SSH 方式连接失败：确认 jenkins 用户 权限、authorized_keys 内容正确、Master 能免密登录；在节点详情页查看 Log 定位问题。
- 构建找不到工具：在 Global Tool Configuration 配置工具路径，或在节点 Tool Locations 覆盖 JDK/Maven/Git/Docker 的实际路径，确保各节点一致可用。
