张翔
9c9f2276f2
- Step-by-step configuration for Pipeline job - Gitea Webhook integration instructions - SSH deployment credentials setup - Notification configuration (email/DingTalk) - Troubleshooting common issues - Performance optimization tips
468 lines
12 KiB
Markdown
468 lines
12 KiB
Markdown
# 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+
|