【CI/CD·Jenkins篇】环境搭建：从零部署 Jenkins 主从架构

前言

本篇带你从零搭建一个生产可用的 Jenkins 主从架构。不是"装上就跑"的玩具版本，而是包含安全加固、多节点配置、Docker 集成的完整方案。跟着做下来，你就有了一个能支撑团队日常 CI/CD 的平台。

一、架构规划

目标架构

复制代码

┌─────────────────────────────────────┐
│         Jenkins Master              │
│  - Web UI (管理界面)                │
│  - Job Scheduling (任务调度)        │
│  - Plugin Management (插件管理)     │
│  - Credential Store (凭据管理)      │
└──────────────┬──────────────────────┘
               │ JNLP/SSH 协议
    ┌──────────┼──────────────────┐
    ▼          ▼                  ▼
┌────────┐ ┌────────┐       ┌────────┐
│ Agent 1│ │ Agent 2│       │ Agent 3│
│ Java   │ │ Docker │       │ K8s    │
│ 构建节点│ │ 镜像构建│       │ 部署节点│
└────────┘ └────────┘       └────────┘

环境规划

| 角色 | 配置 | OS | 用途 |

|------|------|-----|------|

二、Master 节点部署

方式一：Docker 部署（推荐生产环境）

复制代码

# 创建数据目录
mkdir -p /data/jenkins_home
chown -R 1000:1000 /data/jenkins_home

# 启动 Jenkins Master
docker run -d \
  --name jenkins-master \
  --restart unless-stopped \
  -p 8080:8080 \
  -p 50000:50000 \
  -v /data/jenkins_home:/var/jenkins_home \
  -v /etc/localtime:/etc/localtime:ro \
  --memory=4g \
  --cpus=4 \
  jenkins/jenkins:lts-jdk17

# 获取初始密码
docker exec jenkins-master cat /var/jenkins_home/secrets/initialAdminPassword

方式二：直接安装（适合没有 Docker 的环境）

复制代码

# 安装 JDK 17
apt update && apt install -y openjdk-17-jdk

# 添加 Jenkins 源
curl -fsSL https://pkg.jenkins.io/debian-stable/jenkins.io-2023.key | \
  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/" | \
  tee /etc/apt/sources.list.d/jenkins.list > /dev/null

# 安装
apt update
apt install -y jenkins

# 启动
systemctl enable jenkins
systemctl start jenkins

# 查看初始密码
cat /var/lib/jenkins/secrets/initialAdminPassword

初始化配置

浏览器访问 http://your-server-ip:8080
输入初始密码
选择"安装推荐插件"（Install suggested plugins）
创建管理员账号

**踩坑提示**：不要用 root 用户直接运行 Jenkins 二进制版。Jenkins 安装时会自动创建 jenkins 用户，用 systemd 管理生命周期。如果用 Docker 部署，数据目录 owner 必须是 UID 1000。

三、安全加固

1. 禁用注册

Manage Jenkins → Security → Security Realms → 选择 "Jenkins' own user database" → 取消勾选 "Allow users to sign up"。

2. 配置授权策略

Manage Jenkins → Security → Authorization → 选择 "Matrix-based security"：

复制代码

用户/组              Overall        Job
admin             ✓ 全部          ✓ 全部
developers         Read           Build, Read, Cancel
deploy-bot         Read           Build, Read, Cancel, Release

3. 配置 CSRF 防护

复制代码

// 在 Manage Jenkins → Script Console 中执行
hudson.security.csrf.DefaultCrumbIssuer.DISABLE_CSRF_PROTECTION = false

4. 系统配置文件加固

复制代码

# /data/jenkins_home/config.xml 关键配置
<useSecurity>true</useSecurity>
<csrfCrumbIssuer>
  <spec/>
</csrfCrumbIssuer>
<disableRememberMe>true</disableRememberMe>

5. 限制构建权限

在 Job 配置中勾选 "Enable project-based security"，限制只有特定用户/组能触发构建。

四、Agent 节点配置

方式一：SSH 方式连接 Agent（推荐）

Master 端配置：

复制代码

# 在 Master 上生成 SSH 密钥（用 jenkins 用户）
docker exec -u jenkins jenkins-master ssh-keygen -t rsa -b 4096 -f ~/.ssh/jenkins_agent_key -N ""

# 查看公钥
docker exec -u jenkins jenkins-master cat ~/.ssh/jenkins_agent_key.pub

Agent 端配置：

复制代码

# 在 Agent 服务器上
# 创建 jenkins 用户
useradd -m -s /bin/bash jenkins

# 配置 SSH 公钥
mkdir -p /home/jenkins/.ssh
echo "刚才复制的公钥内容" >> /home/jenkins/.ssh/authorized_keys
chmod 700 /home/jenkins/.ssh
chmod 600 /home/jenkins/.ssh/authorized_keys
chown -R jenkins:jenkins /home/jenkins/.ssh

# 安装 JDK（Agent 最低要求）
apt update && apt install -y openjdk-17-jdk

# 安装 Docker（如果是 Docker 构建节点）
curl -fsSL https://get.docker.com | sh
usermod -aG docker jenkins

# 安装 Git
apt install -y git

# 创建工作目录
mkdir -p /home/jenkins/workspace
chown -R jenkins:jenkins /home/jenkins/workspace

在 Jenkins Web UI 中添加 Agent：

Manage Jenkins → Nodes → New Node：

复制代码

Node name: agent-docker
Type: Permanent Agent

配置参数：

| 参数 | 值 | 说明 |

|------|-----|------|

| # of executors | 2 | 并发构建数 |

| Remote root directory | /home/jenkins | Agent 工作目录 |

| Labels | docker build | 标签，Pipeline 中用 |

| Usage | Use this node as much as possible | 尽量使用此节点 |

| Launch method | Launch agents via SSH | SSH 连接 |

| Host | 192.168.1.101 | Agent IP |

| Credentials | jenkins-ssh-key | SSH 密钥凭据 |

| Host Key Verification | Non verifying Verification | 测试环境可关闭 |

方式二：JNLP 方式（Agent 在防火墙后）

复制代码

# 在 Agent 上执行
# 从 Jenkins UI 获取 agent.jar 和 secret
wget http://jenkins-master:8080/jnlpJars/agent.jar

java -jar agent.jar -jnlpUrl http://jenkins-master:8080/computer/agent-1/slave-agent.jnlp \
  -secret YOUR_SECRET -workDir /home/jenkins/workspace

配置为系统服务

复制代码

# /etc/systemd/system/jenkins-agent.service
[Unit]
Description=Jenkins Agent
After=network.target

[Service]
Type=simple
User=jenkins
ExecStart=/usr/bin/java -jar /home/jenkins/agent.jar -jnlpUrl http://jenkins-master:8080/computer/agent-1/slave-agent.jnlp -secret YOUR_SECRET -workDir /home/jenkins/workspace
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

# 启动
systemctl daemon-reload
systemctl enable jenkins-agent
systemctl start jenkins-agent

五、验证主从连通性

创建一个测试 Pipeline：

复制代码

// Jenkinsfile - 测试主从架构
pipeline {
    agent {
        label 'docker-build'  // 使用 docker 构建节点的标签
    }
    
    stages {
        stage('环境检查') {
            steps {
                sh 'java -version'
                sh 'docker --version'
                sh 'git --version'
                sh 'hostname'
                echo "当前节点: ${env.NODE_NAME}"
                echo "工作目录: ${env.WORKSPACE}"
            }
        }
        
        stage('测试构建') {
            steps {
                // 简单的测试项目
                sh '''
                    echo "public class Hello { public static void main(String[] a) { System.out.println(\"Hello from Jenkins Agent\"); } }" > Hello.java
                    javac Hello.java
                    java Hello
                '''
            }
        }
        
        stage('测试 Docker') {
            steps {
                sh 'docker run --rm alpine echo "Docker works on agent"'
            }
        }
    }
}

**踩坑提示**：如果 Agent 连接失败，检查以下几项：

Master 到 Agent 的 SSH 端口是否可达（`telnet agent-ip 22`）

Agent 上的 `authorized_keys` 权限是否正确（700/600）

Master 的 Jenkins 用户是否被 Agent 的 `sshd_config` 允许登录（检查 AllowUsers）

Agent 的 Java 版本是否与 Master 兼容

六、本篇要点回顾

Jenkins 主从架构：Master 负责管理调度，Agent 负责执行构建
推荐用 Docker 部署 Master，Agent 用 SSH 方式连接最可靠
安全加固四件套：禁注册、配授权策略、开 CSRF、限制 Job 权限
Agent 通过 Label 标签区分用途，Pipeline 中用 agent { label 'xxx' } 指定
部署后用测试 Pipeline 验证 Java/Docker/Git 环境完整性

下一篇预告：《Pipeline 基础：Declarative 与 Scripted 语法详解》------环境搭好了，接下来学习 Jenkins 最核心的流水线编写技能。