# 生产发布与数据库上线方案
> 文档版本：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](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](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/backend/migrations) 已完整纳入发布
- [D:\dev\cmr-mini\doc\backend\后台生产闭环架构草案.md](D:/dev/cmr-mini/doc/backend/后台生产闭环架构草案.md) 中当前主线对象已落库
- `DATABASE_URL` 已切到生产库
- JWT / 微信 / OSS 配置已替换为生产值
- workbench / 管理接口在生产环境默认不对外暴露或受限
- demo 事件、demo variant 不进入生产正式运营入口

---

## 9. 一句话结论

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

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

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