everything-is-suitable/WOODPECKER_CI.md

# Woodpecker CI配置说明

## 概述

本项目使用Woodpecker CI作为持续集成/持续部署（CI/CD）工具。Woodpecker CI是一个轻量级、可扩展的CI/CD平台，支持Docker容器化部署。

## 配置文件

Woodpecker CI配置文件位于项目根目录：`.woodpecker.yml`

## Pipeline结构

### 主要Pipeline

#### 1. Setup Pipeline
- **作用**：初始化Docker环境
- **镜像**：`docker:dind`
- **触发条件**：推送到main/develop分支、PR、标签

#### 2. E2E Tests Pipeline
- **作用**：执行端到端测试
- **镜像**：`node:18`
- **并行执行**：4个分片
- **触发条件**：推送到main/develop分支、PR、标签
- **依赖**：setup

#### 3. API Tests Pipeline
- **作用**：执行API集成测试
- **镜像**：`node:18`
- **触发条件**：推送到main/develop分支、PR、标签
- **依赖**：setup

#### 4. Test Report Pipeline
- **作用**：合并测试报告
- **镜像**：`node:18`
- **触发条件**：测试完成后（成功或失败）
- **依赖**：e2e-tests, api-tests

#### 5. Notify Failure Pipeline
- **作用**：测试失败时发送Slack通知
- **镜像**：`plugins/slack`
- **触发条件**：测试失败
- **依赖**：e2e-tests, api-tests

#### 6. Nightly Tests Pipeline
- **作用**：每日定时执行完整测试
- **镜像**：`node:18`
- **触发条件**：每天凌晨2点（cron: "0 2 * * *"）
- **依赖**：setup

## 环境变量配置

在Woodpecker CI管理界面配置以下环境变量：

### 必需变量

| 变量名 | 描述 | 示例 |
|--------|------|------|
| `ADMIN_BASE_URL` | Admin模块URL | `http://localhost:5174` |
| `UNIAPP_BASE_URL` | Uniapp模块URL | `http://localhost:8081` |
| `API_BASE_URL` | 后端API URL | `http://localhost:8080` |
| `TEST_USERNAME` | 测试账号用户名 | `admin` |
| `TEST_PASSWORD` | 测试账号密码 | `admin123` |

### 可选变量

| 变量名 | 描述 | 示例 |
|--------|------|------|
| `SLACK_WEBHOOK` | Slack通知Webhook URL | `https://hooks.slack.com/...` |
| `MOCK_ENABLED` | 是否启用Mock | `false` |
| `TEST_TIMEOUT` | 测试超时时间(ms) | `30000` |

## 触发条件

### 自动触发

- **Push事件**：代码推送到main或develop分支
- **Pull Request事件**：创建或更新PR
- **Tag事件**：创建新的标签
- **定时任务**：每天凌晨2点执行完整测试

### 手动触发

在Woodpecker CI界面中，可以手动触发任何Pipeline。

## 测试执行流程

### E2E测试流程

1. **Setup阶段**：初始化Docker环境
2. **安装依赖**：安装npm依赖和Playwright浏览器
3. **启动服务**：使用docker-compose启动测试环境
4. **执行测试**：并行运行E2E测试（4个分片）
5. **清理环境**：停止并清理Docker容器
6. **生成报告**：合并测试报告并生成HTML报告

### API测试流程

1. **Setup阶段**：初始化Docker环境
2. **安装依赖**：安装npm依赖
3. **启动服务**：仅启动后端服务
4. **执行测试**：运行API集成测试
5. **清理环境**：停止并清理Docker容器

## 并行执行

Woodpecker CI支持并行执行测试以提高效率：

- **E2E测试**：4个并行分片（CI_NODE_INDEX: 1-4）
- **API测试**：独立执行

## 测试报告

### 报告生成

测试完成后会自动生成以下报告：

- **HTML报告**：交互式HTML报告
- **JSON报告**：机器可读的JSON格式
- **JUnit报告**：兼容JUnit的XML格式

### 报告位置

- `playwright-report/`：HTML报告
- `test-results/results.json`：JSON报告
- `test-results/junit.xml`：JUnit报告

### 查看报告

在Woodpecker CI界面中，可以：
1. 查看Pipeline执行日志
2. 下载测试报告artifacts
3. 查看测试截图和录屏

## 通知配置

### Slack通知

当测试失败时，会自动发送Slack通知：

1. 在Woodpecker CI中配置`SLACK_WEBHOOK`环境变量
2. 通知会发送到指定的Slack频道
3. 通知内容包括：
   - 失败的Pipeline名称
   - 失败的原因
   - 相关的commit信息

### 其他通知方式

Woodpecker CI支持多种通知插件：
- Email
- Discord
- Rocket.Chat
- Matrix
- Telegram

## 故障排查

### 常见问题

#### 1. Docker权限问题

**错误信息**：`permission denied while trying to connect to the Docker daemon socket`

**解决方案**：
```yaml
services:
  docker:
    image: docker:dind
    privileged: true
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
```

#### 2. 测试超时

**错误信息**：`Test timeout of 30000ms exceeded`

**解决方案**：
在`.woodpecker.yml`中增加超时时间：
```yaml
environment:
  - TEST_TIMEOUT=60000
```

#### 3. 依赖安装失败

**错误信息**：`npm install failed`

**解决方案**：
```yaml
commands:
  - npm ci --prefer-offline --no-audit
```

#### 4. 服务启动失败

**错误信息**：`Service failed to start`

**解决方案**：
```yaml
commands:
  - docker-compose -f ../docker-compose.test.yml up -d
  - sleep 60  # 增加等待时间
  - docker-compose -f ../docker-compose.test.yml ps  # 检查服务状态
```

### 调试技巧

#### 1. 查看详细日志

在Woodpecker CI界面中：
1. 点击失败的Pipeline
2. 查看详细的执行日志
3. 下载完整的日志文件

#### 2. 本地复现

```bash
# 使用相同的命令在本地执行
cd everything-is-suitable-test
npm ci
docker-compose -f ../docker-compose.test.yml up -d
npx playwright test
```

#### 3. 启用调试模式

在`.woodpecker.yml`中添加：
```yaml
environment:
  - DEBUG=*
  - PWDEBUG=1
```

## 最佳实践

### 1. Pipeline设计

- **模块化**：将不同类型的测试分离到独立的Pipeline
- **并行化**：充分利用并行执行提高效率
- **依赖管理**：明确Pipeline之间的依赖关系

### 2. 资源优化

- **缓存依赖**：使用npm缓存加速依赖安装
- **重用容器**：在可能的情况下重用Docker容器
- **清理资源**：测试完成后及时清理资源

### 3. 安全性

- **敏感信息**：使用环境变量存储敏感信息
- **最小权限**：仅授予必要的权限
- **定期更新**：及时更新镜像和依赖

### 4. 监控和告警

- **实时监控**：监控Pipeline执行状态
- **及时通知**：配置适当的通知机制
- **定期审查**：定期审查Pipeline执行日志

## 扩展和定制

### 添加新的Pipeline

在`.woodpecker.yml`中添加新的Pipeline：

```yaml
  new-pipeline:
    image: node:18
    commands:
      - echo "执行新的测试"
    when:
      event: [push]
      branch: [main]
```

### 使用自定义镜像

```yaml
  custom-test:
    image: your-registry/custom-image:latest
    commands:
      - echo "使用自定义镜像"
```

### 集成其他工具

Woodpecker CI支持丰富的插件生态：

- **代码质量**：SonarQube, CodeClimate
- **部署**：Kubernetes, AWS, GCP
- **通知**：Slack, Email, Discord
- **安全扫描**：Trivy, Snyk

## 相关资源

- [Woodpecker CI官方文档](https://woodpecker-ci.org/docs/)
- [Woodpecker CI插件市场](https://woodpecker-ci.org/plugins/)
- [Playwright CI/CD集成](https://playwright.dev/docs/ci)
- [Docker Compose文档](https://docs.docker.com/compose/)

## 联系方式

如有问题或建议，请联系DevOps团队。