shipping-and-launch

发布与上线

概述

放心发布。目标不只是部署，更要安全地部署：做好监控，准备好回滚方案，并清楚了解成功的标准。每次上线都应可撤销、可观测，并分阶段进行。

适用场景

• 首次将功能部署到生产环境
• 向用户发布重大变更
• 迁移数据或基础设施
• 开启 Beta 版或早期访问计划
• 任何有风险的部署（所有部署都有风险）

上线前检查清单

代码质量

• 所有测试均已通过（单元测试、集成测试、端到端测试）
• 构建成功且没有警告
• Lint 和类型检查均已通过
• 代码已审查并获批准
• 没有应在上线前处理的 TODO 注释
• 生产代码中没有 console.log 调试语句
• 错误处理涵盖了预期的故障模式

安全性

• 代码或版本控制中没有密钥
• 生态系统的依赖项审计（npm audit、pip-audit、cargo audit 等）未发现严重或高危漏洞
• 所有面向用户的端点都进行了输入验证
• 已设置身份验证和授权检查
• 已配置安全标头（CSP、HSTS 等）
• 身份验证端点已启用速率限制
• CORS 已配置为仅允许特定来源（而非通配符）

性能

• Core Web Vitals 符合“良好”阈值
• 关键路径中没有 N+1 查询
• 图片已优化（压缩、自适应尺寸、延迟加载）
• 包体积在预算范围内
• 数据库查询已配置适当的索引
• 已为静态资源和重复查询配置缓存

无障碍

• 所有交互元素均可通过键盘操作
• 屏幕阅读器能够传达页面内容和结构
• 颜色对比度符合 WCAG 2.1 AA（文本为 4.5:1）
• 模态框和动态内容的焦点管理正确
• 错误消息描述清晰，并与表单字段关联
• axe-core 或 Lighthouse 中没有无障碍警告

基础设施

• 已在生产环境中设置环境变量
• 数据库迁移已应用（或已准备好应用）
• 已配置 DNS 和 SSL
• 已为静态资源配置 CDN
• 已配置日志记录和错误报告
• 健康检查端点已创建且能够正常响应

文档

• README 已更新所有新增的设置要求
• API 文档为最新版本
• 已为所有架构决策编写 ADR
• 更新日志已更新
• 面向用户的文档已更新（如适用）

功能标志策略

通过功能标志发布，将部署与发布解耦：

// Feature flag check
const flags = await getFeatureFlags(userId);

if (flags.taskSharing) {
  // New feature: task sharing
  return <TaskSharingPanel task={task} />;
}

// Default: existing behavior
return null;

功能标志生命周期：

1. DEPLOY with flag OFF     → Code is in production but inactive
2. ENABLE for team/beta     → Internal testing in production environment
3. GRADUAL ROLLOUT          → 5% → 25% → 50% → 100% of users
4. MONITOR at each stage    → Watch error rates, performance, user feedback
5. CLEAN UP                 → Remove flag and dead code path after full rollout

规则：

• 每个功能标志都必须有负责人和过期日期
• 全面推出后 2 周内清理功能标志
• 不要嵌套功能标志（会造成组合数量呈指数增长）
• 在 CI 中测试标志的两种状态（开启和关闭）

分阶段发布

发布顺序

1. DEPLOY to staging
   └── Full test suite in staging environment
   └── Manual smoke test of critical flows

2. DEPLOY to production (feature flag OFF)
   └── Verify deployment succeeded (health check)
   └── Check error monitoring (no new errors)

3. ENABLE for team (flag ON for internal users)
   └── Team uses the feature in production
   └── 24-hour monitoring window

4. CANARY rollout (flag ON for 5% of users)
   └── Monitor error rates, latency, user behavior
   └── Compare metrics: canary vs. baseline
   └── 24-48 hour monitoring window
   └── Advance only if all thresholds pass (see table below)

5. GRADUAL increase (25% -> 50% -> 100%)
   └── Same monitoring at each step
   └── Ability to roll back to previous percentage at any point

6. FULL rollout (flag ON for all users)
   └── Monitor for 1 week
   └── Clean up feature flag

发布决策阈值

使用以下阈值，在每个阶段判断是继续推进、暂停调查还是回滚：

指标	继续推进（绿色）	暂停并调查（黄色）	回滚（红色）
错误率	与基线相差不超过 10%	高于基线 10-100%	>2 倍基线
P95 延迟	与基线相差不超过 20%	高于基线 20-50%	高于基线 >50%
客户端 JS 错误	没有新的错误类型	新错误影响 <0.1% 的会话	新错误影响 >0.1% 的会话
业务指标	持平或上升	下降 <5%（可能是噪声）	下降 >5%

何时回滚

出现以下情况时立即回滚：

• 错误率增加超过基线的 2 倍
• P95 延迟增加超过 50%
• 用户反馈的问题激增
• 检测到数据完整性问题
• 发现安全漏洞

监控与可观测性

监控内容

Application metrics:
├── Error rate (total and by endpoint)
├── Response time (p50, p95, p99)
├── Request volume
├── Active users
└── Key business metrics (conversion, engagement)

Infrastructure metrics:
├── CPU and memory utilization
├── Database connection pool usage
├── Disk space
├── Network latency
└── Queue depth (if applicable)

Client metrics:
├── Core Web Vitals (LCP, INP, CLS)
├── JavaScript errors
├── API error rates from client perspective
└── Page load time

错误报告

// Set up error boundary with reporting
class ErrorBoundary extends React.Component {
  state = { hasError: false };

  static getDerivedStateFromError() {
    return { hasError: true };
  }

  componentDidCatch(error: Error, info: React.ErrorInfo) {
    // Report to error tracking service
    reportError(error, {
      componentStack: info.componentStack,
      userId: getCurrentUser()?.id,
      page: window.location.pathname,
    });
  }

  render() {
    if (this.state.hasError) {
      return <ErrorFallback onRetry={() => this.setState({ hasError: false })} />;
    }
    return this.props.children;
  }
}

// Server-side error reporting
app.use((err: Error, req: Request, res: Response, next: NextFunction) => {
  reportError(err, {
    method: req.method,
    url: req.url,
    userId: req.user?.id,
  });

  // Don't expose internals to users
  res.status(500).json({
    error: { code: 'INTERNAL_ERROR', message: 'Something went wrong' },
  });
});

上线后验证

上线后的第一个小时内：

1. Check health endpoint returns 200
2. Check error monitoring dashboard (no new error types)
3. Check latency dashboard (no regression)
4. Test the critical user flow manually
5. Verify logs are flowing and readable
6. Confirm rollback mechanism works (dry run if possible)

错误预算发布门槛

服务的错误预算（即 SLO 允许失败的请求或时间占比）决定了发布是否安全。将其作为客观门槛，而不是协商事项：

Budget remaining > 20%  →  Ship normally; monitor closely
Budget remaining 0–20%  →  Slow rollouts only; no high-risk changes
Budget exhausted        →  Freeze feature work; focus entirely on reliability
Budget resets           →  Resume normal pace; bake in the fix that recovered it

在金丝雀发布期间，如果消耗预算的速度高于基准速率，即出现较高的消耗速率，这是上方发布阈值表中的暂停信号；应将其视为错误率升高的同等情况。

回滚策略

每次部署前都需要制定回滚计划：

## Rollback Plan for [Feature/Release]

### Trigger Conditions
- Error rate > 2x baseline
- P95 latency > [X]ms
- User reports of [specific issue]

### Rollback Steps
1. Disable feature flag (if applicable)
   OR
1. Deploy previous version: `git revert <commit> && git push`
2. Verify rollback: health check, error monitoring
3. Communicate: notify team of rollback

### Database Considerations
- Migration [X] has a rollback: <verified command or runbook link>
- Data inserted by new feature: [preserved / cleaned up]

### Time to Rollback
- Feature flag: < 1 minute
- Redeploy previous version: < 5 minutes
- Database rollback: < 15 minutes

另请参阅

• 如需了解项目范围内每项变更都必须在通过此清单前满足的完成定义，请参阅 ../../references/definition-of-done.md
• 如需了解上线前的安全检查，请参阅 ../../references/security-checklist.md
• 如需了解上线前的性能检查清单，请参阅 ../../references/performance-checklist.md
• 如需了解上线前的无障碍验证，请参阅 ../../references/accessibility-checklist.md
• 如需了解告警规则和与 SLO 挂钩的阈值，请参阅 observability-and-instrumentation

常见借口

借口	事实
“在预发布环境中能用，在生产环境中也能用。”	生产环境的数据、流量模式和边缘情况都不同。部署后要进行监控。
“这个功能不需要功能标志。”	每项功能都适合配备紧急关闭开关。即使是“简单”的变更也可能造成问题。
“监控是额外负担。”	没有监控，就只能从用户投诉中发现问题，而无法通过仪表板及时发现。
“以后再添加监控。”	在上线前添加。看不到的问题就无法调试。
“回滚就等于承认失败。”	回滚是负责任的工程实践。发布有问题的功能才是失败。
“错误率看起来没问题，继续发布吧。”	要检查消耗速率，而不仅是当前错误率。即使各项阈值均为绿色，只要预算消耗速度高于基准速率，就应暂停。

危险信号

• 部署时没有回滚计划
• 生产环境没有监控或错误报告
• 一次性大规模发布（同时发布所有内容，不经过分阶段发布）
• 功能标志没有过期时间或负责人
• 没有人在部署后的第一个小时内监控
• 生产环境配置靠记忆而非代码完成
• “现在是周五下午，直接发布吧”
• 错误预算已耗尽，但功能开发仍照常继续

验证

部署前：

• 已完成上线前检查清单（所有部分均为绿色）
• 已配置功能标志（如适用）
• 已记录回滚计划
• 已设置监控仪表板
• 已通知团队有关部署的安排

部署后：

• 健康检查返回 200
• 错误率正常
• 延迟正常
• 关键用户流程正常
• 日志正常流入
• 已测试回滚，或确认回滚已准备就绪

适用于每项已发布的服务：

• 已制定错误预算策略：明确预算降至 20% 以下以及预算耗尽时应采取的措施