shipping-and-launch

发布与上线

概述

自信地发布。目标不仅仅是部署——而是安全地部署，监控到位，回滚计划就绪，并清楚了解成功的标准。每次发布都应该是可逆的、可观察的和渐进的。

何时使用

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

发布前检查清单

代码质量

• [ ] 所有测试通过（单元测试、集成测试、端到端测试）
• [ ] 构建成功，无警告
• [ ] 代码检查和类型检查通过
• [ ] 代码已审查并批准
• [ ] 没有需要在发布前解决的 TODO 注释
• [ ] 生产代码中没有 console.log 调试语句
• [ ] 错误处理覆盖预期的故障模式

安全

• [ ] 代码或版本控制中没有密钥
• [ ] npm audit 显示无严重或高危漏洞
• [ ] 所有面向用户的端点都有输入验证
• [ ] 身份验证和授权检查已就位
• [ ] 安全头已配置（CSP、HSTS 等）
• [ ] 身份验证端点已限流
• [ ] CORS 配置为特定来源（非通配符）

性能

• [ ] 核心 Web 指标在“良好”阈值内
• [ ] 关键路径中没有 N+1 查询
• [ ] 图片已优化（压缩、响应式尺寸、懒加载）
• [ ] 打包大小在预算内
• [ ] 数据库查询有适当的索引
• [ ] 静态资源和重复查询已配置缓存

无障碍

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

基础设施

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

文档

• [ ] README 已更新，包含任何新的设置要求
• [ ] API 文档是最新的
• [ ] 架构决策记录（ADR）已编写
• [ ] 变更日志已更新
• [ ] 面向用户的文档已更新（如适用）

功能开关策略

通过功能开关发布，将部署与发布解耦：

// 功能开关检查
const flags = await getFeatureFlags(userId);

if (flags.taskSharing) {
  // 新功能：任务共享
  return <TaskSharingPanel task={task} />;
}

// 默认：现有行为
return null;

功能开关生命周期：

1. 部署时开关关闭     → 代码在生产环境中但未激活
2. 为团队/Beta 启用   → 在生产环境中进行内部测试
3. 逐步发布          → 5% → 25% → 50% → 100% 的用户
4. 每个阶段监控      → 观察错误率、性能、用户反馈
5. 清理              → 完全发布后移除开关和死代码路径

规则：

• 每个功能开关都有负责人和过期日期
• 完全发布后 2 周内清理开关
• 不要嵌套功能开关（会产生指数级组合）
• 在 CI 中测试开关的两种状态（开启和关闭）

分阶段发布

发布顺序

1. 部署到预发布环境
   └── 在预发布环境中运行完整测试套件
   └── 手动冒烟测试关键流程

2. 部署到生产环境（功能开关关闭）
   └── 验证部署成功（健康检查）
   └── 检查错误监控（无新错误）

3. 为团队启用（功能开关对内部用户开启）
   └── 团队在生产环境中使用该功能
   └── 24 小时监控窗口

4. 金丝雀发布（功能开关对 5% 的用户开启）
   └── 监控错误率、延迟、用户行为
   └── 比较指标：金丝雀组 vs 基线组
   └── 24-48 小时监控窗口
   └── 仅当所有阈值通过时才推进（见下表）

5. 逐步增加（25% -> 50% -> 100%）
   └── 每一步进行相同监控
   └── 能够随时回滚到之前的百分比

6. 完全发布（功能开关对所有用户开启）
   └── 监控 1 周
   └── 清理功能开关

发布决策阈值

使用这些阈值决定在每个阶段是推进、暂停还是回滚：

指标	推进（绿色）	暂停并调查（黄色）	回滚（红色）
错误率	在基线的 10% 以内	高于基线 10-100%	高于基线 2 倍以上
P95 延迟	在基线的 20% 以内	高于基线 20-50%	高于基线 50% 以上
客户端 JS 错误	无新错误类型	新错误出现在 <0.1% 的会话中	新错误出现在 >0.1% 的会话中
业务指标	中性或正向	下降 <5%（可能是噪声）	下降 >5%

何时回滚

立即回滚，如果：

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

监控与可观测性

监控内容

应用指标：
├── 错误率（总计和按端点）
├── 响应时间（p50、p95、p99）
├── 请求量
├── 活跃用户
└── 关键业务指标（转化率、参与度）

基础设施指标：
├── CPU 和内存利用率
├── 数据库连接池使用率
├── 磁盘空间
├── 网络延迟
└── 队列深度（如适用）

客户端指标：
├── 核心 Web 指标（LCP、INP、CLS）
├── JavaScript 错误
├── 客户端视角的 API 错误率
└── 页面加载时间

错误报告

// 设置带报告的错误边界
class ErrorBoundary extends React.Component {
  componentDidCatch(error: Error, info: React.ErrorInfo) {
    // 报告给错误跟踪服务
    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;
  }
}

// 服务端错误报告
app.use((err: Error, req: Request, res: Response, next: NextFunction) => {
  reportError(err, {
    method: req.method,
    url: req.url,
    userId: req.user?.id,
  });

  // 不向用户暴露内部信息
  res.status(500).json({
    error: { code: 'INTERNAL_ERROR', message: 'Something went wrong' },
  });
});

发布后验证

发布后第一小时内：

1. 检查健康端点返回 200
2. 检查错误监控仪表盘（无新错误类型）
3. 检查延迟仪表盘（无回归）
4. 手动测试关键用户流程
5. 验证日志正常流动且可读
6. 确认回滚机制正常工作（如可能，进行演练）

回滚策略

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

## [功能/版本] 的回滚计划

### 触发条件
- 错误率 > 基线的 2 倍
- P95 延迟 > [X]ms
- 用户报告 [具体问题]

### 回滚步骤
1. 禁用功能开关（如适用）
   或
1. 部署上一个版本：`git revert <commit> && git push`
2. 验证回滚：健康检查、错误监控
3. 沟通：通知团队回滚

### 数据库注意事项
- 迁移 [X] 有回滚：`npx prisma migrate rollback`
- 新功能插入的数据：[保留 / 清理]

### 回滚时间
- 功能开关：< 1 分钟
- 重新部署上一个版本：< 5 分钟
- 数据库回滚：< 15 分钟

参见

• 关于项目范围的“完成定义”，所有变更在应用此检查清单前必须满足，请参见 references/definition-of-done.md
• 关于安全发布前检查，请参见 references/security-checklist.md
• 关于性能发布前检查清单，请参见 references/performance-checklist.md
• 关于发布前无障碍验证，请参见 references/accessibility-checklist.md

常见借口

借口	现实
“在预发布环境能跑，生产环境也能跑”	生产环境有不同的数据、流量模式和边界情况。部署后要监控。
“我们不需要功能开关”	每个功能都受益于一个“杀死开关”。即使是“简单”的变更也可能出问题。
“监控是额外开销”	没有监控意味着你从用户投诉而不是仪表盘发现问题。
“我们以后再添加监控”	在发布前添加。你无法调试你看不到的东西。
“回滚就是承认失败”	回滚是负责任的工程。发布有问题的功能才是失败。

危险信号

• 没有回滚计划就部署
• 生产环境中没有监控或错误报告
• 大爆炸式发布（一次性全部发布，没有预发布）
• 功能开关没有过期时间或负责人
• 发布后第一小时无人监控
• 生产环境配置靠记忆而非代码
• “现在是周五下午，我们发布吧”

验证

部署前：

• [ ] 发布前检查清单已完成（所有部分为绿色）
• [ ] 功能开关已配置（如适用）
• [ ] 回滚计划已记录
• [ ] 监控仪表盘已设置
• [ ] 团队已收到部署通知

部署后：

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