--- name: deployment-verification description: | 部署验证技能：确保部署成功的验证工作流和检查清单。 Use when: 部署到 Vercel/GCP 后需要验证、检查环境变量同步、排查部署问题。 Triggers: "部署", "deploy", "验证", "上线", "发布", "环境变量", "CI/CD" category: deployment --- # Deployment Verification (部署验证) > 🚀 **核心理念**: 部署不是终点，验证才是。未经验证的部署等于没有部署。 ## 🔴 第一原则：部署后必须验证 **任何部署都必须经过完整验证流程！** ``` ❌ 错误思路: "代码推送了，应该没问题" ✅ 正确思路: "代码推送了，让我验证一下部署状态和功能" ❌ 错误思路: "本地测试通过了，线上肯定也行" ✅ 正确思路: "本地测试通过了，但线上环境不同，必须验证" ``` **验证优先级**: 健康检查 > 核心功能 > 边缘场景 > 性能指标 ## When to Use This Skill 使用此技能当你需要： - 部署代码到 Vercel 或 GCP Cloud Run - 验证部署是否成功 - 检查环境变量是否正确同步 - 排查部署失败的问题 - 确认 CI/CD 流程正常运行 - 验证健康检查端点 ## Not For / Boundaries 此技能不适用于： - 本地开发环境调试 - 单元测试编写 - 代码审查流程 --- ## Quick Reference ### 🎯 部署验证工作流 ``` 代码修改 → 本地测试 → Git Commit → Git Push → 等待构建 → 验证部署 → 功能测试 → 完成 ↓ ↓ 失败 → 修复 失败 → 查日志 → 修复 → 重新部署 ``` ### 📋 部署前必查清单 | 检查项 | 命令/操作 | 通过标准 | |--------|----------|----------| | 本地构建 | `npm run build` | 无错误 | | 本地测试 | `npm test` | 全部通过 | | 类型检查 | `npm run typecheck` | 无错误 | | Lint 检查 | `npm run lint` | 无错误 | | 环境变量 | 对比 `.env` 和线上 | 完全同步 | ### ✅ 部署后必验清单 | 验证项 | 方法 | 通过标准 | |--------|------|----------| | 部署状态 | 查看 CI/CD 日志 | 状态为成功 | | 健康检查 | `curl /api/health` | 返回 200 | | 核心功能 | Playwright 测试 | 功能正常 | | 控制台日志 | 浏览器 DevTools | 无错误 | | 网络请求 | Network 面板 | 无失败请求 | --- ## 部署验证工作流 ### Phase 1: 部署前准备 ```bash # 1. 确保代码质量 npm run build # 构建检查 npm run test # 测试检查 npm run lint # 代码规范检查 # 2. 检查环境变量同步 # 本地环境变量 grep -E "^[A-Z]" .env | cut -d= -f1 | sort > /tmp/local-env.txt # Vercel 环境变量 vercel env ls | grep -E "^[A-Z]" | awk '{print $1}' | sort > /tmp/vercel-env.txt # 对比差异 diff /tmp/local-env.txt /tmp/vercel-env.txt # 3. 提交代码 git add . git commit -m "feat: 描述性提交信息" git push origin main ``` ### Phase 2: 监控部署过程 ```bash # Vercel 部署监控 vercel ls --limit 5 # 查看最近部署 # 或通过 GitHub Actions gh run list --limit 5 gh run view ``` ### Phase 3: 部署后验证 ```bash # 1. 健康检查 curl -s https://your-app.vercel.app/api/health | jq # 2. 核心 API 测试 curl -s https://your-app.vercel.app/api/your-endpoint | jq # 3. Playwright 功能测试 npx playwright test --project=chromium tests/e2e/smoke.spec.ts ``` --- ## Vercel 部署验证清单 ### 🔍 部署状态检查 ```bash # 查看部署列表 vercel ls # 查看部署详情 vercel inspect # 查看部署日志 vercel logs ``` ### 📊 Vercel 仪表板检查 1. **Deployments 页面** - 确认最新部署状态为 "Ready" - 检查构建时间是否正常 - 查看是否有构建警告 2. **Functions 页面** - 确认 Serverless Functions 正常运行 - 检查函数执行时间 - 查看错误率 3. **Analytics 页面** - 检查请求成功率 - 查看响应时间分布 - 确认无异常流量 ### ⚠️ 常见 Vercel 部署问题 | 问题 | 原因 | 解决方案 | |------|------|----------| | 构建失败 | 依赖问题 | 检查 `package.json`，清除缓存重试 | | 环境变量缺失 | 未同步 | `vercel env add ` | | 函数超时 | 执行时间过长 | 优化代码或升级套餐 | | 404 错误 | 路由配置 | 检查 `vercel.json` 和路由设置 | | CORS 错误 | 跨域配置 | 添加正确的 CORS 头 | ### 🛠️ Vercel 验证脚本 ```bash # 使用内置脚本 bash .kiro/skills/deployment-verification/scripts/verify-vercel.sh ``` --- ## GCP Cloud Run 部署验证清单 ### 🔍 部署状态检查 ```bash # 查看服务列表 gcloud run services list # 查看服务详情 gcloud run services describe --region= # 查看最近修订版本 gcloud run revisions list --service= # 查看日志 gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=" --limit=50 ``` ### 📊 GCP Console 检查 1. **Cloud Run 服务页面** - 确认服务状态为绿色 - 检查最新修订版本 - 查看流量分配 2. **Metrics 页面** - 请求计数和延迟 - 容器实例数 - 内存和 CPU 使用率 3. **Logs 页面** - 应用日志 - 系统日志 - 错误日志 ### ⚠️ 常见 GCP 部署问题 | 问题 | 原因 | 解决方案 | |------|------|----------| | 部署失败 | 镜像构建错误 | 检查 Dockerfile | | 启动失败 | 端口配置 | 确保监听 `$PORT` | | 冷启动慢 | 容器初始化 | 优化启动时间或设置最小实例 | | 内存不足 | 资源限制 | 增加内存配置 | | 权限错误 | IAM 配置 | 检查服务账号权限 | ### 🛠️ GCP 验证脚本 ```bash # 使用内置脚本 bash .kiro/skills/deployment-verification/scripts/verify-gcp.sh ``` --- ## 环境变量同步检查 ### 🔑 环境变量分类 | 类别 | 示例 | 同步要求 | |------|------|----------| | API 密钥 | `GEMINI_API_KEY`, `OPENAI_API_KEY` | 必须同步 | | 数据库 | `DATABASE_URL`, `SUPABASE_*` | 必须同步 | | 第三方服务 | `LIVEKIT_*`, `STRIPE_*` | 必须同步 | | 应用配置 | `NEXT_PUBLIC_*` | 必须同步 | | 开发专用 | `DEBUG`, `LOG_LEVEL` | 可选同步 | ### 📋 同步检查流程 ```bash # 1. 导出本地环境变量名 grep -E "^[A-Z]" .env | cut -d= -f1 | sort # 2. 导出 Vercel 环境变量名 vercel env ls # 3. 手动对比或使用脚本 # 参考: references/env-sync-checklist.md ``` ### ⚠️ 常见遗漏的环境变量 ``` # AI 服务 GEMINI_API_KEY OPENAI_API_KEY ANTHROPIC_API_KEY # 实时通信 LIVEKIT_URL LIVEKIT_API_KEY LIVEKIT_API_SECRET # 数据库 DATABASE_URL SUPABASE_URL SUPABASE_ANON_KEY SUPABASE_SERVICE_ROLE_KEY # 认证 NEXTAUTH_SECRET NEXTAUTH_URL # 支付 STRIPE_SECRET_KEY STRIPE_WEBHOOK_SECRET ``` --- ## 健康检查端点验证 ### 📍 标准健康检查端点 ```typescript // /api/health.ts export async function GET() { try { // 检查数据库连接 await db.query('SELECT 1'); // 检查外部服务 const services = { database: 'ok', cache: await checkCache(), external: await checkExternalAPI(), }; return Response.json({ status: 'healthy', timestamp: new Date().toISOString(), services, }); } catch (error) { return Response.json({ status: 'unhealthy', error: error.message, }, { status: 503 }); } } ``` ### 🔍 健康检查验证 ```bash # 基本健康检查 curl -s https://your-app.vercel.app/api/health | jq # 预期响应 { "status": "healthy", "timestamp": "2025-01-01T00:00:00.000Z", "services": { "database": "ok", "cache": "ok", "external": "ok" } } # 带超时的检查 curl -s --max-time 10 https://your-app.vercel.app/api/health # 检查响应状态码 curl -s -o /dev/null -w "%{http_code}" https://your-app.vercel.app/api/health ``` --- ## 故障排查指南 ### 🔴 部署失败 ```bash # 1. 查看构建日志 vercel logs --output=raw # 2. 本地复现 npm run build 2>&1 | tee build.log # 3. 检查依赖 npm ls --depth=0 npm audit # 4. 清除缓存重试 vercel --force ``` ### 🟡 部署成功但功能异常 ```bash # 1. 检查环境变量 vercel env ls # 2. 检查函数日志 vercel logs --follow # 3. 检查网络请求 # 使用浏览器 DevTools Network 面板 # 4. Playwright 调试 npx playwright test --debug ``` ### 🟠 性能问题 ```bash # 1. 检查冷启动时间 curl -w "@curl-format.txt" -s https://your-app.vercel.app/api/health # 2. 检查函数执行时间 # Vercel Dashboard > Functions > 查看执行时间 # 3. 检查资源使用 # GCP Console > Cloud Run > Metrics ``` --- ## Examples ### Example 1: Vercel 部署验证 **场景:** 推送代码到 main 分支后验证部署 **Steps:** ```bash # 1. 推送代码 git push origin main # 2. 等待部署完成 (约 1-2 分钟) sleep 120 # 3. 检查部署状态 vercel ls --limit 1 # 4. 健康检查 curl -s https://your-app.vercel.app/api/health | jq # 5. Playwright 功能测试 npx playwright test tests/e2e/smoke.spec.ts ``` **Expected Output:** ``` ✅ 部署状态: Ready ✅ 健康检查: 200 OK ✅ 功能测试: 全部通过 ``` ### Example 2: 环境变量同步 **场景:** 添加新的 API 密钥 **Steps:** ```bash # 1. 添加到本地 .env echo "NEW_API_KEY=xxx" >> .env # 2. 添加到 Vercel vercel env add NEW_API_KEY production # 输入值: xxx # 3. 验证同步 vercel env ls | grep NEW_API_KEY # 4. 重新部署以应用新变量 vercel --prod ``` ### Example 3: 排查部署失败 **场景:** 部署失败，需要排查原因 **Steps:** ```bash # 1. 查看部署状态 vercel ls --limit 5 # 2. 查看失败日志 vercel logs # 3. 本地复现 npm run build # 4. 修复问题后重新部署 git add . git commit -m "fix: 修复构建错误" git push origin main ``` --- ## References - `references/env-sync-checklist.md`: 环境变量同步检查清单 - `scripts/verify-vercel.sh`: Vercel 部署验证脚本 - `scripts/verify-gcp.sh`: GCP Cloud Run 验证脚本 --- ## Maintenance - **Sources**: Vercel 官方文档, GCP Cloud Run 文档, 项目实践经验 - **Last Updated**: 2025-01-01 - **Known Limits**: - 脚本依赖 `vercel` CLI 和 `gcloud` CLI - 某些验证需要相应的访问权限