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

解决方案：

services:
  docker:
    image: docker:dind
    privileged: true
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

2. 测试超时

错误信息：Test timeout of 30000ms exceeded

解决方案： 在.woodpecker.yml中增加超时时间：

environment:
  - TEST_TIMEOUT=60000

3. 依赖安装失败

错误信息：npm install failed

解决方案：

commands:
  - npm ci --prefer-offline --no-audit

4. 服务启动失败

错误信息：Service failed to start

解决方案：

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. 本地复现

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

3. 启用调试模式

在.woodpecker.yml中添加：

environment:
  - DEBUG=*
  - PWDEBUG=1

最佳实践

1. Pipeline设计

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

2. 资源优化

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

3. 安全性

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

4. 监控和告警

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

扩展和定制

添加新的Pipeline

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

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

使用自定义镜像

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

集成其他工具

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

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

相关资源

• Woodpecker CI官方文档
• Woodpecker CI插件市场
• Playwright CI/CD集成
• Docker Compose文档

联系方式

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