环境分支的发布与灰度
本文介绍环境分支开发完成后，如何将改动发布到生产环境，以及如何在线上进行灰度发布，使新版本出现问题时只影响少量用户并能快速回滚。
发布流程
| 阶段 | 做什么 | 使用的能力 |
|---|---|---|
| 在分支上开发与验证 | 使用分支中的数据验证改动 | 环境分支 |
| 发布到生产环境 | 将验证过的改动按顺序应用到生产环境 | 迁移 SQL、函数部署与版本发布 |
| 线上灰度 | 新版本先承接部分流量，确认无误后全量 | 云函数版本流量；需要时自建路由层 |
在分支上开发与验证
分支是从生产环境复制出的另一个环境，拥有独立的环境 ID、数据库副本、HTTP 网关和访问域名。在分支上验证改动，并使用分支中的数据完成测试。Private Alpha 阶段的能力范围见Private Alpha 阶段的建议。
发布到生产环境
- 改动以文件管理：数据库变更写成迁移 SQL，函数代码和配置纳入版本控制。避免只在控制台或 SQL 窗口中手动修改，否则在生产环境上无法准确重放。
- 在分支上验证：使用分支中的数据完成测试。Private Alpha 阶段可在分支上验证的范围见下文。
- 评审：通过代码评审（如 Pull Request）确认变更内容。
- 按顺序发布到生产环境：先执行数据库迁移，再部署函数并发布新版本，最后通过版本流量逐步放量。
规划中：差异对比与合并
后续计划提供分支合并能力：先对比分支与生产环境的差异（数据库结构差异的对比方式参考 Supabase pg-delta），确认后合并到生产环境。分支中的数据不参与合并。
Private Alpha 阶段的建议
环境分支目前处于 Private Alpha 阶段，提供通过 API 创建、查看和删除分支，以及使用分支临时密钥访问分支的数据接口。结合当前能力，建议：
- 表结构在生产环境变更：当前不支持在分支上修改表结构。表结构变更写成迁移 SQL，按先兼容、后清理的方式在生产环境执行；分支中需要用到的表，先在生产环境创建，再创建分支。
- 用分支验证数据读写：使用分支临时密钥在分支中读写数据，验证查询和数据处理逻辑，或交给 AI Agent 操作，生产环境的数据不受影响。
线上灰度
灰度期间，新旧版本需要读写同一份生产数据，因此灰度在生产环境内进行。
云函数：使用版本流量
- 发布一个函数版本，并将线上流量 100% 指向该版本。此后部署新代码只会更新
$LATEST，不影响线上流量。 - 部署新代码并发布新版本。
- 为新版本分配少量流量，观察无误后逐步提高比例，直至 100%。
- 出现问题时，将旧版本流量调回 100%。
版本流量的分配行为如下：
| 场景 | 行为 |
|---|---|
| 路由开启“身份认证” | 同一用户的请求固定落在同一版本 |
| 路由未开启“身份认证” | 每个请求按比例随机分配版本 |
| 逐步提高新版本比例 | 已在新版本的用户不会被切回旧版本 |
| 多个函数同时灰度 | 比例相同时，同一用户在各函数落在相同版本 |
| 回滚 | 调整比例后，通常在数十秒内生效 |
如需按用户保持版本一致，请为对应路由开启身份认证。配置方法见云函数灰度发布。
数据库：先兼容，后清理
新旧版本共用同一个数据库，数据库变更对两个版本同时生效，无法灰度，也无法通过切换流量回滚。建议分两次发布：
- 先兼容：只新增表、列、索引，确保新旧版本的函数均可正常运行。
- 后清理：新版本全量稳定、旧版本不再承接流量后，再删除旧列或旧表。
出现问题时只回切函数版本，数据库不回退；需要修正时，通过新的迁移向前修复。
前端
静态网站托管不提供按版本或按用户分发前端资源的能力。前端出现问题时，重新部署上一个构建即可恢复。如需前端灰度，可将新旧构建部署在不同路径，由自建路由层按规则返回。
自建路由层
以下需求超出云函数版本流量的范围，可在 CloudBase 之前增加一层由您自行维护的路由层（如 CDN 规则、边缘函数、BFF、Nginx）。
每个环境的 HTTP 网关只能将请求路由到本环境的资源，生产环境的网关无法转发到分支环境。需要同时访问两个环境时，路由层应位于两个环境的 HTTP 网关之前，按规则将请求转发到对应环境的域名。
┌─ 生产环境域名 → 生产环境 HTTP 网关 ─┬─ /api-stable → 函数版本 N
客户端 → 自建路由层 ─┤ └─ /api-canary → 函数版本 N+1
│ （共用生产数据库）
└─ 分支环境域名 → 分支环境 HTTP 网关 → 分支中的函数
（仅内部或 Beta 用户）
| 需求 | 做法 |
|---|---|
| 前端灰度 | 新旧前端构建部署在不同路径或站点，路由层按规则返回 |
| 按租户或名单灰度 | 在生产环境的 HTTP 网关为新旧版本各建一条路由，分别绑定固定的函数版本，路由层按租户或名单转发 |
| 内部或 Beta 用户访问分支 | 路由层将指定用户的请求转发到分支环境的域名，限制见分支不承接线上流量 |
按租户或名单灰度时，CloudBase 侧只需在生产环境的 HTTP 网关中为灰度版本新建一条路由，并绑定指定的函数版本：
设计路由层时注意：
- 只设一个分流点：路由层下游的路由绑定固定版本，不要再叠加函数版本流量。
- 使用可信标识：按经过验证的用户 ID 或租户 ID 分流，不信任客户端自行上报的标识。
- 回滚开关优先：切回旧版本的开关优先级高于名单、强制指定等其他规则。
- 不跨版本重试：新版本请求失败时直接返回错误，不自动改发到旧版本。