novalon-website/scripts/README.md

# Woodpecker CI 本地测试工具

本目录包含用于本地测试和验证 Woodpecker CI 配置的工具。

## 📁 文件说明

### 1. `validate-woodpecker.sh` - 配置验证工具

**功能**：全面验证 `.woodpecker.yml` 配置文件的正确性

**检查项目**：
- ✅ YAML 语法检查
- ✅ 必需字段检查（steps, image, commands）
- ✅ 镜像格式验证
- ✅ 环境变量和 secrets 检查
- ✅ when 条件逻辑分析
- ✅ 执行顺序模拟

**使用方法**：
```bash
./scripts/validate-woodpecker.sh
```

**输出示例**：
```
==========================================
Woodpecker CI 配置本地验证工具
==========================================

✅ 文件存在: .woodpecker.yml

1️⃣  YAML 语法检查
----------------------------------------
✅ YAML 语法正确

2️⃣  检查必需字段
----------------------------------------
  ✅ 步骤 'lint' 有分支条件: ['feature/**', 'dev', 'release', 'release/**']
  ✅ 步骤 'lint' 有事件条件: ['push', 'pull_request']
  ...
```

### 2. `test-step.sh` - 单步测试工具

**功能**：在本地 Docker 环境中测试单个 pipeline 步骤

**使用方法**：
```bash
# 查看可用步骤
./scripts/test-step.sh

# Dry-run 模式（仅显示配置，不执行）
./scripts/test-step.sh notify-wechat-success --dry-run

# 实际执行步骤
./scripts/test-step.sh lint
```

**特性**：
- 🔍 自动解析步骤配置
- 🐳 使用 Docker 隔离环境
- 🔐 模拟 Woodpecker CI 环境变量
- 📝 显示详细执行信息

### 3. `test-woodpecker-local.sh` - 本地测试指南

**功能**：显示 Woodpecker CI 本地测试的方法和命令

**使用方法**：
```bash
./scripts/test-woodpecker-local.sh
```

## 🚀 快速开始

### 1. 验证配置文件

在提交代码前，先运行验证工具：

```bash
./scripts/validate-woodpecker.sh
```

如果所有检查都通过，说明配置文件基本正确。

### 2. 测试单个步骤

如果某个步骤有问题，可以使用单步测试工具：

```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

## 📄 许可证

这些测试工具遵循项目的主许可证。