# 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 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+