# CI/CD 问题预防机制与快速修复指南

## 📋 已识别的问题与解决方案

### 问题1: Git LFS 执行失败

**根本原因**:
- Woodpecker CI 的 Git 插件默认启用 LFS 支持
- 项目未使用 Git LFS，但 CI 仍尝试执行 `git lfs fetch` 和 `git lfs checkout`

**解决方案**:
```yaml
clone:
  git:
    image: woodpeckerci/plugin-git
    settings:
      depth: 1
      partial: false
      lfs: false  # 禁用 LFS
```

**验证方法**:
```bash
# 检查项目是否使用 LFS
ls -la .gitattributes  # 应该不存在或无 LFS 配置
git lfs env  # 应该返回 "Git LFS not configured"

# 检查 CI 配置
grep "lfs: false" .woodpecker.yml
```

---

### 问题2: 企业微信通知变量丢失

**根本原因**:
- Shell 脚本中的 heredoc 块内变量展开时机问题
- 多行命令块导致环境变量未正确传递

**解决方案**:
```yaml
commands:
  # 将变量赋值移到单独的命令行
  - BRANCH="${CI_COMMIT_BRANCH:-unknown}"
  - COMMIT="${CI_COMMIT_SHA:0:7}"
  - MESSAGE=$(echo "${CI_COMMIT_MESSAGE:-no message}" | tr '\n' ' ' | sed 's/"/\\"/g')
  - AUTHOR="${CI_COMMIT_AUTHOR:-unknown}"
  - PIPELINE_NUMBER="${CI_PIPELINE_NUMBER:-0}"
  - REPO_ID="${CI_REPO_ID:-1}"
  - TIMESTAMP=$(date "+%Y-%m-%d %H:%M:%S")
  # heredoc 只用于生成 JSON
  - |
    cat > /tmp/payload.json <<EOF
    {
      "msgtype": "markdown",
      "markdown": {
        "content": "## 🚀 Novalon Website 部署通知\n\n> **构建状态**: <font color=\"info\">成功</font>\n\n**项目信息**\n> 分支: \`${BRANCH}\`\n> 提交: \`${COMMIT}\`\n> 作者: ${AUTHOR}\n\n**提交信息**\n> ${MESSAGE}\n\n**操作**\n> [查看构建详情](https://ci.f.novalon.cn/repos/${REPO_ID}/pipeline/${PIPELINE_NUMBER})\n\n---\n> 时间: ${TIMESTAMP}\n> Pipeline #${PIPELINE_NUMBER}"
      }
    }
    EOF
  - curl -X POST "$WECHAT_WEBHOOK" -H 'Content-Type: application/json' -d @/tmp/payload.json
```

**验证方法**:
```bash
# 本地测试企业微信通知
export WECHAT_WEBHOOK='your_webhook_url'
./scripts/test-wechat-notify.sh

# 检查变量展开
echo "BRANCH: ${CI_COMMIT_BRANCH:-unknown}"
echo "COMMIT: ${CI_COMMIT_SHA:0:7}"
```

---

## 🔍 持续监控机制

### 1. 自动化监控脚本

运行监控脚本:
```bash
chmod +x scripts/monitoring/cicd-monitor.sh
./scripts/monitoring/cicd-monitor.sh
```

### 2. 定时监控（Cron）

添加到 crontab:
```bash
# 每小时运行一次监控
0 * * * * cd /path/to/novalon-website && ./scripts/monitoring/cicd-monitor.sh

# 每天凌晨2点清理旧日志
0 2 * * * find /path/to/novalon-website/logs/cicd-monitor -name "*.log" -mtime +7 -delete
```

### 3. 监控指标

| 指标 | 正常值 | 异常处理 |
|------|--------|----------|
| Git LFS 配置 | 禁用 | 检查 `.woodpecker.yml` |
| YAML 语法 | 通过 | 运行 `yamllint .woodpecker.yml` |
| 环境变量展开 | 正确 | 检查通知脚本格式 |
| Secrets 配置 | 完整 | 在 Woodpecker CI 中配置 |
| 健康检查 | 已配置 | 检查部署步骤 |

---

## 🚨 快速故障排查流程

### Step 1: 识别问题类型

```bash
# 运行诊断脚本
./diagnose-cicd-issues.sh
```

### Step 2: 检查 CI 日志

访问: https://ci.f.novalon.cn/repos/1/pipeline/[PIPELINE_NUMBER]

关键检查点:
- ✅ Clone 步骤是否成功
- ✅ 环境变量是否正确传递
- ✅ 通知是否发送成功

### Step 3: 本地验证

```bash
# 验证 Git LFS
git lfs env

# 验证 YAML 语法
yamllint .woodpecker.yml

# 测试企业微信通知
WECHAT_WEBHOOK='your_webhook' ./scripts/test-wechat-notify.sh
```

### Step 4: 修复并验证

1. 修改配置文件
2. 提交并推送到测试分支
3. 观察 CI 执行结果
4. 验证通知是否正常

---

## 📊 预防措施清单

### 配置层面

- [x] 禁用 Git LFS（项目未使用）
- [x] 修复环境变量展开格式
- [x] 配置健康检查和回滚机制
- [x] 使用 Secret 管理敏感信息
- [ ] 添加 npm 缓存（优化性能）
- [ ] 配置分支保护规则

### 监控层面

- [x] 创建监控脚本
- [x] 建立日志记录机制
- [ ] 配置告警通知
- [ ] 集成到 CI/CD 流程

### 文档层面

- [x] 问题预防机制文档
- [x] 快速修复指南
- [x] 故障排查流程
- [ ] 定期更新最佳实践

---

## 🎯 后续优化建议

### 高优先级（本周）

1. **添加 npm 缓存**
   ```yaml
   steps:
     lint:
       image: node:20-alpine
       commands:
         - npm ci
       cache:
         mount:
           - node_modules
           - .npm
   ```

2. **配置分支保护规则**
   - main 分支：禁止直接推送
   - release/** 分支：需要 PR 审核
   - dev 分支：需要 CI 检查通过

3. **添加部署告警**
   - 连续失败 3 次发送告警
   - 部署超时发送告警
   - 健康检查失败发送告警

### 中优先级（本月）

1. **容器镜像安全扫描**
   - 使用 Trivy 扫描镜像漏洞
   - 发现 Critical 漏洞阻止部署

2. **集成 APM 监控**
   - 使用 Sentry 监控应用性能
   - 自动上报错误和性能指标

3. **优化测试策略**
   - 并行执行 E2E 测试
   - 减少测试时间 30-50%

---

## 📝 变更记录

| 日期 | 变更内容 | 负责人 |
|------|---------|--------|
| 2026-03-29 | 禁用 Git LFS | 张翔 |
| 2026-03-29 | 修复企业微信通知变量展开 | 张翔 |
| 2026-03-29 | 创建监控脚本 | 张翔 |
| 2026-03-29 | 建立预防机制文档 | 张翔 |

---

## 🔗 相关文档

- [Woodpecker CI 官方文档](https://woodpecker-ci.org/)
- [Git LFS 文档](https://git-lfs.github.com/)
- [Shell 变量展开](https://www.gnu.org/software/bash/manual/html_node/Shell-Parameter-Expansion.html)
- [YAML 语法检查](https://yamllint.readthedocs.io/)

---

**最后更新**: 2026-03-29  
**维护人员**: 张翔