运维DevOps

Jenkins CI/CD 安装配置与问题排查完全指南：从部署到自动化构建实战

, , ,

引言

Jenkins 是开源 CI/CD 领域的标杆工具，拥有超过 1800 个插件生态，几乎支持所有语言和平台的自动化构建。无论是前端项目打包、后端服务部署，还是移动应用发布，Jenkins 都能提供完整的流水线支持。本文将详细介绍 Jenkins 在 RedHat/CentOS 环境下的完整安装流程、常见问题排查，以及生产环境的安全配置。

Jenkins 架构概览

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
┌─────────────────────────────────────────────────────────────────────┐
│              Jenkins CI/CD 架构                                      │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│   ┌──────────────┐                                                   │
│   │   开发者     │  git push                                         │
│   └──────┬───────┘                                                   │
│          │                                                           │
│          ▼                                                           │
│   ┌──────────────┐      ┌──────────────┐      ┌──────────────┐     │
│   │   Git 仓库   │─────►│   Jenkins    │─────►│  构建节点    │     │
│   │(GitHub/     │ Webhook│  主服务器    │ 分发 │  (Slave)    │     │
│   │  GitLab)   │       │              │ 任务 │              │     │
│   └──────────────┘      └──────┬───────┘      └──────┬───────┘     │
│                                │                     │              │
│                                ▼                     ▼              │
│                         ┌──────────────┐      ┌──────────────┐     │
│                         │   构建产物   │      │   部署目标   │     │
│                         │  (.apk/.jar) │      │ (服务器/     │     │
│                         │              │      │  Docker)    │     │
│                         └──────────────┘      └──────────────┘     │
│                                                                      │
│  核心组件：                                                          │
│  • Jenkins Master：调度任务、管理配置、展示界面                       │
│  • Jenkins Slave：执行实际构建任务（可横向扩展）                      │
│  • Plugin 生态：Git、Maven、Docker、SSH 等 1800+ 插件                │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

安装 Jenkins

前置条件

组件 版本要求 说明
Java JDK 8 或 11 Jenkins 2.x 需要 Java 8+
内存 最低 2GB 建议 4GB 以上
磁盘 最低 10GB 根据构建产物大小调整

RedHat/CentOS 安装

步骤一：添加 Jenkins 仓库

1
2
3
4
5
6
# 下载 Jenkins 官方仓库配置
sudo wget -O /etc/yum.repos.d/jenkins.repo \
    https://pkg.jenkins.io/redhat-stable/jenkins.repo

# 导入 GPG 密钥
sudo rpm --import https://pkg.jenkins.io/redhat-stable/jenkins.io.key

步骤二：安装 Jenkins

1
2
3
4
5
# 使用 yum 安装
sudo yum install jenkins -y

# 如需指定版本
sudo yum install jenkins-2.401.1-1.1 -y

步骤三：启动并启用服务

1
2
3
4
5
6
7
8
# 启动 Jenkins 服务
sudo systemctl start jenkins

# 设置开机自启
sudo systemctl enable jenkins

# 检查服务状态
sudo systemctl status jenkins

正常状态输出示例：

1
2
Loaded: loaded (/etc/rc.d/init.d/jenkins; generated)
Active: active (running) since Tue 2020-04-19 16:19:01 +03; 4min 57s ago

防火墙配置

Jenkins 默认运行在 8080 端口，需要在防火墙中放行：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
# 定义端口变量
YOURPORT=8080
PERM="--permanent"
SERV="$PERM --service=jenkins"

# 创建防火墙服务配置
sudo firewall-cmd $PERM --new-service=jenkins
sudo firewall-cmd $SERV --set-short="Jenkins ports"
sudo firewall-cmd $SERV --set-description="Jenkins port exceptions"
sudo firewall-cmd $SERV --add-port=$YOURPORT/tcp

# 添加服务到防火墙
sudo firewall-cmd $PERM --add-service=jenkins

# 允许 HTTP 访问
sudo firewall-cmd --zone=public --add-service=http --permanent

# 重载防火墙规则
sudo firewall-cmd --reload

# 验证配置
sudo firewall-cmd --list-services
命令 作用
--new-service 创建自定义服务
--add-port 开放指定端口
--reload 重载规则使其生效
--list-services 查看已启用的服务

初始化配置

获取初始管理员密码

Jenkins 首次启动后会生成一个初始密码，用于解锁系统：

1
2
3
4
# 查看初始密码
sudo cat /var/lib/jenkins/secrets/initialAdminPassword

# 输出示例：a1b2c3d4e5f678901234567890123456

访问 http://<服务器IP>:8080，输入上述密码完成解锁。

插件安装

解锁后进入插件安装页面，建议选择安装推荐插件：

推荐插件 作用
Git Git 仓库集成
GitHub Branch Source GitHub 多分支流水线
Pipeline Jenkins 流水线核心插件
SSH Agent SSH 密钥管理
Credentials Binding 凭据安全注入
Timestamper 构建日志添加时间戳

插件安装失败解决方案

由于网络原因，国内用户经常遇到插件安装失败的问题。解决方案是更换为清华大学镜像源：

1
2
# 编辑更新中心配置文件
sudo vi /var/lib/jenkins/updates/default.json

使用 sed 批量替换：

1
2
3
4
5
6
7
8
9
10
11
# 备份原文件
sudo cp /var/lib/jenkins/updates/default.json \
        /var/lib/jenkins/updates/default.json.bak

# 替换为清华镜像
sudo sed -i 's|https://updates.jenkins.io/download/|https://mirrors.tuna.tsinghua.edu.cn/jenkins/|g' \
    /var/lib/jenkins/updates/default.json

# 同时替换更新中心 URL
sudo sed -i 's|https://updates.jenkins.io/update-center.json|https://mirrors.tuna.tsinghua.edu.cn/jenkins/updates/update-center.json|g' \
    /var/lib/jenkins/updates/default.json

替换完成后，在 Jenkins 界面进入 Manage Jenkins → Manage Plugins → Advanced，点击 Check now 刷新插件列表。

核心配置文件

主配置文件

Jenkins 的主配置文件位于 /etc/sysconfig/jenkins（RedHat/CentOS）：

1
2
# 编辑主配置
sudo vi /etc/sysconfig/jenkins

常用配置项：

配置项 默认值 说明
JENKINS_HOME /var/lib/jenkins 数据目录
JENKINS_USER jenkins 运行用户
JENKINS_PORT 8080 HTTP 端口
JENKINS_ARGS "" 启动参数

修改端口示例：

1
2
# 将端口改为 9090
JENKINS_PORT="9090"

修改后重启生效：

1
sudo systemctl restart jenkins

常见问题排查

问题一：SSH 命令执行报 Permission denied

现象：Jenkins 构建时执行 SSH 命令出现权限拒绝错误。

原因：Jenkins 进程用户没有执行目标命令的权限。

解决方案：在执行命令前添加 sudo：

1
2
3
4
5
# 原命令（失败）
ssh user@server "systemctl restart myapp"

# 修改后（成功）
ssh user@server "sudo systemctl restart myapp"

同时确保目标服务器的 /etc/sudoers 允许对应用户无密码执行：

1
2
3
4
5
# 在目标服务器上编辑 sudoers
sudo visudo

# 添加行
deploy ALL=(ALL) NOPASSWD: /bin/systemctl restart myapp

问题二：sudo 报错 “no tty present”

现象：Jenkins 执行 sudo 命令时报错：

1
sudo: no tty present and no askpass program specified

原因：Jenkins 以非交互方式运行，没有 TTY 终端，而 sudo 默认需要密码输入。

解决方案：给 Jenkins 用户配置免密 sudo：

1
2
3
4
5
6
7
8
# 编辑 sudoers 文件
sudo visudo

# 添加以下行（允许 jenkins 用户无需密码执行所有命令）
jenkins ALL=(ALL) NOPASSWD:ALL

# 或更严格的安全策略，只允许特定命令
jenkins ALL=(ALL) NOPASSWD: /usr/bin/systemctl *, /usr/bin/docker *
配置 安全级别 适用场景
NOPASSWD:ALL 低 内部可信环境
NOPASSWD: /path/cmd 高 生产环境推荐

问题三：构建环境变量缺失

现象：Jenkins 中执行的命令找不到已安装的工具（如 Node.js、Docker）。

原因：Jenkins 以 jenkins 用户运行，环境变量与 root 或登录用户不同。

解决方案：

1
2
3
4
5
6
7
8
# 在 Jenkins 构建脚本中使用绝对路径
/var/www/.nvm/versions/node/v14.21.3/bin/node -v

# 或在构建脚本开头加载环境
#!/bin/bash
source /etc/profile
source ~/.bashrc
export PATH="/var/www/.nvm/versions/node/v14.21.3/bin:$PATH"

问题四：磁盘空间不足

Jenkins 构建产物和日志会占用大量磁盘空间，需定期清理：

1
2
3
4
5
6
7
8
9
# 查看 Jenkins 目录大小
du -sh /var/lib/jenkins/

# 查看构建目录大小
du -sh /var/lib/jenkins/jobs/*/builds/

# 清理旧构建（保留最近 10 个）
# 在 Jenkins 任务配置中设置 "丢弃旧的构建"
# Max # of builds to keep: 10

生产环境安全配置

1. 启用 HTTPS

使用 Nginx 反向代理为 Jenkins 添加 HTTPS：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
server {
    listen 443 ssl;
    server_name jenkins.example.com;

    ssl_certificate /etc/nginx/ssl/jenkins.crt;
    ssl_certificate_key /etc/nginx/ssl/jenkins.key;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

2. 配置 Jenkins 安全域

进入 Manage Jenkins → Configure Global Security：

配置项 推荐设置
Security Realm Jenkins’ own user database 或 LDAP
Authorization Matrix-based security
Markup Formatter Safe HTML
CSRF Protection 启用

3. 凭据管理

使用 Jenkins Credentials 存储敏感信息，避免硬编码：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 在流水线中安全使用凭据
pipeline {
    agent any
    environment {
        SSH_KEY = credentials('production-ssh-key')
        API_TOKEN = credentials('api-token')
    }
    stages {
        stage('Deploy') {
            steps {
                sh 'ansible-playbook -i hosts deploy.yml --private-key $SSH_KEY'
            }
        }
    }
}

流水线示例

简单的 Node.js 项目流水线

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
pipeline {
    agent any

    tools {
        nodejs 'NodeJS-14'
    }

    stages {
        stage('Checkout') {
            steps {
                git branch: 'main', url: 'https://github.com/example/project.git'
            }
        }

        stage('Install') {
            steps {
                sh 'npm ci'
            }
        }

        stage('Test') {
            steps {
                sh 'npm test'
            }
        }

        stage('Build') {
            steps {
                sh 'npm run build'
            }
        }

        stage('Deploy') {
            steps {
                sh '''
                    rsync -avz --delete dist/ user@server:/var/www/app/
                    ssh user@server "sudo systemctl restart app"
                '''
            }
        }
    }

    post {
        failure {
            mail to: 'dev@example.com',
                 subject: "构建失败: ${env.JOB_NAME} #${env.BUILD_NUMBER}",
                 body: "请查看: ${env.BUILD_URL}"
        }
    }
}

总结

Jenkins CI/CD 配置的核心要点：

  1. 安装部署：通过官方仓库安装，配置防火墙放行端口，更换国内镜像源加速插件安装
  2. 权限管理：配置 Jenkins 用户的 sudo 权限，区分交互式和非交互式环境变量
  3. 问题排查：SSH 权限问题加 sudo，tty 问题配置 NOPASSWD，环境变量使用绝对路径
  4. 生产安全：启用 HTTPS、配置安全域、使用 Credentials 管理敏感信息、启用 CSRF 保护
  5. 流水线设计：按阶段组织构建流程（拉取 → 安装 → 测试 → 构建 → 部署），配置失败通知

通过合理的 Jenkins 配置，可以实现从代码提交到生产部署的全自动化流程，显著提升团队的交付效率和部署稳定性。