build(ci/cd): add full automated CI/CD setup scripts
新增了完整的Novalon网站CI/CD自动化配置工具链，包括： 1. 一键启动脚本、主配置脚本与配置文件 2. Jenkins容器部署、Gitea Webhook配置、环境验证脚本 3. 完善的中文文档与使用示例 4. 优化了Jenkinsfile流水线，新增构建保留、并发限制、备份清理等功能
This commit is contained in:
张翔
@@ -0,0 +1,373 @@
|
||||
# Novalon Website CI/CD 自动化配置工具
|
||||
|
||||
## 📋 概述
|
||||
|
||||
一套完整的自动化脚本，用于快速配置 **Jenkins + Gitea** 的 CI/CD 流水线，实现：
|
||||
|
||||
- ✅ **一键配置**：自动完成所有 Jenkins 和 Gitea 的配置
|
||||
- ✅ **Docker 适配**：专为 Docker 环境优化（Shell 模式）
|
||||
- ✅ **免密部署**：自动挂载 SSH 密钥，实现生产服务器免密登录
|
||||
- ✅ **Webhook 集成**：自动配置 Gitea Webhook 触发构建
|
||||
- ✅ **完整验证**：自动检测所有配置是否正确
|
||||
|
||||
## 🎯 适用场景
|
||||
|
||||
- **首次部署**：全新环境的一键初始化
|
||||
- **环境重建**：需要重置或迁移时
|
||||
- **故障排查**：验证当前配置状态
|
||||
- **日常维护**：更新插件、重新配置 Webhook
|
||||
|
||||
## 📁 文件结构
|
||||
|
||||
```
|
||||
scripts/setup-cicd/
|
||||
├── cicd.sh # 一键启动器（入口脚本）
|
||||
├── setup-cicd.sh # 主配置流程
|
||||
├── cicd.config # 配置文件（可自定义修改）
|
||||
└── lib/
|
||||
├── utils.sh # 工具函数库
|
||||
├── jenkins-setup.sh # Jenkins 配置逻辑
|
||||
├── gitea-setup.sh # Gitea Webhook 配置
|
||||
└── verify.sh # 验证和测试
|
||||
```
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 前置条件
|
||||
|
||||
1. **Docker 已安装并运行**
|
||||
2. **SSH 密钥已生成**（用于免密登录生产服务器）：
|
||||
```bash
|
||||
ssh-keygen -t rsa -b 4096 -C "your-email@example.com"
|
||||
```
|
||||
3. **生产服务器的 `authorized_keys` 包含你的公钥**：
|
||||
```bash
|
||||
ssh-copy-id root@139.155.109.62
|
||||
```
|
||||
|
||||
### 使用方法
|
||||
|
||||
#### 1️⃣ 完整安装（首次使用）
|
||||
|
||||
```bash
|
||||
# 进入项目目录
|
||||
cd /Users/zhangxiang/Codes/Novalon/novalon-website
|
||||
|
||||
# 赋予执行权限
|
||||
chmod +x scripts/setup-cicd/*.sh scripts/setup-cicd/lib/*.sh
|
||||
|
||||
# 执行完整安装（会重建 Jenkins 容器）
|
||||
./scripts/setup-cicd/cicd.sh --full
|
||||
```
|
||||
|
||||
**执行过程**：
|
||||
```
|
||||
╔════════════════════════════════════════════╗
|
||||
║ 🚀 Novalon Website CI/CD 自动配置工具 ║
|
||||
╚════════════════════════════════════════════╝
|
||||
|
||||
📋 模式: 完整安装（包含 Docker 容器重建）
|
||||
|
||||
════════════════════════════════════════════
|
||||
检查前置条件
|
||||
════════════════════════════════════════════
|
||||
|
||||
✅ docker 已安装
|
||||
✅ curl 已安装
|
||||
✅ jq 已安装
|
||||
✅ 前置条件检查通过
|
||||
|
||||
════════════════════════════════════════════
|
||||
配置 Jenkins Docker 容器
|
||||
════════════════════════════════════════════
|
||||
|
||||
✅ Jenkins 容器已启动
|
||||
容器名称: jenkins
|
||||
访问地址: http://ci.f.novalon.cn:8080
|
||||
|
||||
...（后续步骤自动完成）
|
||||
|
||||
════════════════════════════════════════════
|
||||
✅ 自动化配置完成！
|
||||
════════════════════════════════════════════
|
||||
|
||||
🌐 Jenkins: http://ci.f.novalon.cn:8080
|
||||
🔗 Gitea: https://git.f.novalon.cn
|
||||
🚀 任务名: novalon-website-ci-cd
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### 2️⃣ 快速配置（跳过容器重建）
|
||||
|
||||
如果 Jenkins 容器已经在运行，只是需要重新配置：
|
||||
|
||||
```bash
|
||||
./scripts/setup-cicd/cicd.sh
|
||||
```
|
||||
|
||||
这会跳过容器创建，直接进行工具安装、凭据配置、任务创建和 Webhook 设置。
|
||||
|
||||
---
|
||||
|
||||
#### 3️⃣ 仅配置 Jenkins
|
||||
|
||||
```bash
|
||||
./scripts/setup-cicd/cicd.sh --jenkins
|
||||
```
|
||||
|
||||
适用于：
|
||||
- 安装新的 Jenkins 插件
|
||||
- 更新全局工具配置
|
||||
- 重新创建 Pipeline 任务
|
||||
|
||||
---
|
||||
|
||||
#### 4️⃣ 仅配置 Gitea Webhook
|
||||
|
||||
```bash
|
||||
./scripts/setup-cicd/cicd.sh --webhook
|
||||
```
|
||||
|
||||
适用于：
|
||||
- Webhook 丢失或损坏
|
||||
- 更新 Webhook URL
|
||||
- 重新测试触发机制
|
||||
|
||||
---
|
||||
|
||||
#### 5️⃣ 验证当前配置
|
||||
|
||||
```bash
|
||||
./scripts/setup-cicd/cicd.sh --verify
|
||||
```
|
||||
|
||||
输出示例：
|
||||
```
|
||||
════════════════════════════════════════════
|
||||
验证结果汇总
|
||||
════════════════════════════════════════════
|
||||
|
||||
总计: 7 项检查
|
||||
通过: 7 项
|
||||
|
||||
🎉 所有配置已就绪！可以开始使用 CI/CD 流水线了。
|
||||
|
||||
下一步操作：
|
||||
1. 访问 http://ci.f.novalon.cn:8080/job/novalon-website-ci-cd/
|
||||
2. 点击 'Build Now' 进行首次构建
|
||||
3. 推送代码到 main 分支测试自动触发
|
||||
4. 勾选 DEPLOY_TO_PRODUCTION 参数测试部署
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### 6️⃣ 清理所有配置
|
||||
|
||||
```bash
|
||||
./scripts/setup-cicd/cicd.sh --clean
|
||||
```
|
||||
|
||||
⚠️ **警告**：此操作会删除 Jenkins 容器和所有数据！
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ 自定义配置
|
||||
|
||||
编辑 `cicd.config` 文件可以修改以下参数：
|
||||
|
||||
```bash
|
||||
# Jenkins 配置
|
||||
JENKINS_URL="http://ci.f.novalon.cn:8080"
|
||||
JENKINS_CONTAINER_NAME="jenkins"
|
||||
JENKINS_IMAGE="jenkins/jenkins:lts-jdk17"
|
||||
|
||||
# Gitea 配置
|
||||
GITEA_URL="https://git.f.novalon.cn"
|
||||
GITEA_USERNAME="zhangxiang@novalon.cn"
|
||||
GITEA_PASSWORD="qerqek-cavxaC-5jupri"
|
||||
|
||||
# 生产服务器配置
|
||||
SERVER_IP="139.155.109.62"
|
||||
SERVER_USER="root"
|
||||
DEPLOY_ROOT="/home/novalon/docker-app"
|
||||
|
||||
# 项目配置
|
||||
REPO_OWNER="novalon"
|
||||
REPO_NAME="novalon-website"
|
||||
JOB_NAME="novalon-website-ci-cd"
|
||||
```
|
||||
|
||||
## 🔧 故障排查
|
||||
|
||||
### 问题 1：SSH 连接失败
|
||||
|
||||
**症状**：验证阶段显示 "❌ SSH 免密登录: 失败"
|
||||
|
||||
**解决方案**：
|
||||
```bash
|
||||
# 1. 在宿主机上测试 SSH 连接
|
||||
ssh root@139.155.109.62
|
||||
|
||||
# 2. 如果失败，复制公钥到服务器
|
||||
ssh-copy-id root@139.155.109.62
|
||||
|
||||
# 3. 重新运行配置脚本
|
||||
./scripts/setup-cicd/cicd.sh --jenkins
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 问题 2：Jenkins 容器启动失败
|
||||
|
||||
**症状**：`docker run` 报错或容器无法访问
|
||||
|
||||
**解决方案**：
|
||||
```bash
|
||||
# 查看容器日志
|
||||
docker logs jenkins
|
||||
|
||||
# 检查端口占用
|
||||
lsof -i :8080
|
||||
|
||||
# 清理后重试
|
||||
docker stop jenkins && docker rm jenkins
|
||||
./scripts/setup-cicd/cicd.sh --full
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 问题 3：Webhook 未触发构建
|
||||
|
||||
**症状**：推送代码后 Jenkins 无反应
|
||||
|
||||
**解决方案**：
|
||||
```bash
|
||||
# 1. 验证 Webhook 是否存在
|
||||
./scripts/setup-cicd/cicd.sh --verify
|
||||
|
||||
# 2. 手动测试 Webhook
|
||||
curl -X POST "http://ci.f.novalon.cn:8080/generic-webhook-trigger/invoke?token=novalon-website-ci-token" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"ref":"refs/heads/main"}'
|
||||
|
||||
# 3. 如果不通，检查网络连通性
|
||||
docker exec gitea curl -I http://jenkins:8080
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 问题 4：插件安装失败
|
||||
|
||||
**症状**：Jenkins 插件未正确加载
|
||||
|
||||
**解决方案**：
|
||||
```bash
|
||||
# 重启 Jenkins 使插件生效
|
||||
docker restart jenkins
|
||||
|
||||
# 等待就绪后重新运行
|
||||
sleep 30
|
||||
./scripts/setup-cicd/cicd.sh --jenkins
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 工作流程图
|
||||
|
||||
```
|
||||
┌─────────────────────┐
|
||||
│ 开发者推送代码 │
|
||||
│ git push origin main│
|
||||
└─────────┬───────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────┐ ┌──────────────────┐
|
||||
│ Gitea Webhook │────▶│ Jenkins Trigger │
|
||||
│ (Push Event) │ │ (Generic Trigger) │
|
||||
└─────────────────────┘ └────────┬─────────┘
|
||||
│
|
||||
┌────────────────┼────────────────┐
|
||||
▼ ▼ ▼
|
||||
┌───────────┐ ┌─────────────┐ ┌──────────────┐
|
||||
│ 环境准备 │ │ 依赖安装 │ │ 代码质量检查 │
|
||||
│ (Node.js) │ │ (npm ci) │ │(ESLint+TS) │
|
||||
└───────────┘ └─────────────┘ └──────────────┘
|
||||
│ │ │
|
||||
└────────────────┼────────────────┘
|
||||
▼
|
||||
┌──────────────┐
|
||||
│ 单元测试 │
|
||||
│ (覆盖率≥80%) │
|
||||
└──────┬───────┘
|
||||
▼
|
||||
┌──────────────┐
|
||||
│ 构建 dist │
|
||||
│ (next build) │
|
||||
└──────┬───────┘
|
||||
▼
|
||||
┌──────────────────────────────┐
|
||||
│ DEPLOY_TO_PRODUCTION=true ? │
|
||||
└──────────────┬───────────────┘
|
||||
Yes ↘ ↘ No
|
||||
┌──────────┐ ┌──────────┐
|
||||
│ rsync 部署│ │ 构建完成 │
|
||||
│ Nginx 重载│ │ (仅构建) │
|
||||
│ 验证页面 │ └──────────┘
|
||||
└─────┬────┘
|
||||
▼
|
||||
┌──────────────┐
|
||||
│ 发送通知 │
|
||||
│ (钉钉/邮件) │
|
||||
└──────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 最佳实践建议
|
||||
|
||||
### 1. 定期运行验证
|
||||
|
||||
```bash
|
||||
# 添加到 crontab，每周五上午 10 点自动验证
|
||||
0 10 * * 5 cd /path/to/project && ./scripts/setup-cicd/cicd.sh --verify >> /var/log/cicd-check.log 2>&1
|
||||
```
|
||||
|
||||
### 2. 版本控制配置文件
|
||||
|
||||
将 `cicd.config` 提交到 Git（注意移除敏感信息或使用环境变量）：
|
||||
|
||||
```bash
|
||||
git add scripts/setup-cicd/
|
||||
git commit -m "chore: add automated CI/CD setup scripts"
|
||||
git push origin main
|
||||
```
|
||||
|
||||
### 3. 团队协作
|
||||
|
||||
新成员入职时只需运行：
|
||||
|
||||
```bash
|
||||
git clone <repo-url>
|
||||
cd novalon-website
|
||||
./scripts/setup-cicd/cicd.sh --full
|
||||
```
|
||||
|
||||
即可在 5 分钟内完成完整的开发环境搭建！
|
||||
|
||||
---
|
||||
|
||||
## 📞 技术支持
|
||||
|
||||
如遇到问题：
|
||||
|
||||
1. 运行 `./scripts/setup-cicd/cicd.sh --verify` 查看详细诊断
|
||||
2. 检查日志：`docker logs jenkins`
|
||||
3. 查看 Gitea Webhook 的 Recent Deliveries
|
||||
4. 访问 Jenkins 系统日志：Manage Jenkins → System Log
|
||||
|
||||
---
|
||||
|
||||
**版本**: 1.0.0
|
||||
**最后更新**: 2026-05-12
|
||||
**适用环境**: Docker + Jenkins 2.400+ + Gitea 1.19+
|
||||
Reference in New Issue
Block a user