张翔
34ce9fb968
- 禁用Git LFS（项目未使用LFS） - 修复企业微信通知环境变量展开问题 - 创建CI/CD诊断脚本 - 建立持续监控机制 - 添加预防措施文档 问题根本原因: 1. Woodpecker CI Git插件默认启用LFS，导致不必要的LFS命令执行 2. Shell脚本heredoc块内变量展开时机问题导致环境变量丢失 修复方案: 1. 在clone配置中添加 lfs: false 2. 将环境变量赋值移到单独的命令行，heredoc仅用于生成JSON 验证方法: - 运行 diagnose-cicd-issues.sh 进行诊断 - 运行 scripts/monitoring/cicd-monitor.sh 进行监控
242 lines
5.6 KiB
Markdown
242 lines
5.6 KiB
Markdown
# 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
|
||
**维护人员**: 张翔
|