novalon-website/docs/deployment/CICD_PREVENTION_GUIDE.md

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

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

问题1: Git LFS 执行失败

根本原因:

• Woodpecker CI 的 Git 插件默认启用 LFS 支持
• 项目未使用 Git LFS，但 CI 仍尝试执行 git lfs fetch 和 git lfs checkout

解决方案:

clone:
  git:
    image: woodpeckerci/plugin-git
    settings:
      depth: 1
      partial: false
      lfs: false  # 禁用 LFS

验证方法:

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

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

---

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

根本原因:

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

解决方案:

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

验证方法:

# 本地测试企业微信通知
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. 自动化监控脚本

运行监控脚本:

chmod +x scripts/monitoring/cicd-monitor.sh
./scripts/monitoring/cicd-monitor.sh

2. 定时监控（Cron）

添加到 crontab:

# 每小时运行一次监控
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: 识别问题类型

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

Step 2: 检查 CI 日志

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

关键检查点:

• ✅ Clone 步骤是否成功
• ✅ 环境变量是否正确传递
• ✅ 通知是否发送成功

Step 3: 本地验证

# 验证 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. 验证通知是否正常

---

📊 预防措施清单

配置层面

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

监控层面

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

文档层面

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

---

🎯 后续优化建议

高优先级（本周）

1. 添加 npm 缓存

   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 官方文档
• Git LFS 文档
• Shell 变量展开
• YAML 语法检查

---

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