cmr-mini/doc/backend/生产发布与数据库上线方案.md

生产发布与数据库上线方案

文档版本：v1.0 最后更新：2026-04-03 16:20:00

1. 目标

本文档用于约定：

• 开发测试数据库与正式生产数据库的关系
• 正式上线时数据库如何初始化与升级
• 后端服务如何与数据库发布配合
• 每次上线前后的最小检查项

当前原则只有一条：

• 测试库继续做测试，生产库独立建库，靠 migration 升级，不靠手工拷贝。

---

2. 环境划分

建议至少分 2 套数据库环境：

• dev：开发 / 联调 / demo / workbench
• prod：正式生产

如果条件允许，推荐分 3 套：

• dev
• staging
• prod

其中：

• dev 用于日常开发和联调
• staging 用于上线前预演
• prod 只承载正式业务数据

---

3. 当前数据库结构来源

当前仓库已经采用 migration 驱动结构演进，目录位于：

• D:\dev\cmr-mini\backend\migrations

当前已存在的迁移文件包括：

• 0001_init.sql
• 0002_launch.sql
• 0003_home.sql
• 0004_results.sql
• 0005_config_pipeline.sql
• 0006_resource_objects.sql
• 0007_variant_minimal.sql
• 0008_production_skeleton.sql
• 0009_event_ops_phase2.sql

因此正式上线时，数据库结构应以这些 migration 为准，而不是以当前测试库的现状为准。

---

4. 第一次生产上线

第一次正式上线建议按以下顺序执行：

1. 新建生产 PostgreSQL 数据库
2. 配置生产环境变量
3. 按顺序执行全部 migration
4. 导入必要的生产基础数据
5. 部署后端服务
6. 执行最小 smoke test
7. 再切前端 / 小程序到生产后端

4.1 生产环境变量

至少应与开发环境分离以下配置：

• DATABASE_URL
• JWT 相关密钥
• 微信小程序相关配置
• OSS / 资源发布相关配置
• 其它第三方服务配置

开发环境中的 .env 不能直接视为生产配置。

参考文件：

• D:\dev\cmr-mini\backend.env.example

4.2 生产初始数据

第一次上线时，建议只导入最小必要数据，例如：

• 租户
• 默认渠道
• 最小活动与地图运行数据

不建议把开发联调用的 demo 数据直接原样导入生产。

---

5. 后续版本上线

每次后续正式上线建议固定为以下顺序：

1. 备份生产数据库
2. 部署前确认本次新增 migration
3. 执行新增 migration
4. 发布后端服务
5. 验证关键接口
6. 再切客户端或前端流量

关键接口最少应验证：

• 登录
• 活动列表
• 活动详情
• launch
• session start / finish
• result / history

---

6. 上线原则

6.1 不直接复用测试库

禁止做法：

• 直接把开发测试数据库改名当生产库
• 通过手工拷表来“上线”
• 在生产库中临时手改结构但不补 migration

6.2 结构变更只走 migration

所有数据库结构变化都应：

• 新增 migration 文件
• 进入版本管理
• 随代码一起发布

不应依赖口头约定或临时 SQL。

6.3 生产数据与测试数据分离

开发 demo 数据、联调活动、手工实验数据，应停留在：

• dev
• 或 staging

不要直接进入 prod。

6.4 代码版本与数据库版本对应

每次上线都应能回答两件事：

• 当前代码对应到哪一个 migration 版本
• 当前生产库已经执行到哪一个 migration 版本

---

7. 推荐的发布节奏

建议发布节奏为：

阶段 1：数据库先行

• 新 migration 先在 dev 验证
• 再在 staging 演练
• 最后进入 prod

阶段 2：服务发布

• 后端服务发布到对应环境
• 验证启动、连接数据库、关键接口可用

阶段 3：客户端切换

• 小程序 / App / H5 再切到新的后端能力
• 避免客户端先切到一个数据库未升级的后端版本

---

8. 当前项目建议的最小上线清单

对当前仓库，正式上线前建议至少确认：

• D:\dev\cmr-mini\backend\migrations 已完整纳入发布
• D:\dev\cmr-mini\doc\backend\后台生产闭环架构草案.md 中当前主线对象已落库
• DATABASE_URL 已切到生产库
• JWT / 微信 / OSS 配置已替换为生产值
• workbench / 管理接口在生产环境默认不对外暴露或受限
• demo 事件、demo variant 不进入生产正式运营入口

---

9. 一句话结论

当前项目的正式上线方式应固定为：

• 新建独立生产库
• 通过 migration 初始化和升级
• 通过生产环境变量部署后端
• 通过最小 smoke test 验证
• 最后再切客户端入口

不要把开发测试数据库直接视为生产数据库。