novalon/novalon-website
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c9de8061094cbd89aeed0e2d33967576150889ef
novalon-website/scripts/setup-cicd/README.md
T
张翔 b8ab1fd0e3 build(ci/cd): add full automated CI/CD setup scripts 
新增了完整的Novalon网站CI/CD自动化配置工具链，包括：
1.  一键启动脚本、主配置脚本与配置文件
2.  Jenkins容器部署、Gitea Webhook配置、环境验证脚本
3.  完善的中文文档与使用示例
4.  优化了Jenkinsfile流水线，新增构建保留、并发限制、备份清理等功能
2026-05-14 16:18:30 +08:00

11 KiB
Raw Blame History

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 密钥已生成（用于免密登录生产服务器）： 
    ssh-keygen -t rsa -b 4096 -C "your-email@example.com"
  3. 生产服务器的 authorized_keys 包含你的公钥： 
    ssh-copy-id root@139.155.109.62

使用方法

1️⃣ 完整安装（首次使用）

# 进入项目目录
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 容器已经在运行，只是需要重新配置：

./scripts/setup-cicd/cicd.sh

这会跳过容器创建，直接进行工具安装、凭据配置、任务创建和 Webhook 设置。

3️⃣ 仅配置 Jenkins

./scripts/setup-cicd/cicd.sh --jenkins

适用于：

  • 安装新的 Jenkins 插件
  • 更新全局工具配置
  • 重新创建 Pipeline 任务

4️⃣ 仅配置 Gitea Webhook

./scripts/setup-cicd/cicd.sh --webhook

适用于：

  • Webhook 丢失或损坏
  • 更新 Webhook URL
  • 重新测试触发机制

5️⃣ 验证当前配置

./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️⃣ 清理所有配置

./scripts/setup-cicd/cicd.sh --clean

⚠️ 警告：此操作会删除 Jenkins 容器和所有数据！

⚙️ 自定义配置

编辑 cicd.config 文件可以修改以下参数：

# 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 免密登录: 失败"

解决方案：

# 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 报错或容器无法访问

解决方案：

# 查看容器日志
docker logs jenkins

# 检查端口占用
lsof -i :8080

# 清理后重试
docker stop jenkins && docker rm jenkins
./scripts/setup-cicd/cicd.sh --full

问题 3：Webhook 未触发构建

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

解决方案：

# 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 插件未正确加载

解决方案：

# 重启 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. 定期运行验证

# 添加到 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（注意移除敏感信息或使用环境变量）：

git add scripts/setup-cicd/
git commit -m "chore: add automated CI/CD setup scripts"
git push origin main

3. 团队协作

新成员入职时只需运行：

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 View Git Blame Copy Permalink