refactor: 整理脚本文件到 scripts 目录（任务 2.1/20）
This commit is contained in:
张翔
+62
-239
@@ -1,264 +1,87 @@
|
||||
# Woodpecker CI 本地测试工具
|
||||
# Scripts 目录
|
||||
|
||||
本目录包含用于本地测试和验证 Woodpecker CI 配置的工具。
|
||||
本目录包含项目的所有脚本文件，按功能分类整理。
|
||||
|
||||
## 📁 文件说明
|
||||
## 目录结构
|
||||
|
||||
### 1. `validate-woodpecker.sh` - 配置验证工具
|
||||
|
||||
**功能**：全面验证 `.woodpecker.yml` 配置文件的正确性
|
||||
|
||||
**检查项目**：
|
||||
- ✅ YAML 语法检查
|
||||
- ✅ 必需字段检查（steps, image, commands）
|
||||
- ✅ 镜像格式验证
|
||||
- ✅ 环境变量和 secrets 检查
|
||||
- ✅ when 条件逻辑分析
|
||||
- ✅ 执行顺序模拟
|
||||
|
||||
**使用方法**：
|
||||
```bash
|
||||
./scripts/validate-woodpecker.sh
|
||||
```
|
||||
scripts/
|
||||
├── deployment/ # 部署相关脚本
|
||||
├── monitoring/ # 监控相关脚本
|
||||
├── diagnosis/ # 诊断相关脚本
|
||||
├── security/ # 安全相关脚本
|
||||
├── maintenance/ # 维护相关脚本
|
||||
└── tools/ # 工具脚本
|
||||
```
|
||||
|
||||
**输出示例**：
|
||||
```
|
||||
==========================================
|
||||
Woodpecker CI 配置本地验证工具
|
||||
==========================================
|
||||
## 脚本分类
|
||||
|
||||
✅ 文件存在: .woodpecker.yml
|
||||
### 部署脚本 (deployment/)
|
||||
|
||||
1️⃣ YAML 语法检查
|
||||
----------------------------------------
|
||||
✅ YAML 语法正确
|
||||
- `deploy.sh` - 项目部署脚本
|
||||
- `setup-ssl.sh` - SSL 证书配置脚本
|
||||
|
||||
2️⃣ 检查必需字段
|
||||
----------------------------------------
|
||||
✅ 步骤 'lint' 有分支条件: ['feature/**', 'dev', 'release', 'release/**']
|
||||
✅ 步骤 'lint' 有事件条件: ['push', 'pull_request']
|
||||
...
|
||||
```
|
||||
### 监控脚本 (monitoring/)
|
||||
|
||||
### 2. `test-step.sh` - 单步测试工具
|
||||
- `monitor-pipeline.sh` - CI/CD 流水线监控
|
||||
- `monitor-pipeline-continuous.sh` - 持续监控脚本
|
||||
- `monitor-pipeline-32.sh` - 流水线监控（32位系统）
|
||||
- `ralph-auto-monitor.sh` - Ralph 自动监控
|
||||
- `ralph-loop.sh` - Ralph 循环监控
|
||||
- `ralph-loop.py` - Ralph 循环监控（Python 版本）
|
||||
|
||||
**功能**：在本地 Docker 环境中测试单个 pipeline 步骤
|
||||
### 诊断脚本 (diagnosis/)
|
||||
|
||||
**使用方法**：
|
||||
```bash
|
||||
# 查看可用步骤
|
||||
./scripts/test-step.sh
|
||||
- `diagnose-webhook-detail.sh` - Webhook 详细诊断
|
||||
- `diagnose-woodpecker.py` - Woodpecker CI 诊断
|
||||
- `diagnose-auto-trigger.py` - 自动触发诊断
|
||||
- `diagnose-cicd-issues.sh` - CI/CD 问题诊断
|
||||
|
||||
# Dry-run 模式（仅显示配置，不执行）
|
||||
./scripts/test-step.sh notify-wechat-success --dry-run
|
||||
### 工具脚本 (tools/)
|
||||
|
||||
# 实际执行步骤
|
||||
./scripts/test-step.sh lint
|
||||
```
|
||||
- `test-wechat-notify-*.sh` - 微信通知测试脚本（多个版本）
|
||||
- `test-webhook-headers.sh` - Webhook 头部测试
|
||||
- `test-woodpecker-config.py` - Woodpecker 配置测试
|
||||
- `test-branch-matching.py` - 分支匹配测试
|
||||
- `test-scenarios.py` - 场景测试
|
||||
- `update-jenkins-nginx.sh` - Jenkins Nginx 更新
|
||||
- `fix-jenkins-nginx.sh` - Jenkins Nginx 修复
|
||||
- `capture-webhook.sh` - Webhook 捕获
|
||||
- `analyze-best-practices.py` - 最佳实践分析
|
||||
- `check-job-triggers.groovy` - Jenkins 任务触发检查
|
||||
- `check-woodpecker-logs.sh` - Woodpecker 日志检查
|
||||
|
||||
**特性**：
|
||||
- 🔍 自动解析步骤配置
|
||||
- 🐳 使用 Docker 隔离环境
|
||||
- 🔐 模拟 Woodpecker CI 环境变量
|
||||
- 📝 显示详细执行信息
|
||||
## 使用说明
|
||||
|
||||
### 3. `test-woodpecker-local.sh` - 本地测试指南
|
||||
### 运行脚本
|
||||
|
||||
**功能**：显示 Woodpecker CI 本地测试的方法和命令
|
||||
|
||||
**使用方法**：
|
||||
```bash
|
||||
./scripts/test-woodpecker-local.sh
|
||||
```
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 1. 验证配置文件
|
||||
|
||||
在提交代码前，先运行验证工具：
|
||||
大多数脚本可以直接运行：
|
||||
|
||||
```bash
|
||||
./scripts/validate-woodpecker.sh
|
||||
# 部署脚本
|
||||
bash scripts/deployment/deploy.sh
|
||||
|
||||
# 监控脚本
|
||||
bash scripts/monitoring/monitor-pipeline.sh
|
||||
|
||||
# 诊断脚本
|
||||
python scripts/diagnosis/diagnose-woodpecker.py
|
||||
```
|
||||
|
||||
如果所有检查都通过，说明配置文件基本正确。
|
||||
### 注意事项
|
||||
|
||||
### 2. 测试单个步骤
|
||||
1. **权限问题**：某些脚本可能需要 root 权限或特定用户权限
|
||||
2. **环境变量**：部分脚本依赖环境变量，请确保正确配置
|
||||
3. **依赖工具**：某些脚本依赖特定工具（如 jq、curl、python 等），请确保已安装
|
||||
|
||||
如果某个步骤有问题，可以使用单步测试工具：
|
||||
## 维护说明
|
||||
|
||||
```bash
|
||||
# 先 dry-run 查看配置
|
||||
./scripts/test-step.sh <step_name> --dry-run
|
||||
- **添加新脚本**：请根据脚本功能放入对应的子目录
|
||||
- **更新脚本**：请在脚本头部添加更新说明和版本信息
|
||||
- **删除脚本**：请确保脚本不再使用后再删除
|
||||
|
||||
# 确认无误后执行
|
||||
./scripts/test-step.sh <step_name>
|
||||
```
|
||||
## 相关文档
|
||||
|
||||
### 3. 使用 Woodpecker CLI（推荐）
|
||||
|
||||
安装 Woodpecker CLI：
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
brew install woodpecker-cli
|
||||
|
||||
# Linux
|
||||
curl -L https://github.com/woodpecker-ci/woodpecker/releases/latest/download/woodpecker-cli-linux-amd64 -o /usr/local/bin/woodpecker-cli
|
||||
chmod +x /usr/local/bin/woodpecker-cli
|
||||
```
|
||||
|
||||
本地运行整个 pipeline：
|
||||
|
||||
```bash
|
||||
woodpecker-cli exec .woodpecker.yml
|
||||
```
|
||||
|
||||
### 4. 使用 Docker 模拟
|
||||
|
||||
如果没有安装 Woodpecker CLI，可以使用 Docker：
|
||||
|
||||
```bash
|
||||
docker run --rm \
|
||||
-v $(pwd):/woodpecker/src \
|
||||
-w /woodpecker/src \
|
||||
woodpeckerci/woodpecker-cli:latest \
|
||||
exec .woodpecker.yml
|
||||
```
|
||||
|
||||
## 🔧 高级用法
|
||||
|
||||
### 测试特定分支的步骤
|
||||
|
||||
设置环境变量模拟特定分支：
|
||||
|
||||
```bash
|
||||
export CI_COMMIT_BRANCH="release/v1.0.0"
|
||||
./scripts/test-step.sh notify-wechat-success
|
||||
```
|
||||
|
||||
### 测试 secrets
|
||||
|
||||
**注意**：本地测试无法访问 Woodpecker CI 中的 secrets。
|
||||
|
||||
解决方案：
|
||||
1. 创建 `.env` 文件存储测试用的 secrets（**不要提交到 git**）
|
||||
2. 在测试时手动设置环境变量：
|
||||
|
||||
```bash
|
||||
export WECHAT_WEBHOOK="https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY"
|
||||
./scripts/test-step.sh notify-wechat-success
|
||||
```
|
||||
|
||||
### 调试环境变量
|
||||
|
||||
查看步骤会接收到哪些环境变量：
|
||||
|
||||
```bash
|
||||
./scripts/test-step.sh <step_name> --dry-run | grep "环境变量"
|
||||
```
|
||||
|
||||
## 📋 最佳实践
|
||||
|
||||
### 1. 提交前验证
|
||||
|
||||
在每次修改 `.woodpecker.yml` 后，运行：
|
||||
|
||||
```bash
|
||||
./scripts/validate-woodpecker.sh
|
||||
```
|
||||
|
||||
### 2. 逐步测试
|
||||
|
||||
不要一次性测试整个 pipeline，而是：
|
||||
|
||||
1. 先验证配置文件
|
||||
2. 再测试单个步骤
|
||||
3. 最后测试整个 pipeline
|
||||
|
||||
### 3. 使用版本控制
|
||||
|
||||
将测试脚本纳入版本控制：
|
||||
|
||||
```bash
|
||||
git add scripts/
|
||||
git commit -m "feat: 添加 Woodpecker CI 本地测试工具"
|
||||
```
|
||||
|
||||
### 4. 持续改进
|
||||
|
||||
发现新的测试需求时，更新测试脚本：
|
||||
|
||||
```bash
|
||||
# 编辑验证脚本
|
||||
vim scripts/validate-woodpecker.sh
|
||||
|
||||
# 添加新的检查项
|
||||
```
|
||||
|
||||
## 🐛 常见问题
|
||||
|
||||
### Q1: 为什么本地测试成功，但 CI 中失败？
|
||||
|
||||
**可能原因**：
|
||||
1. 环境变量不同（检查 secrets）
|
||||
2. 网络访问限制
|
||||
3. 文件权限问题
|
||||
4. Docker 镜像版本不一致
|
||||
|
||||
**解决方法**：
|
||||
```bash
|
||||
# 对比环境变量
|
||||
./scripts/test-step.sh <step_name> --dry-run
|
||||
|
||||
# 检查 CI 日志中的环境变量
|
||||
# 在 CI 中添加调试命令
|
||||
commands:
|
||||
- env | sort
|
||||
- echo "Branch: $CI_COMMIT_BRANCH"
|
||||
```
|
||||
|
||||
### Q2: 如何测试需要 secrets 的步骤？
|
||||
|
||||
**方法 1**：使用测试用的 secrets
|
||||
```bash
|
||||
export WECHAT_WEBHOOK="https://test.example.com/webhook"
|
||||
./scripts/test-step.sh notify-wechat-success
|
||||
```
|
||||
|
||||
**方法 2**：跳过 secrets 检查
|
||||
```bash
|
||||
# 修改步骤配置，使用环境变量而不是 from_secret
|
||||
```
|
||||
|
||||
### Q3: 如何测试 when 条件？
|
||||
|
||||
**方法**：设置相应的环境变量
|
||||
```bash
|
||||
# 测试 release 分支的步骤
|
||||
export CI_COMMIT_BRANCH="release/v1.0.0"
|
||||
./scripts/test-step.sh deploy-production --dry-run
|
||||
|
||||
# 测试 feature 分支的步骤
|
||||
export CI_COMMIT_BRANCH="feature/new-feature"
|
||||
./scripts/test-step.sh e2e-smoke --dry-run
|
||||
```
|
||||
|
||||
## 📚 相关资源
|
||||
|
||||
- [Woodpecker CI 官方文档](https://woodpecker-ci.org/docs/intro)
|
||||
- [Woodpecker CLI 文档](https://woodpecker-ci.org/docs/cli)
|
||||
- [Woodpecker 配置参考](https://woodpecker-ci.org/docs/usage/pipeline-syntax)
|
||||
|
||||
## 🤝 贡献
|
||||
|
||||
如果你发现新的测试需求或改进点，欢迎更新这些脚本：
|
||||
|
||||
1. Fork 项目
|
||||
2. 创建特性分支
|
||||
3. 提交改进
|
||||
4. 创建 Pull Request
|
||||
|
||||
## 📄 许可证
|
||||
|
||||
这些测试工具遵循项目的主许可证。
|
||||
- [部署文档](../docs/deployment/)
|
||||
- [监控文档](../docs/guides/monitoring.md)
|
||||
- [CI/CD 文档](../docs/guides/ci-cd.md)
|
||||
|
||||
Reference in New Issue
Block a user