# Jenkins CI/CD 配置指南

## 📋 概述

本文档指导你如何在 Jenkins 中配置自动化 CI/CD 流水线，实现：
- ✅ Gitea Webhook 自动触发构建
- ✅ 多阶段质量门禁（Lint + TypeCheck + Test + Build）
- ✅ 自动部署到生产服务器
- ✅ 构建通知（邮件/钉钉/企业微信）

---

## 🔧 前置条件

### 1. Jenkins 插件安装

确保以下插件已安装在 Jenkins 中：

| 插件名称 | 用途 | 必需 |
|---------|------|------|
| **Pipeline** | 支持 Jenkinsfile 流水线 | ✅ 是 |
| **Git Plugin** | Git 仓库集成 | ✅ 是 |
| **Generic Webhook Trigger** | Gitea Webhook 触发 | ✅ 是 |
| **NodeJS Plugin** | Node.js 环境管理 | ✅ 是 |
| **HTML Publisher** | 发布测试报告 | ✅ 是 |
| **SSH Agent Plugin** | SSH 部署连接 | ✅ 是 |
| **Email Extension** | 邮件通知 | ⚠️ 可选 |
| **DingTalk Plugin** | 钉钉通知 | ⚠️ 可选 |

#### 安装步骤：

1. 登录 Jenkins：`http://<your-jenkins-ip>:8080`
2. 导航到：**Manage Jenkins → Plugins → Available plugins**
3. 搜索并安装上述插件
4. 重启 Jenkins

### 2. 全局工具配置

#### 配置 Node.js：

1. **Manage Jenkins → Tools**
2. 找到 **NodeJS** 部分
3. 点击 **Add NodeJS**
4. 配置如下：

```
Name: Node.js 18
Install automatically: ✅ 勾选
Version: 18.20.x (LTS)
```

5. 点击 **Save**

#### 配置 Git：

1. 同样在 **Tools** 页面
2. 找到 **Git** 部分
3. 确保 Git 路径正确（通常 `/usr/bin/git`）
4. 如果未安装，选择 **Install automatically**

---

## 🚀 创建 Pipeline 任务

### 方法 A：通过 Jenkins UI 创建（推荐新手）

#### 步骤 1：创建新任务

1. 点击 **New Item**
2. 输入任务名称：`novalon-website-ci-cd`
3. 选择 **Pipeline**
4. 点击 **OK**

#### 步骤 2：配置 General

```
☑️ This project is parameterized (勾选)

Parameters:
┌─ Boolean Parameter
│   Name: DEPLOY_TO_PRODUCTION
│   Default Value: false
│   Description: 是否部署到生产环境（仅在 main 分支且测试通过后可用）
└──────────────────────────────

☑️ GitHub project (可选)
Project URL: https://git.f.novalon.cn/novalon/novalon-website
```

#### 步骤 3：配置 Build Triggers（触发器）

##### 选项 1：Gitea Webhook 触发（推荐）

1. 勾选 **Trigger builds remotely**
2. 设置 Authentication Token：`novalon-website-ci-token`

3. 在 **Build Triggers** 部分找到 **Generic Webhook Trigger** 或 **Gitea Webhook**：
   - 如果使用 **Generic Webhook Trigger** 插件：
     ```
     Token: novalon-website-ci-token
     ```

4. **保存任务后，获取 Webhook URL**：
   ```
   http://<jenkins-ip>:8080/generic-webhook-trigger/invoke?token=novalon-website-ci-token
   ```

##### 选项 2：轮询 SCM（备选）

```
☑️ Poll SCM
Schedule: H/15 * * * *  (每 15 分钟检查一次)
```

#### 步骤 4：配置 Pipeline（流水线定义）

选择 **Pipeline script from SCM**：

```
SCM: Git
Repositories:
  Repository URL: https://git.f.novalon.cn/novalon/novalon-website.git
  Credentials: (添加 Gitea 凭据)
  Branch: */dev  (或 */main)

Script Path: Jenkinsfile
Lightweight checkout: ☑️ 勾选
```

#### 步骤 5：添加凭据（Credentials）

1. 点击 **Add → Jenkins**
2. 选择 **Username with password**
3. 输入 Gitea 账号密码：
   - Username: `你的 Gitea 用户名`
   - Password: `你的 Gitea 密码或 Personal Access Token`
4. ID: `gitea-credentials`（自定义）
5. 点击 **Add**

#### 步骤 6：保存并测试

1. 点击 **Save** 保存配置
2. 点击 **Build Now** 手动触发一次构建
3. 查看控制台输出确认流程正常

---

### 方法 B：Pipeline as Code（Jenkinsfile 已包含）

由于项目根目录已包含 [Jenkinsfile](../Jenkinsfile)，Jenkins 会自动读取。

只需确保：
1. ✅ Jenkinsfile 在仓库根目录
2. ✅ Pipeline 任务指向正确的分支和 Jenkinsfile 路径
3. ✅ 所需插件已安装

---

## 🔗 配置 Gitea Webhook

### 步骤 1：在 Gitea 中创建 Webhook

1. 打开 Gitea 仓库：`https://git.f.novalon.cn/novalon/novalon-website`
2. 点击 **Settings → Webhooks → Add Webhook → Gitea**
3. 配置如下：

```
Target URL:
http://<your-jenkins-ip>:8080/generic-webhook-trigger/invoke?token=novalon-website-ci-token

HTTP Method: POST
Content Type: application/json
Secret: (留空或设置密钥)

Trigger On:
☑️ Push Events
☐ Create Events
☐ Pull Request Events (可选)
☐ Tag Events (可选)

Branch Filter:
dev, main, develop  (逗号分隔，留空表示所有分支)

Active: ☑️ 勾选
```

4. 点击 **Add Webhook**

### 步骤 2：测试 Webhook

1. 在 Webhook 列表中，点击刚创建的 Webhook
2. 点击 **Test Delivery → Push Event**
3. 查看 **Recent Deliveries** 确认状态为 **200 OK**
4. 检查 Jenkins 是否收到触发并开始构建

---

## 🔐 配置部署凭据（SSH）

### 步骤 1：生成 SSH 密钥对（如果还没有）

```bash
# 在 Jenkins 服务器上执行
ssh-keygen -t rsa -b 4096 -C "jenkins@novalon" -f ~/.ssh/jenkins_deploy_key
```

### 步骤 2：将公钥添加到生产服务器

```bash
# 复制公钥内容
cat ~/.ssh/jenkins_deploy_key.pub

# 在生产服务器（139.155.109.62）上执行
echo "公钥内容" >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys
```

### 步骤 3：在 Jenkins 中添加 SSH 凭据

1. **Manage Jenkins → Credentials → System → Global credentials**
2. **Add Credentials → SSH Username with private key**
3. 配置：

```
ID: deploy-server-ssh
Username: root
Private Key:
  ☑️ Enter directly
  (粘贴私钥内容：~/.ssh/jenkins_deploy_key 的内容)
Passphrase: (如果有则填写，否则留空)
```

4. 点击 **Save**

### 步骤 4：更新 Jenkinsfile 使用凭据

编辑 [Jenkinsfile](../Jenkinsfile) 中的部署阶段，添加：

```groovy
stage('🚀 部署到生产环境') {
    when {
        allOf {
            anyOf { branch 'main'; branch 'develop' }
            expression { return params.DEPLOY_TO_PRODUCTION }
        }
    }
    steps {
        sshagent(['deploy-server-ssh']) {
            sh '''
                # 部署命令...
            '''
        }
    }
}
```

---

## 📧 配置通知

### 选项 1：邮件通知

1. **Manage Jenkins → System**
2. 找到 **E-mail Notification** 部分：
   ```
   SMTP server: smtp.qq.com (或你的 SMTP 服务器)
   SMTP Port: 465
   Use SSL: ☑️
   Username: your-email@qq.com
   Password: 你的授权码（不是 QQ 密码）
   Reply-To Address: your-email@qq.com
   Charset: UTF-8
   ```
3. 点击 **Test configuration** 发送测试邮件
4. 点击 **Save**

### 选项 2：钉钉机器人通知（推荐国内团队）

1. 创建钉钉群机器人：
   - 打开钉钉群 → 设置 → 智能群助手 → 添加机器人
   - 选择 **Custom（通过 Webhook 地址接入）**
   - 复制 Webhook URL：`https://oapi.dingtalk.com/robot/send?access_token=xxx`

2. 安装 **DingTalk Plugin**（或在 Jenkinsfile 中使用 curl）：

在 Jenkinsfile 的 `post { always {} }` 部分添加：

```groovy
post {
    always {
        script {
            def webhookUrl = 'https://oapi.dingtalk.com/robot/send?access_token=YOUR_TOKEN'
            def message = """
                {
                    "msgtype": "markdown",
                    "markdown": {
                        "title": "Jenkins 构建通知",
                        "text": "## Jenkins 构建通知\\n> 项目：${env.PROJECT_NAME}\\n> 分支：${env.GIT_BRANCH}\\n> 构建号：#${env.BUILD_NUMBER}\\n> 状态：${currentBuild.result ?: 'SUCCESS'}\\n> 时间：${new Date().format('yyyy-MM-dd HH:mm:ss')}"
                    }
                }
            """
            sh "curl -s -X POST '${webhookUrl}' -H 'Content-Type: application/json' -d '${message}'"
        }
    }
}
```

---

## 🧪 手动触发构建验证

### 第一次构建建议手动触发：

1. 进入任务页面：`novalon-website-ci-cd`
2. 点击 **Build Now**
3. 点击正在运行的构建号查看实时日志
4. 确认以下阶段成功：

```
✅ Stage 1: 🔧 环境准备
✅ Stage 2: 📥 安装依赖
✅ Stage 3: 🔍 ESLint 检查
✅ Stage 4: 🔍 TypeScript 类型检查
✅ Stage 5: 🧪 单元测试 + 覆盖率
✅ Stage 6: 🏗️ 生产构建
⏭️  Stage 7: 🧪 E2E 测试（需要 Playwright 浏览器）
⏭️  Stage 8: ⚡ 性能测试（需要 k6）
⏭️  Stage 9: 🚀 部署（需要勾选 DEPLOY_TO_PRODUCTION 参数）
```

### 查看构建产物：

1. 点击完成的构建号
2. 左侧菜单查看：
   - **Console Output** - 完整日志
   - **Coverage Report (Jest)** - 测试覆盖率报告
   - **Edit Build Information** - 构建元数据

---

## 🔄 常见问题排查

### 问题 1：Webhook 未触发构建

**症状**：推送代码后 Jenkins 无反应

**解决方案**：
1. 检查 Gitea Webhook 的 **Recent Deliveries** 状态码是否为 200
2. 确认 Jenkins URL 正确且可从 Gitea 访问
3. 检查 Jenkins 安全设置（Configure Global Security）：
   - CSRF Protection → Enable proxy compatibility
   - Allow anonymous read access（如果需要）

### 问题 2：Node.js 版本错误

**症状**：`ERROR: Node.js version not found`

**解决方案**：
1. 确认已在 **Manage Jenkins → Tools** 中配置 Node.js 18
2. 检查 Jenkinsfile 中的 `nodejs(nodeJSInstallationName: '18')` 名称匹配

### 问题 3：npm install 失败

**症状**：`npm ERR! network error`

**解决方案**：
1. 检查 npm registry 配置（默认使用 npmmirror 镜像）
2. 如果是私有包，配置 `.npmrc` 文件
3. 检查 Jenkins 服务器的网络连接

### 问题 4：SSH 部署失败

**症状**：`Permission denied (publickey)`

**解决方案**：
1. 确认 SSH 私钥已正确添加到 Jenkins 凭据
2. 确认生产服务器的 `~/.ssh/authorized_keys` 包含对应公钥
3. 测试 SSH 连接：`ssh root@139.155.109.62`

### 问题 5：ESLint 或 TypeScript 检查失败

**症状**：构建在代码质量检查阶段失败

**解决方案**：
1. 查看完整错误日志
2. 在本地运行修复：
   ```bash
   npm run lint --fix
   npm run type-check
   ```
3. 修复问题后重新提交代码

---

## 📊 监控与优化

### 构建历史分析

1. 进入任务主页
2. 查看构建趋势图（成功率、平均耗时）
3. 识别瓶颈阶段（通常是安装依赖或测试）

### 性能优化建议

1. **启用构建缓存**：
   ```groovy
   environment {
       CI_CACHE_PATH = "${HOME}/.cache/novalon-website"
   }
   ```

2. **并行化测试**：在 Jenkinsfile 中使用 `parallel` 执行多个测试套件

3. **增量构建**：只对变更的模块运行测试（需要 monorepo 结构）

4. **Docker 化构建环境**：使用 Docker agent 保证一致性

---

## ✅ 完成清单

完成以下所有项后，CI/CD 流水线即可正常运行：

- [x] 推送代码到 Gitea ✅
- [ ] 安装 Jenkins 必要插件
- [ ] 配置全局工具（Node.js 18, Git）
- [ ] 创建 Pipeline 任务（指向 dev 分支的 Jenkinsfile）
- [ ] 添加 Gitea 凭据（Username with Password）
- [ ] 配置 Gitea Webhook（Push Events → Jenkins Generic Trigger）
- [ ] 添加部署 SSH 凭据（生产服务器访问权限）
- [ ] 配置通知渠道（邮件/钉钉）
- [ ] 手动触发首次构建验证
- [ ] 确认所有阶段成功通过
- [ ] 测试自动触发（推送代码 → Jenkins 自动构建）

---

## 🎯 下一步操作

### 立即执行：

1. **登录 Jenkins 并按照上述步骤创建任务**
2. **配置 Gitea Webhook**
3. **手动触发第一次构建**
4. **查看构建日志确认流程正常**

### 本周内完成：

1. **设置构建失败告警**
2. **建立定期审查机制（每周审查构建成功率）**
3. **优化构建性能（目标：<10 分钟完成全流程）**

---

## 📞 技术支持

如遇到问题，请检查：

1. **Jenkins 系统日志**：`Manage Jenkins → System Log`
2. **Gitea Webhook 日志**：Webhook 页面的 Recent Deliveries
3. **构建控制台输出**：每次构建的 Console Output

---

**文档版本**: v1.0
**最后更新**: 2026-01-15
**适用版本**: Jenkins 2.400+, Gitea 1.19+