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：

# 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 检查通过

---

📋 使用流程

开发新功能

# 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

集成测试

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

# 2. 验证集成测试通过

发布到生产

# 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 检查失败

# 本地运行 Lint 检查
npm run lint

# 自动修复
npm run lint:fix

问题2: 类型检查失败

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

问题3: 单元测试失败

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

# 查看覆盖率
npm run test:coverage

问题4: E2E 测试失败

# 本地运行 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. 增量测试: 只运行受影响的测试

---

🔔 通知配置（待实现）

企业微信通知

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]

钉钉通知

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]

---

📚 相关文档

• 验收报告
• 配置文件
• 测试脚本

---

💡 最佳实践

提交信息规范

使用 Conventional Commits 规范：

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

分支命名规范

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

版本标签规范

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

---

🆘 获取帮助

遇到问题时：

1. 查看本文档
2. 查看 验收报告
3. 查看 CI 运行日志
4. 联系运维团队

---

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