fix: 修复企业微信通知环境变量展开问题

- 使用 PAYLOAD=$(cat <<ENDPAYLOAD) 替代 cat > file <<EOF - 确保环境变量在 heredoc 中正确展开 - 添加测试脚本验证环境变量展开 - 修复构建详情链接和消息内容缺失问题
2026-03-28 22:48:22 +08:00
parent 5a27d2fc2a
commit dd2a0999bb
35 changed files with 2728 additions and 915 deletions
@@ -0,0 +1,303 @@
+# 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  
+**维护者**: 张翔