Jenkins 初始化与自动部署：从零搭建 CI/CD 流水线

Jenkins 是一个工作流调度引擎——它本身只提供基础框架和 UI 界面，强大的自动化功能全部依赖插件来扩展。
Pipeline as Code——你编写一份"蓝图"（Jenkinsfile），告诉 Jenkins 在什么情况下（触发器）做什么事（Pipeline 阶段），Jenkins 严格按蓝图执行。

学完你能做什么？

✅ 用 Docker 一键部署 Jenkins
✅ 配置 Git 仓库凭证，安全地拉取代码
✅ 编写完整的 Jenkinsfile 实现编译 → 测试 → 构建镜像 → 部署
✅ 配置 Webhook 实现代码推送自动触发构建
✅ 掌握 Jenkins 初始化的完整流程

③ 概念与原理

Jenkins 的核心工作流程

两个关键概念

概念	解释	类比
Pipeline（流水线）	自动化流程的蓝图，定义从拉代码到部署的所有步骤	工厂里的流水线作业指导书
Jenkinsfile	Pipeline 脚本的具体实现，存放在代码仓库根目录	流水线指导书的电子版

Pipeline as Code 的好处：

流程和代码一起被版本控制
团队所有成员都能看到构建部署流程
分支策略天然支持多环境（dev/staging/prod）

④ 逻辑与对比

Jenkins + Docker 的自动化方案对比

方案	配置复杂度	维护成本	适用场景
手动部署（无自动化）	低	高	个人玩具项目
Jenkins + Shell 脚本	中	中	传统项目
Jenkins + Pipeline + Docker	中高	低	推荐：大多数项目
GitHub Actions / GitLab CI	低	低	轻量级、不想维护 Jenkins
Kubernetes + ArgoCD	高	中	大规模微服务

Jenkins 适合需要高度自定义、私有化部署、复杂流水线逻辑的场景。如果你的需求简单，GitHub Actions 就够了。

⑤ 核心详解

5.1 第一步：用 Docker 部署 Jenkins

原理：用 Docker 部署可以将 Jenkins 的运行环境、所有配置和数据封装在容器中，确保不同机器上的行为完全一致。数据通过 Volume 持久化，容器删了重建也不会丢失配置。

操作步骤：

① 创建 docker-compose.yml

version: '3.8'
services:
  jenkins:
    image: jenkins/jenkins:lts
    container_name: jenkins
    privileged: true            # 允许容器内使用 Docker
    user: root                  # 以 root 运行，避免权限问题
    ports:
      - "8080:8080"             # Jenkins Web 界面
      - "50000:50000"           # Agent 通信端口
    volumes:
      - ./jenkins_home:/var/jenkins_home           # 数据持久化
      - /var/run/docker.sock:/var/run/docker.sock  # 容器内调用宿主机 Docker
    environment:
      - TZ=Asia/Shanghai

② 启动容器

docker compose up -d

如果遇到权限错误：

# Jenkins 容器内进程以 UID 1000 运行
sudo chown -R 1000:1000 ./jenkins_home/

5.2 访问与解锁

启动容器后就可以看到此界面了

原理：为防止未授权访问，Jenkins 首次启动生成一次性临时管理员密码。

操作：

浏览器访问 http://<服务器IP>:8080

查看密码的方式：

# 方式一：查看容器日志
docker compose logs jenkins | grep -i "InitialAdminPassword"

# 方式二：进入容器查看
docker exec -it jenkins bash
cat /var/jenkins_home/secrets/initialAdminPassword

5.3 安装插件与创建管理员

进入 Jenkins Web 界面后依次操作：

安装推荐插件 — 包含 Pipeline、Git、Credentials Binding、Docker Pipeline 等后续必需的插件
创建管理员用户 — 填写自定义用户名和密码（不建议用默认的 admin）

5.4 配置凭证（Credentials）

原理：凭证（Credentials）以一种安全的方式集中存储密钥、密码等敏感信息，Pipeline 按 ID 引用，避免敏感信息写死在代码中。

Git 仓库凭证

Dashboard → 系统管理 → 凭据 → 全局 → 添加凭据

类型: Username with password
用户名: 你的 Git 用户名
密码: 你的 Git 密码/Token
ID: my-git-credentials    ← 这个 ID 在 Pipeline 中使用
描述: GitLab 代码仓库凭证

Docker Hub 凭证

同上步骤，添加 Docker Hub 的账号密码
ID: docker-hub-credentials

SSH 部署凭证

类型: SSH Username with private key
ID: my-ssh-credentials
用户名: deploy
私钥: 将部署服务器的私钥内容粘贴进去

5.5 编写 Jenkinsfile（核心！）

在代码仓库根目录创建 Jenkinsfile：

pipeline {
    agent any

    environment {
        DOCKER_IMAGE = "myapp:${env.BUILD_ID}"
        DOCKER_REGISTRY = "registry.hub.docker.com"
    }

    stages {
        // 【阶段 1】拉取代码
        stage('Checkout') {
            steps {
                checkout scm
            }
        }

        // 【阶段 2】编译打包
        stage('Build') {
            steps {
                sh 'mvn clean package -DskipTests'
            }
            post {
                success {
                    archiveArtifacts artifacts: 'target/*.jar', allowEmptyArchive: true
                }
            }
        }

        // 【阶段 3】构建 Docker 镜像
        stage('Build Docker Image') {
            steps {
                script {
                    docker.build(DOCKER_IMAGE)
                }
            }
        }

        // 【阶段 4】推送镜像到仓库
        stage('Push Docker Image') {
            steps {
                script {
                    docker.withRegistry("https://${DOCKER_REGISTRY}", 'docker-hub-credentials') {
                        docker.image(DOCKER_IMAGE).push()
                    }
                }
            }
        }

        // 【阶段 5】部署到服务器
        stage('Deploy') {
            steps {
                script {
                    sshagent(['my-ssh-credentials']) {
                        sh """
                            ssh deploy@your-server-ip '
                                docker pull ${DOCKER_REGISTRY}/${DOCKER_IMAGE} &&
                                docker rm -f my-app || true &&
                                docker run -d --name my-app -p 8080:8080 ${DOCKER_REGISTRY}/${DOCKER_IMAGE}
                            '
                        """
                    }
                }
            }
        }
    }

    post {
        always {
            emailext (
                subject: "构建通知: ${env.JOB_NAME} - Build # ${env.BUILD_NUMBER} - ${currentBuild.result}",
                body: "项目 ${env.JOB_NAME} 构建已完成。\n查看详情: ${env.BUILD_URL}",
                to: 'team@example.com'
            )
        }
    }
}

每个阶段的作用：

阶段	做了什么	依赖什么
Checkout	拉取 Git 仓库代码	Git 插件 + 代码仓库凭证
Build	Maven 编译打包	Maven（需在 Jenkins 中配置 JDK/Maven）
Build Docker Image	用 Dockerfile 构建镜像	Docker Pipeline 插件
Push Docker Image	推送镜像到仓库	Docker Hub 凭证
Deploy	SSH 到服务器拉取并运行新镜像	SSH Agent 插件 + SSH 凭证
post.always	发送构建结果邮件	Email Extension 插件

5.6 创建流水线任务

① 新建任务

Dashboard → 新建 Item → 输入名称 → 选择"多分支流水线"

② 配置代码仓库

分支源 → 添加 Git 仓库
仓库 URL: https://gitlab.com/your-project/repo.git
凭证: my-git-credentials

③ 保存后自动扫描 保存后 Jenkins 会扫描仓库中的 Jenkinsfile，并为每个包含 Jenkinsfile 的分支自动创建流水线任务。

5.7 配置 Webhook 自动触发

原理：Webhook 是回调机制——代码仓库有 push 事件时，主动通知 Jenkins 触发构建。

Jenkins 侧

进入流水线任务 → 配置 → 构建触发器
勾选: Build when a change is pushed to GitLab
复制生成的 Webhook URL 和 Secret Token

GitLab 侧

项目 → Settings → Integrations
URL: 粘贴 Jenkins 生成的 Webhook URL
Secret Token: 粘贴令牌
触发条件: Push events
点击 Add webhook → 保存

现在，每次 push 代码到仓库，GitLab 会自动通知 Jenkins 执行整个流水线：

代码 push → GitLab 通知 → Jenkins 触发构建 → 执行 Pipeline

⑥ 案例实战

实战：Java Spring Boot 项目的完整 CI/CD

项目结构：

my-java-app/
├── Dockerfile
├── Jenkinsfile
├── pom.xml
├── src/
│   └── main/
│       └── java/
│           └── ...
└── docker-compose.yml

Dockerfile：

FROM eclipse-temurin:17-jre-alpine
WORKDIR /app
COPY target/*.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]

配置 Jenkins 全局工具（Dashboard → 系统管理 → 工具）：

JDK: 添加 JDK 17（选择"自动安装"或指定路径）
Maven: 添加 Maven 3.9+

推送测试：

# 开发者提交代码
git add .
git commit -m "fix: update order logic"
git push origin master

# 自动触发 Jenkins 构建 ✓
# 自动构建 Docker 镜像 ✓
# 自动部署到服务器 ✓

⑦ 避坑 & 最佳实践

常见坑点

坑 1：容器内 Docker 权限问题

// ❌ 报错：Cannot connect to the Docker daemon
// 原因：容器内没有 Docker CLI 或者没挂载 socket
// 解决：privileged: true + 挂载 docker.sock

坑 2：.env 文件被提交到仓库

// ❌ 密码泄露！.env 文件包含数据库密码
// 解决：.gitignore 中添加 .env
// Jenkins 凭证系统替代硬编码环境变量

坑 3：Jenkins 因重启丢失数据

// ❌ docker compose down 后所有配置消失
// 解决：使用绑定挂载持久化 ./jenkins_home 目录

坑 4：SSH 部署失败

// ❌ 报错：Host key verification failed
// 原因：首次连接需要确认主机指纹
// 解决：在 Jenkins 容器中先手动 ssh 一次
// 或在 SSH 命令中加上 -o StrictHostKeyChecking=no

最佳实践清单

定期备份 jenkins_home 目录 — 它是 Jenkins 的命根子
使用非 admin 账号 — 配合"基于角色的授权策略"插件实现权限控制
定期更新插件 — 获取新功能和安全修复
Jenkinsfile 永远放在代码仓库 — Pipeline as Code 才有意义
敏感信息只用凭证系统 — 绝不要写在 Jenkinsfile 里
给 Pipeline 加超时限制 — 防止构建卡死

pipeline {
    options {
        timeout(time: 30, unit: 'MINUTES')  // 30 分钟超时
        buildDiscarder(logRotator(numToKeepStr: '10'))  // 保留最近 10 次构建
    }
    // ...
}

⑧ 总结 & 路线图

知识串联

阶段	操作	对应原理
核心认知	Jenkins 是自动化调度引擎	通过插件扩展能力
初始化	Docker 部署 + 临时密码 + 推荐插件	第一道安全门 + 定义能力边界
凭证管理	添加 Git/Docker Hub/SSH 凭证	安全集中管理敏感信息
Pipeline	创建 Jenkinsfile	Pipeline as Code
触发器	Webhook	Git 事件回调 Jenkins
构建流程	Checkout → Build → Dockerize → Deploy	流水线定义做什么
后置通知	post 块配置邮件	构建完成收尾

下一步学习路线

基础（本文完成）:
  Jenkins 初始化 + 基础 Pipeline
  ↓
进阶:
  Blue Ocean 界面（可视化 Pipeline）
  Shared Libraries（共享流水线库）
  ↓
中级:
  多分支流水线策略（dev/staging/prod 不同行为）
  并行阶段执行（加速构建）
  ↓
高级:
  Jenkins + Kubernetes 动态 Agent
  声明式 Pipeline 的 when/input/matrix 高级指令