java_demo/JENKINS_PANEL_GUIDE.md

# Jenkins面板完整构建配置指南

## 🎯 项目信息
- **Git仓库**: http://116.62.163.84:15006/wangtianqi/java_demo.git
- **目标服务器**: 116.62.163.84
- **SonarQube服务器**: http://116.62.163.84:15010
- **认证方式**: 用户名密码（SSH）

---

## 📋 第一部分：前期准备

### 1. 登录Jenkins
1. 打开浏览器，访问您的Jenkins服务器：
   ```
   http://您的Jenkins服务器IP:8080
   ```
2. 输入管理员用户名和密码登录

### 2. 安装必需插件
**管理Jenkins** → **插件管理** → **可选插件**

搜索并安装以下插件：
```
✓ Maven Integration Plugin
✓ JaCoCo Plugin  
✓ SonarQube Scanner Plugin
✓ Docker Pipeline Plugin
✓ SSH Agent Plugin
✓ Git Plugin
✓ Pipeline Plugin
✓ Credentials Binding Plugin
✓ Blue Ocean Plugin (推荐)
```

**安装步骤：**
1. 勾选需要的插件
2. 点击 **"直接安装"**
3. 等待安装完成并重启Jenkins

---

## 🔧 第二部分：系统配置

### 1. 配置全局工具
**管理Jenkins** → **全局工具配置**

#### 1.1 JDK配置
- 点击 **"新增JDK"**
- **Name**: `JDK-17`
- **JAVA_HOME**: `/usr/lib/jvm/java-17-openjdk`（Linux）或您的JDK安装路径
- 取消勾选 **"自动安装"**

#### 1.2 Maven配置
- 点击 **"新增Maven"**
- **Name**: `Maven-3.9.3`
- 勾选 **"自动安装"**
- **版本**: 选择 `3.9.3`

#### 1.3 Git配置（如果需要）
- 通常系统已有Git，保持默认即可

### 2. 配置SonarQube服务器
**管理Jenkins** → **系统配置** → **SonarQube servers**

- 点击 **"Add SonarQube"**
- **Name**: `SonarQube`
- **Server URL**: `http://116.62.163.84:15010`
- **Server authentication token**: `squ_7e4217cabd0faae6f3b8ee359b3b8e2ac52eb69a`

---

## 🔐 第三部分：凭据配置

### 1. 配置Git凭据
**管理Jenkins** → **凭据** → **系统** → **全局凭据** → **添加凭据**

**Git仓库访问凭据：**
- **类型**: `Username with password`
- **范围**: `全局`
- **用户名**: `wangtianqi`
- **密码**: `[您的Git密码]`
- **ID**: `git-credentials`
- **描述**: `Git Repository Access`

### 2. 配置SSH服务器凭据
**继续添加凭据**

**服务器SSH访问凭据：**
- **类型**: `Username with password`
- **范围**: `全局`
- **用户名**: `root`
- **密码**: `[您的服务器root密码]`
- **ID**: `deploy-server-ssh`
- **描述**: `Deploy Server SSH Access`

---

## 🚀 第四部分：创建Pipeline项目

### 1. 创建新项目
1. 回到Jenkins首页
2. 点击左侧 **"新建任务"** 或 **"New Item"**
3. **输入任务名称**: `java-demo-pipeline`
4. **选择类型**: `Pipeline`
5. 点击 **"确定"**

### 2. 配置项目基本信息

#### 2.1 基本设置
- **描述**: 
  ```
  Jenkins CI/CD Demo Project with Spring Boot 3
  用于演示完整的CI/CD流程，包括代码拉取、编译构建、单元测试、代码扫描、Docker打包和部署
  ```

#### 2.2 构建保留策略
- 勾选 **"丢弃旧的构建"**
- **保持构建的最大个数**: `10`
- **保持构建的天数**: `30`

#### 2.3 构建触发器（可选）
- **GitHub hook trigger for GITScm polling**: 勾选此项实现代码提交自动构建
- **轮询SCM**: 输入 `H/5 * * * *`（每5分钟检查一次代码变更）

### 3. 配置Pipeline

#### 3.1 Pipeline基本配置
- **Definition**: 选择 `Pipeline script from SCM`
- **SCM**: 选择 `Git`

#### 3.2 Git仓库配置
- **Repository URL**: 
  ```
  http://116.62.163.84:15006/wangtianqi/java_demo.git
  ```
- **Credentials**: 选择之前创建的 `git-credentials`
- **Branch Specifier**: `*/main`

#### 3.3 Script Path
- **Script Path**: `Jenkinsfile`

#### 3.4 轻量级检出（推荐）
- 勾选 **"Lightweight checkout"**

### 4. 保存配置
点击页面底部的 **"保存"**

---

## 🎬 第五部分：执行构建

### 1. 立即构建
1. 在项目主页点击左侧 **"立即构建"** 或 **"Build Now"**
2. 系统开始执行Pipeline

### 2. 监控构建过程

#### 2.1 查看构建历史
- 在左侧 **"构建历史"** 中可以看到构建列表
- 点击构建号（如 #1）进入构建详情

#### 2.2 查看控制台输出
- 在构建详情页面点击 **"控制台输出"**
- 可以实时查看构建日志

#### 2.3 使用Blue Ocean界面（推荐）
1. 点击左侧 **"Open Blue Ocean"**
2. 可以看到可视化的Pipeline流程
3. 每个阶段的状态一目了然

### 3. 构建阶段说明

构建将按以下顺序执行：

1. **🔄 Checkout** - 代码检出
   - 从Git仓库拉取最新代码
   - 显示Git提交ID

2. **🔍 环境检查** - 环境验证
   - 检查Java版本
   - 检查Maven版本
   - 检查Git版本

3. **🔨 编译** - 代码编译
   - 执行 `mvn clean compile`
   - 跳过测试阶段

4. **🧪 单元测试** - 测试执行
   - 运行所有单元测试
   - 生成测试报告和代码覆盖率

5. **🔍 代码质量扫描** - SonarQube分析
   - 静态代码分析
   - 代码质量评估

6. **📦 打包** - 应用打包
   - 生成可执行JAR文件
   - 归档构建产物

7. **🐳 构建Docker镜像** - 容器化
   - 构建Docker镜像
   - 创建版本标签

8. **📤 传输Docker镜像** - 镜像部署
   - 将镜像传输到目标服务器
   - 在目标服务器加载镜像

9. **🚀 部署应用** - 环境部署
   - **测试环境**: develop/feature分支 → 端口8080
   - **生产环境**: main/master分支 → 端口80

10. **🏥 健康检查** - 应用验证
    - 等待应用启动
    - 验证健康检查接口

---

## 📊 第六部分：查看构建结果

### 1. 构建状态说明
- **🔵 蓝色**: 构建成功
- **🔴 红色**: 构建失败
- **🟡 黄色**: 构建不稳定（测试失败但编译成功）
- **⚪ 灰色**: 构建被取消或未执行

### 2. 查看测试报告
1. 进入构建详情页面
2. 点击 **"测试结果"**
3. 查看单元测试通过率和详细结果

### 3. 查看代码覆盖率
1. 在构建详情页面找到 **"JaCoCo代码覆盖率"**
2. 查看代码覆盖率报告
3. 分析哪些代码未被测试覆盖

### 4. 查看SonarQube报告
1. 构建成功后访问：`http://116.62.163.84:15010`
2. 找到项目：`jenkins-demo`
3. 查看代码质量分析结果

### 5. 验证部署结果
构建成功后，根据分支验证部署：

**测试环境（develop分支）：**
```bash
curl http://116.62.163.84:8080/api/health
curl http://116.62.163.84:8080/api/users
```

**生产环境（main分支）：**
```bash
curl http://116.62.163.84/api/health
curl http://116.62.163.84/api/users
```

---

## 🔧 第七部分：故障排除

### 常见问题及解决方案

#### 1. Git克隆失败
**现象**: `fatal: could not read Username`
**解决**: 
- 检查Git凭据配置是否正确
- 确认仓库URL可以访问
- 验证用户名密码是否正确

#### 2. Maven构建失败
**现象**: `command not found: mvn`
**解决**:
- 检查Maven工具配置
- 确认Maven自动安装是否完成
- 查看系统环境变量设置

#### 3. Docker构建失败
**现象**: `Cannot connect to the Docker daemon`
**解决**:
- 确认Jenkins服务器已安装Docker
- 检查Jenkins用户是否在docker组
- 确认Docker服务是否运行

#### 4. SSH连接失败
**现象**: `Permission denied (publickey,password)`
**解决**:
- 检查SSH凭据用户名密码
- 确认目标服务器允许密码认证
- 检查防火墙设置

#### 5. 健康检查失败
**现象**: `应用健康检查失败，HTTP状态码: 000`
**解决**:
- 检查应用是否正常启动
- 确认端口映射是否正确
- 查看Docker容器日志

### 日志查看方式
```bash
# 查看构建日志
Jenkins控制台输出

# 查看应用日志
docker logs jenkins-demo-prod
docker logs jenkins-demo-test

# 查看系统日志
journalctl -u docker
```

---

## 📈 第八部分：高级配置

### 1. 配置构建通知
可以配置邮件、钉钉、企业微信等通知方式

### 2. 配置多分支Pipeline
支持自动发现和构建Git仓库的多个分支

### 3. 配置并行构建
充分利用服务器资源，加快构建速度

### 4. 配置构建缓存
缓存Maven依赖，减少构建时间

---

## 🎉 完成！

配置完成后，您的CI/CD流程就搭建好了！

**工作流程：**
1. 开发人员提交代码到Git仓库
2. Jenkins自动检测代码变更
3. 执行完整的构建、测试、部署流程
4. 自动部署到对应环境
5. 发送构建结果通知

**访问地址：**
- Jenkins: `http://您的Jenkins服务器:8080`
- SonarQube: `http://116.62.163.84:15010`
- 应用生产环境: `http://116.62.163.84`
- 应用测试环境: `http://116.62.163.84:8080`

现在您的团队可以享受高效的DevOps工作流程了！🚀