novalon-website/CICD_QUICKSTART.md

# Woodpecker CI/CD 快速启动指南

## 🚀 快速开始

### 1. 前置准备

确保以下条件已满足：

- ✅ Git 仓库已配置 Woodpecker CI
- ✅ 已配置以下 Secrets：
  - `ssh_private_key`: SSH 私钥（用于 Git 操作和服务器部署）
  - `registry_password`: Docker Registry 密码

### 2. 配置 Secrets

在 Woodpecker CI 界面中配置以下 Secrets：

```bash
# SSH 私钥（用于 Git 操作和服务器部署）
ssh_private_key: |
  -----BEGIN OPENSSH PRIVATE KEY-----
  ...
  -----END OPENSSH PRIVATE KEY-----

# Docker Registry 密码
registry_password: your_registry_password
```

### 3. 配置 Git 分支保护规则

在 Git 仓库设置中配置：

#### main 分支
- ✅ 禁止直接推送
- ✅ 禁止强制推送
- ✅ 仅允许 CI 自动合并

#### release/** 分支
- ✅ 禁止强制推送
- ✅ 需要 PR 审核通过

#### dev 分支
- ✅ 需要 PR 审核通过
- ✅ 需要 CI 检查通过

---

## 📋 使用流程

### 开发新功能

```bash
# 1. 从 dev 创建 feature 分支
git checkout dev
git pull origin dev
git checkout -b feature/new-feature

# 2. 开发并提交代码
git add .
git commit -m "feat: 添加新功能"
git push origin feature/new-feature

# 3. 创建 PR 到 dev 分支
# CI 自动执行: Lint + TypeCheck + Unit Test + Smoke E2E

# 4. PR 审核通过后合并到 dev
```

### 集成测试

```bash
# 1. feature 分支合并到 dev 后
# CI 自动执行: Lint + TypeCheck + Unit Test + Standard E2E

# 2. 验证集成测试通过
```

### 发布到生产

```bash
# 1. 从 dev 创建 release 分支
git checkout dev
git pull origin dev
git checkout -b release/v1.0.0
git push origin release/v1.0.0

# 2. CI 自动执行完整流程:
# - 完整测试套件
# - 构建 Docker 镜像
# - 部署到生产环境
# - 归档到 main 分支
# - 创建版本标签

# 3. 验证部署成功
curl https://novalon.cn/api/health
```

---

## 🔍 监控与调试

### 查看 CI 运行状态

1. 访问 Woodpecker CI 界面
2. 选择对应的仓库
3. 查看最新的 Pipeline 运行状态

### 常见问题排查

#### 问题1: Lint 检查失败

```bash
# 本地运行 Lint 检查
npm run lint

# 自动修复
npm run lint:fix
```

#### 问题2: 类型检查失败

```bash
# 本地运行类型检查
npm run type-check
```

#### 问题3: 单元测试失败

```bash
# 本地运行单元测试
npm run test

# 查看覆盖率
npm run test:coverage
```

#### 问题4: E2E 测试失败

```bash
# 本地运行 E2E 测试
npm run test:e2e

# 运行特定测试
npx playwright test tests/smoke.spec.ts
```

#### 问题5: 部署失败

1. 检查健康检查日志
2. 检查服务器日志
3. 验证 Secrets 配置
4. 检查网络连接

---

## 🎯 质量门禁

### feature 分支

| 检查项 | 通过标准 | 失败后果 |
|--------|---------|---------|
| Lint | 0 errors | ❌ 阻止合并 |
| TypeCheck | 0 errors | ❌ 阻止合并 |
| Unit Test | 覆盖率 ≥ 80% | ❌ 阻止合并 |
| Smoke E2E | 100% 通过 | ❌ 阻止合并 |

### dev 分支

| 检查项 | 通过标准 | 失败后果 |
|--------|---------|---------|
| Lint | 0 errors | ❌ 阻止合并 |
| TypeCheck | 0 errors | ❌ 阻止合并 |
| Unit Test | 覆盖率 ≥ 80% | ❌ 阻止合并 |
| Standard E2E | 100% 通过 | ❌ 阻止合并 |

### release 分支

| 检查项 | 通过标准 | 失败后果 |
|--------|---------|---------|
| 完整测试套件 | 100% 通过 | ❌ 阻止部署 |
| 健康检查 | HTTP 200 OK | ❌ 自动回滚 |

---

## 📊 性能指标

### 预期执行时间

| 分支类型 | 预期时间 | 主要步骤 |
|---------|---------|---------|
| feature/** | 5-10 分钟 | Lint + TypeCheck + Unit Test + Smoke E2E |
| dev | 10-15 分钟 | Lint + TypeCheck + Unit Test + Standard E2E |
| release/** | 30-45 分钟 | 完整测试 + 构建 + 部署 + 归档 |

### 优化建议

1. **添加缓存**: 减少 50-70% 的依赖安装时间
2. **并行执行**: 减少 30-50% 的测试时间
3. **增量测试**: 只运行受影响的测试

---

## 🔔 通知配置（待实现）

### 企业微信通知

```yaml
notify-wechat:
  image: alpine:latest
  commands:
    - |
      curl -X POST "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY" \
        -H 'Content-Type: application/json' \
        -d '{
          "msgtype": "markdown",
          "markdown": {
            "content": "## 部署通知\n> 状态: 成功\n> 分支: release/v1.0.0\n> 提交: abc1234"
          }
        }'
  when:
    status: [success, failure]
```

### 钉钉通知

```yaml
notify-dingtalk:
  image: alpine:latest
  commands:
    - |
      curl -X POST "https://oapi.dingtalk.com/robot/send?access_token=YOUR_TOKEN" \
        -H 'Content-Type: application/json' \
        -d '{
          "msgtype": "markdown",
          "markdown": {
            "title": "部署通知",
            "text": "## 部署通知\n> 状态: 成功\n> 分支: release/v1.0.0"
          }
        }'
  when:
    status: [success, failure]
```

---

## 📚 相关文档

- [验收报告](./CICD_ACCEPTANCE_REPORT.md)
- [配置文件](./.woodpecker.yml)
- [测试脚本](./test-woodpecker-config.py)

---

## 💡 最佳实践

### 提交信息规范

使用 [Conventional Commits](https://www.conventionalcommits.org/) 规范：

```
feat: 添加新功能
fix: 修复 bug
docs: 更新文档
style: 代码格式调整
refactor: 重构代码
test: 添加测试
chore: 构建/工具链更新
```

### 分支命名规范

```
feature/功能名称    # 新功能开发
bugfix/问题描述     # Bug 修复
hotfix/紧急修复     # 紧急修复
release/v版本号     # 发布分支
```

### 版本标签规范

```
v2026.03.28-abc1234
│  │  │  └─ commit SHA 前 7 位
│  │  └──── 日期
│  └─────── 年份
└────────── 版本前缀
```

---

## 🆘 获取帮助

遇到问题时：

1. 查看本文档
2. 查看 [验收报告](./CICD_ACCEPTANCE_REPORT.md)
3. 查看 CI 运行日志
4. 联系运维团队

---

**最后更新**: 2026-03-28  
**维护者**: 张翔